@erclx/canon 5.58.0 → 5.60.0

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/design.ts

@@ -1,7 +1,9 @@
 import { existsSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import type { Command } from 'commander'
+import { auditDesign } from '@/design/audit'
 import { buildDesignCss } from '@/design/css'
+import { currentWorktreeRoot } from '@/git/worktree'
 import { HAND_DRAWN_FONT_FACES } from '@/design/fonts'
 import { DESIGN_DOCUMENT, regenDesign } from '@/design/regen'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
@@ -11,7 +13,7 @@ export function register(program: Command): void {
   const design = program
     .command('design')
     .helpOption('-h, --help', 'Show this help message')
-    .description('Design system commands (regen, css)')
+    .description('Design system commands (regen, css, audit)')
 
   design
     .command('regen')
@@ -77,4 +79,58 @@ export function register(program: Command): void {
         }),
       )
     })
+
+  design
+    .command('audit')
+    .helpOption('-h, --help', 'Show this help message')
+    .description(
+      'Measure the design record against the prose budget and check its custom properties against the stylesheet',
+    )
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--root <path>', 'Project root, defaulting to the current worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads canon/DESIGN.md. Prose findings carry their counts against the',
+        'budget the design standard sets. Each custom property in the Colors and',
+        'Shapes tables is checked against the stylesheet the lead names. A lead',
+        'naming none reads as `tokens.status: "unchecked"`, never as a pass.',
+        '',
+        'Exit codes:',
+        '  0  the reading completed, whatever it found',
+        '',
+        'It gates nothing and writes nothing.',
+        '',
+        'Examples:',
+        '  canon design audit',
+        '  canon design audit --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: { json?: boolean; root?: string }) => {
+      const root = opts.root ?? (await currentWorktreeRoot())
+      const audit = auditDesign(root)
+
+      if (opts.json ?? false) {
+        process.stdout.write(`${JSON.stringify(audit)}\n`)
+        return
+      }
+
+      intro('canon design audit')
+      if (audit.record === null) {
+        logInfo('No design record to audit')
+      } else {
+        for (const finding of audit.prose) logWarn(finding)
+        if (audit.tokens?.status === 'unchecked') {
+          logWarn(`Tokens unchecked: ${audit.tokens.reason}`)
+        } else if (audit.tokens?.status === 'checked') {
+          for (const property of audit.tokens.missing) {
+            logWarn(`${property} is not declared in ${audit.tokens.stylesheet}`)
+          }
+        }
+        if (audit.clean) logInfo(`${audit.record} is within budget`)
+      }
+      outro()
+    })
 }

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/commands/tooling.ts

@@ -107,6 +107,9 @@ export function register(program: Command): void {
         'A target below its git root syncs as a subfolder. It withholds',
         '.github/, which GitHub reads only at the root.',
         '',
+        'The dependency install is bounded at 120 seconds. A stalled or failed',
+        'install refuses with exit 1, and the stamp stays unwritten.',
+        '',
         'To gate CI on tooling drift, run headlessly with neither flag. That',
         'exits 1 when a file would be replaced and 0 when none would, which is',
         'what `canon sync --check --exit-code` spells with a flag. Pass --check',
@@ -444,7 +447,14 @@ async function runSync(
   }
 
   await injectSeeds(prepared.chain, prepared.target)
-  await injectManifest(prepared.chain, prepared.target)
+  const manifest = await injectManifest(prepared.chain, prepared.target)
+  if (!manifest.ok) {
+    return refuse(
+      opts,
+      manifest.reason,
+      `${manifest.message}\nConfigs and seeds above were written. Scripts, gitignore entries, and the stamp were not, so the next sync retries.`,
+    )
+  }
 
   await stampChain(prepared.chain, prepared.target)
 
@@ -553,7 +563,12 @@ async function runInject(
     await injectSeeds(prepared.chain, prepared.target)
   }
   if (opts.manifest || applyAll) {
-    await injectManifest(prepared.chain, prepared.target)
+    const manifest = await injectManifest(prepared.chain, prepared.target)
+    if (!manifest.ok) {
+      logWarn(manifest.message)
+      if (framed) outro()
+      return 1
+    }
   } else if (opts.gitignore) {
     await injectGitignore(prepared.chain, prepared.target)
   }

package/src/design/audit.ts

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { measureDesignProse } from '@/design/budget'
+import { parseDesignDoc } from '@/design/parse'
+import { DESIGN_DOCUMENT } from '@/design/regen'
+
+/** The custom property a table row names, such as `--color-accent`. */
+const PROPERTY = /--[A-Za-z0-9_-]+/g
+
+/** A custom property declaration, which a stylesheet and a Tailwind `@theme` block share. */
+const DECLARATION = /(--[A-Za-z0-9_-]+)\s*:/g
+
+/** A backticked path to a stylesheet. */
+const STYLESHEET = /`([^`\s]+\.css)`/
+
+export type TokenCheck =
+  | {
+      readonly status: 'checked'
+      readonly stylesheet: string
+      readonly properties: number
+      readonly missing: readonly string[]
+    }
+  | { readonly status: 'unchecked'; readonly reason: string }
+  | { readonly status: 'not-applicable'; readonly reason: string }
+
+export interface DesignAudit {
+  readonly ok: true
+  /** The record read, or null where the project holds none. */
+  readonly record: string | null
+  readonly prose: readonly string[]
+  readonly tokens: TokenCheck | null
+  /** True only when the prose is within budget and the token check ran clean. */
+  readonly clean: boolean
+}
+
+/**
+ * Reads a project's design record against the prose budget and checks each
+ * custom property its tables name against the stylesheet its lead names. It
+ * writes nothing.
+ *
+ * A token check that cannot run says why under `unchecked` and leaves `clean`
+ * false, since a check that did not look is no pass.
+ */
+export function auditDesign(root: string): DesignAudit {
+  const path = join(root, DESIGN_DOCUMENT)
+  if (!existsSync(path)) {
+    return { ok: true, record: null, prose: [], tokens: null, clean: true }
+  }
+
+  const source = readFileSync(path, 'utf8')
+  const prose = measureDesignProse(source)
+  const tokens = checkTokens(root, path, source)
+  const clean =
+    prose.length === 0 &&
+    tokens.status !== 'unchecked' &&
+    (tokens.status !== 'checked' || tokens.missing.length === 0)
+
+  return { ok: true, record: DESIGN_DOCUMENT, prose, tokens, clean }
+}
+
+function checkTokens(root: string, path: string, source: string): TokenCheck {
+  const doc = parseDesignDoc(path)
+  const rows = [...doc.color, ...doc.borders]
+
+  // A values record renders from a token module and carries `Value` where an
+  // intent record carries `Property`, so it has no property to compare.
+  if (!rows.some((row) => 'Property' in row)) {
+    return {
+      status: 'not-applicable',
+      reason:
+        'The record has no Property column, so it holds no property to compare.',
+    }
+  }
+
+  const lead = source.split(/^##\s/m)[0]
+  const named = lead.match(STYLESHEET)?.[1]
+  if (named === undefined) {
+    return {
+      status: 'unchecked',
+      reason: 'The lead names no stylesheet, so no property could be checked.',
+    }
+  }
+
+  const stylesheet = resolve(root, named)
+  if (!stylesheet.startsWith(resolve(root)) || !existsSync(stylesheet)) {
+    return {
+      status: 'unchecked',
+      reason: `The lead names ${named}, which does not resolve in the project.`,
+    }
+  }
+
+  const css = readFileSync(stylesheet, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '')
+  const declared = new Set([...css.matchAll(DECLARATION)].map((m) => m[1]))
+
+  const properties = [
+    ...new Set(
+      rows.flatMap((row) =>
+        [...(row['Property']?.value.matchAll(PROPERTY) ?? [])].map((m) => m[0]),
+      ),
+    ),
+  ]
+
+  return {
+    status: 'checked',
+    stylesheet: named,
+    properties: properties.length,
+    missing: properties.filter((property) => !declared.has(property)),
+  }
+}

package/src/design/css.ts

@@ -154,8 +154,6 @@ export function fontFaceBlock(
 }
 
 export interface CssOptions {
-  /** Prepended as a comment, naming what wrote the file and from where. */
-  readonly banner?: string
   /**
    * Component rules ride along by default; a token-only consumer opts out
    * with `false`. Pass an explicit list to emit those instead of the generic default.
@@ -173,8 +171,6 @@ export function buildDesignCss(
   tokens: DesignTokens = TOKENS,
   options: CssOptions = {},
 ): string {
-  const banner =
-    options.banner === undefined ? '' : `/* ${options.banner} */\n\n`
   const root = [':root {', ...tokenProperties(tokens), '}'].join('\n')
   const faces =
     options.embedFonts === true
@@ -193,5 +189,5 @@ export function buildDesignCss(
         : COMPONENTS
   if (components) parts.push(componentBlock(components))
 
-  return `${banner}${parts.join('\n\n')}\n`
+  return `${parts.join('\n\n')}\n`
 }

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
+}

package/src/migrate/callers.ts

@@ -0,0 +1,192 @@
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { isAbsolute, join, relative } from 'node:path'
+import { RETIRED_VERBS, type RetiredVerb } from '@/cli/retired'
+
+export interface RetiredCaller {
+  /** Project-relative path of the file holding the call. */
+  readonly file: string
+  /** One-based line of the call. */
+  readonly line: number
+  /** The call as typed, such as `canon design render`. */
+  readonly verb: string
+  readonly release: string
+  readonly movedTo: string
+}
+
+const WORKFLOWS = '.github/workflows'
+const SCRIPTS = 'scripts'
+const CODE_FILE = /\.(?:sh|bash|zsh|ts|mts|cts|js|mjs|cjs)$/
+const WORKFLOW_FILE = /\.ya?ml$/
+// A script path a command line names, such as `bun tools/sync.ts`.
+const NAMED_FILE = /[\w./-]+\.(?:sh|bash|zsh|ts|mts|cts|js|mjs|cjs)\b/g
+const MAX_FILE_BYTES = 1_000_000
+
+function escape(word: string): string {
+  return word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * The two call shapes, a command line and an argument list. A command line may
+ * go through `bunx -y` or `npx`, and an argument list carries `canon` as its
+ * own quoted element ahead of the verb words.
+ */
+function callPatterns(verb: RetiredVerb): readonly RegExp[] {
+  const words = verb.path.map(escape)
+  const shell = words.join('\\s+')
+  const list = words.map((word) => `['"]${word}['"]`).join('\\s*,\\s*')
+  return [
+    new RegExp(`(?:^|[\\s;&|(\`"'])canon\\s+${shell}(?![\\w-])`),
+    new RegExp(`['"]canon['"]\\s*,\\s*(?:\\[\\s*)?${list}`),
+  ]
+}
+
+const PATTERNS = RETIRED_VERBS.map((verb) => ({
+  verb,
+  patterns: callPatterns(verb),
+}))
+
+function isComment(line: string): boolean {
+  const trimmed = line.trimStart()
+  return trimmed.startsWith('#') || trimmed.startsWith('//')
+}
+
+function scanText(file: string, text: string): RetiredCaller[] {
+  const callers: RetiredCaller[] = []
+  text.split('\n').forEach((content, index) => {
+    if (isComment(content)) return
+    for (const { verb, patterns } of PATTERNS) {
+      if (!patterns.some((pattern) => pattern.test(content))) continue
+      callers.push({
+        file,
+        line: index + 1,
+        verb: `canon ${verb.path.join(' ')}`,
+        release: verb.release,
+        movedTo: verb.movedTo,
+      })
+    }
+  })
+  return callers
+}
+
+async function readText(root: string, file: string): Promise<string | null> {
+  try {
+    const path = join(root, file)
+    if ((await stat(path)).size > MAX_FILE_BYTES) return null
+    return await readFile(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+async function listFiles(
+  root: string,
+  dir: string,
+  accepts: RegExp,
+): Promise<string[]> {
+  try {
+    const entries = await readdir(join(root, dir), { withFileTypes: true })
+    const nested = await Promise.all(
+      entries.map(async (entry) => {
+        const path = `${dir}/${entry.name}`
+        if (entry.isDirectory()) {
+          return entry.name === 'node_modules'
+            ? []
+            : listFiles(root, path, accepts)
+        }
+        return entry.isFile() && accepts.test(entry.name) ? [path] : []
+      }),
+    )
+    return nested.flat()
+  } catch {
+    return []
+  }
+}
+
+async function readScripts(root: string): Promise<Record<string, string>> {
+  const text = await readText(root, 'package.json')
+  if (text === null) return {}
+  try {
+    const scripts = (JSON.parse(text) as { scripts?: unknown }).scripts
+    if (typeof scripts !== 'object' || scripts === null) return {}
+    return Object.fromEntries(
+      Object.entries(scripts).filter(
+        (entry): entry is [string, string] => typeof entry[1] === 'string',
+      ),
+    )
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Reads the script values rather than the whole manifest, so a description
+ * naming a verb never reports. The line is the script's key, since JSON keeps
+ * no line for a value.
+ */
+async function scanPackageScripts(
+  root: string,
+  scripts: Record<string, string>,
+): Promise<RetiredCaller[]> {
+  const lines = ((await readText(root, 'package.json')) ?? '').split('\n')
+  return Object.entries(scripts).flatMap(([name, command]) => {
+    const key = `${JSON.stringify(name)}:`
+    const line = lines.findIndex((text) => text.includes(key)) + 1
+    return scanText('package.json', command).map((caller) => ({
+      ...caller,
+      line: Math.max(line, 1),
+    }))
+  })
+}
+
+function namedFiles(commandLines: readonly string[]): string[] {
+  return commandLines.flatMap((line) => line.match(NAMED_FILE) ?? [])
+}
+
+function insideRoot(root: string, file: string): boolean {
+  if (isAbsolute(file)) return false
+  const path = relative(root, join(root, file))
+  return path !== '' && !path.startsWith('..')
+}
+
+/**
+ * Finds the places a project calls a retired verb. It reads only the workflow
+ * folder, the `package.json` scripts, `scripts/`, and the files those scripts
+ * and workflow steps name, and it runs nothing. A markdown file is never read,
+ * so prose naming a verb never reports.
+ */
+export async function scanRetiredCallers(
+  root: string,
+): Promise<RetiredCaller[]> {
+  const scripts = await readScripts(root)
+  const workflows = await listFiles(root, WORKFLOWS, WORKFLOW_FILE)
+  const ownScripts = await listFiles(root, SCRIPTS, CODE_FILE)
+  const workflowTexts = await Promise.all(
+    workflows.map(async (file) => ({
+      file,
+      text: (await readText(root, file)) ?? '',
+    })),
+  )
+
+  const named = namedFiles([
+    ...Object.values(scripts),
+    ...workflowTexts.flatMap(({ text }) => text.split('\n')),
+  ])
+    .map((file) => file.replace(/^\.\//, ''))
+    .filter((file) => insideRoot(root, file))
+
+  const codeFiles = [...new Set([...ownScripts, ...named])]
+  const codeTexts = await Promise.all(
+    codeFiles.map(async (file) => ({
+      file,
+      text: await readText(root, file),
+    })),
+  )
+
+  return [
+    ...(await scanPackageScripts(root, scripts)),
+    ...workflowTexts.flatMap(({ file, text }) => scanText(file, text)),
+    ...codeTexts.flatMap(({ file, text }) =>
+      text === null ? [] : scanText(file, text),
+    ),
+  ]
+}