@erclx/canon 4.0.0

package/src/audits/run.ts

@@ -0,0 +1,204 @@
+import { join } from 'node:path'
+import { execa } from 'execa'
+import type { Delta } from '@/audits/baseline'
+import { type AuditResult, type AuditSpec, classify } from '@/audits/catalog'
+import { gitEnv } from '@/git-env'
+import { PROJECT_ROOT } from '@/project-root'
+
+/** At least one audit reported a finding that is a fact. */
+export const EXIT_FINDING = 2
+
+/** At least one audit did not report, so the run measured less than the set. */
+export const EXIT_UNMEASURED = 3
+
+export type Verdict =
+  /** Every audit reported and every count it produced was zero. */
+  | 'clean'
+  /** Every audit reported and at least one carries a judgment finding. */
+  | 'reported'
+  /** At least one audit carries a finding that is a fact. */
+  | 'findings'
+  /** At least one audit did not report, so this is not a pass. */
+  | 'incomplete'
+
+export interface SpawnResult {
+  readonly exitCode: number
+  readonly stdout: string
+}
+
+export type Spawn = (spec: AuditSpec) => Promise<SpawnResult>
+
+/**
+ * Runs each verb out of the checkout this CLI is executing from.
+ *
+ * `process.execPath` and the resolved `cli.ts` rather than a bare `canon`, for
+ * the reason `cliRunner` in `src/gate/sequencer.ts` already names: a globally
+ * installed binary resolves to
+ * the main checkout no matter which worktree is running, so the aggregate would
+ * measure the wrong tree and report a pass over a branch it never read.
+ *
+ * `reject: false` because a findings exit is the ordinary outcome for half of
+ * these verbs, and a throw there would be an error path for a working check.
+ */
+export function spawnAudit(root: string): Spawn {
+  const cli = join(PROJECT_ROOT, 'src', 'cli.ts')
+
+  return async (spec) => {
+    const result = await execa(process.execPath, [cli, ...spec.argv], {
+      cwd: root,
+      reject: false,
+      // `gitEnv` already returns the whole ambient environment minus git's
+      // resolution variables, so it replaces the environment rather than
+      // extending it. Spreading `process.env` alongside would put back the very
+      // variables it strips, and a hook's `GIT_DIR` would then point every
+      // history-reading verb at a repository nobody asked about.
+      env: { ...gitEnv(), CANON_NON_INTERACTIVE: '1' },
+      extendEnv: false,
+    })
+
+    return { exitCode: result.exitCode ?? 1, stdout: result.stdout }
+  }
+}
+
+/**
+ * Runs every audit and reads each one's own record shape.
+ *
+ * The verbs walk separate trees and share no state, so they run together
+ * rather than in sequence. Serially, the aggregate would be the slowest thing
+ * in the verify pipeline for no reason beyond the order they were written in.
+ *
+ * A spawn that throws becomes an `unmeasured` result rather than a rejection.
+ * One absent binary would otherwise take the whole aggregate down and report
+ * nothing about the audits that did run.
+ */
+export async function runAudits(
+  specs: readonly AuditSpec[],
+  spawn: Spawn,
+): Promise<AuditResult[]> {
+  return Promise.all(
+    specs.map(async (spec) => {
+      try {
+        const { exitCode, stdout } = await spawn(spec)
+        return classify(spec, exitCode, stdout)
+      } catch (error) {
+        return {
+          id: spec.id,
+          label: spec.label,
+          status: 'unmeasured' as const,
+          tracked: spec.corpus === 'tracked',
+          corpus: spec.corpus,
+          exitCode: 1,
+          reason: `could not be started: ${error instanceof Error ? error.message : String(error)}`,
+        }
+      }
+    }),
+  )
+}
+
+/**
+ * The single verdict over the set.
+ *
+ * `incomplete` outranks a quiet set on purpose. An aggregate reporting a pass
+ * over a tree it did not finish measuring is the failure this whole command
+ * exists against, and an empty set takes it for the same reason: nothing ran,
+ * so nothing passed.
+ *
+ * An `absent` per-machine corpus does not reach it. That folder is gitignored
+ * and missing on every fresh clone, so folding it in would pin the verdict at
+ * `incomplete` on every CI run and leave the word meaning nothing.
+ */
+export function verdictOf(results: readonly AuditResult[]): Verdict {
+  if (results.length === 0) return 'incomplete'
+  if (results.some((result) => result.status === 'finding')) return 'findings'
+  if (results.some((result) => result.status === 'unmeasured')) {
+    return 'incomplete'
+  }
+  if (results.some((result) => result.status === 'reported')) return 'reported'
+  return 'clean'
+}
+
+/**
+ * Exits non-zero only on a fact, which is the split this aggregate inherits
+ * rather than moves. A growing judgment count reports as a delta and fails
+ * nothing, because the standards behind those measures set no hard cap.
+ *
+ * An audit that did not report takes its own code rather than the findings one.
+ * The two mean opposite things to whoever reads the exit: a fact is a defect in
+ * the tree, and an unmeasured audit is a defect in the run.
+ */
+export function exitCodeFor(results: readonly AuditResult[]): number {
+  const verdict = verdictOf(results)
+  if (verdict === 'findings') return EXIT_FINDING
+  if (verdict === 'incomplete') return EXIT_UNMEASURED
+  return 0
+}
+
+export interface Summary {
+  readonly verdict: Verdict
+  /** Audits that reported, out of the whole set. */
+  readonly audited: number
+  /** Audits carrying a finding that is a fact. */
+  readonly facts: number
+  /** Audits that did not report at all. */
+  readonly unmeasured: number
+  /**
+   * Audits whose per-machine folder is not on this disk.
+   *
+   * Published rather than folded into `audited`, so a run stating twelve
+   * audits never implies twelve corpora were read.
+   */
+  readonly absent: number
+  /** Tracked counts that rose against the recorded floor. */
+  readonly grown: number
+  /** Tracked counts that fell against the recorded floor. */
+  readonly shrunk: number
+  /** Tracked audits with no recorded floor to compare against. */
+  readonly unrecorded: number
+}
+
+/**
+ * The flat reading a shell stage takes without parsing the nested record.
+ *
+ * Published rather than left to a consumer to derive, for the reason the
+ * context audit already gives about its own join: deriving it means restating
+ * which question each number answers, and one wrong restatement is growth
+ * reported against a measure that never moved. Every key here is unique across
+ * the whole record, so a grep for one reaches the top level alone.
+ */
+export function summarize(
+  results: readonly AuditResult[],
+  deltas: readonly Delta[],
+): Summary {
+  let grown = 0
+  let shrunk = 0
+  let unrecorded = 0
+
+  for (const delta of deltas) {
+    if (delta.kind === 'unrecorded') {
+      unrecorded += 1
+      continue
+    }
+    if (delta.kind !== 'compared') continue
+
+    for (const moved of delta.moved) {
+      if (moved.delta > 0) grown += 1
+      else shrunk += 1
+    }
+  }
+
+  const counting = (status: AuditResult['status']) =>
+    results.filter((result) => result.status === status).length
+
+  return {
+    verdict: verdictOf(results),
+    audited: results.filter(
+      (result) => result.status !== 'unmeasured' && result.status !== 'absent',
+    ).length,
+    facts: counting('finding'),
+    unmeasured: counting('unmeasured'),
+    absent: counting('absent'),
+    grown,
+    shrunk,
+    unrecorded,
+  }
+}

package/src/autoship/classify.ts

@@ -0,0 +1,75 @@
+import {
+  BEHAVIOR_FILES,
+  BEHAVIOR_PREFIXES,
+  PROSE_EXTENSIONS,
+} from '@/autoship/paths'
+
+/**
+ * Which of the two tests a file failed.
+ *
+ * Named apart rather than folded into one boolean, because the repair differs.
+ * A non-prose extension means the branch carries code and review is ordinary. A
+ * behavior path means prose that states what an agent does, which is the half
+ * three sessions read past.
+ */
+export type FailedTest = 'extension' | 'behavior-path'
+
+/** Why a classification produced no reading. */
+export type ClassifyRefusal = 'no-changes'
+
+export type Classification =
+  | { readonly kind: 'skip' }
+  | {
+      readonly kind: 'review'
+      readonly test: FailedTest
+      readonly file: string
+    }
+  | { readonly kind: 'refused'; readonly reason: ClassifyRefusal }
+
+/**
+ * Prefix-anchored against the folders, matching how `resolveCoverage` reads the
+ * label map, and equality against the whole paths a prefix cannot reach.
+ */
+function underBehaviorPath(path: string): boolean {
+  if (BEHAVIOR_FILES.some((file) => file === path)) return true
+  return BEHAVIOR_PREFIXES.some((prefix) => path.startsWith(prefix))
+}
+
+function readsAsProse(path: string): boolean {
+  const lowered = path.toLowerCase()
+  return PROSE_EXTENSIONS.some((extension) => lowered.endsWith(extension))
+}
+
+/**
+ * Decides whether a branch's changed set skips the review pass.
+ *
+ * The skip needs both tests to pass: every name reads as prose, and no name
+ * sits under a behavior path. One behavior file sends the whole branch to
+ * review, since documentation shipped beside a behavior change does not cancel
+ * it.
+ *
+ * An empty set refuses rather than skipping. Both tests are universally
+ * quantified, so an empty set satisfies them vacuously, and reading that as
+ * prose-only would route a branch past review for having produced no output at
+ * all.
+ *
+ * Names only. The caller hands the set the ship chain already computed, so no
+ * second baseline is read here and the stale-baseline half stays closed.
+ */
+export function classifyChanges(paths: readonly string[]): Classification {
+  if (paths.length === 0) return { kind: 'refused', reason: 'no-changes' }
+
+  // First failure in the caller's order wins, and each file is tested for its
+  // extension before its path. A set failing both tests reports one file and
+  // one test, which is all the branch needs to route.
+  for (const path of paths) {
+    if (!readsAsProse(path)) {
+      return { kind: 'review', test: 'extension', file: path }
+    }
+    if (underBehaviorPath(path)) {
+      return { kind: 'review', test: 'behavior-path', file: path }
+    }
+  }
+
+  return { kind: 'skip' }
+}

package/src/autoship/paths.ts

@@ -0,0 +1,51 @@
+/**
+ * The surfaces where markdown states what an agent does, and the extensions
+ * that read as prose, held as data one command parses.
+ *
+ * Lifted verbatim in content from the list `claude-autoship/SKILL.md` Step 5
+ * carried, which a session was asked to apply by hand. It failed that
+ * application three times, so the set moved here and the body now calls a verb
+ * that reads it. Being machine-parsed makes it permanently exempt from any
+ * later design that folds a standard back into the surface citing it, per the
+ * machine-parsed clause in `.claude/ARCHITECTURE.md`.
+ */
+
+/**
+ * Path prefixes under which a markdown change is a behavior change.
+ *
+ * Most carry two spellings, the one a surface authors at and the one it reaches
+ * a session at, so the rule reads the same in this toolkit and in a project
+ * that consumed one. `standards/` and `snippets/` carry one apiece: neither
+ * installs into a project, reaching a reader by resolution and through the
+ * `claude/snippets` symlink respectively, so no `.claude/` spelling exists to
+ * name.
+ */
+export const BEHAVIOR_PREFIXES = [
+  'claude/skills/',
+  '.claude/skills/',
+  'governance/rules/',
+  '.claude/rules/',
+  'standards/',
+  'snippets/',
+  'internal/',
+  'tooling/',
+] as const
+
+/**
+ * Behavior surfaces named as whole paths rather than as prefixes.
+ *
+ * A path prefix reaches nothing that sits in no folder, which is what the root
+ * instruction file is. Matching is equality rather than a suffix test, so a
+ * nested `docs/CLAUDE.md` stays informational the way the body's "at the
+ * repository root" qualifier says it should.
+ */
+export const BEHAVIOR_FILES = ['CLAUDE.md'] as const
+
+/**
+ * Extensions a changed file may carry for the branch to read as prose-only.
+ *
+ * Compared lowercased, so a `README.MD` is not routed to review for its
+ * spelling. Everything else is code, a config, or an asset, and one of them
+ * sends the whole branch to review.
+ */
+export const PROSE_EXTENSIONS = ['.md', '.txt'] as const

package/src/binary.ts

@@ -0,0 +1,16 @@
+/**
+ * Whether the bytes are something a line scanner should not read.
+ *
+ * A NUL byte rather than an extension list, since a shipped tree carries fonts
+ * and images under names no scanner has reason to enumerate, and a list would
+ * go stale the first time a format was added. Decoded text holds no NUL, so the
+ * test costs one scan and never rejects source.
+ *
+ * Neutral rather than owned by either sweep that calls it. The secret scan
+ * shaped it and the superseded-value sweep reads the same corpus, so leaving it
+ * in `src/secrets/` would put a `src/gov/` dependency on the secret scanner for
+ * a predicate about bytes.
+ */
+export function isBinary(text: string): boolean {
+  return text.includes('\0')
+}

package/src/browser/engine.ts

@@ -0,0 +1,40 @@
+/**
+ * What every browser-driving command needs to know before it can report a
+ * failure honestly: how the binary is installed, and how each of the two ways
+ * it can be absent reads when it is thrown.
+ *
+ * The two are different states with different remedies. A package that never
+ * resolved means the target installed the CLI without the engine, and a binary
+ * that was never downloaded means the engine is present and its browser is not.
+ * Both were spelled inside `src/demo/` when `demo` was the only command driving
+ * a browser, and a second command is what makes them shared rather than local.
+ */
+
+/** Fetches the browser revision the pinned engine expects. */
+export const INSTALL_BROWSER = 'bunx playwright install chromium'
+
+/**
+ * Separates a browser binary that was never installed from every other launch
+ * failure, because the first is a setup step the operator has to run and the
+ * second is a defect. A target inherits that setup step, which is the stated
+ * cost of shipping a browser command outside the toolkit.
+ */
+export function isBrowserMissing(error: unknown): boolean {
+  const text = error instanceof Error ? error.message : String(error)
+  return /executable doesn't exist|playwright install/i.test(text)
+}
+
+/**
+ * Reports the engine package failing to resolve, which is the case a target
+ * hits before installing it. Any other import failure is a defect inside the
+ * module being loaded and propagates, rather than being reported as a missing
+ * dependency.
+ */
+export function isEngineMissing(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    error.code === 'ERR_MODULE_NOT_FOUND'
+  )
+}

package/src/census/count.ts

@@ -0,0 +1,113 @@
+import { readFile } from 'node:fs/promises'
+import { extname, join } from 'node:path'
+import { isBinary } from '@/binary'
+import { listRepositoryFiles } from '@/git-files'
+
+export type CensusRefusal = 'no-git'
+
+export interface ExtensionCount {
+  readonly extension: string
+  readonly files: number
+  readonly lines: number
+}
+
+export interface CensusResult {
+  readonly kind: 'measured'
+  readonly files: number
+  /** Binary or unreadable, counted toward `files` and excluded from `lines`. */
+  readonly skipped: number
+  readonly lines: number
+  readonly byExtension: readonly ExtensionCount[]
+}
+
+export interface CensusFailure {
+  readonly kind: 'refused'
+  readonly reason: CensusRefusal
+}
+
+/**
+ * Open descriptors allowed at once while reading the tree, matching
+ * `src/comments/scan.ts`. A single `Promise.all` over every path opens one
+ * descriptor per file, which exhausts a default 1024 limit on a large
+ * repository and fails the whole census with EMFILE.
+ */
+const CONCURRENT_READS = 64
+
+interface ReadOutcome {
+  readonly path: string
+  /** Absent when the read failed: a symlink leaving the tree, or a file git
+   * listed and the working tree no longer holds. */
+  readonly text?: string
+}
+
+async function readOne(root: string, path: string): Promise<ReadOutcome> {
+  try {
+    return { path, text: await readFile(join(root, path), 'utf8') }
+  } catch {
+    return { path }
+  }
+}
+
+function extensionFor(path: string): string {
+  const ext = extname(path)
+  return ext === '' ? 'no-extension' : ext.slice(1).toLowerCase()
+}
+
+/**
+ * A trailing newline is the file's terminator rather than an empty final line,
+ * which is what keeps a file ending `a\nb\n` at two lines rather than three.
+ */
+function countLines(text: string): number {
+  if (text === '') return 0
+  const lines = text.split('\n')
+  return text.endsWith('\n') ? lines.length - 1 : lines.length
+}
+
+/**
+ * Censuses the tracked-plus-untracked tree under `root`: a file count, a
+ * breakdown by extension, and a line total that skips whatever reads as
+ * binary.
+ *
+ * Reads `listRepositoryFiles`, the same corpus the citation check, the
+ * markdown corpus, and the secret scan already share, so this is not a
+ * fourth definition of what counts.
+ */
+export async function census(
+  root: string,
+): Promise<CensusResult | CensusFailure> {
+  const listed = await listRepositoryFiles(root)
+  if (listed === undefined) return { kind: 'refused', reason: 'no-git' }
+
+  const totals = new Map<string, { files: number; lines: number }>()
+  let skipped = 0
+  let lines = 0
+
+  for (let start = 0; start < listed.length; start += CONCURRENT_READS) {
+    const batch = listed.slice(start, start + CONCURRENT_READS)
+    const outcomes = await Promise.all(batch.map((path) => readOne(root, path)))
+
+    for (const outcome of outcomes) {
+      const extension = extensionFor(outcome.path)
+      const entry = totals.get(extension) ?? { files: 0, lines: 0 }
+      entry.files += 1
+
+      // A read that failed and a file that read as binary are counted the
+      // same way: toward `files`, excluded from every line count.
+      if (outcome.text === undefined || isBinary(outcome.text)) {
+        skipped += 1
+      } else {
+        const counted = countLines(outcome.text)
+        entry.lines += counted
+        lines += counted
+      }
+
+      totals.set(extension, entry)
+    }
+  }
+
+  const byExtension = [...totals.entries()]
+    .map(([extension, counts]) => ({ extension, ...counts }))
+    .sort((a, b) => b.files - a.files || a.extension.localeCompare(b.extension))
+
+  return { kind: 'measured', files: listed.length, skipped, lines, byExtension }
+}

package/src/claude/cases/all.ts

@@ -0,0 +1,24 @@
+import type { SkillCase } from '@/claude/skills-rank'
+import { AUTHORING_CASES } from '@/claude/cases/authoring'
+import { CLAUDE_WORKFLOW_CASES } from '@/claude/cases/claude-workflow'
+import { GIT_CASES } from '@/claude/cases/git'
+import { MISC_CASES } from '@/claude/cases/misc'
+import { SETUP_CASES } from '@/claude/cases/setup'
+
+/**
+ * The full routing case corpus, one file per domain so a description change
+ * in one family touches only the file beside it.
+ *
+ * Bootstrapped from each skill's own quoted trigger phrases and then
+ * rephrased and supplemented rather than shipped verbatim, since a positive
+ * lifted unchanged from a trigger passes by construction and never tests a
+ * person's own words. See `.claude/groundwork/42-ai-blueprint/08-spikes.md`
+ * for the extraction arm this corpus replaces as the shipped measure.
+ */
+export const SKILL_CASES: readonly SkillCase[] = [
+  ...CLAUDE_WORKFLOW_CASES,
+  ...GIT_CASES,
+  ...SETUP_CASES,
+  ...AUTHORING_CASES,
+  ...MISC_CASES,
+]

package/src/claude/cases/authoring.ts

@@ -0,0 +1,53 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/**
+ * Script, skill, snippet, standard, and doc authoring, plus the two prose
+ * skills that revise rather than generate.
+ */
+export const AUTHORING_CASES: readonly SkillCase[] = [
+  {
+    prompt:
+      'I need a shell tool with prompts and a nice terminal UI for people to run by hand.',
+    expect: 'bash-script',
+  },
+  {
+    prompt:
+      'Wire up a GitHub Actions pipeline with parallel jobs for this repo.',
+    expect: 'ci-workflow',
+  },
+  {
+    prompt:
+      'Write me a headless automation script with no interactive prompts.',
+    expect: 'bash-cli-script',
+  },
+  {
+    prompt: 'Scaffold a brand-new SKILL.md for this capability.',
+    expect: 'create-skill',
+  },
+  {
+    prompt: 'I need a new reusable prompt snippet added to the corpus.',
+    expect: 'create-snippet',
+  },
+  {
+    prompt: 'Write a fresh authoring convention as a new standard file.',
+    expect: 'create-standard',
+  },
+  {
+    prompt:
+      "The docs folder and README are stale against what's on main, refresh them.",
+    expect: 'docs-sync',
+  },
+  {
+    prompt: 'Say what that dense answer actually means in plain terms.',
+    expect: 'restate-plainly',
+  },
+  {
+    prompt: 'This passage reads flat and robotic, give it some real cadence.',
+    expect: 'write-human',
+  },
+  {
+    prompt:
+      'Pull the captions off this YouTube link and save them with metadata.',
+    expect: 'youtube-transcripts',
+  },
+]