diff --git a/.agents/skills/release-workflow/SKILL.md b/.agents/skills/release-workflow/SKILL.md index bd75544..3442d6d 100644 --- a/.agents/skills/release-workflow/SKILL.md +++ b/.agents/skills/release-workflow/SKILL.md @@ -181,6 +181,29 @@ assembled specification is explicitly assigned to a script or CI closure because exact artifact selections run in separate jobs. Reusable test contracts with assertions belong in their actual tier; support holds fixture setup and executable fixture programs. Tier scripts run the complete tier directory directly; an individual-file selector does not qualify. When CI partitions cases with name filters, every static registered case must match exactly one nonempty partition. Missing, overlapping or malformed partitions fail verification. +## Mandatory: Readable Capability Layers and Contextual Refactoring + +Follow AGENTS.md's critical readable-capability-layer rule. New or changed executable methods, +constructors and accessors have at most 20 canonically formatted body lines; declarative schemas +and data are outside that behavioral count. Keep classes cohesive and orchestration as named +capability calls. Refactor affected behavior and its immediate responsibility boundary when touched; +a directed cleanup/refinement audits and refactors its stated scope. Never compress statements, +introduce trivial wrappers or move complexity to evade the rule. + +Run `bun .agents/skills/release-workflow/scripts/source-readability.ts` in normal owner checks and +CI with pinned `prettier@3.6.2`. The first policy baseline records only violations in the verified +`origin/cordis` commit, not unmerged drafts. Baseline source fingerprints preserve unchanged debt; +a changed method cannot gain a new baseline entry. Exceptions in `.readability.json` identify the +exact file/symbol/fingerprint, a concrete reason and owning issue; review them with the PR. Stale +or unused entries fail. Preserve the baseline provenance; it cannot advance to grandfather new +work. The check validates original Git blobs, so CI must retain full Git history and the integration +reference. Setup-only future initialization copies the helper without installing dependencies; +the first implementation wires it. + +Review checklist: readable capability orchestration; contextual refactoring completed; method gate +passed; every exception justified and reviewed; no baseline additions; no artificial class splitting. +These helpers are development only, never runtime dependencies on AGENTS.md or private target rules. + ## ⚠️ MANDATORY: Testing Tiers and the Composition Root Outside-in testing only works if the **outer** rung exists. Unit tests of injected, isolated diff --git a/.agents/skills/release-workflow/scripts/source-readability.ts b/.agents/skills/release-workflow/scripts/source-readability.ts new file mode 100644 index 0000000..8e072ea --- /dev/null +++ b/.agents/skills/release-workflow/scripts/source-readability.ts @@ -0,0 +1,345 @@ +import ts from 'typescript'; +import { format, version } from 'prettier'; +import { createHash } from 'node:crypto'; +import { existsSync, lstatSync, readFileSync, writeFileSync } from 'node:fs'; +import { resolve, join } from 'node:path'; +import { execFileSync } from 'node:child_process'; + +interface Identity { file: string; symbol: string; fingerprint: string; } +interface Method extends Identity { lines: number; compressed: boolean; } +interface Exception extends Identity { reason: string; issue: number; } +interface Policy { formatVersion: 1; baselineCommit: string; violations: Identity[]; exceptions: Exception[]; } +interface Report { success: boolean; errors: string[]; violations: Method[]; } +interface Options { root: string; capture: string | null; json: boolean; } + +class GitSource { + constructor(readonly root: string) {} + + run(args: string[]): string { + return execFileSync('git', args, { cwd: this.root, encoding: 'utf8', + maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] }).trimEnd(); + } + + integration(): string { return this.run(['rev-parse', 'refs/remotes/origin/cordis']); } + source(commit: string, file: string): string { return this.run(['show', commit + ':' + file]); } + tree(commit: string): string[] { return this.run(['ls-tree', '-r', '--name-only', commit]).split('\n'); } + + files(): string[] { + return this.run(['ls-files', '--cached', '--others', '--exclude-standard', '-z']).split('\0'); + } + + ancestor(commit: string, integration: string): void { + this.run(['merge-base', '--is-ancestor', commit, integration]); + } + + storedPolicy(commit: string): Policy | null { + if (!this.tree(commit).includes('.readability.json')) return null; + return PolicyFile.parse(this.source(commit, '.readability.json')); + } +} + +class MethodSyntax { + static body(node: ts.Node): ts.Block | undefined { + if (ts.isMethodDeclaration(node) || ts.isConstructorDeclaration(node) || + ts.isGetAccessor(node) || ts.isSetAccessor(node)) return node.body; + return undefined; + } + + static className(node: ts.Node): string { + const names: string[] = []; + for (let parent = node.parent; parent; parent = parent.parent) { + if (ts.isClassDeclaration(parent) || ts.isClassExpression(parent)) { + names.unshift(parent.name?.text ?? ''); + } + } + return names.join('.'); + } + + static symbol(node: ts.Node): string { + const named = node as ts.MethodDeclaration; + const name = ts.isConstructorDeclaration(node) ? 'constructor' : named.name.getText(); + const kind = ts.isGetAccessor(node) ? 'get ' : ts.isSetAccessor(node) ? 'set ' : ''; + const scope = ts.getCombinedModifierFlags(named) & ts.ModifierFlags.Static ? 'static ' : ''; + return this.className(node) + '.' + scope + kind + name; + } + + static fingerprint(node: ts.Node): string { + return createHash('sha256').update(node.getText()).digest('hex'); + } + + static line(source: ts.SourceFile, position: number): number { + return source.getLineAndCharacterOfPosition(position).line; + } + + static lines(body: ts.Block, source: ts.SourceFile): number { + const text = source.text.slice(body.getStart(source) + 1, body.end - 1); + const scanner = ts.createScanner(ts.ScriptTarget.Latest, true, ts.LanguageVariant.Standard, text); + const lines = new Set(); + let token = scanner.scan(); + while (token !== ts.SyntaxKind.EndOfFileToken) { + const start = scanner.getTokenPos(); + const end = scanner.getTextPos(); + for (let index = start; index < end; index++) { + if (!/\s/.test(text[index]!)) { + lines.add(this.line(source, body.getStart(source) + 1 + index)); + } + } + token = scanner.scan(); + } + return lines.size; + } +} + +class CompressedSyntax { + private compressed = false; + constructor(private readonly source: ts.SourceFile) {} + + inspect(body: ts.Block): boolean { + this.compressed = false; + this.visit(body); + return this.compressed; + } + + private visit(node: ts.Node): void { + if (ts.isBlock(node)) this.statements(node.statements); + if (ts.isVariableDeclarationList(node) && node.declarations.length > 1) { + this.statements(node.declarations); + } + if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.CommaToken) { + this.compressed = true; + } + ts.forEachChild(node, this.visit.bind(this)); + } + + private statements(nodes: readonly ts.Node[]): void { + for (let index = 1; index < nodes.length; index++) { + const prior = nodes[index - 1]!; + const next = nodes[index]!; + if (MethodSyntax.line(this.source, prior.end - 1) === + MethodSyntax.line(this.source, next.getStart(this.source))) this.compressed = true; + } + } +} + +class MethodCollector { + readonly methods: Method[] = []; + constructor(private readonly file: string, private readonly source: ts.SourceFile) {} + + collect(): Method[] { + this.visit(this.source); + return this.methods; + } + + private visit(node: ts.Node): void { + const body = MethodSyntax.body(node); + if (body) this.methods.push({ file: this.file, symbol: MethodSyntax.symbol(node), + fingerprint: MethodSyntax.fingerprint(node), lines: MethodSyntax.lines(body, this.source), + compressed: new CompressedSyntax(this.source).inspect(body) }); + ts.forEachChild(node, this.visit.bind(this)); + } +} + +class SourceMethods { + static accepted(file: string): boolean { + if (!/\.(?:[cm]?ts|tsx)$/.test(file)) return false; + if (file.startsWith('.agents/')) { + return file.startsWith('.agents/skills/release-workflow/scripts/'); + } + return !/^(?:node_modules|dist|vendor|\.git|\.codegraph)\//.test(file); + } + + static parse(file: string, source: string): Method[] { + const parsed = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true); + return new MethodCollector(file, parsed).collect(); + } + + static async inspect(file: string, source: string): Promise { + if (version !== '3.6.2') throw new Error('CANONICAL_FORMATTER_VERSION'); + const original = this.parse(file, source); + const canonical = await format(source, { parser: 'typescript', filepath: file, + printWidth: 100, tabWidth: 2, singleQuote: true, semi: true, trailingComma: 'all' }); + const formatted = this.parse(file, canonical); + if (formatted.length !== original.length) throw new Error('CANONICAL_METHOD_MISMATCH'); + for (let index = 0; index < original.length; index++) original[index]!.lines = formatted[index]!.lines; + return original; + } + + static violating(method: Method): boolean { return method.lines > 20 || method.compressed; } + static identity(method: Identity): Identity { + return { file: method.file, symbol: method.symbol, fingerprint: method.fingerprint }; + } + static key(method: Identity): string { return JSON.stringify(this.identity(method)); } +} + +class PolicyFile { + static parse(source: string): Policy { + const value = JSON.parse(source) as Policy; + if (value.formatVersion !== 1 || !/^[a-f0-9]{40}$/.test(value.baselineCommit) || + !Array.isArray(value.violations) || !Array.isArray(value.exceptions)) { + throw new Error('INVALID_READABILITY_POLICY'); + } + return value; + } + + static baseline(policy: Policy): string { + return JSON.stringify({ baselineCommit: policy.baselineCommit, violations: policy.violations }); + } + + static write(root: string, policy: Policy): void { + writeFileSync(join(root, '.readability.json'), JSON.stringify(policy, null, 2) + '\n', { flag: 'wx' }); + } +} + +class Baseline { + constructor(private readonly git: GitSource) {} + + async inventory(commit: string): Promise { + const inventory: Identity[] = []; + for (const file of this.git.tree(commit).sort()) { + if (!SourceMethods.accepted(file)) continue; + const methods = await SourceMethods.inspect(file, this.git.source(commit, file)); + for (const method of methods) { + if (SourceMethods.violating(method)) inventory.push(SourceMethods.identity(method)); + } + } + return inventory; + } + + async capture(commit: string): Promise { + if (commit !== this.git.integration()) throw new Error('BASELINE_MUST_MATCH_ORIGIN_CORDIS'); + const violations = await this.inventory(commit); + PolicyFile.write(this.git.root, { formatVersion: 1, baselineCommit: commit, violations, exceptions: [] }); + } + + async verify(policy: Policy): Promise { + const integration = this.git.integration(); + this.git.ancestor(policy.baselineCommit, integration); + const stored = this.git.storedPolicy(integration); + if (stored && PolicyFile.baseline(stored) !== PolicyFile.baseline(policy)) { + throw new Error('BASELINE_PROVENANCE_CHANGED'); + } + if (!stored && policy.baselineCommit !== integration) throw new Error('BASELINE_PROVENANCE_CHANGED'); + const expected = await this.inventory(policy.baselineCommit); + if (JSON.stringify(expected) !== JSON.stringify(policy.violations)) throw new Error('BASELINE_MISMATCH'); + } +} + +class Exceptions { + private readonly used = new Set(); + constructor(private readonly values: Exception[]) { this.validate(); } + + private validate(): void { + const identities = new Set(); + for (const value of this.values) { + const key = SourceMethods.key(value); + if (identities.has(key) || !Number.isSafeInteger(value.issue) || value.issue < 1 || + typeof value.reason !== 'string' || value.reason.trim().length < 20) { + throw new Error('INVALID_READABILITY_EXCEPTION'); + } + identities.add(key); + } + } + + accept(method: Method): boolean { + for (const value of this.values) { + if (SourceMethods.key(value) === SourceMethods.key(method)) { + this.used.add(value); + return true; + } + } + return false; + } + + finish(errors: string[]): void { + for (const value of this.values) { + if (!this.used.has(value)) errors.push('STALE_EXCEPTION: ' + value.file + ':' + value.symbol); + } + } +} + +class WorkingSource { + constructor(private readonly git: GitSource) {} + + async methods(): Promise { + const methods: Method[] = []; + for (const file of [...new Set(this.git.files())].sort()) { + if (!SourceMethods.accepted(file)) continue; + const path = join(this.git.root, file); + if (!existsSync(path)) continue; + if (!lstatSync(path).isFile()) throw new Error('SOURCE_SYMLINK_OR_NONFILE: ' + file); + methods.push(...await SourceMethods.inspect(file, readFileSync(path, 'utf8'))); + } + return methods; + } +} + +class ReadabilityCheck { + constructor(private readonly git: GitSource) {} + + async run(): Promise { + const policy = PolicyFile.parse(readFileSync(join(this.git.root, '.readability.json'), 'utf8')); + await new Baseline(this.git).verify(policy); + const grandfathered = new Set(); + for (const method of policy.violations) grandfathered.add(SourceMethods.key(method)); + const exceptions = new Exceptions(policy.exceptions); + const errors: string[] = []; + const violations: Method[] = []; + for (const method of await new WorkingSource(this.git).methods()) { + if (!SourceMethods.violating(method) || grandfathered.has(SourceMethods.key(method))) continue; + violations.push(method); + this.errors(method, exceptions, errors); + } + exceptions.finish(errors); + return { success: errors.length === 0, errors, violations }; + } + + private errors(method: Method, exceptions: Exceptions, errors: string[]): void { + const location = method.file + ':' + method.symbol; + if (method.lines > 20 && !exceptions.accept(method)) { + errors.push('METHOD_LENGTH: ' + location + ' has ' + method.lines + ' body lines'); + } + if (method.compressed) errors.push('COMPRESSED_STATEMENTS: ' + location); + } +} + +class ReadabilityArguments { + static parse(args: string[]): Options { + const options: Options = { root: process.cwd(), capture: null, json: false }; + const seen = new Set(); + for (let index = 0; index < args.length; index++) { + const flag = args[index]!; + if (seen.has(flag)) throw new Error('INVALID_ARGUMENTS'); + seen.add(flag); + if (flag === '--json') options.json = true; + else if (flag === '--root' && args[index + 1]) options.root = resolve(args[++index]!); + else if (flag === '--capture' && /^[a-f0-9]{40}$/.test(args[index + 1] ?? '')) { + options.capture = args[++index]!; + } else throw new Error('INVALID_ARGUMENTS'); + } + return options; + } +} + +class ReadabilityProgram { + static async run(): Promise { + let json = process.argv.includes('--json'); + try { + const options = ReadabilityArguments.parse(process.argv.slice(2)); + json = options.json; + const git = new GitSource(options.root); + if (options.capture) return await new Baseline(git).capture(options.capture); + this.output(await new ReadabilityCheck(git).run(), json); + } catch (error) { + const message = error instanceof Error ? error.message : 'READABILITY_CHECK_FAILED'; + this.output({ success: false, errors: [message], violations: [] }, json); + } + } + + private static output(report: Report, json: boolean): void { + if (json) process.stdout.write(JSON.stringify(report) + '\n'); + else if (!report.success) process.stderr.write(report.errors.join('\n') + '\n'); + if (!report.success) process.exitCode = 1; + } +} + +if (import.meta.main) await ReadabilityProgram.run(); diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml index 67e0897..dfbf8ae 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/verify.yml @@ -32,6 +32,8 @@ jobs: CORDIS_REQUIRE_PLAN: '1' steps: - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 + with: + fetch-depth: 0 - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 with: bun-version: 1.4.4 diff --git a/.readability.json b/.readability.json new file mode 100644 index 0000000..09ec91d --- /dev/null +++ b/.readability.json @@ -0,0 +1,407 @@ +{ + "formatVersion": 1, + "baselineCommit": "7225330dd8d78a6953849886fa873b5ba0216a1f", + "violations": [ + { + "file": ".agents/skills/release-workflow/scripts/test-layout.ts", + "symbol": "TestLayout.inspect", + "fingerprint": "bfff01a3fe612610a72c2bcc0f00c92fdb5abbe557d2b876614a24990d557a0c" + }, + { + "file": ".agents/skills/release-workflow/scripts/test-layout.ts", + "symbol": "TestLayout.check", + "fingerprint": "aec11cb99ea6438078fa6cbf353bbf8c4b5f5803a1e0102c86b725180f20e669" + }, + { + "file": ".agents/skills/release-workflow/scripts/test-layout.ts", + "symbol": "TestLayout.discovery", + "fingerprint": "771becf2a0f493fa9ee054d98379140581968b2134e1ccfd778ac1618eb4074b" + }, + { + "file": ".agents/skills/release-workflow/scripts/test-layout.ts", + "symbol": "TestLayout.partitions", + "fingerprint": "95cef1faa4182536c0be52904c7525d3ed245bac04f22d969ea73307ef0fa2bd" + }, + { + "file": ".agents/skills/release-workflow/scripts/test-layout.ts", + "symbol": "TestLayout.directory", + "fingerprint": "fb2f15a07b290e17c566adedf0e37dd7b4093a59a6085ebbf4f787474f6adb0a" + }, + { + "file": ".agents/skills/release-workflow/scripts/test-layout.ts", + "symbol": "TestRegistrationVisitor.inspect", + "fingerprint": "ccbfb614b5e447bf0eb3230ba9a80b6a369bae7ec130ef5e134c087a2d0c7058" + }, + { + "file": ".agents/skills/release-workflow/scripts/test-layout.ts", + "symbol": "TestRegistrationVisitor.visit", + "fingerprint": "8740012694378c96522cedfa0f69377ee1f26c18d316baaee9050fcb4d6e752d" + }, + { + "file": ".agents/skills/release-workflow/scripts/test-layout.ts", + "symbol": "TestRegistrationVisitor.test", + "fingerprint": "facc0ab411b33f7d001b6f8e5852eebf4ff02716394b318b20ec046794e30fe1" + }, + { + "file": "scripts/build-cli.ts", + "symbol": "CliBuild.static run", + "fingerprint": "b204ac0f3e040a37e6323df25148031e53c5625531bcf3cc54be6f66ef6cbb2c" + }, + { + "file": "src/main.ts", + "symbol": "CliArguments.static plan", + "fingerprint": "9896e7907d86155e23cecab04a30bbb98a2b402a1660dee14bd949bc70f97558" + }, + { + "file": "src/main.ts", + "symbol": "CliArguments.static installed", + "fingerprint": "ad62ce51b4f7a20f0845b99b28fc11ccaf1b3ed3849895e001453885fa16b757" + }, + { + "file": "src/main.ts", + "symbol": "CliArguments.static doctor", + "fingerprint": "08b977260660e131c8e3330256eb53c6563dc1c1cc5c0d8d8b5d07ed14ff3bf7" + }, + { + "file": "src/main.ts", + "symbol": "ConfigurationFile.property", + "fingerprint": "d6c47f58fa55ef31148a6b38605ce61dab9f9268f4e50e9b085691d52a8eede3" + }, + { + "file": "src/main.ts", + "symbol": "ConfigurationFile.value", + "fingerprint": "770f623d67da32f3cde8263ecf193b89b8c2755ee34bb8259ff058e298d5448b" + }, + { + "file": "src/main.ts", + "symbol": "ConfigurationFile.read", + "fingerprint": "6119b9d6f71ab13821dbcada322bcee251d4ddba35303e3c54e37a1e84cf504d" + }, + { + "file": "src/main.ts", + "symbol": "ConfigurationFile.object", + "fingerprint": "4c47f7499b8e2332eb1b276087295cde7e278f06700997e79f1b3b6cb4ab5e52" + }, + { + "file": "src/main.ts", + "symbol": "CliCommands.execute", + "fingerprint": "98528d5aa3a3a47759e2376a32a97b477ea47cc59a941f406e777e3aa39fce44" + }, + { + "file": "src/main.ts", + "symbol": "TerminalPresentation.render", + "fingerprint": "ddc3d1087c3f5f9c57b6ba6a5e6782ea9f5e1ebe64fc04939661b982cb7fbd02" + }, + { + "file": "src/main.ts", + "symbol": "CliViews.static primary", + "fingerprint": "dc70d947f1abb9f76f7c52617c7854bd35a722ba15bb516ec0e07bab63a4ac24" + }, + { + "file": "src/main.ts", + "symbol": "CliViews.static errors", + "fingerprint": "d678c5c70b3437746310a6e4f3d19bce8b97f5000e49e5a07e00c0dc9ecff200" + }, + { + "file": "src/main.ts", + "symbol": "CliOutput.render", + "fingerprint": "fbfcc9284e72fe24b222f6267ac12181ef5c7232c200d13a87e127446ae91f8e" + }, + { + "file": "src/main.ts", + "symbol": "NativeStreams.static write", + "fingerprint": "ff4fd8b2812c6e1325da9a21a5853cfff18a0bb9ab5e9d879d2fa1ff151acc12" + }, + { + "file": "src/main.ts", + "symbol": "CapabilityValidation.parse", + "fingerprint": "95cfc1daceea571d0fb7dc3fd881e8df081f106f224c14ca2be10f4abc4eb7dd" + }, + { + "file": "src/main.ts", + "symbol": "CliComposition.static core", + "fingerprint": "36e4a2ce91ff859f2d7168b0c5f3997292d92058b32e15781ff663b88b03f81a" + }, + { + "file": "src/main.ts", + "symbol": "CliComposition.static prepared", + "fingerprint": "ddf96731c002ee3fba55015c394aedf0e0151dabec6b4c6f5ef9a25f423f65dd" + }, + { + "file": "src/main.ts", + "symbol": "CliApplication.invoke", + "fingerprint": "6ee7a4bb8895baea9849eedc29c5661101c28ca161877092bfa82ea9b7456022" + }, + { + "file": "src/main.ts", + "symbol": "CliApplication.static start", + "fingerprint": "09bed38cf49d367102c0b1f53b99eddbe3116d0096eaec3f6d2ceac967948312" + }, + { + "file": "src/plugins.ts", + "symbol": "PluginArgumentsReader.static read", + "fingerprint": "c566a08c28d4e84939f50a20a16b3af1002dba371c3f99228bf3f4db34cede4e" + }, + { + "file": "src/plugins.ts", + "symbol": "InstalledPluginCommands.execute", + "fingerprint": "ec7f0351651cc442d753a99d735a683f7fe9b4f741ce9a5f0707d5eb204cb369" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "CliTests.snapshot", + "fingerprint": "e63f548fd497b3b7c848278aafcf4bab7488a8782b2a38bf680f301c412c2ba9" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "ProviderFixture.copy", + "fingerprint": "5dd502f5c132dffad97fe0d40a46426ce4b14f3151351a3e40fe19429b590265" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "ProviderFixture.prepare", + "fingerprint": "8fbcc2ddc11a723027eba54a6754467a3b195f7e4c9183027c7fe3c280b1718b" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "ProviderFixture.inventory", + "fingerprint": "64d7e88942e708e57ac83e5bd973b86a2748a575c790ed91b30a3600777ff787" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "ProviderFixture.permissions", + "fingerprint": "842711724a63a9b88f3ecb96599d70d9c54b3fb9be815a6ecbe79660e7854a6e" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "ProviderFixture.refresh", + "fingerprint": "67591c68cde904a4ed987184fb48cf61fb58957784dfe2e090de128042c70471" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "ProviderFixture.address", + "fingerprint": "62aab529844e20d7a263873f9d9d030609633f4075121e766368601dabbab689" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "ProviderFixture.run", + "fingerprint": "a39fb5e653f167cb15eaceb7fa552369418f8c3c4b21540f604575a72a4f7399" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "ProviderFixture.close", + "fingerprint": "20d2794fb3cf2a7d58bfb562c260eed9eebbe0a44048903f33540516ca39aa3e" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "ExtensiblePlanProgramTests.listeners", + "fingerprint": "1db722c800a659a6612fc0a34c54c5f49f90c618ade8bc12f83a6c582acb2831" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "InstalledProgramTests.json", + "fingerprint": "b0c414193d2e64e2cd4d9208dccdb1cde8996e7363b0f29db3ada673f9c09436" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "InstalledProgramTests.signal", + "fingerprint": "bf553370209847ba835fc86b7cef9db5be405202b913e4740acd9bd32ea6c02f" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "InstalledPluginCliTests.request", + "fingerprint": "c5ccace2ac7652b346f1c9249b544d4d0ebf8213b368f0e938f1fe85461eaedb" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "InstalledPluginCliTests.settled", + "fingerprint": "0dc1b08866946fd1c6e81be0f27ef2fa21a0aaef8308c7aa508cd3a35e21b3f6" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "InstalledPluginCliTests.receipts", + "fingerprint": "910bb7037f9f85c0dca4e87dbae634ebe83f4958fa06a0dae033aedd9c4841d8" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "InstalledPluginCliTests.same", + "fingerprint": "5329d1f488907a6b8b955e772ab3bca4a3522d0ed0d2c710bc4c2d3413f0f0b4" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "InstalledPluginCliTests.direct", + "fingerprint": "f583523c00faa6d64dd7d7c6f183d93a87c96365d55cc5e899610cde4161e3c7" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "InstalledPluginCliTests.identify", + "fingerprint": "fe7995fc92084dee540a7845ff123fcfd029e3c2753d365984ee3f5edda47727" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "InstalledPluginCliTests.signal", + "fingerprint": "be927c59663fa7706cdcde14be9fd1f6f6d8340bcffc69446edcaa8eb986c7ac" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "LivePluginCliTests.run", + "fingerprint": "ef12d9e013ae5a5fc34f062b2507cdfd7d86524b1e0fc7c76297ab8343c3330e" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "LivePluginCliTests.settled", + "fingerprint": "7dd1ae2c3a08865ef9dcc0a9292345cc2d5d65acce3d16f83ef1bc58bc15154f" + }, + { + "file": "tests/acceptance/cli-program-contract.ts", + "symbol": "LivePluginCliTests.static physical", + "fingerprint": "03f8e7f3d23d39d839dcd165ec81e3d5188257562c44162d3bbea1044f815240" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CliTestsAcceptance.pluginArguments", + "fingerprint": "54374bac2fb0756b43efe1a0e83fec85e27700e5ab10e9395899e1ff8e40eb8a" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CliTestsAcceptance.installedArguments", + "fingerprint": "e7441587f18dbdf9668c4807bafe6895a41c86974fe7fc6e5271b2a70776244c" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CliTestsAcceptance.identity", + "fingerprint": "964d21391c93e2fb12027fa5bb956e504dfa27e9cd079188a235ee1ad3310dc0" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CliTestsAcceptance.diagnosis", + "fingerprint": "ab8a7d0930b13820c6b11b926e808657f12a49cd5f6046d2c29ea8708079b346" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CliTestsAcceptance.blockers", + "fingerprint": "837a6811265aece0ccd9a5cafabe850864ecf8b6098717e18820906feec56216" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CliTestsAcceptance.invalidProgram", + "fingerprint": "adf458d5aa60b789884580b097cd2f39eb601464e3f616d18f7033b3f2cceb33" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CliTestsAcceptance.plan_changes_no_runtime", + "fingerprint": "90db06b5f10668c507b46330077fbedc52bc34737b92ca719312cdb2dac797b3" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CliTestsAcceptance.installationPaths", + "fingerprint": "e24729300562274f01ff72e759fa943b89e61078d487046931ddb398b01115c7" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CliTestsAcceptance.invalidPlans", + "fingerprint": "bd09ed92bf50329a240d75cfb134086b97281310db1ea5e678c1c9f8834fee6d" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CompositionProgramTestsAcceptance.selected", + "fingerprint": "63ea8b66981aa4db2517ea44cf440dfd77ab93e891d4ec646a6130fae3c98284" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CompositionProgramTestsAcceptance.lifecycleFailures", + "fingerprint": "8fc16d8acf7228be4d2cedd1366e5d9ee407c0226822e30c7534f4df147e2879" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CompositionProgramTestsAcceptance.metadataFailures", + "fingerprint": "8ada1d23540531fa07b91146bd98a9d98a6ce9b5293d87768b8dbf31505e3b1a" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "CompositionProgramTestsAcceptance.rejected", + "fingerprint": "e194c722af9aa2a6e69123456ee124185525df0d5b176bc2922d82e3a66b9efe" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "UiOutputProgramTestsAcceptance.human", + "fingerprint": "7c74ed6e73cfa927439a8b6cdc0438d4c6ced0cd1ba75a23b61b6b7c0017648c" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "ExtensiblePlanProgramTestsAcceptance.plan", + "fingerprint": "8ab40ee190996332ee3a3ff29b6e9a8a1b3a45e411954224ddc75b6a4db74eb2" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "InstalledProgramTestsAcceptance.installed", + "fingerprint": "f323bdac986747f515c04de260c41b2df4b987b3d007d865cd989d4caeda87fc" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "InstalledPluginCliTestsAcceptance.program", + "fingerprint": "0127133eb4b9973777813897b4b46a023b80b6210c9923d2efcd4653a3aeb140" + }, + { + "file": "tests/acceptance/cli-program.test.ts", + "symbol": "LivePluginCliTestsAcceptance.program", + "fingerprint": "d443698c6c319a048fd72c76d02e8b80acf8f0a5ca90dc8a202db36ac4201ef7" + }, + { + "file": "tests/integration/cli-program.test.ts", + "symbol": "CliTestsIntegration.defaultComposition", + "fingerprint": "0751390132903c5f4337b170864e2ed7d65f9b289abf5e67de2b3a69c66e9014" + }, + { + "file": "tests/integration/command-classification.test.ts", + "symbol": "CliTestsIntegration.parser", + "fingerprint": "7c79d79862e48693aafc50cfeb614476358a0d50994f4561913df303ed1f64f9" + }, + { + "file": "tests/regression/test-layout.test.ts", + "symbol": "TestLayoutRegression.check", + "fingerprint": "58a1e54d5b4d5e806480547f2c44fc7fd4a30b548e11033ce1aec339518628f4" + }, + { + "file": "tests/regression/test-layout.test.ts", + "symbol": "TestLayoutRegression.discovery", + "fingerprint": "9a2d5796d031c1f6b33cfe9b537b6ebaacb870e3bcdf578110c016bbc44dca2d" + }, + { + "file": "tests/regression/test-layout.test.ts", + "symbol": "TestLayoutRegression.matrix", + "fingerprint": "ec2572e83c489f133b4c787afaaa99cc1106c22b8e76a2cbbc5dae077a23c0c5" + }, + { + "file": "tests/regression/test-layout.test.ts", + "symbol": "TestLayoutRegression.partitions", + "fingerprint": "99923590bc7eb9c1f0b70fd32403786ecdc51b98ed1eec4241ae1a0693c17dcd" + }, + { + "file": "tests/regression/test-layout.test.ts", + "symbol": "TestLayoutRegression.support", + "fingerprint": "e933ea0a60e46f10d31f0368c7d6413a5b60d3e5b392dca3f3c18daa81cb0966" + }, + { + "file": "tests/support/cli-program-test-support.ts", + "symbol": "CliProgramFixture.constructor", + "fingerprint": "e7ca425ee932d322f9b863a14d30018193f605ee56263c7024a74a53e0befe7f" + }, + { + "file": "tests/support/cli-program-test-support.ts", + "symbol": "CliNetworkFixture.listen", + "fingerprint": "11c894b7edac93b9d2a6d56b483595efea49d4bbf4dd134ebf0e4fdf7e517f38" + }, + { + "file": "tests/support/cli-program-test-support.ts", + "symbol": "CliNetworkFixture.listening", + "fingerprint": "e3ce299407d99592d5ef419bb01783fd4bb30d141d18b931b5a15f740ff6f525" + }, + { + "file": "tests/support/cli-program-test-support.ts", + "symbol": "CliNetworkFixture.port", + "fingerprint": "14be352ee488db287d91b52ad160aeea6fdeee419f4f0902e61a27ea6b2405b6" + } + ], + "exceptions": [] +} diff --git a/AGENTS.md b/AGENTS.md index 411c147..25aa6e1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -127,6 +127,30 @@ The first implementation slice must make the existing compiler/lint checks rejec JavaScript and function-based implementation paths, using semantic source checks rather than claiming that prose alone enforces architecture. Missing enforcement remains an explicit gap. +## Critical Architecture Rule: Readable Capability Layers (MANDATORY) + +Organize implementation into small, cohesive TypeScript classes with short, normally formatted +methods. Each layer must read as a clear sequence of named capabilities supplied through typed +contracts and native Cordis composition. New or changed executable methods, constructors and +accessors must contain at most **20 canonically formatted body lines**, excluding blank lines, +comment-only lines and the outer method delimiters, unless an exact documented exception is +reviewed. Declarative schemas and data are outside this behavioral limit; class cohesion and +readability still require review. Do not compress statements, introduce trivial wrapper classes, +or move complexity elsewhere merely to satisfy the limit. + +When changing existing behavior, refactor the affected methods and their immediate responsibility +boundary to this style. When directed to refine or clean up a project or source area, audit and +refactor the stated scope. Unrelated historical implementation is not permission for a sweeping +rewrite; untouched violations may remain only under the immutable verified integration baseline. +A changed method loses grandfathering. An exception identifies its exact symbol, source fingerprint, +reason and owning issue and must be reviewed with the change; stale or unused exceptions fail. + +Run the shared development-only readability check in normal owner checks and CI. It uses pinned +`prettier@3.6.2` for canonical measurement and rejects compressed behavioral statements and baseline +manipulation. Neither shipped behavior nor target-project code may depend on these instructions +or their development helpers. Future setup copies this rule and helper resources without installing +dependencies or adding scaffolding; wire the gate during the first implementation. + ## Workflow Gate (MANDATORY) **At the START of every new project or statement of work:** load the `release-workflow` skill, diff --git a/CHANGELOG.md b/CHANGELOG.md index 7396583..5c8e337 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ ## [Unreleased] ### Changed +- Require readable capability layers and contextual refactoring with a twenty-line method gate (#327). - Organize permanent tests by tier and enforce the shared development/testing strategy (#325). - Qualify built plugin commands against exact packaged Git, approved Git build and native live probe installation artifacts (#317). diff --git a/bun.lock b/bun.lock index 502c642..68e2bdb 100644 --- a/bun.lock +++ b/bun.lock @@ -16,6 +16,7 @@ "@types/bun": "1.4.4", "@types/node": "24.10.1", "cordis": "4.0.0-rc.12", + "prettier": "3.6.2", "typescript": "5.9.3", }, }, @@ -61,6 +62,8 @@ "postgres": ["postgres@3.4.9", "", {}, "sha512-GD3qdB0x1z9xgFI6cdRD6xu2Sp2WCOEoe3mtnyB5Ee0XrrL5Pe+e4CCnJrRMnL1zYtRDZmQQVbvOttLnKDLnaw=="], + "prettier": ["prettier@3.6.2", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ=="], + "react": ["react@19.3.1", "", {}, "sha512-QNhWdt7nrgVWWQG58QuGsAR3jv3Hbe4mb4vz7w2csnHavciZJgda1CPNaldF6eVxv90ud3jUXpKlHL69gO38yw=="], "react-dom": ["react-dom@19.3.1", "", { "dependencies": { "scheduler": "^0.28.0" }, "peerDependencies": { "react": "^19.3.1" } }, "sha512-Y0bARz53lhEC1NMCASs0/j+faB/zqt3R8hpvg1e8+61ZVJ4UL0UdC4cBbXfZMcIuhrfgeILTLe+ZeBCavQPtKQ=="], diff --git a/package.json b/package.json index b5d7791..d6dcbb5 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,7 @@ "license": "Apache-2.0", "packageManager": "bun@1.4.4", "scripts": { - "check": "bun run check:test-layout && bun scripts/build-cli.ts check", + "check": "bun run check:readability && bun run check:test-layout && bun scripts/build-cli.ts check", "build": "bun scripts/build-cli.ts build", "test:unit": "bun test ./tests/unit --pass-with-no-tests", "test:integration": "bun test ./tests/integration --timeout 30000", @@ -14,7 +14,8 @@ "verify": "bun run check && bun run build && bun run test:acceptance && bun run test:regression && bun run test:integration && bun run test:unit", "check:test-layout": "bun .agents/skills/release-workflow/scripts/test-layout.ts", "test:regression": "bun test ./tests/regression", - "test:acceptance": "bun test ./tests/acceptance --timeout 60000" + "test:acceptance": "bun test ./tests/acceptance --timeout 60000", + "check:readability": "bun .agents/skills/release-workflow/scripts/source-readability.ts" }, "dependencies": { "@treeseed-cordis/sdk": "file:vendor/sdk.tgz", @@ -28,7 +29,8 @@ "@types/bun": "1.4.4", "@types/node": "24.10.1", "cordis": "4.0.0-rc.12", - "typescript": "5.9.3" + "typescript": "5.9.3", + "prettier": "3.6.2" }, "cordisCandidate": { "sdk": { diff --git a/tests/acceptance/source-readability.test.ts b/tests/acceptance/source-readability.test.ts new file mode 100644 index 0000000..e42bbf7 --- /dev/null +++ b/tests/acceptance/source-readability.test.ts @@ -0,0 +1,174 @@ +import { test, expect } from 'bun:test'; +import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs'; +import { join, resolve } from 'node:path'; +import { tmpdir } from 'node:os'; +import { spawnSync } from 'node:child_process'; +import type { SpawnSyncReturns } from 'node:child_process'; + +interface Violation { file: string; symbol: string; fingerprint: string; } +interface Report { success: boolean; errors: string[]; violations: Violation[]; } +interface Policy { baselineCommit: string; violations: Violation[]; exceptions: object[]; } + +class ReadabilityFixture { + readonly root = mkdtempSync(join(tmpdir(), 'readable-capabilities-')); + readonly helper = resolve('.agents/skills/release-workflow/scripts/source-readability.ts'); + + constructor(source = 'export class Provider { run(): number { return 1; } }') { + mkdirSync(join(this.root, 'src')); + this.source(source); + this.git(['init', '-q']); + this.git(['add', '.']); + this.git(['-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', + 'commit', '--no-gpg-sign', '-qm', 'fixture baseline']); + this.git(['update-ref', 'refs/remotes/origin/cordis', 'HEAD']); + this.capture(); + } + + private git(args: string[]): string { + const result = spawnSync('git', args, { cwd: this.root, encoding: 'utf8' }); + if (result.status !== 0) throw new Error('Git fixture failed: ' + result.stderr); + return result.stdout.trim(); + } + + private capture(): void { + const result = this.run(['--capture', this.git(['rev-parse', 'HEAD'])]); + expect(result.status, result.stderr).toBe(0); + } + + run(args: string[] = []): SpawnSyncReturns { + return spawnSync(process.execPath, [this.helper, '--root', this.root, ...args], { + encoding: 'utf8', timeout: 30000, + }); + } + + check(): Report { + const result = this.run(['--json']); + expect(result.error).toBeUndefined(); + const report = JSON.parse(result.stdout) as Report; + expect(result.status).toBe(report.success ? 0 : 1); + return report; + } + + source(value: string): void { writeFileSync(join(this.root, 'src/provider.ts'), value); } + policy(): Policy { return JSON.parse(readFileSync(join(this.root, '.readability.json'), 'utf8')); } + save(value: Policy): void { writeFileSync(join(this.root, '.readability.json'), JSON.stringify(value)); } + close(): void { rmSync(this.root, { recursive: true, force: true }); } +} + +class ReadabilityPrograms { + static longMethod(name = 'run'): string { + const statements = []; + for (let index = 0; index < 23; index++) statements.push(' this.step();'); + return 'export class Provider {\n ' + name + '(): void {\n' + statements.join('\n') + + '\n }\n step(): void {}\n}\n'; + } + + unchangedDebt(): void { + const fixture = new ReadabilityFixture(ReadabilityPrograms.longMethod()); + try { expect(fixture.check().success).toBe(true); } + finally { fixture.close(); } + } + + changedMethod(): void { + const fixture = new ReadabilityFixture(ReadabilityPrograms.longMethod()); + try { + fixture.source(ReadabilityPrograms.longMethod().replace('this.step();', 'this.step();\n this.step();')); + expect(fixture.check().errors.join('\n')).toContain('METHOD_LENGTH'); + } finally { fixture.close(); } + } + + newMethod(): void { + const fixture = new ReadabilityFixture(); + try { + fixture.source(ReadabilityPrograms.longMethod()); + expect(fixture.check().errors.join('\n')).toContain('METHOD_LENGTH'); + } finally { fixture.close(); } + } + + compressedStatements(): void { + const fixture = new ReadabilityFixture(); + try { + fixture.source('export class Provider { run(): number { const value = 1; return value; } }'); + expect(fixture.check().errors.join('\n')).toContain('COMPRESSED_STATEMENTS'); + } finally { fixture.close(); } + } + + baselineTampering(): void { + const fixture = new ReadabilityFixture(ReadabilityPrograms.longMethod()); + try { + const policy = fixture.policy(); + policy.violations = []; + fixture.save(policy); + expect(fixture.check().errors.join('\n')).toContain('BASELINE_MISMATCH'); + } finally { fixture.close(); } + } + + exactException(): void { + const fixture = new ReadabilityFixture(); + try { + fixture.source(ReadabilityPrograms.longMethod()); + const violation = fixture.check().violations[0]!; + const policy = fixture.policy(); + policy.exceptions = [{ ...violation, issue: 1, reason: 'Keep this fixture transition coherent for review.' }]; + fixture.save(policy); + expect(fixture.check().success).toBe(true); + fixture.source(ReadabilityPrograms.longMethod('other')); + expect(fixture.check().errors.join('\n')).toContain('STALE_EXCEPTION'); + } finally { fixture.close(); } + } + + declarativeData(): void { + const fixture = new ReadabilityFixture(); + try { + const values = []; + for (let index = 0; index < 100; index++) values.push(' "value-' + index + '",'); + fixture.source('export class Provider {\n static readonly values = [\n' + values.join('\n') + '\n ];\n}'); + expect(fixture.check().success).toBe(true); + } finally { fixture.close(); } + } + + constructorsAndAccessors(): void { + const fixture = new ReadabilityFixture(); + try { + const source = ReadabilityPrograms.longMethod(); + fixture.source(source.replace('run(): void', 'constructor()')); + expect(fixture.check().errors.join('\n')).toContain('Provider.constructor'); + fixture.source(source.replace('run(): void', 'get result(): void')); + expect(fixture.check().errors.join('\n')).toContain('Provider.get result'); + } finally { fixture.close(); } + } + + provenance(): void { + const fixture = new ReadabilityFixture(); + try { + const policy = fixture.policy(); + policy.baselineCommit = '0'.repeat(40); + fixture.save(policy); + expect(fixture.check().success).toBe(false); + expect(fixture.run(['--capture', policy.baselineCommit]).status).toBe(1); + } finally { fixture.close(); } + } + + unusedException(): void { + const fixture = new ReadabilityFixture(); + try { + const policy = fixture.policy(); + policy.exceptions = [{ file: 'src/provider.ts', symbol: 'Provider.missing', + fingerprint: '0'.repeat(64), issue: 1, reason: 'This exemption has no matching violating method.' }]; + fixture.save(policy); + expect(fixture.check().errors.join('\n')).toContain('STALE_EXCEPTION'); + } finally { fixture.close(); } + } +} + +const suite = new ReadabilityPrograms(); +test('acceptance: readability gate preserves exact unchanged integration debt', suite.unchangedDebt.bind(suite)); +test('acceptance: changed long methods lose baseline grandfathering', suite.changedMethod.bind(suite)); +test('acceptance: new long methods fail canonical measurement', suite.newMethod.bind(suite)); +test('acceptance: compressed statements cannot evade readable layout', suite.compressedStatements.bind(suite)); +test('acceptance: baseline inventory tampering fails verified Git read-back', suite.baselineTampering.bind(suite)); +test('acceptance: reviewed exact exceptions become invalid after source changes', suite.exactException.bind(suite)); +test('acceptance: declarative data remains outside the behavioral line limit', suite.declarativeData.bind(suite)); +test('acceptance: constructors and accessors share the executable method gate', suite.constructorsAndAccessors.bind(suite)); +test('acceptance: changing baseline provenance cannot grandfather feature code', suite.provenance.bind(suite)); +test('acceptance: unused exemptions fail instead of silently accumulating', suite.unusedException.bind(suite));