@erclx/canon 5.57.0 → 5.59.0

package/scripts/core/install-check.ts

@@ -0,0 +1,193 @@
+/**
+ * Verifies the published install path end to end: packs this repo, installs
+ * the tarball for production, and runs `canon init` from it into a fresh
+ * project. Runs on Bun alone.
+ */
+import { existsSync, mkdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  intro,
+  logError,
+  logInfo,
+  logStep,
+  outro,
+  pipeOutput,
+} from '../../src/cli/ui'
+
+const root = fileURLToPath(new URL('../..', import.meta.url)).replace(/\/$/, '')
+const tmpRoot = join(root, '.canon/tmp/install-check')
+const packDir = join(tmpRoot, 'pack')
+const extractDir = join(tmpRoot, 'extract')
+const targetDir = join(tmpRoot, 'target')
+
+const HELP = `Usage: scripts/core/install-check.ts [--keep]
+
+Verifies the published install path end to end:
+  1. Packs this repo into a tarball at .canon/tmp/install-check/pack
+  2. Extracts it and asserts sandbox is absent from the tree
+  3. Runs bun install --production in the extracted tree
+  4. Runs the CLI with --help from the extracted tree to confirm it resolves
+  5. Scaffolds a fresh project in .canon/tmp/install-check/target
+  6. Runs canon init from the extracted package and asserts a scaffold landed
+
+Flags:
+  --keep    Keep the tmp tree on exit for inspection
+`
+
+/**
+ * Every domain canon init installs needs at least one path here. A domain with
+ * no assertion can truncate silently: init still exits 0 because run_domain
+ * catches a failed domain, and the gate stays green while the target is
+ * missing everything that domain provides.
+ *
+ * Authoring references name no path because they ship inside the plugin's
+ * skills rather than installing into a target. The two rule paths stand for
+ * the `claude` and `canon` groups `base` takes whole.
+ */
+const SCAFFOLD_PATHS = [
+  'CLAUDE.md',
+  '.claude',
+  'canon/context/index.md',
+  '.oxfmtrc.json',
+  '.lintstagedrc',
+  '.husky/pre-commit',
+  '.github/workflows/verify.yml',
+  'scripts/verify.ts',
+  '.claude/rules/canon/claude/output.md',
+  '.claude/rules/canon/canon/scratch.md',
+]
+
+const args = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(HELP)
+  process.exit(0)
+}
+const keep = args.includes('--keep')
+
+/** Runs a command to completion, showing its output inside the frame. */
+function run(
+  failure: string,
+  cmd: string[],
+  opts: { cwd?: string; show?: boolean } = {},
+): string {
+  const result = Bun.spawnSync(cmd, {
+    cwd: opts.cwd ?? root,
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const stdout = result.stdout.toString()
+  const output = `${stdout}${result.stderr.toString()}`.trim()
+  if (opts.show && output !== '') pipeOutput(output)
+  if (result.exitCode !== 0) {
+    if (!opts.show && output !== '') pipeOutput(output)
+    throw new Error(failure)
+  }
+  return stdout
+}
+
+function check(): void {
+  logStep('Assert excluded path exists in source')
+  // An absence check over a path the source tree no longer holds passes on
+  // nothing, so the excluded tree has to exist here before its absence below
+  // can mean the publish left it out.
+  if (!existsSync(join(root, 'sandbox/exempt.toml'))) {
+    throw new Error(
+      'sandbox/exempt.toml is missing from the source tree, so the absence check below would pass on nothing',
+    )
+  }
+  logInfo('Present: sandbox/exempt.toml')
+
+  logStep('Pack')
+  const packed = run('bun pm pack failed', [
+    'bun',
+    'pm',
+    'pack',
+    '--quiet',
+    '--ignore-scripts',
+    '--destination',
+    packDir,
+  ])
+  const tarball = packed.trim().split('\n').pop() ?? ''
+  logInfo(`Packed to ${tarball}`)
+
+  logStep('Extract')
+  run('tar extract failed', [
+    'tar',
+    '-xzf',
+    tarball,
+    '-C',
+    extractDir,
+    '--strip-components=1',
+  ])
+  logInfo(`Extracted to ${extractDir}`)
+
+  logStep('Assert excluded path is absent')
+  if (existsSync(join(extractDir, 'sandbox'))) {
+    throw new Error(
+      'sandbox shipped in the tarball, and the files field in package.json leaves it out',
+    )
+  }
+  logInfo('Absent: sandbox')
+
+  logStep('Install dependencies (production)')
+  run(
+    'bun install --production failed',
+    ['bun', 'install', '--production', '--ignore-scripts', '--silent'],
+    { cwd: extractDir, show: true },
+  )
+  logInfo('Dependencies installed without devDependencies')
+
+  logStep('Confirm CLI runs')
+  run('canon --help failed', ['bun', 'run', 'src/cli.ts', '--help'], {
+    cwd: extractDir,
+  })
+  logInfo('canon --help ran clean from the extracted package')
+
+  logStep('Scaffold fresh project')
+  mkdirSync(targetDir, { recursive: true })
+  run('git init failed', ['git', 'init', '--quiet'], { cwd: targetDir })
+  logInfo(`Initialized git in ${targetDir}`)
+
+  logStep('Run canon init')
+  run(
+    'canon init failed',
+    ['bun', 'run', join(extractDir, 'src/cli.ts'), 'init', '--stack', 'base'],
+    { cwd: targetDir, show: true },
+  )
+  logInfo('canon init completed')
+
+  logStep('Assert scaffold')
+  for (const path of SCAFFOLD_PATHS) {
+    if (!existsSync(join(targetDir, path))) {
+      throw new Error(`Missing after canon init: ${path}`)
+    }
+    logInfo(`Found: ${path}`)
+  }
+
+  logStep('Verification passed')
+  logInfo('Manual check still needed: bun link and global canon invocation')
+}
+
+rmSync(tmpRoot, { recursive: true, force: true })
+mkdirSync(packDir, { recursive: true })
+mkdirSync(extractDir, { recursive: true })
+
+intro('Install verification')
+let failed = false
+try {
+  check()
+} catch (error) {
+  failed = true
+  logError(error instanceof Error ? error.message : String(error))
+} finally {
+  if (keep) {
+    logInfo(`Kept artifacts at ${tmpRoot}`)
+  } else {
+    rmSync(tmpRoot, { recursive: true, force: true })
+  }
+  outro()
+}
+process.exit(failed ? 1 : 0)

package/src/cli/retired.ts

@@ -0,0 +1,63 @@
+export interface RetiredVerb {
+  /** The words a caller types after `canon`, one for a group and two for a subcommand. */
+  readonly path: readonly string[]
+  /** The release that dropped the verb, from the changelog. */
+  readonly release: string
+  readonly movedTo: string
+}
+
+const DESIGN_MOVED =
+  'the design values now live in the stylesheet your canon/DESIGN.md lead names'
+
+/**
+ * Every verb a release dropped, with the release and where the work went. The
+ * router reads this ahead of the parser, and `canon migrate status` reads it to
+ * find project calls. A verb that returns leaves this table in the same change.
+ */
+export const RETIRED_VERBS: readonly RetiredVerb[] = [
+  {
+    path: ['canvas'],
+    release: '5.54.0',
+    movedTo: 'Frameboard, which carries the design board in its own repository',
+  },
+  { path: ['design', 'render'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'install'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'sync'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'fonts'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'list'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'add'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  {
+    path: ['teach'],
+    release: '5.53.0',
+    movedTo: 'the canon:teach-craft skill',
+  },
+  {
+    path: ['slides'],
+    release: '5.53.0',
+    movedTo: 'the canon:teach-craft skill',
+  },
+  {
+    path: ['demo'],
+    release: '5.53.0',
+    movedTo: 'a tool built for composed video',
+  },
+]
+
+/**
+ * Matches the leading words of argv, stopping at the first option so a flag's
+ * value is never read as a verb name.
+ */
+export function findRetired(args: readonly string[]): RetiredVerb | undefined {
+  const words: string[] = []
+  for (const arg of args) {
+    if (arg.startsWith('-')) break
+    words.push(arg)
+  }
+  return RETIRED_VERBS.find((verb) =>
+    verb.path.every((word, index) => words[index] === word),
+  )
+}
+
+export function retiredMessage(verb: RetiredVerb): string {
+  return `error: 'canon ${verb.path.join(' ')}' was retired in v${verb.release}. The work moved to ${verb.movedTo}.`
+}

package/src/cli/ui.ts

@@ -90,9 +90,8 @@ export function intro(title: string): void {
 }
 
 /**
- * Timeline log levels matching `scripts/lib/ui.sh`, so a migrated command
- * prints the same frame as the bash it replaced. All output is stderr,
- * leaving stdout clean for JSON and lists.
+ * Timeline log levels for the framed output every command and `scripts/core/`
+ * script prints. All output is stderr, leaving stdout clean for JSON and lists.
  */
 export function logInfo(message: string): void {
   if (quiet) return
@@ -151,8 +150,7 @@ export function outroSuccess(message: string, detail?: string): void {
 }
 
 /**
- * Indents borrowed output inside an open frame, matching `pipe_output` in
- * `scripts/lib/ui.sh`. Used for a document the command did not compose itself,
+ * Indents borrowed output inside an open frame. Used for a document the command did not compose itself,
  * such as a pull request body or the output of a git mutation.
  */
 export function pipeOutput(text: string): void {

package/src/cli.ts

@@ -40,6 +40,7 @@ import { register as changelog } from '@/commands/changelog'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { renderHelp } from '@/cli/help'
 import { renderAll, routeHelp } from '@/cli/help-all'
+import { findRetired, retiredMessage } from '@/cli/retired'
 import { setQuiet } from '@/cli/ui'
 
 function showHelp(): void {
@@ -101,8 +102,13 @@ gate(program)
 upgrade(program)
 changelog(program)
 
-const route = routeHelp(program, process.argv.slice(2))
-if (route.kind === 'top') showHelp()
+const args = process.argv.slice(2)
+const retired = findRetired(args)
+const route = routeHelp(program, args)
+if (retired !== undefined) {
+  console.error(retiredMessage(retired))
+  process.exitCode = 1
+} else if (route.kind === 'top') showHelp()
 else if (route.kind === 'all') process.stdout.write(renderAll(route.command))
 else if (route.kind === 'unknown') {
   console.error(`error: unknown command '${route.name}'`)

package/src/commands/gov.ts

@@ -210,6 +210,7 @@ export function register(program: Command): void {
     .description('Update rules already installed under .claude/rules/canon/')
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit the coverage record as JSON on stdout')
     .addHelpText(
       'after',
       [
@@ -219,17 +220,22 @@ export function register(program: Command): void {
         'It adds no new rule, which is `canon gov install`, and never touches',
         '.claude/rules/project/.',
         '',
+        'After an apply it lists each rule it copied with the globs it loads on',
+        'and how many files in the target match them. --json writes the same',
+        'list as { "coverage": [{ rule, paths, files, ui }] } on stdout, empty',
+        'when nothing was copied. The report never changes the exit code.',
+        '',
         'Exit codes:',
         '  0  synced, already up to date, or the prompt was cancelled',
         '  1  the target is missing or is the toolkit root',
         '',
       ].join('\n'),
     )
-    .action(async (target: string) => {
+    .action(async (target: string, opts: { json?: boolean }) => {
       process.exitCode = await runDomainSync(
         createGovAdapter(PROJECT_ROOT),
         target,
-        { protectedRoot: PROJECT_ROOT },
+        { protectedRoot: PROJECT_ROOT, json: opts.json },
       )
     })
 

package/src/commands/migrate.ts

@@ -1056,7 +1056,7 @@ async function runStatus(opts: StatusOptions): Promise<number> {
   const mismatch = checkoutMismatchWarning(process.cwd())
   if (mismatch !== undefined) logWarn(mismatch)
 
-  const report = await readMigrationStatus(cliRunner(root))
+  const report = await readMigrationStatus(cliRunner(root), root)
 
   if (opts.json) {
     process.stdout.write(
@@ -1071,6 +1071,12 @@ async function runStatus(opts: StatusOptions): Promise<number> {
     }
   }
 
+  for (const caller of report.retiredCallers) {
+    logWarn(
+      `Retired: ${caller.verb} at ${caller.file}:${caller.line}, retired in v${caller.release}, moved to ${caller.movedTo}`,
+    )
+  }
+
   if (report.pending === 0 && report.refused === 0) {
     logInfo('No migration is pending.')
   }

package/src/commands/pr.ts

@@ -935,7 +935,7 @@ export function register(program: Command): void {
 
   pr.command('merge')
     .description(
-      'Squash-merge a ready pull request with a message carrying only its Summary, Key changes, and Technical context',
+      "Squash-merge a ready pull request with a message carrying only the change: its Summary, Key changes, and Technical context, or a bot pull request's own changelog or package table",
     )
     .argument('[number]', 'Pull request to merge, defaulting to this branch')
     .helpOption('-h, --help', 'Show this help message')
@@ -955,6 +955,13 @@ export function register(program: Command): void {
         'UI pass line dropped. Technical context is optional. Testing, the',
         'reviewer requests, and every other section stay out of the trunk.',
         '',
+        'A release-please or Dependabot pull request is read off its head',
+        'branch, plus the release body opening or a bot author, and needs no',
+        'flag. A release composes to its changelog without the robot line, the',
+        'dividers, and the footer. Dependabot composes to its lead and package',
+        'table, cut at the first `Updates ` line or `<details>` block. A bot body with nothing left',
+        'refuses missing-summary.',
+        '',
         'Refusals are read before the one write, which sends the head it read',
         'as `sha`, so a push after the read refuses rather than merging. The',
         'verb reads the draft flag and not the reviews, since a ready pull',
@@ -4124,6 +4131,8 @@ function mergeApi(root: string, number: string): MergeApi {
           title: row.title,
           body: row.body ?? '',
           head: row.head.sha,
+          branch: row.head.ref ?? '',
+          isBotAuthor: row.user?.type === 'Bot',
         }
       } catch {
         return undefined

package/src/context/audit.ts

@@ -616,8 +616,16 @@ function shapeIssues(
   let inItem = false
   let inParagraph = false
   let afterBlank = false
+  let afterTable = false
+  let deferred = false
+
+  const settleDeferred = (): void => {
+    if (deferred && folder) folder.paragraphs++
+    deferred = false
+  }
 
   const closeFolder = (): void => {
+    settleDeferred()
     if (folder && !exempt.has(folder.text)) {
       if (folder.paragraphs > LAYOUT_PARAGRAPH_CAP) {
         issues.push({
@@ -661,6 +669,7 @@ function shapeIssues(
       inItem = false
       inParagraph = false
       afterBlank = false
+      afterTable = false
 
       if (level <= 2) {
         closeFolder()
@@ -697,11 +706,22 @@ function shapeIssues(
       inItem = true
       inParagraph = false
       afterBlank = false
+      afterTable = false
+      deferred = false
       if (gotchas) gotchas.bullets++
       if (folder) folder.bullets++
       continue
     }
 
+    if (folder && TABLE_ROW.test(line.text)) {
+      settleDeferred()
+      inItem = false
+      inParagraph = false
+      afterBlank = false
+      afterTable = true
+      continue
+    }
+
     const continues = inItem && (!afterBlank || INDENTED.test(line.text))
     afterBlank = false
     if (continues) continue
@@ -717,7 +737,12 @@ function shapeIssues(
         text: line.text.trim(),
       })
     }
-    if (folder) folder.paragraphs++
+    if (folder) {
+      settleDeferred()
+      if (afterTable) deferred = true
+      else folder.paragraphs++
+    }
+    afterTable = false
   }
 
   closeFolder()

package/src/gov/adapter.ts

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs'
 import { basename, join, relative, resolve } from 'node:path'
+import { readCoverage } from '@/gov/coverage'
 import { canonRulesDir, ruleSubdir } from '@/gov/install'
 import { loadRenames, resolveSuccessor } from '@/gov/renames'
 import { resolveMissingRules } from '@/gov/stacks'
@@ -93,6 +94,7 @@ export function createGovAdapter(root: string): SyncAdapter {
           ),
       }
     },
+    coverage: readCoverage,
     stamp: { domain: 'governance', toolkitRoot: root },
   }
 }

package/src/gov/coverage.ts

@@ -0,0 +1,62 @@
+import { readFileSync } from 'node:fs'
+import { relative } from 'node:path'
+import { listRepositoryFiles } from '@/git/files'
+import { canonRulesDir } from '@/gov/install'
+import { parseFrontmatter } from '@/indexes/frontmatter'
+import type { RuleCoverage, SyncChange } from '@/sync/engine'
+
+/** Rule folder whose rules govern rendered output. */
+const UI_FOLDER = 'ui'
+
+/**
+ * One record per rule the sync copied, in apply order. A delete wrote nothing,
+ * so it has no record, and a rename arrives as the copy to the new path.
+ *
+ * `files` is undefined when git cannot list the target, and `paths` is empty
+ * for a rule that loads everywhere. Listing runs once for all rules, so a
+ * large target costs one git call rather than one per rule.
+ */
+export async function readCoverage(
+  target: string,
+  changes: readonly SyncChange[],
+): Promise<RuleCoverage[]> {
+  const written = changes.filter((change) => change.kind === 'copy')
+  if (written.length === 0) return []
+
+  const listed = await listRepositoryFiles(target)
+  const rulesDir = canonRulesDir(target)
+
+  return written.map((change) => {
+    const paths = declaredPaths(change.dest)
+    return {
+      rule: change.rel,
+      paths,
+      files: listed === undefined ? undefined : countMatches(listed, paths),
+      ui: relative(rulesDir, change.dest).split(/[\\/]/)[0] === UI_FOLDER,
+    }
+  })
+}
+
+/** An unreadable file or an unparseable frontmatter reads as always loaded. */
+function declaredPaths(path: string): string[] {
+  let text: string
+  try {
+    text = readFileSync(path, 'utf8')
+  } catch {
+    return []
+  }
+
+  const paths = parseFrontmatter(text)?.fields.paths
+  if (!Array.isArray(paths)) return []
+  return paths.filter((entry): entry is string => typeof entry === 'string')
+}
+
+function countMatches(
+  files: readonly string[],
+  paths: readonly string[],
+): number {
+  if (paths.length === 0) return 0
+
+  const globs = paths.map((path) => new Bun.Glob(path))
+  return files.filter((file) => globs.some((glob) => glob.match(file))).length
+}