@erclx/canon 5.63.0 → 5.65.0

package/src/commands/context.ts

@@ -30,26 +30,6 @@ import {
   type ShapeIssue,
 } from '@/context/audit'
 import { auditCitations, type CitationReport } from '@/context/citations'
-import {
-  CANONICAL_DOC_TYPES,
-  type CanonicalDocType,
-} from '@/context/classify/extract'
-import {
-  classifyDiff,
-  classifySweep,
-  type ClassifyOutcome,
-  type ClassifyRefusal,
-  type DiffFinding,
-  type DiffRecord,
-  type SweepFinding,
-  type SweepRecord,
-} from '@/context/classify/run'
-import {
-  CLASSIFIER_CONFIG_REL,
-  type ClassifierBackend,
-  resolveClassifier,
-  writeClassifierConfig,
-} from '@/context/classify/settings'
 import {
   type AuditedFolder,
   DEFAULT_FOLDERS,
@@ -159,411 +139,6 @@ export function register(program: Command): void {
     .action(async (path: string | undefined, opts: AuditCommandOptions) => {
       process.exitCode = await runAudit(path, opts)
     })
-
-  const classify = context
-    .command('classify')
-    .description(
-      'Classify canonical-doc content as keep, replace/rewrite, history, or move',
-    )
-    .helpOption('-h, --help', 'Show this help message')
-
-  classify
-    .command('diff')
-    .description(
-      'Classify the chunks a git range changed, each with the section it landed in',
-    )
-    .argument('[path]', 'Project root, defaulting to the current directory')
-    .helpOption('-h, --help', 'Show this help message')
-    .option('--base <ref>', 'Far side of the range, defaulting to the trunk')
-    .option(
-      '--doc-types <list>',
-      `Comma-separated canonical doc types (default: all three: ${CANONICAL_DOC_TYPES.join(', ')})`,
-    )
-    .option(
-      '--backend <name>',
-      'Override the resolved model backend for this run',
-    )
-    .option('--model <name>', 'Override the resolved model name for this run')
-    .option('--json', 'Add a machine-readable record on stdout')
-    .addHelpText(
-      'after',
-      [
-        '',
-        'The regex layer always runs. The model layer runs only when a',
-        'backend resolves through `canon context classifier show`, and a',
-        'configured-but-unreachable backend warns and falls back to regex',
-        'rather than failing the run.',
-        '',
-        'Exit codes:',
-        '  0  the run completed, whatever the findings say',
-        '  1  refused: a bad range or a file this could not read',
-        '',
-        'Examples:',
-        '  canon context classify diff',
-        '  canon context classify diff --base origin/main --json',
-        '  canon context classify diff --doc-types context',
-        '',
-      ].join('\n'),
-    )
-    .action(async (path: string | undefined, opts: ClassifyDiffOptions) => {
-      process.exitCode = await runClassifyDiff(path, opts)
-    })
-
-  classify
-    .command('sweep')
-    .description(
-      'Classify every section of the three canonical doc types, split at H3',
-    )
-    .argument('[path]', 'Project root, defaulting to the current directory')
-    .helpOption('-h, --help', 'Show this help message')
-    .option(
-      '--doc-types <list>',
-      `Comma-separated canonical doc types (default: all three: ${CANONICAL_DOC_TYPES.join(', ')})`,
-    )
-    .option(
-      '--backend <name>',
-      'Override the resolved model backend for this run',
-    )
-    .option('--model <name>', 'Override the resolved model name for this run')
-    .option('--json', 'Add a machine-readable record on stdout')
-    .addHelpText(
-      'after',
-      [
-        '',
-        'Exit codes:',
-        '  0  the run completed, whatever the findings say',
-        '  1  refused: a file this could not read',
-        '',
-        'Examples:',
-        '  canon context classify sweep',
-        '  canon context classify sweep --doc-types design,requirements --json',
-        '',
-      ].join('\n'),
-    )
-    .action(async (path: string | undefined, opts: ClassifySweepOptions) => {
-      process.exitCode = await runClassifySweep(path, opts)
-    })
-
-  const classifier = context
-    .command('classifier')
-    .description('Read or write the project classifier setting')
-    .helpOption('-h, --help', 'Show this help message')
-
-  classifier
-    .command('show')
-    .description(
-      'Report the backend and model that would run, and which source decided it',
-    )
-    .argument('[path]', 'Project root, defaulting to the current directory')
-    .helpOption('-h, --help', 'Show this help message')
-    .option('--json', 'Add a machine-readable record on stdout')
-    .action((path: string | undefined, opts: { json?: boolean }) => {
-      runClassifierShow(path, opts)
-    })
-
-  classifier
-    .command('set')
-    .description('Write the project classifier setting')
-    .argument('[path]', 'Project root, defaulting to the current directory')
-    .helpOption('-h, --help', 'Show this help message')
-    .requiredOption('--backend <name>', 'ollama or off')
-    .option('--model <name>', 'Model name, required when --backend is ollama')
-    .option('--json', 'Add a machine-readable record on stdout')
-    .action((path: string | undefined, opts: ClassifierSetOptions) => {
-      process.exitCode = runClassifierSet(path, opts)
-    })
-}
-
-interface ClassifyDiffOptions {
-  readonly json?: boolean
-  readonly base?: string
-  readonly docTypes?: string
-  readonly backend?: string
-  readonly model?: string
-}
-
-interface ClassifySweepOptions {
-  readonly json?: boolean
-  readonly docTypes?: string
-  readonly backend?: string
-  readonly model?: string
-}
-
-interface ClassifierSetOptions {
-  readonly json?: boolean
-  readonly backend: string
-  readonly model?: string
-}
-
-function parseDocTypes(
-  list: string | undefined,
-): readonly CanonicalDocType[] | string {
-  if (!list) return CANONICAL_DOC_TYPES
-
-  const names = list
-    .split(',')
-    .map((name) => name.trim())
-    .filter(Boolean)
-
-  const invalid = names.filter(
-    (name) => !CANONICAL_DOC_TYPES.includes(name as CanonicalDocType),
-  )
-  if (invalid.length > 0) {
-    return `--doc-types takes ${CANONICAL_DOC_TYPES.join(', ')}: ${invalid.join(', ')}`
-  }
-
-  return names as CanonicalDocType[]
-}
-
-/**
- * Validates `--backend` up front, so a typo'd value refuses rather than
- * falling through `resolveBackend`'s tier chain to the environment, the
- * file, or the default, which reads as the flag having been ignored.
- */
-function parseBackendFlag(value: string | undefined): string | undefined {
-  if (value === undefined || value === 'ollama' || value === 'off') {
-    return undefined
-  }
-  return `--backend takes ollama or off: ${value}`
-}
-
-/** Widens the extraction refusals with the CLI's own argument-parsing failure. */
-type CliRefusal = ClassifyRefusal | 'bad-flags'
-
-function refuseClassify(
-  reason: CliRefusal,
-  message: string,
-  emitJson: boolean,
-): number {
-  intro('canon context classify')
-  logStep('Refused')
-  logWarn(message)
-  outro()
-
-  if (emitJson) {
-    process.stdout.write(
-      `${JSON.stringify({ decision: 'refused', reason, message })}\n`,
-    )
-  }
-  return 1
-}
-
-/** How each not-off model-layer state reads in the report. */
-const MODEL_LAYER_LABEL: Record<string, string> = {
-  ran: 'ran',
-  'skipped-no-model': 'skipped, no model resolved for the configured backend',
-  'skipped-unreachable': 'skipped, the configured backend did not answer',
-}
-
-function reportLayers(record: DiffRecord | SweepRecord): void {
-  logStep('Layers')
-  logInfo('regex: ran')
-
-  if (record.modelLayer === 'off') {
-    logInfo('model: off, no backend configured')
-    return
-  }
-
-  logInfo(
-    `model: ${MODEL_LAYER_LABEL[record.modelLayer]} (${record.backend ?? 'none'}${record.model ? `, ${record.model}` : ''})`,
-  )
-  if (record.modelLayer !== 'ran') {
-    logWarn('Falling back to the regex layer alone for this run.')
-  }
-}
-
-function reportFindings(
-  findings: readonly (DiffFinding | SweepFinding)[],
-  label: (finding: DiffFinding | SweepFinding) => string,
-): void {
-  logStep('Findings')
-
-  if (findings.length === 0) {
-    logInfo('Nothing met the extraction floor under the requested doc types.')
-    return
-  }
-
-  const flagged = findings.filter((finding) => finding.verdict !== 'KEEP')
-  logInfo(
-    `${plural(findings.length, 'item')} read, ${plural(flagged.length, 'flagged')}`,
-  )
-
-  if (flagged.length === 0) return
-
-  pipeOutput(
-    flagged
-      .map((finding) => {
-        const chosen =
-          finding.decidedBy === 'model' ? finding.model : finding.regex
-        return `${label(finding)}  ${finding.verdict} (${finding.decidedBy})\n  ${chosen?.quote ? `"${chosen.quote}"  ` : ''}${chosen?.reason ?? ''}`
-      })
-      .join('\n'),
-  )
-}
-
-async function runClassifyDiff(
-  path: string | undefined,
-  opts: ClassifyDiffOptions,
-): Promise<number> {
-  const root = resolve(path ?? process.cwd())
-  const emitJson = opts.json ?? false
-
-  const docTypes = parseDocTypes(opts.docTypes)
-  if (typeof docTypes === 'string') {
-    return refuseClassify('bad-flags', docTypes, emitJson)
-  }
-
-  const backendError = parseBackendFlag(opts.backend)
-  if (backendError !== undefined) {
-    return refuseClassify('bad-flags', backendError, emitJson)
-  }
-
-  const result: ClassifyOutcome<DiffRecord> = await classifyDiff(
-    root,
-    opts.base,
-    {
-      docTypes,
-      flags: { backend: opts.backend, model: opts.model },
-    },
-  )
-
-  if (result.kind === 'refused') {
-    return refuseClassify(result.reason, result.message, emitJson)
-  }
-
-  intro('canon context classify diff')
-  reportLayers(result.record)
-  reportFindings(result.record.findings, (finding) => finding.file)
-  outro()
-
-  if (emitJson) {
-    process.stdout.write(
-      `${JSON.stringify({ decision: 'ok', ...result.record })}\n`,
-    )
-  }
-
-  return 0
-}
-
-async function runClassifySweep(
-  path: string | undefined,
-  opts: ClassifySweepOptions,
-): Promise<number> {
-  const root = resolve(path ?? process.cwd())
-  const emitJson = opts.json ?? false
-
-  const docTypes = parseDocTypes(opts.docTypes)
-  if (typeof docTypes === 'string') {
-    return refuseClassify('bad-flags', docTypes, emitJson)
-  }
-
-  const backendError = parseBackendFlag(opts.backend)
-  if (backendError !== undefined) {
-    return refuseClassify('bad-flags', backendError, emitJson)
-  }
-
-  const result: ClassifyOutcome<SweepRecord> = await classifySweep(root, {
-    docTypes,
-    flags: { backend: opts.backend, model: opts.model },
-  })
-
-  if (result.kind === 'refused') {
-    return refuseClassify(result.reason, result.message, emitJson)
-  }
-
-  intro('canon context classify sweep')
-  reportLayers(result.record)
-  reportFindings(
-    result.record.findings,
-    (finding) => `${finding.file}:${(finding as SweepFinding).heading}`,
-  )
-  outro()
-
-  if (emitJson) {
-    process.stdout.write(
-      `${JSON.stringify({ decision: 'ok', ...result.record })}\n`,
-    )
-  }
-
-  return 0
-}
-
-function runClassifierShow(
-  path: string | undefined,
-  opts: { json?: boolean },
-): void {
-  const root = resolve(path ?? process.cwd())
-  const resolution = resolveClassifier(root, {})
-
-  intro('canon context classifier show')
-
-  if (resolution.kind === 'off') {
-    logInfo(
-      `Model layer off (source: ${resolution.source}). Regex layer always runs.`,
-    )
-  } else if (resolution.kind === 'no-model') {
-    logWarn(
-      `Backend ${resolution.backend} configured (source: ${resolution.source}) with no model name. \`classify\` runs regex only.`,
-    )
-  } else {
-    logInfo(
-      `Backend ${resolution.backend}, model ${resolution.model} (source: ${resolution.source}).`,
-    )
-  }
-
-  logInfo(
-    `Reads ${CLASSIFIER_CONFIG_REL} when neither a flag nor an environment variable decides.`,
-  )
-  outro()
-
-  if (opts.json) {
-    process.stdout.write(`${JSON.stringify(resolution)}\n`)
-  }
-}
-
-function runClassifierSet(
-  path: string | undefined,
-  opts: ClassifierSetOptions,
-): number {
-  const root = resolve(path ?? process.cwd())
-  const emitJson = opts.json ?? false
-
-  if (opts.backend !== 'ollama' && opts.backend !== 'off') {
-    return refuseClassify(
-      'bad-flags',
-      '--backend takes ollama or off.',
-      emitJson,
-    )
-  }
-
-  if (opts.backend === 'ollama' && !opts.model) {
-    return refuseClassify(
-      'bad-flags',
-      '--model is required when --backend is ollama.',
-      emitJson,
-    )
-  }
-
-  const backend: ClassifierBackend | 'off' = opts.backend
-  writeClassifierConfig(
-    root,
-    backend,
-    backend === 'off' ? undefined : opts.model,
-  )
-
-  intro('canon context classifier set')
-  logInfo(
-    `Wrote ${CLASSIFIER_CONFIG_REL}: backend ${opts.backend}${opts.model ? `, model ${opts.model}` : ''}.`,
-  )
-  outro()
-
-  if (emitJson) {
-    process.stdout.write(
-      `${JSON.stringify({ decision: 'ok', backend: opts.backend, model: opts.model })}\n`,
-    )
-  }
-
-  return 0
 }
 
 function parseFolders(list: string | undefined): string[] | string {

package/src/commands/sandbox.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { basename, dirname, join, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
 import {
@@ -27,8 +27,24 @@ import {
 } from '@/sandbox/expect'
 import { runHeadless } from '@/sandbox/headless/run'
 import { runSandbox } from '@/sandbox/provision'
+import {
+  EXPECTED_FILE,
+  expectationOf,
+  judgeDrift,
+  readExpectation,
+  writeExpectation,
+  type ReplayExpectation,
+} from '@/sandbox/replay/expected'
+import {
+  checkoutRefusal,
+  hasFormatter,
+  listSnapshots,
+  replaySource,
+  type ReplayResult,
+  type ReplaySource,
+} from '@/sandbox/replay/run'
 import { listCategories, listScenarioFiles } from '@/sandbox/scenario'
-import { sandboxTree } from '@/sandbox/tree'
+import { assertSandboxDirSafe, sandboxRoots, sandboxTree } from '@/sandbox/tree'
 import {
   frameError,
   intro,
@@ -434,6 +450,194 @@ async function runEquivalence(
   process.exitCode = equivalenceExitCode(record)
 }
 
+interface ReplayOptions {
+  readonly json?: boolean
+  readonly record?: boolean
+}
+
+const REPLAY_FINDINGS_SHOWN = 5
+
+function refuseReplay(reason: string, message: string, json: boolean): void {
+  logError(message)
+  if (json)
+    process.stdout.write(`${JSON.stringify({ ok: false, reason, message })}\n`)
+  outro()
+  process.exitCode = 1
+}
+
+/**
+ * Replays each consumer through a sync with this checkout's CLI and judges
+ * the reads that follow. Bare, it replays the frozen snapshots, which is what
+ * the gate runs. Given paths, it copies each real checkout, the operator's
+ * step before a release. Every source is checked before any replay starts, so
+ * a refusal never arrives after half the runs. A snapshot is judged against
+ * the answer recorded beside it, since a frozen tree answers the same on every
+ * push, and `--record` rewrites that answer from a run that broke nothing.
+ */
+function runReplay(paths: string[], options: ReplayOptions): void {
+  if (reportAbsentScenarioTree()) return
+
+  intro('canon sandbox replay')
+  const json = options.json === true
+  const record = options.record === true
+
+  if (record && paths.length > 0) {
+    refuseReplay(
+      'record-checkout',
+      'A named checkout moves between runs, so --record pins snapshots only. Drop the paths.',
+      json,
+    )
+    return
+  }
+
+  if (!hasFormatter(PROJECT_ROOT)) {
+    refuseReplay(
+      'no-formatter',
+      'No oxfmt under node_modules, so the format step cannot run. Run bun install in this checkout.',
+      json,
+    )
+    return
+  }
+
+  let sources: ReplaySource[]
+  if (paths.length === 0) {
+    sources = listSnapshots(join(SANDBOX_DIR, 'fixtures', 'replay'))
+    if (sources.length === 0) {
+      refuseReplay(
+        'no-snapshots',
+        'No snapshot under sandbox/fixtures/replay/',
+        json,
+      )
+      return
+    }
+  } else {
+    sources = []
+    for (const raw of paths) {
+      const path = resolve(process.cwd(), raw)
+      const refusal = checkoutRefusal(path)
+      if (refusal !== undefined) {
+        refuseReplay(refusal.reason, refusal.message, json)
+        return
+      }
+      sources.push({ name: basename(path), path, kind: 'checkout' })
+    }
+  }
+
+  // Beside the provisioned tree rather than inside it, since `canon sandbox
+  // clean` wipes that one and a concurrent replay would lose its tree.
+  const tempRoot = join(dirname(sandboxTree()), 'replay')
+  const unsafe = assertSandboxDirSafe(
+    join(tempRoot, 'tree'),
+    sandboxRoots(PROJECT_ROOT),
+  )
+  if (unsafe !== undefined) {
+    refuseReplay('unsafe-root', unsafe, json)
+    return
+  }
+
+  const expectations = new Map<string, ReplayExpectation | undefined>()
+  if (!record)
+    for (const source of sources) {
+      if (source.kind !== 'snapshot') continue
+      try {
+        expectations.set(source.name, readExpectation(source.path))
+      } catch (error) {
+        refuseReplay('bad-expectation', (error as Error).message, json)
+        return
+      }
+    }
+
+  const replays: ReplayResult[] = []
+  for (const source of sources) {
+    const run = replaySource(source, {
+      checkoutRoot: PROJECT_ROOT,
+      tempRoot,
+    })
+    const result: ReplayResult =
+      source.kind === 'snapshot' && !record
+        ? {
+            ...run,
+            steps: judgeDrift(run.steps, expectations.get(source.name)),
+          }
+        : run
+    replays.push(result)
+
+    logStep(`${result.name} (${result.kind})`)
+    for (const step of result.steps) {
+      if (step.verdict === 'ok') logInfo(`${step.step}, exit ${step.exit}`)
+      else
+        logError(`${result.name}: ${step.step} ${step.verdict}: ${step.detail}`)
+      // A sync over an old layout prints a line per rule it moves, so the
+      // frame shows the first few and the record carries every one.
+      if (json) continue
+      for (const finding of step.findings.slice(0, REPLAY_FINDINGS_SHOWN))
+        logWarn(`${step.step}: ${finding}`)
+      const hidden = step.findings.length - REPLAY_FINDINGS_SHOWN
+      if (hidden > 0)
+        logWarn(`${step.step}: ${hidden} more, listed under --json`)
+    }
+  }
+
+  const failed = replays
+    .flatMap((r) => r.steps)
+    .filter((s) => s.verdict !== 'ok')
+
+  if (record) {
+    recordReplays(sources, replays, failed.length, json)
+    return
+  }
+
+  logStep('Replay')
+  const summary = `${replays.length} replayed, ${failed.length} failed steps`
+  if (failed.length === 0) logInfo(summary)
+  else logWarn(summary)
+
+  if (json)
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, failed: failed.length, replays })}\n`,
+    )
+
+  outro()
+  process.exitCode = failed.length === 0 ? 0 : 2
+}
+
+/**
+ * Writes each snapshot's expectation from its run, or refuses and writes none
+ * when any step broke, since pinning a crash would make it the expected answer.
+ */
+function recordReplays(
+  sources: readonly ReplaySource[],
+  replays: readonly ReplayResult[],
+  broken: number,
+  json: boolean,
+): void {
+  if (broken > 0) {
+    refuseReplay(
+      'broken-run',
+      `${broken} steps broke, so nothing was recorded. Fix the run, then record it.`,
+      json,
+    )
+    return
+  }
+
+  logStep('Record')
+  const recorded: string[] = []
+  for (const [i, source] of sources.entries()) {
+    const replay = replays[i]
+    if (replay === undefined) continue
+    writeExpectation(source.path, expectationOf(replay.steps))
+    const path = relative(PROJECT_ROOT, join(source.path, EXPECTED_FILE))
+    recorded.push(path)
+    logInfo(path)
+  }
+
+  if (json)
+    process.stdout.write(`${JSON.stringify({ ok: true, recorded, replays })}\n`)
+
+  outro()
+  process.exitCode = 0
+}
+
 function runCheck(
   target: string,
   arm: string | undefined,
@@ -683,4 +887,45 @@ export function register(program: Command): void {
     .action((targets: string[], options: EquivalenceOptions) =>
       runEquivalence(targets, options),
     )
+
+  sandbox
+    .command('replay')
+    .description(
+      'Sync a copy of each consumer with this checkout and judge the reads that follow',
+    )
+    .argument(
+      '[paths...]',
+      'Consumer checkouts to copy, defaulting to every snapshot under sandbox/fixtures/replay/',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit the record as JSON on stdout')
+    .option(
+      '--record',
+      `Write each snapshot's ${EXPECTED_FILE} from this run instead of judging against it`,
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Examples:',
+        '  canon sandbox replay',
+        '  canon sandbox replay --record',
+        '  canon sandbox replay ../frameboard ../jobtriage --json',
+        '',
+        'Each replay copies the source to a temp tree outside the repository,',
+        'runs sync, then sync --check, context audit, markdown audit, and',
+        'migrate status, and checks what sync wrote with oxfmt. A finding or a',
+        'refusal from a read is the verb working. Only a crash, stdout a --json',
+        'caller cannot parse, or an unformatted write fails the run.',
+        'A snapshot also fails a step whose exit or finding count drifted from',
+        `the ${EXPECTED_FILE} beside it, and fails every step when it has none.`,
+        '--record rewrites those files, refusing named paths and a broken run.',
+        'A named checkout with uncommitted changes is refused, never synced over.',
+        '',
+        'Exit codes: 0 clean or recorded, 1 refused, 2 when any step failed.',
+      ].join('\n'),
+    )
+    .action((paths: string[], options: ReplayOptions) => {
+      runReplay(paths, options)
+    })
 }