@erclx/canon 5.58.0 → 5.59.0

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),
+    ),
+  ]
+}

package/src/migrate/status.ts

@@ -1,4 +1,5 @@
 import type { RunCommand } from '@/gate/measures'
+import { type RetiredCaller, scanRetiredCallers } from '@/migrate/callers'
 
 interface Migration {
   readonly name: string
@@ -38,6 +39,8 @@ export interface StatusReport {
   readonly migrations: readonly MigrationStatus[]
   readonly pending: number
   readonly refused: number
+  /** Project calls to a retired verb. Reported only, since no `--write` fixes one. */
+  readonly retiredCallers: readonly RetiredCaller[]
 }
 
 function parseRecord(stdout: string): unknown {
@@ -111,14 +114,19 @@ async function readOne(
  * subcommand shares: 0 with nothing to move, 2 with a plan and no `--write`,
  * anything else a refusal. It never passes `--write`, and it reads no count,
  * since the records share no field to count from.
+ * A retired caller is listed beside them and never changes the exit, since
+ * exit 2 means the pending verbs can be run.
  */
 export async function readMigrationStatus(
   run: RunCommand,
+  root: string,
 ): Promise<StatusReport> {
-  const migrations = await Promise.all(
-    MIGRATIONS.map((migration) => readOne(run, migration)),
-  )
+  const [migrations, retiredCallers] = await Promise.all([
+    Promise.all(MIGRATIONS.map((migration) => readOne(run, migration))),
+    scanRetiredCallers(root),
+  ])
   return {
+    retiredCallers,
     migrations,
     pending: migrations.filter((m) => m.state === 'pending').length,
     refused: migrations.filter((m) => m.state === 'refused').length,

package/src/pr/merge.ts

@@ -22,8 +22,14 @@ export interface MergePull {
   readonly body: string
   /** The head the merge is pinned to, so a push after the read refuses. */
   readonly head: string
+  /** The head branch name, which a bot pull request is recognized by. */
+  readonly branch: string
+  /** Whether the author is a bot account, which a release pull request's is not. */
+  readonly isBotAuthor: boolean
 }
 
+export type BotKind = 'release-please' | 'dependabot'
+
 export interface MergeRequest {
   readonly title: string
   readonly description: string
@@ -105,6 +111,72 @@ export function composeDescription(body: string): Composed {
   }
 }
 
+const RELEASE_BRANCH = 'release-please--branches--'
+const RELEASE_OPENING = ':robot: I have created a release'
+const RELEASE_FOOTER = 'This PR was generated with'
+const DEPENDABOT_BRANCH = 'dependabot/'
+
+/**
+ * The bot a pull request comes from, read off the pull request itself. The
+ * release pull request's author is the operator's own account, so the head
+ * branch carries it, and a second condition keeps a human pull request that
+ * borrows the branch prefix on the human path.
+ */
+export function botKind(
+  pull: Pick<MergePull, 'branch' | 'body' | 'isBotAuthor'>,
+): BotKind | undefined {
+  if (
+    pull.branch.startsWith(RELEASE_BRANCH) &&
+    pull.body.trimStart().startsWith(RELEASE_OPENING)
+  ) {
+    return 'release-please'
+  }
+  if (pull.branch.startsWith(DEPENDABOT_BRANCH) && pull.isBotAuthor) {
+    return 'dependabot'
+  }
+  return undefined
+}
+
+/**
+ * Where a Dependabot body stops. A group body runs a table and then one
+ * `Updates ` line per package, and a single-package body has neither and goes
+ * from its `Bumps` lead straight to a `<details>` block, so either line ends
+ * the kept text. Neither match relies on the commands footer, which a truncated
+ * body lacks.
+ */
+function dependabotCut(lines: readonly string[]): number {
+  const cut = lines.findIndex(
+    (line) =>
+      line.startsWith('Updates ') || line.trim().startsWith('<details>'),
+  )
+  return cut >= 0 ? cut : lines.length
+}
+
+/**
+ * The squash description of a bot pull request, from the bot's own body. A
+ * release keeps its changelog without the robot line, the dividers, and the
+ * footer. Dependabot keeps its lead and package table. A body with nothing left
+ * refuses `missing-summary`.
+ */
+export function composeBotDescription(kind: BotKind, body: string): Composed {
+  const lines = body.replaceAll('\r\n', '\n').split('\n')
+  const kept =
+    kind === 'release-please'
+      ? lines.filter((line) => {
+          const text = line.trim()
+          return (
+            text !== '---' &&
+            !text.startsWith(RELEASE_OPENING) &&
+            !text.startsWith(RELEASE_FOOTER)
+          )
+        })
+      : lines.slice(0, dependabotCut(lines))
+  const description = kept.join('\n').trim()
+  return description === ''
+    ? { kind: 'refused', reason: 'missing-summary' }
+    : { kind: 'composed', description }
+}
+
 /** The suffix the web merge adds and the trunk log carries. */
 export function mergeTitle(title: string, number: number): string {
   return `${title} (#${number})`
@@ -137,7 +209,11 @@ export async function merge(
   if (pull.isDraft) return refused('pull-draft', number)
 
   const title = mergeTitle(pull.title, number)
-  const composed = composeDescription(pull.body)
+  const bot = botKind(pull)
+  const composed =
+    bot === undefined
+      ? composeDescription(pull.body)
+      : composeBotDescription(bot, pull.body)
   if (composed.kind === 'refused') {
     return refused(composed.reason, number, { title })
   }

package/src/pr/rest.ts

@@ -20,6 +20,7 @@ export interface RestPull {
   readonly mergeable_state?: string
   readonly state?: string
   readonly draft?: boolean
+  readonly user?: { readonly type?: string }
   readonly node_id?: string
 }
 

package/src/sandbox/expect.ts

@@ -224,7 +224,7 @@ export function parseExpectation(source: string): Expectation {
 /**
  * `manual` is deliberately excluded. Counting it would let an arm declare five
  * prose lines, assert nothing, and still read green, which is the vacuous case
- * `scripts/core/install-check.sh` warns about in its own comment.
+ * `scripts/core/install-check.ts` warns about in its own comment.
  */
 export function countMechanicalAssertions(expectation: Expectation): number {
   return (

package/src/sync/engine.ts

@@ -27,6 +27,7 @@ import {
   logWarn,
   outro,
   outroSuccess,
+  plural,
   select,
 } from '@/cli/ui'
 import { compareVersions, parseVersion } from '@/version/compare'
@@ -112,6 +113,17 @@ export interface SyncPlan {
   readonly historyUnavailable: boolean
 }
 
+/**
+ * What an applied rule governs in the target. `paths` empty means the rule
+ * loads everywhere, and `files` unset means the target could not be listed.
+ */
+export interface RuleCoverage {
+  readonly rule: string
+  readonly paths: readonly string[]
+  readonly files: number | undefined
+  readonly ui: boolean
+}
+
 /**
  * What a headless run does once the plan has changes. Domains whose files the
  * toolkit owns apply them. Domains whose files a project is expected to edit
@@ -189,6 +201,14 @@ export interface SyncAdapter {
   readonly nonInteractive?: NonInteractivePolicy
   /** Runs on a completed sync, including one with no changes. */
   onComplete?(target: string): Promise<void>
+  /**
+   * What each rule an apply copied governs in the target. Called only after
+   * an apply, and advisory: a throw is reported and never changes the exit.
+   */
+  coverage?(
+    target: string,
+    changes: readonly SyncChange[],
+  ): Promise<readonly RuleCoverage[]>
   /** Where this domain's hashes are stamped. Unset domains go unstamped. */
   readonly stamp?: StampSource
 }
@@ -403,6 +423,8 @@ export async function applyChanges(
 export interface SyncRunOptions {
   /** Path the sync refuses to run against, normally the toolkit root. */
   readonly protectedRoot: string
+  /** Writes the coverage record to stdout on every run that exits 0. */
+  readonly json?: boolean
 }
 
 /**
@@ -442,6 +464,7 @@ export async function runDomainSync(
     plan.retired.length === 0
   ) {
     logWarn(adapter.missingMessage)
+    emitCoverage(options, [])
     outro()
     return 0
   }
@@ -452,6 +475,7 @@ export async function runDomainSync(
   if (count === 0) {
     await adapter.onComplete?.(resolved)
     await recordStamp(adapter, resolved, new Date())
+    emitCoverage(options, [])
     outroSuccess('Everything up to date')
     return 0
   }
@@ -464,6 +488,7 @@ export async function runDomainSync(
   ) {
     logWarn(policy.message)
     logInfo(policy.hint)
+    emitCoverage(options, [])
     outro()
     return 0
   }
@@ -479,6 +504,7 @@ export async function runDomainSync(
 
   if (!shouldApply) {
     logWarn('Sync cancelled')
+    emitCoverage(options, [])
     outro()
     return 0
   }
@@ -487,10 +513,68 @@ export async function runDomainSync(
   await adapter.onComplete?.(resolved)
   await recordStamp(adapter, resolved, new Date())
 
+  const coverage = await readAdapterCoverage(adapter, resolved, plan.changes)
+  reportCoverage(coverage)
+  emitCoverage(options, coverage)
+
   outroSuccess('Sync complete', `(${count} ${adapter.unit})`)
   return 0
 }
 
+async function readAdapterCoverage(
+  adapter: SyncAdapter,
+  target: string,
+  changes: readonly SyncChange[],
+): Promise<readonly RuleCoverage[]> {
+  if (adapter.coverage === undefined) return []
+
+  try {
+    return await adapter.coverage(target, changes)
+  } catch (error) {
+    logWarn(
+      `Coverage unavailable: ${error instanceof Error ? error.message : String(error)}`,
+    )
+    return []
+  }
+}
+
+function reportCoverage(coverage: readonly RuleCoverage[]): void {
+  if (coverage.length === 0) return
+
+  logStep('Coverage')
+  for (const entry of coverage) {
+    logInfo(describeCoverage(entry))
+    if (entry.ui) {
+      logInfo('  Audit those files with /canon:ux-audit.')
+    }
+  }
+}
+
+function describeCoverage(entry: RuleCoverage): string {
+  if (entry.paths.length === 0) return `${entry.rule} (loads everywhere)`
+
+  const globs = entry.paths.join(', ')
+  if (entry.files === undefined) return `${entry.rule} (${globs})`
+
+  return `${entry.rule} (${globs}): ${plural(entry.files, 'file')}`
+}
+
+/** The one stdout write of a `--json` run, so a pipe reads JSON alone. */
+function emitCoverage(
+  options: SyncRunOptions,
+  coverage: readonly RuleCoverage[],
+): void {
+  if (options.json !== true) return
+
+  const records = coverage.map((entry) => ({
+    rule: entry.rule,
+    paths: entry.paths,
+    files: entry.files ?? null,
+    ui: entry.ui,
+  }))
+  process.stdout.write(`${JSON.stringify({ coverage: records })}\n`)
+}
+
 /**
  * Reports in walk order rather than grouped by state, so a long rule tree
  * reads as a directory listing with drift called out in place.

package/src/sync/stamp.ts

@@ -286,7 +286,7 @@ async function putDomain(
 
   const path = stampPath(target)
   await mkdir(dirname(path), { recursive: true })
-  await writeFile(path, `${JSON.stringify(stamp, null, 2)}\n`)
+  await writeFile(path, `${serializeStamp(stamp)}\n`)
 
   // The stamp hashes every file but itself, so reshaping it cannot read as
   // drift. Seeds and goldens stay as copied for the opposite reason: their
@@ -302,6 +302,56 @@ async function putDomain(
   recordTarget(target, now)
 }
 
+const WIDTH = 80
+
+/**
+ * `JSON.stringify` expands every array one element per line, a shape oxfmt and
+ * prettier both reject, so a sync with no formatter to run would leave a
+ * target's format gate red. This inlines a string array that fits the default
+ * print width and expands one that does not, as both formatters would, and
+ * leaves objects expanded, which both preserve. Content and key order are
+ * `JSON.stringify`'s own.
+ */
+function serializeStamp(value: unknown): string {
+  return serialize(value, 0, 0, true)
+}
+
+function serialize(
+  value: unknown,
+  depth: number,
+  taken: number,
+  last: boolean,
+): string {
+  if (Array.isArray(value) && value.every((item) => typeof item === 'string')) {
+    const inline = JSON.stringify(value).replace(/","/g, '", "')
+    // A comma follows every entry but the last of its object, and counts
+    // against the width as it does for a formatter.
+    return taken + inline.length + (last ? 0 : 1) <= WIDTH
+      ? inline
+      : expand(value, depth)
+  }
+
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const entries = Object.entries(value).filter(([, v]) => v !== undefined)
+    if (entries.length === 0) return '{}'
+
+    const pad = '  '.repeat(depth + 1)
+    const lines = entries.map(([key, child], index) => {
+      const head = `${pad}${JSON.stringify(key)}: `
+      return `${head}${serialize(child, depth + 1, head.length, index === entries.length - 1)}`
+    })
+    return `{\n${lines.join(',\n')}\n${'  '.repeat(depth)}}`
+  }
+
+  return JSON.stringify(value)
+}
+
+function expand(items: readonly string[], depth: number): string {
+  const pad = '  '.repeat(depth + 1)
+  const lines = items.map((item) => `${pad}${JSON.stringify(item)}`)
+  return `[\n${lines.join(',\n')}\n${'  '.repeat(depth)}]`
+}
+
 const commitCache = new Map<string, Promise<string | undefined>>()
 
 /**