@erclx/canon 4.0.0

package/src/commands/feedback.ts

@@ -0,0 +1,112 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Command } from 'commander'
+import { deriveSlug, deriveTitle } from '@/commands/feedback-format'
+import { PROJECT_ROOT } from '@/project-root'
+import { createGithubIssue } from '@/github'
+import { frameError, frameSuccess, palette } from '@/ui'
+
+function readStdin(): Promise<string> {
+  return new Promise((resolveStream, rejectStream) => {
+    const chunks: Buffer[] = []
+    process.stdin.on('data', (chunk: Buffer) => chunks.push(chunk))
+    process.stdin.on('end', () =>
+      resolveStream(Buffer.concat(chunks).toString('utf8')),
+    )
+    process.stdin.on('error', rejectStream)
+  })
+}
+
+function timestamp(): string {
+  const d = new Date()
+  const pad = (n: number): string => n.toString().padStart(2, '0')
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`
+}
+
+/**
+ * A registry install ships no `.claude/`, so a local write would land inside
+ * `node_modules/` and report a project-relative path the operator cannot find.
+ * The toolkit source is the only root where local scratch reaches a maintainer.
+ */
+function isToolkitSource(): boolean {
+  return existsSync(join(PROJECT_ROOT, '.claude'))
+}
+
+/**
+ * One producer, one subfolder. The review folder carries the output of four
+ * unrelated producers, and the filename prefix was doing the folder's job by
+ * hand, so each writes under its own name and the enclosing folder keeps the
+ * single ignore entry and the single backed-folder entry it already had.
+ */
+function writeLocal(body: string): string {
+  const relativeDir = join('.claude', 'review', 'feedback')
+  const reviewDir = join(PROJECT_ROOT, relativeDir)
+  mkdirSync(reviewDir, { recursive: true })
+  const filename = `feedback-${deriveSlug(body)}-${timestamp()}.md`
+  const filePath = join(reviewDir, filename)
+  writeFileSync(filePath, `${body}\n`, 'utf8')
+  frameSuccess('canon feedback', join(relativeDir, filename))
+  return filePath
+}
+
+export function register(program: Command): void {
+  program
+    .command('feedback')
+    .description(
+      'Write toolkit feedback from stdin to .claude/review/feedback/, or open a GitHub issue with --github',
+    )
+    .option(
+      '--github',
+      'Open a GitHub issue on the toolkit repo instead of writing local scratch',
+    )
+    .action(async (opts: { github?: boolean }) => {
+      if (process.stdin.isTTY) {
+        frameError(
+          'No feedback on stdin. Pipe a markdown block: pbpaste | canon feedback',
+        )
+        process.exitCode = 1
+        return
+      }
+      const body = (await readStdin()).trim()
+      if (!body) {
+        frameError('Empty feedback body. Provide a markdown block on stdin.')
+        process.exitCode = 1
+        return
+      }
+
+      if (opts.github) {
+        const url = await createGithubIssue({
+          title: deriveTitle(body),
+          body,
+          labels: ['feedback'],
+        })
+        if (url) {
+          frameSuccess('canon feedback', url)
+          process.stdout.write(`${url}\n`)
+          return
+        }
+        if (!isToolkitSource()) {
+          frameError(
+            'gh unavailable and no toolkit source to fall back to. Install gh, or file it at https://github.com/erclx/canon/issues/new',
+          )
+          process.exitCode = 1
+          return
+        }
+        const { NC, YELLOW } = palette(process.stderr)
+        process.stderr.write(
+          `${YELLOW}! gh unavailable, wrote local scratch instead${NC}\n`,
+        )
+      }
+
+      if (!isToolkitSource()) {
+        frameError(
+          'Local scratch needs the toolkit source. Re-run with --github to open an issue instead.',
+        )
+        process.exitCode = 1
+        return
+      }
+
+      const filePath = writeLocal(body)
+      process.stdout.write(`${filePath}\n`)
+    })
+}

package/src/commands/gate.ts

@@ -0,0 +1,189 @@
+import type { Command } from 'commander'
+import {
+  cliRunner,
+  collectChangedFiles,
+  commandRunner,
+  exitCodeFor,
+  type GateContext,
+  repairBareFlag,
+  type StageResult,
+  type Summary,
+  runStages,
+  summarize,
+} from '@/gate/sequencer'
+import { STAGES } from '@/gate/stages'
+import { PROJECT_ROOT } from '@/project-root'
+import {
+  intro,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  palette,
+  pipeOutput,
+  plural,
+} from '@/ui'
+
+interface RunCommandOptions {
+  readonly all?: boolean
+  readonly write?: boolean
+  readonly nested?: boolean
+  readonly json?: boolean
+}
+
+export function register(program: Command): void {
+  const gate = program
+    .command('gate')
+    .description('Run the merge gate this repository verifies a branch with')
+    .helpOption('-h, --help', 'Show this help message')
+
+  gate
+    .command('run')
+    .description(
+      'Run every gating stage in order, scoping shell, types, and tests to the changed set',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--all',
+      'Run every stage instead of scoping shell, types, and tests to changed files',
+    )
+    .option(
+      '--no-write',
+      'Check formatting instead of applying it, which is what a merge gate wants',
+    )
+    .option(
+      '--nested',
+      'Suppress the outer frame when another script opened one',
+    )
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every stage that ran reported, and none found a fact',
+        '  1  a stage found a fact, or could not measure its input under CI',
+        '',
+        'A stage halts the run, so clearing a regenerate-then-assert stage',
+        'reveals the next one behind it rather than the whole set at once.',
+        '',
+        'A stage that cannot read its input reports rather than passing. On a',
+        "contributor's machine that is a warning and the run still exits 0,",
+        'because an absent tool there is somebody mid-setup. Under CI it',
+        'refuses, because the same absence is a broken workflow step and a',
+        'green run over a stage that measured nothing is the pass the gate',
+        'exists to withhold.',
+        '',
+        'Examples:',
+        '  canon gate run',
+        '  canon gate run --all --no-write',
+        '  canon gate run --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RunCommandOptions) => {
+      process.exitCode = await runGate(opts)
+    })
+}
+
+async function runGate(opts: RunCommandOptions): Promise<number> {
+  const root = PROJECT_ROOT
+  const emitJson = opts.json ?? false
+  const nested = opts.nested ?? false
+  const write = opts.write ?? true
+  const run = commandRunner(root)
+
+  if (!emitJson && !nested) intro('canon gate run')
+
+  await repairBareFlag(root)
+
+  const changed = opts.all
+    ? { scoped: false, files: [] }
+    : await collectChangedFiles(run)
+  if (!emitJson && changed.notice !== undefined) logWarn(changed.notice)
+
+  const ctx: GateContext = {
+    root,
+    ci: process.env.CI === 'true',
+    run,
+    cli: cliRunner(root),
+    write,
+    changed: changed.scoped ? changed.files : undefined,
+  }
+
+  const results = await runStages(
+    STAGES,
+    ctx,
+    emitJson ? undefined : (result) => report(result),
+  )
+  const summary = summarize(results)
+  const code = exitCodeFor(results)
+
+  if (emitJson) {
+    const failed = results.find((result) => result.status === 'failed')
+    // Diagnostics reach stderr in every mode, so a caller reading the record
+    // alone is not the only one told what went wrong.
+    if (failed?.failure !== undefined) {
+      process.stderr.write(`${failed.label}: ${failed.failure}\n`)
+    }
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: code === 0,
+        root,
+        scoped: changed.scoped,
+        changed: changed.files.length,
+        summary,
+        stages: results.map(({ id, label, status, failure }) => ({
+          id,
+          label,
+          status,
+          failure,
+        })),
+      })}\n`,
+    )
+    return code
+  }
+
+  if (!nested) close(summary, code)
+  return code
+}
+
+function report(result: StageResult): void {
+  logStep(result.label)
+  for (const emission of result.emissions) {
+    if (emission.kind === 'info') logInfo(emission.text)
+    else if (emission.kind === 'warn') logWarn(emission.text)
+    else pipeOutput(emission.text)
+  }
+  if (result.failure !== undefined) logError(result.failure)
+}
+
+/**
+ * The closing verdict, which names what the run did not measure rather than
+ * reporting a bare pass over it.
+ *
+ * A run where every stage read its input still closes on the line the script
+ * this replaces closed on, so nothing about the ordinary case moved. A run
+ * carrying an unmeasured stage says so, because a green line over a stage that
+ * looked at nothing is exactly the silence the reporting outcome exists
+ * against.
+ */
+function close(summary: Summary, code: number): void {
+  const { GREEN, NC, RED, YELLOW } = palette(process.stderr)
+  outro()
+
+  if (code !== 0) {
+    process.stderr.write(`${RED}✗ Verification failed${NC}\n\n`)
+    return
+  }
+
+  if (summary.unmeasured > 0) {
+    process.stderr.write(
+      `${YELLOW}! Verification passed, ${plural(summary.unmeasured, 'stage')} measured nothing${NC}\n\n`,
+    )
+    return
+  }
+
+  process.stderr.write(`${GREEN}✓ Verification passed${NC}\n\n`)
+}