From 099293ad72ee161cd26adcc12deb6229eb14859e Mon Sep 17 00:00:00 2001 From: Adrian Webb Date: Tue, 27 Oct 2026 16:00:33 -0400 Subject: [PATCH 1/3] docs: require readable capability layers (#148) --- .agents/skills/release-workflow/SKILL.md | 23 +++++++++++++++++++++++ AGENTS.md | 24 ++++++++++++++++++++++++ CHANGELOG.md | 1 + 3 files changed, 48 insertions(+) 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.md b/AGENTS.md index 2cf1691..127a0f4 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 44e14b2..9b53780 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 (#148). - Organize permanent tests by tier and enforce the shared development/testing strategy (#146). - Rebuild Admin from exact SDK .16, Identity .7 and reusable UI .16 owner archives (#137). From 066b3b17dfdba66e9471672a180493331c6c5b3e Mon Sep 17 00:00:00 2001 From: Adrian Webb Date: Tue, 27 Oct 2026 16:12:35 -0400 Subject: [PATCH 2/3] test: specify executable readability gate behavior (#148) --- tests/acceptance/source-readability.test.ts | 174 ++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 tests/acceptance/source-readability.test.ts 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)); From b8295c15558bc65e4fd203b3f6bf6d8161262ab4 Mon Sep 17 00:00:00 2001 From: Adrian Webb Date: Tue, 27 Oct 2026 16:22:04 -0400 Subject: [PATCH 3/3] feat: enforce readable capability layers (#148) --- .../scripts/source-readability.ts | 345 ++++++++++++++++++ .github/workflows/verify.yml | 2 + .readability.json | 297 +++++++++++++++ bun.lock | 3 + package.json | 8 +- 5 files changed, 652 insertions(+), 3 deletions(-) create mode 100644 .agents/skills/release-workflow/scripts/source-readability.ts create mode 100644 .readability.json 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 fdfd8a3..069fd3e 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/verify.yml @@ -12,6 +12,8 @@ jobs: timeout-minutes: 10 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..9e282f1 --- /dev/null +++ b/.readability.json @@ -0,0 +1,297 @@ +{ + "formatVersion": 1, + "baselineCommit": "362ab46a30f32e0157d2bf7a5e5a775d09dfe2cf", + "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/tooling.ts", + "symbol": "AdminTooling.static run", + "fingerprint": "0ee9fbfaa6d185d0796bf121391ca9d2162b01c061421dcc991a2cf031f6855d" + }, + { + "file": "src/admin.ts", + "symbol": "AdminAdapter.parse", + "fingerprint": "f411b96cc38630047570ea7833f99f95dc5dace75d4abb1a1755f85a67caaa88" + }, + { + "file": "src/admin.ts", + "symbol": "AdminRoutes.static cookie", + "fingerprint": "9ac5edf0c30437418ffa2e73b06d3c3ea81aedc3aa8e36097bae75a7feca9e02" + }, + { + "file": "src/admin.ts", + "symbol": "AdminRoutes.redirect", + "fingerprint": "ac5ad819947c60c4a7b90d00a1bd72e317a77e687b92e4bc7b7eecc83be5aad5" + }, + { + "file": "src/admin.ts", + "symbol": "AdminRoutes.handle", + "fingerprint": "3e966105b8a6374ef2b97d303fc20f263be049beaced18cb6fff38b3deb4d704" + }, + { + "file": "src/admin.ts", + "symbol": "AdminValidator.parse", + "fingerprint": "833a8e1ff3fea6ae670176381865202c7895c9da5eb19c8b661f1ce5533af28b" + }, + { + "file": "src/admin.ts", + "symbol": "AdminPresentationPlugin.[Service.init]", + "fingerprint": "41ff5c6a11d723f74c92b5832cf5590248ae6434dda74506df8a8dfe60f48be3" + }, + { + "file": "src/admin.ts", + "symbol": "AdminComposition.static registrations", + "fingerprint": "21d6113b31a839dea3fc53e284ab6c3884566fb289b8b6b4bcb5c2c44b08cad6" + }, + { + "file": "src/admin.ts", + "symbol": "AdminBuild.static asset", + "fingerprint": "b14385148a58df2d8a3d04dced3cdd9c22fdce9f78cdd2e6ff023f0559ca129a" + }, + { + "file": "src/admin.ts", + "symbol": "AdminBuild.static run", + "fingerprint": "da7a827447eafff8ad627e4bf0b26c8e4a1750cd2277ab8632dfa94be6ef809b" + }, + { + "file": "src/assets.ts", + "symbol": "AdminAssetCatalog.constructor", + "fingerprint": "db70e3bbcfd7a83380b6e0ec91dd0235dc6f1b1ad8e7c9388ba477c6319af748" + }, + { + "file": "src/assets.ts", + "symbol": "AdminAssetCatalog.static order", + "fingerprint": "fc2df4ce3dda52d68c34ed3719bbfc736fcec402a58ff89b8560157cf5947abf" + }, + { + "file": "src/assets.ts", + "symbol": "AdminAssetCatalog.asset", + "fingerprint": "ca888e2edff405ad8501f0cce00227f43caa0e02ccc9356c354b5f8d0640161e" + }, + { + "file": "src/browser.ts", + "symbol": "BrowserAdapter.parse", + "fingerprint": "b293aafa3062ff84b086586bbc7393bb26b520b8681585e013ffae57e89f5447" + }, + { + "file": "src/browser.ts", + "symbol": "StatusClient.request", + "fingerprint": "9cf955429974ab88083395368d25267656393c7c8a9fb37f7c170f250723230f" + }, + { + "file": "src/browser.ts", + "symbol": "StatusClient.presentation", + "fingerprint": "59ccedd7452335ea60ad95274f69ebb395c195b73cd73ac238ef263a661bdd7a" + }, + { + "file": "src/browser.ts", + "symbol": "StatusClient.logout", + "fingerprint": "6980cefe577343f571a1246b6129bf008c023da7e29c238f004152cc878727e5" + }, + { + "file": "src/browser.ts", + "symbol": "HttpStatusPlugin.constructor", + "fingerprint": "fd36e17e652aabf1ddb1e3e8155b92f1387dba8cd148af62003f1a1292b35e2b" + }, + { + "file": "src/browser.ts", + "symbol": "AdminBrowserState.open", + "fingerprint": "bbc172073a4defdcef7a7d56f561b8e5cde3c0ce599c703757ba0d1c45c6cade" + }, + { + "file": "src/browser.ts", + "symbol": "AdminBrowserState.refresh", + "fingerprint": "68d2aaf698f993e81b72a6db39566f9f2edb353da67e55972d521ed27140439c" + }, + { + "file": "src/browser.ts", + "symbol": "AdminBrowserState.close", + "fingerprint": "de792b8e155ada55aef2b3b86ebfe3ccc0b65a206c75d135b4d69e333780d822" + }, + { + "file": "src/browser.ts", + "symbol": "AdminBrowserStatePlugin.constructor", + "fingerprint": "9241fbaf3bbe8cc550ec5e0beff536fce6bc3aa145ea83592bee910cb3d4e68b" + }, + { + "file": "src/browser.ts", + "symbol": "AdminNavigationPlugin.navigate", + "fingerprint": "12965ac2a700810253b094606acb510bfd007a975a8ddc21d0a8d26b1f038d7b" + }, + { + "file": "src/browser.ts", + "symbol": "AdminNavigationPlugin.leave", + "fingerprint": "b71b884c8ab7cbd647b97db268a35ed02eb9ebb229cd84cc2f8e2cae3b262217" + }, + { + "file": "src/browser.ts", + "symbol": "AdminActionsPlugin.invoke", + "fingerprint": "c66bc6aa57dd162ac42e68d5bf21be5e554028d4b52f3398886c750e2db920c6" + }, + { + "file": "src/browser.ts", + "symbol": "StatusPagePlugin.[Service.init]", + "fingerprint": "39321c276f65d56fdfda049ae46590b52955f13fd8a14b5969cbf5b3a639cd4e" + }, + { + "file": "src/browser.ts", + "symbol": "AdminBrowserApplication.static start", + "fingerprint": "eb79c6a216844d0b77d49e9b2ecadd32cf0e2d910565b94639f3ed23615c8792" + }, + { + "file": "src/browser.ts", + "symbol": "AdminBrowserApplication.dispose", + "fingerprint": "e6f13a40f1176dbe11482df5468f63ab0350e24a3b447904a4f6d9f8ab212cfe" + }, + { + "file": "src/browser.ts", + "symbol": "AdminBrowserApplication.close", + "fingerprint": "faeb4e0bb532a7d58d99c11594f290f14f30b10cfecba498f8c50a1443f61af9" + }, + { + "file": "src/views.ts", + "symbol": "AdminViews.static initial", + "fingerprint": "7f11a3bf9b330647fa09e312bde85f10b66f21942ab4651c7952a29dc50971f6" + }, + { + "file": "src/views.ts", + "symbol": "AdminViews.static refreshed", + "fingerprint": "1ce7ce432b5e32ee388d849f79357196191857c2dca6d49730101b3030a93b04" + }, + { + "file": "tests/acceptance/admin.test.ts", + "symbol": "AdminTestsAcceptance.nodeAssets", + "fingerprint": "901b18eca8e3986825c614e5dac2e0b5fd9a53fc84cfdef871e9acee66d2a617" + }, + { + "file": "tests/acceptance/admin.test.ts", + "symbol": "AdminTestsAcceptance.program", + "fingerprint": "ebdd992f3edd199bd45b65eaa7850549e6f10732369108a973063440d09d1555" + }, + { + "file": "tests/acceptance/browser.test.ts", + "symbol": "AuthorityFixture.callback", + "fingerprint": "7424aa400e02e0e55a27900d4f041d27a72159fb67b88f1c9161492d99be3360" + }, + { + "file": "tests/acceptance/browser.test.ts", + "symbol": "AuthorityFixture.logout", + "fingerprint": "b0fa88fa72d4c85ad4786724645638d513240ecdf1bd3c2bdc05085049ea84e3" + }, + { + "file": "tests/acceptance/browser.test.ts", + "symbol": "AuthorityFixture.invoke", + "fingerprint": "6c6afacdca469b58bdbe4d113d41f6d4b8aea7599222f7ff2c28376b65964a55" + }, + { + "file": "tests/acceptance/browser.test.ts", + "symbol": "AdminBrowserTest.command", + "fingerprint": "c069c7f7cc63a329f0bf9d505eb5b8b4aee8a651d0b6364fbe174d06c4bc873a" + }, + { + "file": "tests/acceptance/browser.test.ts", + "symbol": "AdminBrowserTest.run", + "fingerprint": "8a83be28eeb9d9dbadff86585df9f5d9d37ad367b4e46e2a09e88cb15e481d82" + }, + { + "file": "tests/acceptance/browser.test.ts", + "symbol": "AdminBrowserTest.fetch", + "fingerprint": "ea3a6fae74d79aee61f6e9c0889d1244660d8d4e3471a0ab7e0380aa29925ff6" + }, + { + "file": "tests/integration/admin.test.ts", + "symbol": "AdminTestsIntegration.assets", + "fingerprint": "b605420bb58b3ed8cefdba3ffd16e92cc740055ba3cf8dd0ba5929109116c8c5" + }, + { + "file": "tests/integration/admin.test.ts", + "symbol": "AdminTestsIntegration.browser", + "fingerprint": "155acdd8c6f04571ab18b0684ceed009f8cdb14f580fa7e38035300c999e63b8" + }, + { + "file": "tests/regression/adoption.test.ts", + "symbol": "AdoptionTests.program", + "fingerprint": "3185dbd5ff08267740f4994138b6d26c710ffe2da927e55aa20d12ac1746624f" + }, + { + "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/unit/admin.test.ts", + "symbol": "AdminTestsUnit.status", + "fingerprint": "a6ce491108a8208c9850677cdc99cb77e0c74d8c317e0a24baaee13cac98b060" + }, + { + "file": "tests/unit/admin.test.ts", + "symbol": "AdminTestsUnit.policy", + "fingerprint": "bd45a37f47409d62a46d1050a4514f1907e8d454c1ca60058690c63352124b55" + }, + { + "file": "tests/unit/admin.test.ts", + "symbol": "AdminTestsUnit.cookies", + "fingerprint": "621b353ea960853039adc65cd974575dfe95eb513dc8ca9275c749cd457bf187" + } + ], + "exceptions": [] +} diff --git a/bun.lock b/bun.lock index 3448137..8918328 100644 --- a/bun.lock +++ b/bun.lock @@ -16,6 +16,7 @@ "@types/react": "19.3.0", "@types/react-dom": "19.3.0", "playwright": "1.64.1", + "prettier": "3.6.2", "react": "19.3.1", "react-dom": "19.3.1", "typescript": "5.9.3", @@ -68,6 +69,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 dc091c3..429316a 100644 --- a/package.json +++ b/package.json @@ -24,7 +24,7 @@ "LICENSE" ], "scripts": { - "check": "bun run check:test-layout && bun scripts/tooling.ts check", + "check": "bun run check:readability && bun run check:test-layout && bun scripts/tooling.ts check", "build": "bun scripts/tooling.ts build && bun dist/src/admin.js --build-assets", "test:unit": "bun test ./tests/unit", "test:integration": "bun test ./tests/integration", @@ -32,7 +32,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" + "test:acceptance": "bun test ./tests/acceptance", + "check:readability": "bun .agents/skills/release-workflow/scripts/source-readability.ts" }, "peerDependencies": { "@treeseed-cordis/sdk": "0.0.0-cordis.16", @@ -52,7 +53,8 @@ "react-dom": "19.3.1", "playwright": "1.64.1", "@types/react": "19.3.0", - "@types/react-dom": "19.3.0" + "@types/react-dom": "19.3.0", + "prettier": "3.6.2" }, "dependencies": { "cordis": "4.0.0-rc.12"