Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
#!/usr/bin/env node
// DCO(Developer Certificate of Origin)门禁:校验一段 commit 范围里每个非豁免 commit
// 都带有与其 author(或 committer)一致的 Signed-off-by trailer。DCO 全文见仓库根
// 的 DCO 文件,贡献者侧说明见 CONTRIBUTING.md「贡献的许可与署名(DCO)」。
//
// 只检查 PR 引入的新 commit(merge-base..head),不追溯仓库历史,因此对 DCO 生效前
// 的既有提交无影响。只读 git 元数据,不访问网络、不读任何私有配置或凭证。
//
// PR 上的权威门禁是 DCO GitHub App 的 check(配置见 .github/dco.yml),本脚本是提交前
// 的本地自查,判定刻意与 App 对齐或更严,好让本地通过一定意味着 App 通过。
//
// 本地用法:
// pnpm check:dco 校验 origin/main..HEAD
// node scripts/check-dco.mjs --base <ref> --head <ref>
// 在 pull_request 事件下运行时(GITHUB_EVENT_PATH 存在)自动从 payload 取
// base.sha 与 head.sha 作为范围。
import { execFileSync } from 'node:child_process';
import { existsSync, readFileSync, realpathSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { isSignOffHookInstalled } from './install-dco-hook.mjs';
// git log 的字段/记录分隔符:用 ASCII 控制字符,避免与 commit message 内容碰撞。
const FIELD_SEP = '\u001f';
const RECORD_SEP = '\u001e';
const LOG_FORMAT = ['%H', '%P', '%an', '%ae', '%cn', '%ce', '%B'].join(FIELD_SEP) + RECORD_SEP;
// 与 DCO App 的匹配器逐字对齐(dcoapp/app 的 `lib/dco.js`:
// `/^Signed-off-by: (.*) <(.*)>\s*$/gim`)。逐行匹配而不强求在 message 末尾:trailer
// 之后常见还有 Co-authored-by 等其他 trailer。
//
// 刻意不放宽这三处,它们都会造成「本地绿、PR 红」:
// - 不允许行首空白:App 的 `^Signed-off-by:` 锚在行首,缩进过的行在它眼里根本不是签名。
// - `Signed-off-by:` 后只允许一个空格:写两个空格时 App 会把多出来的空格算进 name,
// 于是 name 与 author 比不上。
// - 捕获值不 trim(见 validateCommit):App 拿原样捕获去比,`Alice ` 不等于 `Alice`。
const SIGN_OFF_LINE = /^Signed-off-by: (.*) <(.*)>\s*$/i;
// bot 地址的形状特征:dependabot 等用 `<name>[bot]@users.noreply.github.com`,
// GitHub Web UI 用 web-flow 的 [email protected]。
//
// **这只用于在失败输出里提示,不用于豁免。** App 判定 bot 的依据是 GitHub 账号类型
// (`author.type === "Bot"`),离线拿不到也伪造不了;而 author 邮箱谁都能设成
// `999999+not-a-real-account[bot]@users.noreply.github.com`。按邮箱豁免就等于给本地检查
// 留一个可伪造的后门,方向还是最坏的那种——「本地绿、PR 红」。所以本地一律检查,
// 只在输出里说明「若它真是 bot,PR 上的 App 会豁免」。
const BOT_EMAILS = new Set(['[email protected]']);
const BOT_EMAIL_SUFFIX = '[bot]@users.noreply.github.com';
// 本地默认基准。upstream/main 排在前面:从 fork 干活时 origin/main 可能领先于上游,
// 拿它当基准会把 fork 自己那些未签名的提交排除在范围外,而 PR 的真实 base 是上游。
// 这只是本地自查的启发式——真实 base 以 PR 上的 DCO check 为准,所以通过时会把实际用的
// 基准打印出来。
const DEFAULT_BASE_CANDIDATES = ['upstream/main', 'origin/main', 'main'];
const git = (args, options = {}) =>
execFileSync('git', args, { encoding: 'utf8', ...options }).trim();
export function normalizeEmail(email) {
return String(email ?? '').trim().toLowerCase();
}
export function normalizeName(name) {
return String(name ?? '').trim().toLowerCase();
}
// 邮箱形状:对齐 DCO App 用的 validator.isEmail 的默认规则。
// - local part 限定为 RFC 5322 的 atext 字符集,点分隔且不允许连续点或首尾点。
// 注意 atext 不含括号、方括号、引号等,所以 `a(b)@x.com` 会被拒——validator 也拒。
// - 域名每个 label 不能以连字符开头或结尾,不允许下划线,且必须有字母 TLD(于是 git 未配
// user.email 时自动生成的 `user@hostname` 会被拒)。
// 无法逐条复刻 validator,取舍上刻意偏严:宁可本地误报,也不要放行一个 App 会拒的地址,
// 那才会变成「本地绿、PR 红」。含方括号的 bot 邮箱(dependabot 等)同样不符合 atext,
// 于是这类提交在本地会被报出来——而 App 因为账号是 Bot 直接跳过。结论不同但方向安全
// (本地红、PR 绿),失败输出里会说明这一点。
const ATEXT = "[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]";
const DOMAIN_LABEL = '[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?';
const EMAIL_LOCAL_PART = new RegExp(`^${ATEXT}+(?:\\.${ATEXT}+)*$`);
const EMAIL_DOMAIN = new RegExp(`^${DOMAIN_LABEL}(?:\\.${DOMAIN_LABEL})*\\.[A-Za-z]{2,}$`);
// validator.isEmail 的长度上限,超出即拒。整体上限单独存在:local part 与 domain 各自
// 合规、加起来仍可能超过 254。
const MAX_TOTAL = 254;
const MAX_LOCAL_PART = 64;
const MAX_DOMAIN = 254;
const MAX_DOMAIN_LABEL = 63;
export function looksLikeEmail(email) {
const value = String(email ?? '').trim();
if (value.length > MAX_TOTAL) return false;
const at = value.lastIndexOf('@');
if (at <= 0 || at === value.length - 1) return false;
const localPart = value.slice(0, at);
const domain = value.slice(at + 1);
if (localPart.length > MAX_LOCAL_PART || domain.length > MAX_DOMAIN) return false;
if (domain.split('.').some((label) => label.length > MAX_DOMAIN_LABEL)) return false;
return EMAIL_LOCAL_PART.test(localPart) && EMAIL_DOMAIN.test(domain);
}
/**
* 提取 message 里所有 Signed-off-by 行。捕获值原样保留、不 trim——App 也不 trim,
* 多出来的空白会让它与 author 比对失败,这里跟着一起失败才不会「本地绿、PR 红」。
*/
export function parseSignOffs(message) {
const signOffs = [];
for (const line of String(message ?? '').split(/\r?\n/)) {
const match = SIGN_OFF_LINE.exec(line);
if (match) signOffs.push({ name: match[1], email: match[2] });
}
return signOffs;
}
/** 只判断「地址长得像 bot」,供失败输出提示用;不构成豁免,理由见上面的注释。 */
export function looksLikeBotAddress(email) {
const normalizedEmail = normalizeEmail(email);
return BOT_EMAILS.has(normalizedEmail) || normalizedEmail.endsWith(BOT_EMAIL_SUFFIX);
}
/**
* 返回豁免原因,不豁免则返回 null。
*
* 只有 merge commit 能离线可靠判定(父提交数量),所以只豁免它。bot 提交交给 App 按账号
* 类型豁免——本地宁可多报一条,也不放过一个可伪造的身份。
*/
export function exemptReason(commit) {
if (commit.parents.length > 1) return 'merge commit';
return null;
}
/**
* 返回错误列表;空列表即通过。判定与 DCO App(dcoapp/app 的 lib/dco.js)对齐,两处
* 刻意更严——偏严只会「本地红、PR 绿」,偏宽才会「本地绿、PR 红」,后者才是要避免的:
*
* 1. 签名必须整体匹配 author 或 committer 这一个身份。App 是把 name 与 email 拆成两个
* 集合分别判断,于是 author=Alice<a@x>、committer=Bob<b@x> 时 `Alice <b@x>` 也能过,
* 尽管这个身份并不存在——这里按 name+email 成对比较。
* 2. 邮箱形状见 looksLikeEmail。
*
* 本脚本同样不识别 remediation commit(App 侧由 .github/dco.yml 开启),也是同一取舍。
* 面向贡献者的文案统一用英文。
*/
export function validateCommit(commit) {
const signOffs = parseSignOffs(commit.message);
if (signOffs.length === 0) {
return ['No Signed-off-by trailer.'];
}
// 与 App 一致:只看 author.email(缺失时回落 committer.email)。改成「两者都非法才
// 失败」会比 App 宽松,反而制造本地绿、PR 红。
const email = commit.authorEmail || commit.committerEmail;
if (!looksLikeEmail(email)) {
return [`${email} is not a valid email address.`];
}
const identities = [
{ name: normalizeName(commit.authorName), email: normalizeEmail(commit.authorEmail) },
{ name: normalizeName(commit.committerName), email: normalizeEmail(commit.committerEmail) },
];
// 签名侧只 lowercase、不 trim(App 亦然);commit 侧 trim 是安全的,git ident 本身
// 不带前后空白。两边处理方式刻意不同,正是为了让「Alice 」这种写法在本地也失败。
const matches = (signOff) =>
identities.some(
(identity) =>
identity.name === String(signOff.name).toLowerCase() &&
identity.email === String(signOff.email).toLowerCase()
);
if (signOffs.some(matches)) return [];
const got = signOffs.map((signOff) => `"${signOff.name} <${signOff.email}>"`).join(', ');
return [
`Expected a sign-off from "${commit.authorName} <${commit.authorEmail}>" or ` +
`"${commit.committerName} <${commit.committerEmail}>", got ${got}. ` +
'The name and the address have to match one of them as a whole.',
];
}
export function validateCommits(commits) {
const failures = [];
const exempted = [];
let checked = 0;
for (const commit of commits) {
const reason = exemptReason(commit);
if (reason) {
exempted.push({ commit, reason });
continue;
}
checked += 1;
const errors = validateCommit(commit);
if (errors.length > 0) failures.push({ commit, errors });
}
return { failures, exempted, checked };
}
export function parseGitLog(stdout) {
return String(stdout)
.split(RECORD_SEP)
.map((record) => record.replace(/^\r?\n/, ''))
.filter((record) => record.trim() !== '')
.map((record) => {
const [sha, parents, authorName, authorEmail, committerName, committerEmail, message] =
record.split(FIELD_SEP);
return {
sha: (sha ?? '').trim(),
parents: (parents ?? '').trim() ? parents.trim().split(/\s+/) : [],
authorName: authorName ?? '',
authorEmail: authorEmail ?? '',
committerName: committerName ?? '',
committerEmail: committerEmail ?? '',
message: message ?? '',
};
});
}
export function shortSha(sha) {
return String(sha ?? '').slice(0, 8);
}
export function subjectOf(commit) {
return String(commit.message ?? '').split(/\r?\n/, 1)[0].trim();
}
function readArg(name) {
const index = process.argv.indexOf(name);
return index !== -1 ? process.argv[index + 1] : undefined;
}
function revParse(ref) {
try {
return git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { stdio: ['ignore', 'pipe', 'ignore'] });
} catch {
return null;
}
}
/** 解析待校验范围。返回的 start 是排除端点(start..head)。 */
function resolveRange() {
const explicitBase = readArg('--base');
const explicitHead = readArg('--head');
const eventPath = process.env.GITHUB_EVENT_PATH;
let base = explicitBase;
let head = explicitHead ?? 'HEAD';
if (!base && eventPath) {
const event = JSON.parse(readFileSync(eventPath, 'utf8'));
const pr = event.pull_request;
if (!pr) throw new Error('Event payload has no pull_request; check the workflow trigger.');
base = pr.base?.sha;
head = explicitHead ?? pr.head?.sha ?? 'HEAD';
if (!base) throw new Error('Event payload is missing pull_request.base.sha.');
}
if (!base) {
base = DEFAULT_BASE_CANDIDATES.find((candidate) => revParse(candidate));
if (!base) {
throw new Error(
`No default base ref found (${DEFAULT_BASE_CANDIDATES.join(' / ')}); pass --base <ref>.`
);
}
}
const baseSha = revParse(base);
if (!baseSha) throw new Error(`Cannot resolve base ref: ${base} (fetch it first if missing).`);
const headSha = revParse(head);
if (!headSha) throw new Error(`Cannot resolve head ref: ${head}.`);
// 用 merge-base 而不是 base 本身:base 分支在 PR 开着期间会前进,直接用
// base.sha..head 会把 base 侧的他人提交也算进来,造成误报。
let start = baseSha;
try {
start = git(['merge-base', baseSha, headSha]);
} catch {
// 没有共同祖先(例如孤立分支)时退回 base 本身。
}
return { start, head: headSha, baseRef: base };
}
function reportFailures({ failures, start }) {
const plural = failures.length === 1 ? 'commit' : 'commits';
console.error(`DCO check failed: ${failures.length} ${plural} without a valid Signed-off-by.\n`);
for (const { commit, errors } of failures) {
console.error(`- ${shortSha(commit.sha)} ${subjectOf(commit)}`);
for (const error of errors) console.error(` ${error}`);
// 地址像 bot 时给一句解释,免得有人以为门禁在为难 dependabot:真 bot 由 App 按 GitHub
// 账号类型豁免,而账号类型离线取不到,所以本地照常报。
if (looksLikeBotAddress(commit.authorEmail)) {
console.error(' This looks like a bot address. Bot commits are exempt on the pull request,');
console.error(' where the DCO App can check the GitHub account type — this check cannot,');
console.error(' so it reports them rather than trusting a forgeable address.');
}
}
// 用完整 sha:短 sha 在大仓里可能歧义,让复制粘贴的命令直接失败。
console.error('\nHow to fix, on your pull request branch:');
console.error(' most recent commit only: git commit --amend -s --no-edit');
console.error(` several commits: git rebase --signoff ${start}`);
console.error(' then update the PR: git push --force-with-lease');
console.error('\nTo stop forgetting, commit with `git commit -s`, or install the hook shipped');
console.error('with this repository once: `pnpm dco:install-hook` (.githooks/prepare-commit-msg).');
console.error('The DCO file at the repository root states what the sign-off certifies;');
console.error('CONTRIBUTING.en.md explains the requirement in full.');
}
function main() {
const { start, head, baseRef } = resolveRange();
const stdout = execFileSync('git', ['log', `--format=${LOG_FORMAT}`, `${start}..${head}`], {
encoding: 'utf8',
maxBuffer: 64 * 1024 * 1024,
});
const commits = parseGitLog(stdout);
if (commits.length === 0) {
console.log(`No new commits in ${shortSha(start)}..${shortSha(head)}; nothing to check.`);
return;
}
const { failures, exempted, checked } = validateCommits(commits);
if (failures.length > 0) {
reportFailures({ failures, start });
process.exit(1);
}
const exemptNote = exempted.length > 0 ? `, ${exempted.length} exempt (merge commits)` : '';
console.log(
`DCO check passed: ${checked} ${checked === 1 ? 'commit' : 'commits'} signed off${exemptNote} ` +
`— range ${shortSha(start)}..${shortSha(head)} (base ${baseRef}).`
);
if (!process.env.GITHUB_EVENT_PATH && !isSignOffHookInstalled()) {
console.log('Tip: `pnpm dco:install-hook` signs off local commits automatically.');
}
}
// 仅作为入口执行时运行;被 import 时只导出纯函数,便于单测。
const isDirectRun =
process.argv[1] && existsSync(process.argv[1]) && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
if (isDirectRun) {
try {
main();
} catch (error) {
console.error(String(error?.message ?? error));
process.exit(1);
}
}