diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74daf09..91272dc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ [脚注:Refs: #12 / Closes: #34 / BREAKING CHANGE: ...] ``` -- ``:下面表格里该类型对应的 emoji,后面跟**一个空格**。 +- ``:下面表格里该类型对应的 emoji,后面跟**一个空格**。emoji 是必需的,且必须与本行类型一致——`📝 docs:` 对,`✨ docs:` 不对。 - ``:小写英文关键字,见下表。 - `(scope)`:可选,改动范围。用 `()` 包住一个简短英文标识,例如 `docs(ci)`、`fix(client)`、`feat(host)`。 - `!`:可选,紧跟在 type 或 scope 之后、冒号之前,表示破坏性变更。 @@ -83,6 +83,17 @@ emoji 在行首是本仓库的有意选择,视觉上整齐。代价是:以 ^(?:\p{Extended_Pictographic}\uFE0F?\s+)?(?[a-z]+)(?:\((?[^)]*)\))?(?!)?:\s(?.+)$ ``` +## 自查 + +`scripts/check-commit-log.mjs` 会按本规范检查现有提交的首行,只报告、不拦提交: + +```bash +node scripts/check-commit-log.mjs # 最近 10 条 +node scripts/check-commit-log.mjs all # 全部 +``` + +它从本文件的类型表里读 emoji 对照表,所以改了表不用改脚本。规范之前的提交不符合是正常的。 + ## 启用提交模板(可选) `.gitmessage` 是提交信息模板。启用后每次 `git commit` 会带上前缀提示,删掉不需要的部分即可: diff --git a/scripts/check-commit-log.mjs b/scripts/check-commit-log.mjs new file mode 100644 index 0000000..03760e1 --- /dev/null +++ b/scripts/check-commit-log.mjs @@ -0,0 +1,74 @@ +// Checks real commit subjects (newest first) against the CONTRIBUTING.md spec: +// the documented regex must parse them, the leading emoji must be present and +// match the type table exactly, and the subject must stay within 72 width. +// +// This is a reporting tool, not a hook: it never blocks a commit. +// +// Usage: +// node scripts/check-commit-log.mjs # newest 10 commits +// node scripts/check-commit-log.mjs 50 # newest 50 commits +// node scripts/check-commit-log.mjs all # every commit +// DSD_SPEC=path/to/CONTRIBUTING.md node scripts/check-commit-log.mjs +import { execFileSync } from 'node:child_process' +import { readFileSync } from 'node:fs' +import { dirname, resolve } from 'node:path' +import { fileURLToPath } from 'node:url' + +const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..') +const specPath = process.env.DSD_SPEC ?? resolve(repoRoot, 'CONTRIBUTING.md') +const doc = readFileSync(specPath, 'utf8') +const count = process.argv[2] ?? '10' + +/** The regex the spec documents for stripping a leading emoji. */ +const SUBJECT = new RegExp( + '^(?:\\p{Extended_Pictographic}\\uFE0F?\\s+)?' + + '(?[a-z]+)' + + '(?:\\((?[^)]*)\\))?' + + '(?!)?' + + ':\\s(?.+)$', + 'u', +) + +// The spec's table is the single source of truth for the type → emoji mapping, +// so a table edit cannot drift from what this script checks. +const emojiOfType = new Map() +for (const row of doc.split('\n').filter((line) => /^\| `[a-z]+` \| /.test(line))) { + const cells = row.split('|').map((cell) => cell.trim()) + emojiOfType.set(cells[1].replaceAll('`', ''), cells[2]) +} +if (emojiOfType.size === 0) throw new Error(`${specPath} has no type table to read`) + +/** Strip the variation selector, so '♻' and '♻️' compare equal. */ +const base = (text) => text.replace(/\uFE0F/g, '') +/** Display width, counting anything above U+2000 as double. */ +const widthOf = (text) => [...text].reduce((n, c) => n + (c.codePointAt(0) > 0x2000 ? 2 : 1), 0) + +const args = count === 'all' ? ['log', '--format=%h%x09%s'] : ['log', `-${Number(count)}`, '--format=%h%x09%s'] +const rows = execFileSync('git', args, { encoding: 'utf8', cwd: repoRoot }) + .trim().split('\n').filter((line) => line !== '') + +let problems = 0 +for (const row of rows) { + const [hash, subject] = row.split('\t') + const notes = [] + const match = SUBJECT.exec(subject) + if (match === null) { + notes.push('缺少类型前缀,或整体格式不是 [(scope)][!]: <描述>') + } else { + const expected = emojiOfType.get(match.groups.type) + const lead = [...subject][0] + if (expected === undefined) notes.push(`类型不在规范表里:${match.groups.type}`) + else if (base(lead) !== base(expected)) notes.push(`类型 ${match.groups.type} 的 emoji 应为 ${expected},实际是 ${lead}`) + const width = widthOf(subject) + if (width > 72) notes.push(`首行宽度 ${width},超过 72`) + if (/[。.]$/.test(subject)) notes.push('首行结尾不应有句号') + } + if (notes.length > 0) problems += 1 + const mark = notes.length === 0 ? 'ok ' : 'FAIL' + console.log(` ${mark} ${hash} ${notes.length === 0 ? '' : notes.join(';') + ' — '}${subject}`) +} + +console.log(problems === 0 + ? `\n检查了 ${rows.length} 条提交,全部符合规范` + : `\n检查了 ${rows.length} 条提交,其中 ${problems} 条不符合规范(规范文件:${specPath})`) +process.exit(problems === 0 ? 0 : 1)