feat(register): a decided title, and an org-profile that stops lying
Three changes at the register/engine boundary, all agreed with org-ops after census 05 and all about a check missing a place to record a legitimate exception. `titles`: an optional per-repo README title. Set, the H1 matches it and is OK; unset, the WARN stands as before. A human title was already this engine's stated position and rds-v1's prescription, but a decided YES had nowhere to live, so the same 6 WARNs were reported three censuses running and would have been reported forever. Five registered, each H1 read from the repo rather than copied from the census; `ai-psychosis` deliberately left out so the one repo where a reader cannot connect title to name stands alone. Measured across 21 local clones: 6 WARN before, 1 after, nothing else moved. `readme_desc_match: false` on the org-profile class: for an ordinary repo the README opening and the forge description describe the same subject and equality is right; for this class they do not — the README is the org's landing page, the forge text describes the repo. The equality is what does not apply, not either text. Class data, not a hardcoded name, and the exemption is RECORDED as an OK naming its reason, not dropped. `.profile` went ERROR to 0 ERROR / 0 WARN; the same README under a plugin class is still an ERROR. `engineCommit`: the version names a file, only the sha names the code. A sweep stamped 18 files 0.4.0 while four carried a 0.5.0-only finding — feature and version bump are two commits, so the stamp lied without being broken. Present-and-null when underivable, never absent: an absent key means an older engine, null means this one ran without a HEAD to read. 135 to 147 tests. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NELsvPY5gnJjN3esdhWYWC
This commit is contained in:
parent
a7276e6f78
commit
5884a64e54
8 changed files with 358 additions and 27 deletions
|
|
@ -37,6 +37,23 @@ export function readEngineVersion(path = PACKAGE_PATH) {
|
|||
return JSON.parse(readFileSync(path, 'utf8')).version;
|
||||
}
|
||||
|
||||
// The version names a FILE; only the sha names the CODE. A sweep once stamped
|
||||
// 18 raw files `0.4.0` while four of them carried findings from a check that
|
||||
// only exists in 0.5.0 — the feature and the version bump are two commits, so
|
||||
// the worktree held new code under an old number for a window. Derived from
|
||||
// this checkout, no network call; null outside a git checkout (a vendored copy
|
||||
// or a tarball has no HEAD, and that is not a crash).
|
||||
export function readEngineCommit(dir = join(HERE, '..')) {
|
||||
try {
|
||||
return execFileSync('git', ['-C', dir, 'rev-parse', 'HEAD'], {
|
||||
encoding: 'utf8',
|
||||
stdio: ['ignore', 'pipe', 'ignore'],
|
||||
}).trim() || null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
const LEVELS = ['OK', 'SKIP', 'WARN', 'ERROR'];
|
||||
|
||||
// Findings carry a level AND a bucket, and the two are independent axes.
|
||||
|
|
@ -189,7 +206,7 @@ export function checkDescription(description, register) {
|
|||
// The opening line makes description == catalog == README: the same thread on a
|
||||
// third surface, and the only one of the three a machine can check from inside
|
||||
// the repo.
|
||||
export function checkFirstScreen({ readme, name, description }) {
|
||||
export function checkFirstScreen({ readme, name, description, klass }, register) {
|
||||
const findings = [];
|
||||
const lines = String(readme ?? '').split('\n');
|
||||
const firstIdx = lines.findIndex((l) => l.trim() !== '');
|
||||
|
|
@ -211,15 +228,47 @@ export function checkFirstScreen({ readme, name, description }) {
|
|||
});
|
||||
return findings;
|
||||
}
|
||||
if (heading !== `# ${name}`) {
|
||||
|
||||
// A registered title is where that operator call gets WRITTEN DOWN. Without
|
||||
// one, the same WARN reappears every census and "we decided this is correct"
|
||||
// is indistinguishable from "nobody has looked". With one, the two separate —
|
||||
// and a repo whose title nobody has ruled on is left standing alone, which is
|
||||
// the wanted side effect, not a cost.
|
||||
const title = register?.titles?.[name];
|
||||
if (heading === `# ${name}`) {
|
||||
findings.push({ level: 'OK', code: 'README-H1', msg: `H1 is \`# ${name}\`` });
|
||||
} else if (title && heading === `# ${title}`) {
|
||||
findings.push({ level: 'OK', code: 'README-H1', msg: `H1 is \`# ${title}\` — the registered title for \`${name}\`` });
|
||||
} else if (title) {
|
||||
findings.push({
|
||||
level: 'WARN',
|
||||
code: 'README-H1',
|
||||
bucket: 'weakening',
|
||||
msg: `H1 is \`${heading}\`, not \`# ${name}\` — deliberate title, or drift? Operator's call.`,
|
||||
msg: `H1 is \`${heading}\`, which is neither \`# ${name}\` nor the registered title \`${title}\` — one of the two has drifted.`,
|
||||
});
|
||||
} else {
|
||||
findings.push({ level: 'OK', code: 'README-H1', msg: `H1 is \`# ${name}\`` });
|
||||
findings.push({
|
||||
level: 'WARN',
|
||||
code: 'README-H1',
|
||||
bucket: 'weakening',
|
||||
msg: `H1 is \`${heading}\`, not \`# ${name}\` — deliberate title, or drift? Operator's call. Record the decision as \`titles.${name}\` in the register.`,
|
||||
});
|
||||
}
|
||||
|
||||
// For an ordinary repo the README opening and the forge description describe
|
||||
// the SAME subject, and equality is the right demand. `org-profile` is the one
|
||||
// class where they do not: its README is the organisation's landing page and
|
||||
// the forge text describes the repo. Both are correct about their own subject,
|
||||
// so it is the EQUALITY that does not apply — and a landing page's opening
|
||||
// link could only ever match by putting raw markdown on a plain-text surface.
|
||||
// Class-level data, not a hardcoded name: class rules live in the register.
|
||||
if (register?.classes?.[klass]?.readme_desc_match === false) {
|
||||
findings.push({
|
||||
level: 'OK',
|
||||
code: 'README-DESC',
|
||||
msg: `class \`${klass}\` is exempt: the README describes the org, the forge description describes the repo — different subjects, so equality is not required`,
|
||||
});
|
||||
return findings;
|
||||
}
|
||||
|
||||
if (description === null || description === undefined) {
|
||||
|
|
@ -883,7 +932,7 @@ export function classifyRepo(
|
|||
const traits = register.traits?.[name] ?? [];
|
||||
const readme = (files ?? {})['README.md'] ?? '';
|
||||
const findings = [
|
||||
...checkFirstScreen({ readme, name, description }),
|
||||
...checkFirstScreen({ readme, name, description, klass }, register),
|
||||
...checkInstallBlock({ readme, name, klass }, register),
|
||||
...checkInstallTruth({ name, klass, catalogNames }),
|
||||
...checkHeadings({ readme, klass, traits }, register),
|
||||
|
|
@ -1106,19 +1155,23 @@ const BUCKET_TITLE = {
|
|||
// engine is visible, not just correctable in hindsight.
|
||||
const MARK = { OK: '✓', WARN: '!', ERROR: '✗', SKIP: '·' };
|
||||
|
||||
export function headerLine(result, engineVersion) {
|
||||
export function headerLine(result, engineVersion, engineCommit = null) {
|
||||
const klass = result.klass ? ` [${result.klass}]` : '';
|
||||
const traits = result.traits?.length ? ` {${result.traits.join(', ')}}` : '';
|
||||
return `${MARK[result.status]} ${result.name}${klass}${traits} — ${result.status} (repo-standard v${engineVersion})`;
|
||||
const sha = engineCommit ? ` @${String(engineCommit).slice(0, 7)}` : '';
|
||||
return `${MARK[result.status]} ${result.name}${klass}${traits} — ${result.status} (repo-standard v${engineVersion}${sha})`;
|
||||
}
|
||||
|
||||
export function withEngineVersion(result, engineVersion) {
|
||||
return { ...result, engineVersion };
|
||||
// `engineCommit` is always present, null when underivable: an ABSENT key means
|
||||
// an older engine, an explicit null means this engine ran and had no HEAD to
|
||||
// read. A consumer sorting raw files by stamp needs those to be different.
|
||||
export function withEngineVersion(result, engineVersion, engineCommit = null) {
|
||||
return { ...result, engineVersion, engineCommit };
|
||||
}
|
||||
|
||||
function render(result, engineVersion) {
|
||||
function render(result, engineVersion, engineCommit) {
|
||||
const mark = MARK;
|
||||
console.log(`\n${headerLine(result, engineVersion)}`);
|
||||
console.log(`\n${headerLine(result, engineVersion, engineCommit)}`);
|
||||
|
||||
for (const bucket of BUCKETS) {
|
||||
const inBucket = result.findings.filter((f) => f.bucket === bucket);
|
||||
|
|
@ -1182,11 +1235,12 @@ async function main(argv) {
|
|||
|
||||
const result = inspectRepo(dir, name, register, description, catalogNames);
|
||||
const engineVersion = readEngineVersion();
|
||||
const engineCommit = readEngineCommit();
|
||||
|
||||
if (argv.includes('--json')) {
|
||||
console.log(JSON.stringify(withEngineVersion(result, engineVersion), null, 2));
|
||||
console.log(JSON.stringify(withEngineVersion(result, engineVersion, engineCommit), null, 2));
|
||||
} else {
|
||||
render(result, engineVersion);
|
||||
render(result, engineVersion, engineCommit);
|
||||
}
|
||||
process.exit(result.status === 'ERROR' ? 1 : 0);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -33,6 +33,7 @@ import {
|
|||
fetchWithRetry,
|
||||
headerLine,
|
||||
withEngineVersion,
|
||||
readEngineCommit,
|
||||
loadRegister,
|
||||
} from './repo-standard-check.mjs';
|
||||
|
||||
|
|
@ -69,9 +70,12 @@ const REGISTER = {
|
|||
install: 'catalog',
|
||||
},
|
||||
'shared-asset': { required_files: ['README.md', 'LICENSE'], required_headings: ['## Non-goals'], install: 'vendor' },
|
||||
'org-profile': { required_files: ['README.md'], required_headings: [], install: 'none' },
|
||||
'org-profile': { required_files: ['README.md'], required_headings: [], install: 'none', readme_desc_match: false },
|
||||
standalone: { required_files: ['README.md', 'LICENSE'], required_headings: ['## Install', '## Non-goals'], install: 'package' },
|
||||
},
|
||||
titles: {
|
||||
'llm-security': 'LLM Security Plugin for Claude Code',
|
||||
},
|
||||
traits: {
|
||||
'llm-security': ['security'],
|
||||
'llm-ingestion-pipeline-security': ['security'],
|
||||
|
|
@ -306,7 +310,7 @@ test('an unavailable description is SKIP, never a pass', () => {
|
|||
test('README line 1 must be the H1, and the description line must match the forge', () => {
|
||||
const readme = '# repo-mailbox\nA local mailbox for coordination.\n';
|
||||
assert.equal(
|
||||
checkFirstScreen({ readme, name: 'repo-mailbox', description: 'A local mailbox for coordination.' })
|
||||
checkFirstScreen({ readme, name: 'repo-mailbox', description: 'A local mailbox for coordination.' }, REGISTER)
|
||||
.every((f) => f.level === 'OK'),
|
||||
true,
|
||||
);
|
||||
|
|
@ -314,17 +318,17 @@ test('README line 1 must be the H1, and the description line must match the forg
|
|||
|
||||
test('a README whose opening line diverges from the description is an ERROR', () => {
|
||||
const readme = '# repo-mailbox\nSomething else entirely.\n';
|
||||
const f = checkFirstScreen({ readme, name: 'repo-mailbox', description: 'A local mailbox for coordination.' });
|
||||
const f = checkFirstScreen({ readme, name: 'repo-mailbox', description: 'A local mailbox for coordination.' }, REGISTER);
|
||||
assert.equal(f.some((x) => x.level === 'ERROR' && x.code === 'README-DESC'), true);
|
||||
});
|
||||
|
||||
test('first-screen description match is SKIP when the forge text is unavailable', () => {
|
||||
const f = checkFirstScreen({ readme: '# x\nbody\n', name: 'x', description: null });
|
||||
const f = checkFirstScreen({ readme: '# x\nbody\n', name: 'x', description: null }, REGISTER);
|
||||
assert.equal(f.some((x) => x.code === 'README-DESC' && x.level === 'SKIP'), true);
|
||||
});
|
||||
|
||||
test('a missing H1 is an ERROR', () => {
|
||||
const f = checkFirstScreen({ readme: 'no heading here\n', name: 'x', description: null });
|
||||
const f = checkFirstScreen({ readme: 'no heading here\n', name: 'x', description: null }, REGISTER);
|
||||
assert.equal(f.some((x) => x.level === 'ERROR' && x.code === 'README-H1'), true);
|
||||
});
|
||||
|
||||
|
|
@ -332,16 +336,84 @@ test('an H1 that differs from the repo name is a WARN, not a failure', () => {
|
|||
// `# OKR for Public Sector` is a naming choice, not a defect: the thread that
|
||||
// must hold is description == catalog == opening line, and the H1 is none of
|
||||
// those three. Surface it; let the operator decide.
|
||||
const f = checkFirstScreen({ readme: '# OKR for Public Sector\nbody\n', name: 'okr', description: null });
|
||||
const f = checkFirstScreen({ readme: '# OKR for Public Sector\nbody\n', name: 'okr', description: null }, REGISTER);
|
||||
assert.equal(f.some((x) => x.level === 'WARN' && x.code === 'README-H1'), true);
|
||||
assert.equal(f.some((x) => x.level === 'ERROR'), false);
|
||||
});
|
||||
|
||||
test('a differing H1 does not stop the description check from running', () => {
|
||||
const f = checkFirstScreen({ readme: '# Nice Title\nthe description\n', name: 'x', description: 'the description' });
|
||||
const f = checkFirstScreen({ readme: '# Nice Title\nthe description\n', name: 'x', description: 'the description' }, REGISTER);
|
||||
assert.equal(f.some((x) => x.code === 'README-DESC' && x.level === 'OK'), true);
|
||||
});
|
||||
|
||||
// ------------------------------------------------- registered README titles
|
||||
// Census 05 measured the same 6 README-H1 WARNs three rounds running, because
|
||||
// a decided YES had nowhere to live. `titles` is that place: with an entry the
|
||||
// H1 is OK, without one it WARNs exactly as before — so "we decided this" and
|
||||
// "nobody has looked at it" stop sharing one outcome. The wanted side effect is
|
||||
// that a repo nobody has ruled on stands alone once the others are registered.
|
||||
|
||||
test('an H1 matching the registered title is OK, not a WARN', () => {
|
||||
const readme = '# LLM Security Plugin for Claude Code\nbody\n';
|
||||
const f = checkFirstScreen({ readme, name: 'llm-security', description: null }, REGISTER);
|
||||
assert.equal(f.some((x) => x.code === 'README-H1' && x.level === 'OK'), true);
|
||||
assert.equal(f.some((x) => x.code === 'README-H1' && x.level === 'WARN'), false);
|
||||
});
|
||||
|
||||
test('a repo with no registered title still WARNs — deciding and not looking stay different outcomes', () => {
|
||||
const f = checkFirstScreen({ readme: '# Interaction Awareness\nbody\n', name: 'repo-mailbox', description: null }, REGISTER);
|
||||
assert.equal(f.some((x) => x.code === 'README-H1' && x.level === 'WARN'), true);
|
||||
});
|
||||
|
||||
test('an H1 matching neither the name nor the registered title WARNs, and the message names both', () => {
|
||||
const f = checkFirstScreen({ readme: '# Something Drifted\nbody\n', name: 'llm-security', description: null }, REGISTER);
|
||||
const warn = f.find((x) => x.code === 'README-H1' && x.level === 'WARN');
|
||||
assert.ok(warn, 'expected a README-H1 WARN');
|
||||
assert.match(warn.msg, /Something Drifted/);
|
||||
assert.match(warn.msg, /LLM Security Plugin for Claude Code/);
|
||||
});
|
||||
|
||||
test('the repo name still passes when a title is registered — both spellings are accepted', () => {
|
||||
const f = checkFirstScreen({ readme: '# llm-security\nbody\n', name: 'llm-security', description: null }, REGISTER);
|
||||
assert.equal(f.some((x) => x.code === 'README-H1' && x.level === 'OK'), true);
|
||||
});
|
||||
|
||||
// --------------------------------------------- org-profile README-DESC exemption
|
||||
// For an ordinary repo the README opening and the forge description describe the
|
||||
// SAME subject, and equality is the right demand. For `org-profile` they do not:
|
||||
// the README is the organisation's landing page, the forge description describes
|
||||
// the repo. Both texts are correct about their own subject. The description field
|
||||
// also renders as PLAIN TEXT, so a landing page's opening link could only ever
|
||||
// match by putting raw markdown on a real surface.
|
||||
const PROFILE_README = '# .profile\nCompanion repos, plugins, and tools for [From AI to Chitta](https://fromaitochitta.com).\n';
|
||||
|
||||
test('org-profile is exempt from the README-DESC equality check', () => {
|
||||
const f = checkFirstScreen(
|
||||
{ readme: PROFILE_README, name: '.profile', klass: 'org-profile', description: 'Organization profile and navigation for the open org.' },
|
||||
REGISTER,
|
||||
);
|
||||
const desc = f.find((x) => x.code === 'README-DESC');
|
||||
assert.ok(desc, 'expected a README-DESC finding — an exemption must still be recorded');
|
||||
assert.equal(desc.level, 'OK');
|
||||
assert.equal(f.some((x) => x.level === 'ERROR'), false);
|
||||
});
|
||||
|
||||
test('the exemption is per class, not global — the same README under a plugin class is still an ERROR', () => {
|
||||
const f = checkFirstScreen(
|
||||
{ readme: PROFILE_README, name: 'llm-security', klass: 'plugin', description: 'Organization profile and navigation for the open org.' },
|
||||
REGISTER,
|
||||
);
|
||||
assert.equal(f.some((x) => x.code === 'README-DESC' && x.level === 'ERROR'), true);
|
||||
});
|
||||
|
||||
test('the exemption does not silence the H1 check for org-profile', () => {
|
||||
const f = checkFirstScreen(
|
||||
{ readme: 'no heading here\n', name: '.profile', klass: 'org-profile', description: 'anything' },
|
||||
REGISTER,
|
||||
);
|
||||
assert.equal(f.some((x) => x.code === 'README-H1' && x.level === 'ERROR'), true);
|
||||
});
|
||||
|
||||
// ------------------------------------------------------------ install block
|
||||
|
||||
const MKT = REGISTER.marketplace;
|
||||
|
|
@ -1390,3 +1462,44 @@ test('withEngineVersion adds the version without disturbing existing fields', ()
|
|||
assert.equal(stamped.status, 'OK');
|
||||
assert.deepEqual(result, { name: 'x', klass: 'plugin', status: 'OK', findings: [] });
|
||||
});
|
||||
|
||||
// ---------------------------------------------------- engine commit stamp
|
||||
// Measured 2026-08-09 by org-ops: a sweep stamped 18 raw files `0.4.0`, and
|
||||
// four of them carried findings from a check that only exists in 0.5.0. The
|
||||
// stamp lied without being broken — `9eb210b` (the feature) and `63c75d8` (the
|
||||
// version bump) are TWO commits, so the worktree held new code under an old
|
||||
// number for a window. The version names a FILE; only the sha names the CODE,
|
||||
// and the bump is by definition a different commit from the change it describes.
|
||||
|
||||
test('headerLine names the engine commit alongside the version', () => {
|
||||
const line = headerLine({ name: 'voyage', klass: 'plugin', traits: [], status: 'OK' }, '0.5.0', 'a7276e6f0d1e2b3c');
|
||||
assert.match(line, /0\.5\.0/);
|
||||
assert.match(line, /a7276e6/);
|
||||
});
|
||||
|
||||
test('headerLine falls back to the version alone when the commit is underivable', () => {
|
||||
const line = headerLine({ name: 'voyage', klass: 'plugin', traits: [], status: 'OK' }, '0.5.0', null);
|
||||
assert.match(line, /0\.5\.0/);
|
||||
assert.doesNotMatch(line, /null|undefined/);
|
||||
});
|
||||
|
||||
test('withEngineVersion stamps the commit next to the version', () => {
|
||||
const stamped = withEngineVersion({ name: 'x', status: 'OK', findings: [] }, '0.5.0', 'a7276e6f0d1e2b3c');
|
||||
assert.equal(stamped.engineVersion, '0.5.0');
|
||||
assert.equal(stamped.engineCommit, 'a7276e6f0d1e2b3c');
|
||||
});
|
||||
|
||||
test('engineCommit is present-and-null when underivable, never absent', () => {
|
||||
// An ABSENT key means an older engine; an explicit null means this engine ran
|
||||
// and could not derive the sha. A consumer sorting raw files by stamp needs
|
||||
// those two to be different, which is the whole point of the field.
|
||||
const stamped = withEngineVersion({ name: 'x', status: 'OK', findings: [] }, '0.5.0', null);
|
||||
assert.equal(Object.hasOwn(stamped, 'engineCommit'), true);
|
||||
assert.equal(stamped.engineCommit, null);
|
||||
});
|
||||
|
||||
test('readEngineCommit returns null outside a git checkout instead of throwing', () => {
|
||||
// Derived from the engine's own checkout with no network call. A consumer of
|
||||
// a tarball or a vendored copy has no HEAD, and that is not a crash.
|
||||
assert.equal(readEngineCommit('/nonexistent-path-for-repo-standard-test'), null);
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue