Skip to content

Commit df9e1c9

Browse files
authored
test(repo-guards): fail when an ADR cites a missing repository file
Closes the last #4205 completion condition. The guard checks every backticked repository path and bare test file name in docs/adr against the tracked tree, and skips device paths, globs and runtime state names. Also fixes the follow-ups from the slimming reviews: ADR 0005's stale test name, ADR 0012's linkSync rule with --force/--overwrite, ADR 0019's test-IME startup gap, ADR 0024's perf-capture status, and the platform-plugin contract comment that credited ADR 0009.
1 parent 0db6ed4 commit df9e1c9

8 files changed

Lines changed: 103 additions & 8 deletions

File tree

‎docs/adr/0005-ios-runner-interaction-lifecycle.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ The cost of a `RUNNER_BUSY` refusal to the caller depends on the daemon's own pe
103103
It does not depend on any runner-side classification of the command.
104104
The trait is `RUNNER_COMMAND_TRAITS` in `packages/apple-runner/src/runner-command-traits.ts`.
105105
`runAppleRunnerCommand` reads it through `isReadOnlyRunnerCommand` when it decides whether to wrap the send in a resend loop.
106-
This asymmetry is shipped, and `runner-client-busy-resend.test.ts` asserts it:
106+
This asymmetry is shipped, and `index-busy-resend.test.ts` in the Apple runner package asserts it:
107107

108108
- A read-only command treats the refusal as *not yet*.
109109
It waits for the drain on the busy-specific budget sized to outlast the drain.

‎docs/adr/0012-interactive-replay.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,7 @@ Every teardown commits if and only if the state is `COMPLETE`.
153153
Before `COMPLETE`, teardown publishes nothing, and idle-reap or shutdown leaves a `REPAIR_SESSION_EXPIRED` tombstone.
154154
An armed replay skips a terminal source `close` and marks the transaction `COMPLETE`.
155155
Publication writes `<original-stem>.healed.ad` beside the original unless the caller names a path. The original is never overwritten in place.
156-
One exclusive `linkSync` publishes the file and refuses every pre-existing target, for repair and ordinary `--save-script` recording alike.
156+
Without `--force`/`--overwrite`, one exclusive `linkSync` publishes the file and refuses a pre-existing target, for repair and ordinary `--save-script` recording alike; with the flag, publication replaces the target atomically.
157157

158158
Inside an armed repair segment, out-of-band observation-only commands are excluded from the healed script by default.
159159
Plan-step provenance (`internal.replayPlanStep`) keeps authored observations.

‎docs/adr/0019-request-bound-platform-runtime.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,7 @@ Startup recovery is triggered only by persisted durable manifests or platform-ow
220220
Daemon shutdown first detaches helper managers for handoff, then stops each still-owned generation at most once after session resources finalize.
221221
Each domain owns its isolated session-teardown step; there is no generic lifecycle-hook API.
222222
Test-IME restoration is durable device state with marker recovery; helper stops follow platform policy; close-time cleanup uses neutral owner services.
223-
Android test-IME marker and web browser orphan startup recovery still need to move to the evidence-triggered pattern when their owning domains migrate.
223+
Android test-IME marker recovery already runs only on recovery evidence; web browser orphan startup cleanup still needs to move to the evidence-triggered pattern when its owning domain migrates.
224224

225225
### 11. The platform-services port carries host asks that bind no device
226226

‎docs/adr/0024-screen-recording-provable-signal.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Proposed (2026-09-14).
66
This ADR amends ADR 0019 section 5 and the capture-kit recovery contracts for the `screen-recording` resource kind only.
77
ADR 0019 receives a short pointer paragraph, which section 2.7 of this ADR describes.
88
ADR 0022 and ADR 0023 have the same relationship to ADR 0019.
9-
App-log, audio-probe, and perf-capture keep the ADR 0019 contract unchanged.
9+
App-log and audio-probe keep the ADR 0019 contract unchanged; perf capture already preserves retry material after a failed finish.
1010
The shared mechanism of rule 6 reaches each of these kinds only through the own failed-finish test of that kind.
1111

1212
Completed rollout history is in git history.
@@ -70,7 +70,7 @@ Six rules make the table operational:
7070
Forced cleanup is never inferred from "finish threw".
7171
The mechanism is in the shared coordinator (`packages/capture-kit/src/durable-capture/transitions.ts`).
7272
But each kind must earn its scope.
73-
Each of app-log, audio-probe, and perf-capture gets its own failed-finish test that proves what its retry needs.
73+
Each of app-log and audio-probe gets its own failed-finish test that proves what its retry needs; perf capture already has one.
7474
A kind whose retry needs nothing keeps its current disposal explicitly.
7575
The Android data loss alone establishes the rule for recording only.
7676

@@ -322,7 +322,7 @@ This kind would remove the `cleanup-pending` phase and admission ledger.
322322
It would record the recorder observation and native-path disposition beside the committed export.
323323
A manifest would remain archived by fence generation until both are settled.
324324
For each durable kind, failed finish would no longer imply forced cleanup once its failed-finish test states its retry requirements.
325-
App-log, audio-probe, and perf-capture would retain the ADR 0019 contract unchanged.*
325+
App-log and audio-probe would retain the ADR 0019 contract unchanged.*
326326

327327
### 2.8 Android duration (separate decision)
328328

‎docs/adr/FORMAT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Do not repeat general repo guidance that `AGENTS.md` already gives.
4444

4545
## The record stays current
4646

47-
An ADR states the current truth. It is not a log of the discussion around the decision. An optional dated "Decision history" line records a real change of direction. If the direction really changed, you may add one such line with its reason and a link.
47+
An ADR states the current truth. It is not a log of the discussion around the decision. A repo guard fails when an ADR cites a repository file that does not exist. An optional dated "Decision history" line records a real change of direction. If the direction really changed, you may add one such line with its reason and a link.
4848

4949
## Before you amend
5050

‎packages/contracts/src/platform-plugin.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ import type { PlatformGatedProviderResolverKey } from './platform-providers.ts';
44
import type { Interactor, RunnerContext } from './interactor-types.ts';
55

66
/**
7-
* The platform-plugin contract (ADR-0009).
7+
* The platform-plugin contract. ADR 0009 owns the Apple family decision; ADR 0019 replaced the
8+
* original shallow `PlatformPlugin` shape with the request-bound runtime seam.
89
*
910
* One plugin owns one platform FAMILY: a plugin may cover several leaf
1011
* {@link Platform} literals (the Apple plugin owns both `ios` and `macos`,

‎scripts/layering/tracked-sources.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,11 @@ export function listTrackedSrcUtilsFiles(repoRoot: string): string[] {
5757
return listTrackedFilesUnderRoot(repoRoot, 'src/utils');
5858
}
5959

60+
/** Every tracked path in the repository. */
61+
export function listTrackedRepoFiles(repoRoot: string): string[] {
62+
return listTrackedFiles(repoRoot, []);
63+
}
64+
6065
function listTrackedFilesUnderRoot(repoRoot: string, root: string): string[] {
6166
return listTrackedFiles(repoRoot, [root]);
6267
}
Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
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

Comments
 (0)