mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-10-21 22:46:32 +00:00
docs(server): the Nest README is a blueprint again, and guides may only name paths that exist
server/src/nest/README.md drops from 988 lines to under 200: the module shape with weather as the reference, the cross-cutting pieces, the guards, parity and the test layout, without the bridge playbook and the services recipe that contradicted the code. The migration log moves verbatim to server/docs/nest-migration-history.md, marked historical. scripts/ci/doc-paths.mjs resolves every backtick path in the CLAUDE.md files, the root README, the blueprint and the wiki against the tracked files. The paths already missing are listed in a baseline that only shrinks, and the changes job runs it so docs-only changes are checked too. The wiki no longer says the Playwright flows stay out of CI.
This commit is contained in:
Maurice
@@ -0,0 +1,30 @@
|
||||
[
|
||||
"client/CLAUDE.md :: slices/remoteEventHandler.ts",
|
||||
"plugin-sdk/CLAUDE.md :: protocol/output-contract.ts",
|
||||
"plugin-sdk/CLAUDE.md :: scripts/validate-entry.mjs",
|
||||
"server/CLAUDE.md :: db/migrations.ts",
|
||||
"server/CLAUDE.md :: host/plugin-data.service.ts",
|
||||
"server/CLAUDE.md :: host/rpc-host.ts",
|
||||
"server/CLAUDE.md :: pg-probe/arg-samples.ts",
|
||||
"server/CLAUDE.md :: pg-probe/recorder.ts",
|
||||
"server/CLAUDE.md :: protocol/envelope.ts",
|
||||
"server/CLAUDE.md :: protocol/output-contract.ts",
|
||||
"server/CLAUDE.md :: runtime/egress-policy.ts",
|
||||
"server/CLAUDE.md :: runtime/plugin-host-entry.ts",
|
||||
"wiki/Encryption-Key-Rotation.md :: scripts/migrate-encryption.ts",
|
||||
"wiki/Environment-Variables.md :: scripts/migrate-encryption.ts",
|
||||
"wiki/Environment-Variables.md :: templates/configmap.yaml",
|
||||
"wiki/Environment-Variables.md :: templates/secret.yaml",
|
||||
"wiki/Plugin-Development.md :: client/settings.html",
|
||||
"wiki/Plugin-Development.md :: server/index.js",
|
||||
"wiki/Plugin-Permissions.md :: docs/screenshot.png",
|
||||
"wiki/Plugin-Permissions.md :: server/index.js",
|
||||
"wiki/Plugin-Publishing.md :: docs/screenshot.png",
|
||||
"wiki/Plugin-Publishing.md :: schema/example-entry.json",
|
||||
"wiki/Plugin-Publishing.md :: schema/plugin-entry.schema.json",
|
||||
"wiki/Plugin-Publishing.md :: scripts/check-readme.mjs",
|
||||
"wiki/Plugin-Publishing.md :: scripts/validate-entry.mjs",
|
||||
"wiki/Plugin-Publishing.md :: server/index.js",
|
||||
"wiki/Plugins.md :: server/data/plugins",
|
||||
"wiki/Plugins.md :: server/data/travel.db"
|
||||
]
|
||||
@@ -0,0 +1,179 @@
|
||||
#!/usr/bin/env node
|
||||
// Every repository path a guide names in backticks has to exist.
|
||||
//
|
||||
// The CLAUDE.md files, the root README, the Nest module blueprint and the wiki
|
||||
// are what a contributor (or an agent) reads before touching the code, and a
|
||||
// path in them is an instruction: open this file, copy that module. When the
|
||||
// file has moved or died, the guide sends the reader to nothing, or worse, to
|
||||
// a recipe for a layer that no longer exists. So this reads each guide,
|
||||
// takes every inline code span that looks like a path into the repository and
|
||||
// checks it against the files git tracks.
|
||||
//
|
||||
// A span counts as a repository path when it has no spaces, globs,
|
||||
// placeholders or URL parts, holds a slash, does not start with `/`, `~` or
|
||||
// `@` (a route, a home path, a package name), and either ends in a file
|
||||
// extension or starts with a directory that exists from one of the bases it
|
||||
// is read against. A trailing `:line` or `:line-line` is ignored. The bases
|
||||
// are the repository root, the guide's own directory, its workspace
|
||||
// (`server/` for anything under server/) and that workspace's `src/`, so
|
||||
// `src/nest/README.md` in server/CLAUDE.md and `nest/database/unit-of-work.ts`
|
||||
// both resolve. Fenced code blocks are not read: they hold commands and
|
||||
// examples, not references.
|
||||
//
|
||||
// The paths that were already missing when the check came in are listed in
|
||||
// scripts/ci/doc-paths-baseline.json as "<guide> :: <path>". The list only
|
||||
// shrinks: a missing path outside it fails, and so does a listed one that
|
||||
// resolves now or whose guide is gone, until --update takes it off.
|
||||
//
|
||||
// node scripts/ci/doc-paths.mjs check against the baseline (CI)
|
||||
// node scripts/ci/doc-paths.mjs --update take resolved entries off the list;
|
||||
// it never adds one
|
||||
// node scripts/ci/doc-paths.mjs --list print every missing path
|
||||
//
|
||||
// It needs nothing but Node and git, so it runs in the changes job before
|
||||
// anything is installed.
|
||||
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { join, posix } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { fileList, lowerList, readBaseline, runCli, writeBaseline } from '../lib/ratchet.mjs';
|
||||
|
||||
export const WORKSPACES = ['client', 'server', 'shared', 'plugin-sdk'];
|
||||
|
||||
/** The guides the check reads, out of the tracked files. */
|
||||
export function guidesOf(tracked) {
|
||||
return [...tracked]
|
||||
.filter(
|
||||
(path) =>
|
||||
path === 'README.md' ||
|
||||
path === 'server/src/nest/README.md' ||
|
||||
posix.basename(path) === 'CLAUDE.md' ||
|
||||
/^wiki\/[^/]+\.md$/.test(path),
|
||||
)
|
||||
.sort();
|
||||
}
|
||||
|
||||
/** The inline code spans of a Markdown text, outside fenced code blocks. */
|
||||
export function inlineSpans(markdown) {
|
||||
const spans = [];
|
||||
let fence = null;
|
||||
for (const line of markdown.replace(/\r\n?/g, '\n').split('\n')) {
|
||||
const marker = /^\s*(`{3,}|~{3,})/.exec(line);
|
||||
if (marker) {
|
||||
if (!fence) fence = marker[1][0];
|
||||
else if (marker[1][0] === fence) fence = null;
|
||||
continue;
|
||||
}
|
||||
if (fence) continue;
|
||||
for (const match of line.matchAll(/(?<!`)`([^`\n]+)`(?!`)/g)) spans.push(match[1].trim());
|
||||
}
|
||||
return spans;
|
||||
}
|
||||
|
||||
const EXTENSION = /\.(?:md|ts|tsx|mts|cts|js|mjs|cjs|jsx|json|ya?ml|sh|css|sql|html|txt|toml|svg|png|webp)$/;
|
||||
|
||||
/** The directories a guide's relative paths are read against. */
|
||||
export function basesOf(guide) {
|
||||
const dir = posix.dirname(guide);
|
||||
const bases = new Set(['', dir === '.' ? '' : dir]);
|
||||
const workspace = guide.split('/')[0];
|
||||
if (WORKSPACES.includes(workspace)) {
|
||||
bases.add(workspace);
|
||||
bases.add(`${workspace}/src`);
|
||||
}
|
||||
return [...bases];
|
||||
}
|
||||
|
||||
const join2 = (base, path) => posix.normalize(base ? `${base}/${path}` : path).replace(/\/$/, '');
|
||||
|
||||
/**
|
||||
* The span as a repository path to check, or null when it is not one. exists
|
||||
* tells whether a path (file or directory, no trailing slash) is tracked.
|
||||
*/
|
||||
export function pathOf(span, bases, exists) {
|
||||
const path = span.replace(/:\d+(?:-\d+)?$/, '').replace(/[.,;]$/, '');
|
||||
if (!path.includes('/') || /[\s*?<>{}[\]$|=()'"\\,]/.test(path)) return null;
|
||||
if (/^[/~@]/.test(path) || path.includes('://') || /^[a-z]+:/i.test(path)) return null;
|
||||
const first = path.replace(/^(?:\.\.?\/)+/, '').split('/')[0];
|
||||
const fromKnownDir = bases.some((base) => exists(join2(base, first)));
|
||||
if (!EXTENSION.test(path) && !fromKnownDir) return null;
|
||||
return path;
|
||||
}
|
||||
|
||||
/** Module specifiers are often written without their extension (`api/client`). */
|
||||
const IMPLIED = ['', '.ts', '.tsx', '.js', '.mjs'];
|
||||
|
||||
/** Whether the path resolves from one of the bases, as written or as a module specifier. */
|
||||
export function resolves(path, bases, exists) {
|
||||
return bases.some((base) => IMPLIED.some((ext) => exists(join2(base, path) + ext)));
|
||||
}
|
||||
|
||||
/** The missing paths of every guide, as "<guide> :: <path>" entries. */
|
||||
export function missingPaths({ tracked, read }) {
|
||||
const files = new Set(tracked);
|
||||
const dirs = new Set();
|
||||
for (const file of files) {
|
||||
for (let at = file.indexOf('/'); at !== -1; at = file.indexOf('/', at + 1)) dirs.add(file.slice(0, at));
|
||||
}
|
||||
const exists = (path) => files.has(path) || dirs.has(path);
|
||||
const missing = new Set();
|
||||
for (const guide of guidesOf(files)) {
|
||||
const bases = basesOf(guide);
|
||||
for (const span of inlineSpans(read(guide))) {
|
||||
const path = pathOf(span, bases, exists);
|
||||
if (path && !resolves(path, bases, exists)) missing.add(`${guide} :: ${path}`);
|
||||
}
|
||||
}
|
||||
return [...missing].sort();
|
||||
}
|
||||
|
||||
/** Runs the check against the list at baselinePath and returns the exit code. */
|
||||
export function check({
|
||||
root,
|
||||
tracked,
|
||||
baselinePath = join(root, 'scripts/ci/doc-paths-baseline.json'),
|
||||
update = false,
|
||||
list = false,
|
||||
log = console.log,
|
||||
error = console.error,
|
||||
}) {
|
||||
const found = missingPaths({ tracked, read: (path) => readFileSync(join(root, path), 'utf8') });
|
||||
let baseline = readBaseline(baselinePath, fileList);
|
||||
if (update) {
|
||||
baseline = lowerList(baseline, found);
|
||||
writeBaseline(baselinePath, baseline);
|
||||
}
|
||||
const allowed = new Set(baseline);
|
||||
const now = new Set(found);
|
||||
const fresh = found.filter((entry) => !allowed.has(entry));
|
||||
const stale = baseline.filter((entry) => !now.has(entry));
|
||||
|
||||
if (list) for (const entry of found) log(`${allowed.has(entry) ? 'listed' : 'new '} ${entry}`);
|
||||
for (const entry of fresh) {
|
||||
const [guide, path] = entry.split(' :: ');
|
||||
error(`FAIL ${guide} names \`${path}\`, which does not exist. Point it at the file that does, or drop it.`);
|
||||
}
|
||||
for (const entry of stale) {
|
||||
error(`FAIL "${entry}" is listed in scripts/ci/doc-paths-baseline.json but resolves now or its guide is gone.`);
|
||||
}
|
||||
if (stale.length) error('Run node scripts/ci/doc-paths.mjs --update to take it off the list.');
|
||||
log(`doc-paths: ${found.length} missing path(s) in the guides, ${baseline.length} listed in the baseline`);
|
||||
return fresh.length || stale.length ? 1 : 0;
|
||||
}
|
||||
|
||||
function trackedFiles(root) {
|
||||
const out = execFileSync('git', ['-c', 'core.quotePath=false', 'ls-files', '-z'], {
|
||||
cwd: root,
|
||||
encoding: 'utf8',
|
||||
maxBuffer: 64 * 1024 * 1024,
|
||||
});
|
||||
return out.split('\0').filter(Boolean);
|
||||
}
|
||||
|
||||
if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
|
||||
const root = fileURLToPath(new URL('../..', import.meta.url));
|
||||
await runCli('doc-paths', (args) =>
|
||||
check({ root, tracked: trackedFiles(root), update: args.includes('--update'), list: args.includes('--list') }),
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,154 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { dirname, join } from 'node:path';
|
||||
import { afterEach, describe, it } from 'node:test';
|
||||
import { basesOf, check, guidesOf, inlineSpans, missingPaths, pathOf, resolves } from './doc-paths.mjs';
|
||||
|
||||
const TRACKED = [
|
||||
'CLAUDE.md',
|
||||
'README.md',
|
||||
'server/CLAUDE.md',
|
||||
'server/src/nest/README.md',
|
||||
'server/src/nest/weather/weather.service.ts',
|
||||
'server/src/nest/database/unit-of-work.ts',
|
||||
'server/src/config.ts',
|
||||
'server/tests/e2e/harness.ts',
|
||||
'client/src/api/client.ts',
|
||||
'.github/workflows/test.yml',
|
||||
'wiki/Home.md',
|
||||
'wiki/assets/a.png',
|
||||
'docs/other.md',
|
||||
];
|
||||
|
||||
const exists = (path) => {
|
||||
const files = new Set(TRACKED);
|
||||
return files.has(path) || TRACKED.some((file) => file.startsWith(`${path}/`));
|
||||
};
|
||||
|
||||
describe('doc-paths', () => {
|
||||
it('reads the CLAUDE.md files, the root README, the Nest blueprint and the top-level wiki pages', () => {
|
||||
assert.deepEqual(guidesOf([...TRACKED, 'wiki/sub/Deep.md', 'server/README.md']), [
|
||||
'CLAUDE.md',
|
||||
'README.md',
|
||||
'server/CLAUDE.md',
|
||||
'server/src/nest/README.md',
|
||||
'wiki/Home.md',
|
||||
]);
|
||||
});
|
||||
|
||||
it('takes inline code spans and skips fenced blocks of either kind', () => {
|
||||
const md = [
|
||||
'Open `server/src/config.ts` and `a b`.',
|
||||
'```bash',
|
||||
'cat `server/nope.ts`',
|
||||
'```',
|
||||
'~~~',
|
||||
'`server/also-nope.ts`',
|
||||
'~~~',
|
||||
'Then ``double`` and `client/src/api/client.ts`.',
|
||||
].join('\r\n');
|
||||
assert.deepEqual(inlineSpans(md), ['server/src/config.ts', 'a b', 'client/src/api/client.ts']);
|
||||
});
|
||||
|
||||
it('reads a relative path against the guide directory, its workspace and the workspace src', () => {
|
||||
assert.deepEqual(basesOf('server/src/nest/README.md'), ['', 'server/src/nest', 'server', 'server/src']);
|
||||
assert.deepEqual(basesOf('CLAUDE.md'), ['']);
|
||||
assert.deepEqual(basesOf('wiki/Home.md'), ['', 'wiki']);
|
||||
});
|
||||
|
||||
it('only treats a span as a path when it looks like one', () => {
|
||||
const bases = basesOf('server/CLAUDE.md');
|
||||
assert.equal(pathOf('src/nest/README.md', bases, exists), 'src/nest/README.md');
|
||||
assert.equal(pathOf('.github/workflows/test.yml:250-251', [''], exists), '.github/workflows/test.yml');
|
||||
assert.equal(pathOf('nest/database/unit-of-work.ts,', bases, exists), 'nest/database/unit-of-work.ts');
|
||||
assert.equal(pathOf('src/gone/', bases, exists), 'src/gone/');
|
||||
for (const span of [
|
||||
'weather.service.ts',
|
||||
'/api/health/ready',
|
||||
'~/.ssh/key',
|
||||
'@trek/shared',
|
||||
'https://example.com/a.md',
|
||||
'text/plain',
|
||||
'src/**/*.ts',
|
||||
'<domain>/<domain>.rpc.ts',
|
||||
'npm run lint',
|
||||
'a/{b,c}.ts',
|
||||
'C:/tmp/x.ts',
|
||||
]) {
|
||||
assert.equal(pathOf(span, bases, exists), null, span);
|
||||
}
|
||||
});
|
||||
|
||||
it('resolves a path as written or as a module specifier without its extension', () => {
|
||||
assert.equal(resolves('src/config', basesOf('server/CLAUDE.md'), exists), true);
|
||||
assert.equal(resolves('api/client', ['', 'client/src'], exists), true);
|
||||
assert.equal(resolves('weather/weather.service.ts', basesOf('server/src/nest/README.md'), exists), true);
|
||||
assert.equal(resolves('src/nope.ts', basesOf('server/CLAUDE.md'), exists), false);
|
||||
});
|
||||
|
||||
it('lists every missing path once per guide', () => {
|
||||
const texts = {
|
||||
'CLAUDE.md': 'See `server/src/config.ts`, `server/src/gone.ts` and again `server/src/gone.ts`.',
|
||||
'README.md': 'Nothing here.',
|
||||
'server/CLAUDE.md': 'Use `nest/database/unit-of-work.ts` and `tests/e2e/harness.ts`, not `db/migrations.ts`.',
|
||||
'server/src/nest/README.md': '`weather/weather.service.ts` and `src/services/`.',
|
||||
'wiki/Home.md': 'Pictures live in `assets/a.png`; plugins ship `server/index.js`.',
|
||||
};
|
||||
assert.deepEqual(missingPaths({ tracked: TRACKED, read: (path) => texts[path] }), [
|
||||
'CLAUDE.md :: server/src/gone.ts',
|
||||
'server/CLAUDE.md :: db/migrations.ts',
|
||||
'server/src/nest/README.md :: src/services/',
|
||||
'wiki/Home.md :: server/index.js',
|
||||
]);
|
||||
});
|
||||
|
||||
describe('check', () => {
|
||||
let root;
|
||||
afterEach(() => root && rmSync(root, { recursive: true, force: true }));
|
||||
|
||||
function tree(files, baseline) {
|
||||
root = mkdtempSync(join(tmpdir(), 'doc-paths-'));
|
||||
for (const [path, text] of Object.entries({ ...files, 'scripts/ci/doc-paths-baseline.json': JSON.stringify(baseline) })) {
|
||||
mkdirSync(dirname(join(root, path)), { recursive: true });
|
||||
writeFileSync(join(root, path), text);
|
||||
}
|
||||
const out = { log: [], error: [] };
|
||||
const run = (opts = {}) =>
|
||||
check({
|
||||
root,
|
||||
tracked: Object.keys(files),
|
||||
log: (l) => out.log.push(l),
|
||||
error: (l) => out.error.push(l),
|
||||
...opts,
|
||||
});
|
||||
return { out, run };
|
||||
}
|
||||
|
||||
it('passes when every missing path is listed, and fails a new one', () => {
|
||||
const listed = tree({ 'CLAUDE.md': '`server/a.ts`', 'server/b.ts': '' }, ['CLAUDE.md :: server/a.ts']);
|
||||
assert.equal(listed.run(), 0);
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
const fresh = tree({ 'CLAUDE.md': '`server/a.ts` `server/c.ts`', 'server/b.ts': '' }, ['CLAUDE.md :: server/a.ts']);
|
||||
assert.equal(fresh.run(), 1);
|
||||
assert.match(fresh.out.error.join('\n'), /CLAUDE\.md names `server\/c\.ts`, which does not exist/);
|
||||
});
|
||||
|
||||
it('fails a listed entry that resolves now until --update takes it off, and never adds one', () => {
|
||||
const t = tree({ 'CLAUDE.md': '`server/b.ts` `server/new.ts`', 'server/b.ts': '' }, ['CLAUDE.md :: server/b.ts']);
|
||||
assert.equal(t.run(), 1);
|
||||
assert.match(t.out.error.join('\n'), /"CLAUDE\.md :: server\/b\.ts" is listed .* resolves now/);
|
||||
assert.match(t.out.error.join('\n'), /--update/);
|
||||
assert.equal(t.run({ update: true }), 1);
|
||||
assert.deepEqual(JSON.parse(readFileSync(join(root, 'scripts/ci/doc-paths-baseline.json'), 'utf8')), []);
|
||||
});
|
||||
|
||||
it('prints every missing path with --list, and stops on a broken baseline', () => {
|
||||
const t = tree({ 'CLAUDE.md': '`server/a.ts`', 'server/b.ts': '' }, ['CLAUDE.md :: server/a.ts']);
|
||||
assert.equal(t.run({ list: true }), 0);
|
||||
assert.ok(t.out.log.includes('listed CLAUDE.md :: server/a.ts'));
|
||||
writeFileSync(join(root, 'scripts/ci/doc-paths-baseline.json'), '{');
|
||||
assert.throws(() => t.run(), /not valid JSON/);
|
||||
});
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user