|
| 1 | +import assert from 'node:assert/strict'; |
| 2 | +import fs from 'node:fs'; |
| 3 | +import path from 'node:path'; |
| 4 | +import { test } from 'vitest'; |
| 5 | +import { REPO_ROOT } from '@agent-device/test-kit'; |
| 6 | +import { listTrackedRepoFiles } from '../../scripts/layering/tracked-sources.ts'; |
| 7 | + |
| 8 | +/** |
| 9 | + * An ADR states the current truth (docs/adr/FORMAT.md), so every repository file it cites must |
| 10 | + * exist. A citation is a backticked token with a source or config extension: |
| 11 | + * |
| 12 | + * 1. a repository path (it contains `/`) must name a tracked file; |
| 13 | + * 2. a bare test file name (`*.test.ts` and similar) must match a tracked file's name. |
| 14 | + * |
| 15 | + * Absolute and home paths (device or host files), globs, and bare non-test names (runtime state |
| 16 | + * files such as `daemon.json`) are not repository citations. |
| 17 | + */ |
| 18 | + |
| 19 | +const ADR_DIR = 'docs/adr'; |
| 20 | +const CITED_EXTENSIONS = 'ts|mts|cts|mjs|cjs|js|swift|kt|java|json|sh|yml|yaml|py'; |
| 21 | +const CITATION = new RegExp(`\`([A-Za-z0-9_./@{}*-]+\\.(?:${CITED_EXTENSIONS}))\``, 'g'); |
| 22 | +const TEST_FILE = /\.test\.[a-z]+$/; |
| 23 | + |
| 24 | +type Citation = Readonly<{ adr: string; token: string }>; |
| 25 | + |
| 26 | +function findStaleAdrCitations( |
| 27 | + adrs: ReadonlyArray<Readonly<{ name: string; text: string }>>, |
| 28 | + trackedFiles: readonly string[], |
| 29 | +): Citation[] { |
| 30 | + const tracked = new Set(trackedFiles); |
| 31 | + const trackedNames = new Set(trackedFiles.map((file) => path.posix.basename(file))); |
| 32 | + const stale: Citation[] = []; |
| 33 | + for (const adr of adrs) { |
| 34 | + for (const [, token] of adr.text.matchAll(CITATION)) { |
| 35 | + if (!token || isNotRepositoryCitation(token)) continue; |
| 36 | + const exists = token.includes('/') ? tracked.has(token) : trackedNames.has(token); |
| 37 | + if (!exists) stale.push({ adr: adr.name, token }); |
| 38 | + } |
| 39 | + } |
| 40 | + return stale; |
| 41 | +} |
| 42 | + |
| 43 | +function isNotRepositoryCitation(token: string): boolean { |
| 44 | + if (token.startsWith('/') || token.startsWith('~')) return true; |
| 45 | + if (/[*{}]/.test(token)) return true; |
| 46 | + return !token.includes('/') && !TEST_FILE.test(token); |
| 47 | +} |
| 48 | + |
| 49 | +function readAdrs(): Array<{ name: string; text: string }> { |
| 50 | + const dir = path.join(REPO_ROOT, ADR_DIR); |
| 51 | + return fs |
| 52 | + .readdirSync(dir) |
| 53 | + .filter((name) => /^\d{4}-.*\.md$/.test(name)) |
| 54 | + .map((name) => ({ name, text: fs.readFileSync(path.join(dir, name), 'utf8') })); |
| 55 | +} |
| 56 | + |
| 57 | +test('every repository file an ADR cites exists', () => { |
| 58 | + const stale = findStaleAdrCitations(readAdrs(), listTrackedRepoFiles(REPO_ROOT)); |
| 59 | + assert.deepEqual( |
| 60 | + stale.map(({ adr, token }) => `${adr}: ${token}`), |
| 61 | + [], |
| 62 | + 'Fix or remove each stale citation; see docs/adr/FORMAT.md "The record stays current".', |
| 63 | + ); |
| 64 | +}); |
| 65 | + |
| 66 | +test('the citation scan rejects missing paths and test names, and skips non-repository tokens', () => { |
| 67 | + const stale = findStaleAdrCitations( |
| 68 | + [ |
| 69 | + { |
| 70 | + name: '0001-example.md', |
| 71 | + text: [ |
| 72 | + '`packages/a/src/kept.ts`', |
| 73 | + '`packages/a/src/gone.ts`', |
| 74 | + '`commands/runtime-types.ts`', |
| 75 | + '`kept.test.ts`', |
| 76 | + '`gone.test.ts`', |
| 77 | + '`daemon.json`', |
| 78 | + '`/sdcard/marker.json`', |
| 79 | + '`src/platform-runtime-*.ts`', |
| 80 | + ].join('\n'), |
| 81 | + }, |
| 82 | + ], |
| 83 | + ['packages/a/src/kept.ts', 'packages/a/src/__tests__/kept.test.ts'], |
| 84 | + ); |
| 85 | + assert.deepEqual( |
| 86 | + stale.map(({ token }) => token), |
| 87 | + ['packages/a/src/gone.ts', 'commands/runtime-types.ts', 'gone.test.ts'], |
| 88 | + ); |
| 89 | +}); |
0 commit comments