/** * readSource 源码钉子占比的**逐文件台账**棘轮(只许减)。 * * 为什么不是两个标量:只钉「总用例数 + 含钉子的文件数」时,A 文件加一条、B 文件减一条 * 就双双不动地绕过去了。基线必须落在每个文件上,且"台账外的新文件带钉子"同样算破口。 * * 为什么切分器是锚点分段而不是括号配对:这棵树里 1,704 个 `test(`/`it(` 全部行首出现 * (缩进 ≤4、可带 await),没有一条由循环生成;而括号配对会被正则字面量里的 `)` 提前收口, * 实测漏掉 48 处。"分母悄悄变小"对只许减的棘轮是沉默的,所以这里另用一把独立口径对账 * (countTestOccurrences),两者不等就红。 * * **第二把尺子(reads,2026-10-08 加)**:`pins` 只认落在用例体内的读盘调用,于是有一条免费的绕过路—— * 把 `readSource(...)` 从用例体挪进模块级 helper,钉子数当场变 0 而守卫一个都没少 * (本仓 `ops-cell-must-wrap.test.ts` 第一天就被记成 `{cases:2, pins:0}`,实测有读盘却"零钉子"; * 全树这样"体内 0 钉而有读点"的文件 21 个)。所以台账每格再加一个 `reads`=**全文读点总数(不分体内体外)**, * 规则两条:① `reads` 同样只许减;② `pins` 相对基线降了,`reads` 必须至少同步降同样多—— * 降不下来就认定是"搬家"而不是"去掉源码钉子",直接红。 * * 本机:`node --test tests/source-pin-ratchet.test.ts`(这面原先 0 个 node_modules, * 纯 node 24 类型剥离就能跑,不依赖 vitest/vue-tsc) * 重生成基线:`UPDATE_SOURCE_PIN_BASELINE=1 node --test tests/source-pin-ratchet.test.ts` */ import { test } from 'node:test' import assert from 'node:assert/strict' import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs' import { dirname, join } from 'node:path' import { fileURLToPath } from 'node:url' const HERE = dirname(fileURLToPath(import.meta.url)) const BASELINE_PATH = join(HERE, 'baselines', 'source-pin-ledger.json') /** 这把尺子自己的源码里有 readSource/readFileSync 的字样,不能把自己算成钉子。 */ const SELF = 'source-pin-ratchet.test.ts' export type FileLedger = { cases: number; pins: number; reads: number } export type Ledger = Record type Baseline = { note: string totals: { files: number; cases: number; pins: number; reads: number } files: Ledger } /** 剥掉块注释、行注释、单/双引号与模板字符串的内容,保留长度与换行以便回指行号。 */ export function stripNonCode(src: string): string { const out: string[] = [] let i = 0 const n = src.length while (i < n) { const two = src.slice(i, i + 2) if (two === '/*') { const close = src.indexOf('*/', i + 2) const end = close < 0 ? n : close + 2 for (let k = i; k < end; k++) out.push(src[k] === '\n' ? '\n' : ' ') i = end; continue } if (two === '//') { const nl = src.indexOf('\n', i + 2) const end = nl < 0 ? n : nl for (let k = i; k < end; k++) out.push(' ') i = end; continue } const q = src[i] if (q === '"' || q === "'" || q === '`') { let k = i + 1 out.push(' ') while (k < n) { if (src[k] === '\\') { out.push(' ', src[k + 1] === '\n' ? '\n' : ' '); k += 2; continue } if (src[k] === q) { out.push(' '); k++; break } out.push(src[k] === '\n' ? '\n' : ' ') k++ } i = k; continue } out.push(src[i]); i++ } return out.join('') } const ANCHOR = /^[ \t]{0,4}(?:await[ \t]+)?(?:test|it)[ \t]*\(/gm const PIN = /readSource\s*\(|readFileSync\s*\(|globSync\s*\(/ const READ_SITE = /readSource\s*\(|readFileSync\s*\(|globSync\s*\(/g /** 全文读点(体内 + 模块级夹具 + helper 都算),注释与字符串里的字样不算。 */ export function countReadSites(src: string): number { return (stripNonCode(src).match(READ_SITE) || []).length } /** 独立口径:出现次数(不做归属),用来给锚点分母对账。 */ export function countTestOccurrences(src: string): number { return (stripNonCode(src).match(/(^|[^\w$.])(test|it)[ \t]*\(/g) || []).length } export function sliceCases(src: string): string[] { const code = stripNonCode(src) const starts: number[] = [] let m: RegExpExecArray | null while ((m = ANCHOR.exec(code)) !== null) starts.push(m.index) const regions: string[] = [] for (let i = 0; i < starts.length; i++) { const to = i + 1 < starts.length ? starts[i + 1] : code.length regions.push(code.slice(starts[i], to)) } return regions } export function ledgerFor(src: string): FileLedger { const cases = sliceCases(src) return { cases: cases.length, pins: cases.filter((r) => PIN.test(r)).length, reads: countReadSites(src), } } export function collectSources(): Record { const out: Record = {} for (const name of readdirSync(HERE).sort()) { if (name === SELF || !name.endsWith('.test.ts')) continue const p = join(HERE, name) if (!statSync(p).isFile()) continue out[name] = readFileSync(p, 'utf8') } return out } export function buildLedger(sources: Record): Ledger { const led: Ledger = {} for (const [name, src] of Object.entries(sources)) led[name] = ledgerFor(src) return led } export type Breach = { file: string; got: FileLedger; cap: FileLedger; why: string[] } export function diffAgainstBaseline(got: Ledger, baseline: Ledger): Breach[] { const breaches: Breach[] = [] const push = (file: string, g: FileLedger, cap: FileLedger, why: string) => { let hit = breaches.find((b) => b.file === file) if (!hit) { hit = { file, got: g, cap, why: [] }; breaches.push(hit) } hit.why.push(why) } for (const [file, cap] of Object.entries(baseline)) { const g = got[file] ?? { cases: 0, pins: 0, reads: 0 } if (g.pins > cap.pins) push(file, g, cap, `钉子 ${cap.pins}→${g.pins}`) if (g.cases > cap.cases) push(file, g, cap, `用例 ${cap.cases}→${g.cases}`) if (g.reads > cap.reads) push(file, g, cap, `读点 ${cap.reads}→${g.reads}`) // 钉子降了就得问一句"读盘真的少了吗":只降计数不降读点=挪出体内,占比是搬出来的不是修出来的。 const droppedPins = cap.pins - g.pins const droppedReads = cap.reads - g.reads if (droppedPins > 0 && droppedReads < droppedPins) { push(file, g, cap, `钉子降 ${droppedPins} 而读点只降 ${droppedReads}:` + '把 readSource 挪出用例体/塞进 helper 不算改进') } } for (const [file, g] of Object.entries(got)) { if (!(file in baseline) && (g.pins > 0 || g.reads > 0)) { push(file, g, { cases: 0, pins: 0, reads: 0 }, '台账外新文件带源码钉子或读盘') } } return breaches } function measure() { const sources = collectSources() return { sources, ledger: buildLedger(sources) } } function totals(ledger: Ledger) { let files = 0, cases = 0, pins = 0, reads = 0 for (const v of Object.values(ledger)) { files++; cases += v.cases; pins += v.pins; reads += v.reads } return { files, cases, pins, reads } } function loadBaseline(): Baseline { assert.ok(existsSync(BASELINE_PATH), `基线台账不存在:${BASELINE_PATH}(用 UPDATE_SOURCE_PIN_BASELINE=1 跑一次生成)`) return JSON.parse(readFileSync(BASELINE_PATH, 'utf8')) as Baseline } test('分母自证:切分器与独立出现次数口径逐文件对平', () => { const { sources, ledger } = measure() const bad: string[] = [] for (const [name, src] of Object.entries(sources)) { const occ = countTestOccurrences(src) if (ledger[name].cases !== occ) bad.push(`${name} 切分=${ledger[name].cases} 出现=${occ}`) } assert.deepEqual(bad, [], '切分器漏切用例 ⇒ 分母变小 ⇒ 棘轮变松:\n' + bad.join('\n')) assert.ok(totals(ledger).cases > 1500, `分母只有 ${totals(ledger).cases},不像整棵 tests/ 树`) // 两把尺子的关系必须站得住:体内钉子是全文读点的子集。reads < pins ⇒ 有一把在说谎。 const liar: string[] = [] for (const [name, v] of Object.entries(ledger)) { if (v.reads < v.pins) liar.push(`${name} 读点=${v.reads} < 钉子=${v.pins}`) if (v.pins > 0 && v.reads === 0) liar.push(`${name} 有钉子却读不到读点`) } assert.deepEqual(liar, [], '体内口径与全文口径互相矛盾:\n' + liar.join('\n')) }) test('基线自身不许是被清空的壳', () => { const b = loadBaseline() assert.ok(b.totals.cases > 1500, `基线 cases=${b.totals.cases} 小得可疑`) assert.ok(Object.keys(b.files).length >= 100, `基线只覆盖 ${Object.keys(b.files).length} 个文件`) // 第二把尺子的基线缺格就等于那把尺子没装:`reads > undefined` 恒 false,红不出来。 const noReads = Object.entries(b.files) .filter(([, v]) => typeof (v as FileLedger).reads !== 'number') .map(([f]) => f) assert.deepEqual(noReads, [], `基线里 ${noReads.length} 个文件没有 reads 字段(用 UPDATE_SOURCE_PIN_BASELINE=1 重生成):\n` + noReads.slice(0, 8).join('\n')) assert.ok(b.totals.reads > 0 && Object.values(b.files).reduce((a, v) => a + v.reads, 0) > 0, '基线 reads 合计为 0 ⇒ 全文口径是个空壳') }) test('逐文件台账只许减:钉子数、用例数、全文读点都不得高于基线', () => { const breaches = diffAgainstBaseline(measure().ledger, loadBaseline().files) assert.deepEqual(breaches, [], JSON.stringify(breaches, null, 2)) }) test('钉子判定落在用例体内,不是文件里出现过 readSource', () => { const two = ` import { readSource } from './helpers/x.ts' test('钉源码', () => { assert.match(readSource('a.vue'), /company_id/) }) test('纯行为', () => { assert.equal(sum(1, 2), 3) }) ` const led = ledgerFor(two) assert.equal(led.cases, 2) assert.equal(led.pins, 1, '只有第一条是源码钉子') const header = ` import { readFileSync } from 'node:fs' const SRC = readFileSync('a.vue', 'utf8') test('用夹具断行为', () => { assert.ok(SRC.length > 0) }) ` assert.equal(ledgerFor(header).pins, 0, '把文件头的夹具读取算成钉子会让占比虚高') const commented = ` test('行为用例', () => { // 这里提一句 readSource('x') 只是注释 assert.equal(1, 1) }) ` assert.equal(ledgerFor(commented).pins, 0, '注释里的字样不该被算成钉子') // 两把尺子的分工就在这格:helper 里的读盘体内看不见,全文口径必须照样抓到。 const hoisted = ` import { readSource } from './helpers/x.ts' function src(p) { return readSource(p) } test('靠 helper 读盘', () => { assert.match(src('a.vue'), /company_id/) }) ` const hoistedLedger = ledgerFor(hoisted) assert.equal(hoistedLedger.pins, 0, '体内口径对 helper 是瞎的(第二把尺子存在的原因)') assert.equal(hoistedLedger.reads, 1, '全文口径必须抓到 helper 里那一处读盘') }) test('台账有牙:加钉子、搬进新文件都要红;减钉子不许红', () => { const base = measure().ledger const first = Object.keys(base)[0] const bumped: Ledger = JSON.parse(JSON.stringify(base)) bumped[first] = { ...bumped[first], pins: bumped[first].pins + 1, reads: bumped[first].reads + 1 } assert.equal(diffAgainstBaseline(bumped, base).length, 1, '同文件加钉子没被抓到 ⇒ 棘轮是摆设') const moved: Ledger = { ...base, 'brand-new-pin.test.ts': { cases: 3, pins: 3, reads: 3 } } assert.ok(diffAgainstBaseline(moved, base).some((b) => b.file === 'brand-new-pin.test.ts'), '新文件装钉子绕过台账 ⇒ "内部搬家"这条路必须堵住') const improved: Ledger = JSON.parse(JSON.stringify(base)) improved[first] = { ...improved[first], pins: improved[first].pins, reads: improved[first].reads } assert.deepEqual(diffAgainstBaseline(improved, base), [], '基线等于实测时不该有任何破口') const withPin = Object.entries(base).find(([, v]) => v.pins >= 1)?.[0] assert.ok(withPin, '实测台账里一个带钉子的文件都没有 ⇒ 下面两条断言无从判定') const cap = base[withPin] // 真改进:钉子与读点一起少(把源码钉子换成行为断言,readSource 调用点随之消失)。 const reallyFixed: Ledger = JSON.parse(JSON.stringify(base)) reallyFixed[withPin] = { ...cap, pins: cap.pins - 1, reads: cap.reads - 1 } assert.deepEqual(diffAgainstBaseline(reallyFixed, base), [], '把改进报成破口等于拦住别人修好它') // 假改进(2026-10-08 踩到的那条):读点从用例体挪进模块级 helper,钉子数掉了而一个读盘都没少。 const smuggled: Ledger = JSON.parse(JSON.stringify(base)) smuggled[withPin] = { ...cap, pins: cap.pins - 1 } const smuggledBreach = diffAgainstBaseline(smuggled, base) assert.equal(smuggledBreach.length, 1, '把读盘挪出体内被记成改进 ⇒ 占比可以凭搬家一路降到 0') assert.match(smuggledBreach[0].why.join(' '), /不算改进/, '红必须点名是搬家不是修好') // 只动体外也要红:体内口径看不见的那一半,由 reads 兜住。 const extraRead: Ledger = JSON.parse(JSON.stringify(base)) extraRead[withPin] = { ...cap, reads: cap.reads + 1 } assert.ok(diffAgainstBaseline(extraRead, base).some((b) => b.file === withPin && b.why.join(' ').includes('读点')), '体外新增读盘绕开台账 ⇒ 第二把尺子是摆设') // 台账缺 reads 字段时第二把尺子不能静默失明(`x > undefined` 恒 false)。 const legacy: Ledger = JSON.parse(JSON.stringify(base)) legacy[withPin] = { cases: cap.cases, pins: cap.pins + 1 } assert.equal(diffAgainstBaseline(legacy, base).length, 1, '基线格子里没有 reads 也要按 pins 抓到破口') }) test('占比读数当场打印,供四面评分尺子取数', () => { const t = totals(measure().ledger) const b = totals(loadBaseline().files) const ratio = (100 * t.pins / t.cases).toFixed(2) const outside = t.reads - t.pins console.log(`[source-pin] 当前 文件=${t.files} 用例=${t.cases} 钉子=${t.pins} 占比=${ratio}%` + ` |全文读点=${t.reads}(体内 ${t.pins} + 体外 ${outside})` + ` |基线 用例=${b.cases} 钉子=${b.pins} 读点=${b.reads}`) assert.ok(Number(ratio) <= 30, `钉子占比 ${ratio}% 高得不合理`) assert.ok(t.reads >= t.pins, '全文读点少于体内钉子 ⇒ 两把尺子有一把坏了') }) if (process.env.UPDATE_SOURCE_PIN_BASELINE === '1') { const ledger = measure().ledger const t = totals(ledger) mkdirSync(dirname(BASELINE_PATH), { recursive: true }) writeFileSync(BASELINE_PATH, JSON.stringify({ note: 'readSource 钉子逐文件基线。两把尺子:pins=落在用例体内的读盘,reads=全文读点总数(含模块级夹具与 helper)。' + '都只许减;pins 下降而 reads 没同步下降=把读盘挪出体内,不算改进。由 tests/source-pin-ratchet.test.ts 生成。', totals: { files: t.files, cases: t.cases, pins: t.pins, reads: t.reads }, files: ledger, }, null, 1), 'utf8') console.log('[source-pin] 基线已重写 -> ' + BASELINE_PATH) }