@erclx/canon 5.58.0 → 5.60.0

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

@@ -16,9 +16,10 @@ import { readInstalled } from '@/version/installed'
  *
  * A stamp written before the standards or snippets install channel closed
  * still carries a `standards` or `snippets` record, and one written before the
- * design install retired carries a `design` record. `isStamp` ignores the key
- * and `sortDomains` drops it on the next write, so the target loses a domain
- * nothing can refresh rather than losing the whole file.
+ * design install retired carries a `design` record. `isStamp` ignores the key,
+ * `readStamp` drops it from what it returns, and `sortDomains` drops it from
+ * the file on the next write, so the target loses a domain nothing can refresh
+ * rather than losing the whole file.
  */
 export const STAMP_DOMAINS = ['governance', 'tooling'] as const
 
@@ -183,12 +184,31 @@ function readStampFile(path: string): Stamp | undefined {
 
   try {
     const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
-    return isStamp(parsed) ? parsed : undefined
+    return isStamp(parsed) ? withoutRetired(parsed) : undefined
   } catch {
     return undefined
   }
 }
 
+/**
+ * A stamp written before a domain retired still names it until the next write.
+ * Filtering here keeps a report on a target that has not synced since from
+ * listing a domain nothing can refresh. The file itself is left as it is.
+ */
+function withoutRetired(stamp: Stamp): Stamp {
+  const domains: Partial<Record<StampDomain, DomainStamp>> = {}
+  for (const domain of STAMP_DOMAINS) {
+    const record = stamp.domains[domain]
+    if (record !== undefined) domains[domain] = record
+  }
+
+  const covers = Array.isArray(stamp.covers)
+    ? stamp.covers.filter((domain) => STAMP_DOMAINS.includes(domain))
+    : []
+
+  return { covers, domains }
+}
+
 /** The newest canon release that has written this domain, when one was recorded. */
 export function stampedVersion(
   stamp: Stamp | undefined,
@@ -286,7 +306,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 +322,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>>()
 
 /**

package/src/tooling/inject.ts

@@ -1,8 +1,8 @@
 import { existsSync } from 'node:fs'
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
-import { $ } from 'bun'
 import { copyPreservingMode } from '@/sync/copy'
+import { type InstallResult, installDevDependencies } from '@/tooling/install'
 import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
 import { resolveSurfacePath } from '@/roots/surface'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'
@@ -165,7 +165,7 @@ export async function pruneGitignore(
 export async function injectManifest(
   chain: readonly Manifest[],
   target: string,
-): Promise<void> {
+): Promise<InstallResult> {
   const packagePath = join(target, 'package.json')
 
   if (!existsSync(packagePath) && declaresInstalls(chain)) {
@@ -183,7 +183,8 @@ export async function injectManifest(
 
     if (missing.length > 0) {
       logStep('Installing missing dependencies')
-      await $`bun add -D ${missing}`.cwd(target)
+      const installed = await installDevDependencies(missing, target)
+      if (!installed.ok) return installed
       for (const spec of missing) logAdd(spec)
     }
 
@@ -202,6 +203,8 @@ export async function injectManifest(
   await injectGitignore(chain, target)
 
   if (!pkg) warnUnreadablePackage(chain, target)
+
+  return { ok: true }
 }
 
 /**

package/src/tooling/install.ts

@@ -0,0 +1,55 @@
+import { execa } from 'execa'
+
+export const INSTALL_TIMEOUT_MS = 120_000
+const TAIL_LINES = 20
+
+export type InstallResult =
+  | { ok: true }
+  | {
+      ok: false
+      reason: 'install-timeout' | 'install-failed'
+      message: string
+    }
+
+/**
+ * Runs `bun add -D` for the specs and bounds it, since a registry that accepts
+ * a connection and never answers would otherwise hang the caller for good. A
+ * stall or a failure comes back as a refusal naming the packages and the tail
+ * of the output, never as a thrown error.
+ */
+export async function installDevDependencies(
+  specs: readonly string[],
+  cwd: string,
+  timeoutMs: number = INSTALL_TIMEOUT_MS,
+): Promise<InstallResult> {
+  const tried = specs.join(', ')
+  const result = await execa('bun', ['add', '-D', ...specs], {
+    cwd,
+    all: true,
+    reject: false,
+    stdin: 'ignore',
+    timeout: timeoutMs,
+  })
+
+  if (!result.failed) return { ok: true }
+
+  if (result.timedOut) {
+    return {
+      ok: false,
+      reason: 'install-timeout',
+      message: `Install timed out after ${Math.round(timeoutMs / 1000)}s. Tried: ${tried}`,
+    }
+  }
+
+  const detail = tail(result.all) || String(result.shortMessage ?? '')
+  return {
+    ok: false,
+    reason: 'install-failed',
+    message: `Install failed. Tried: ${tried}${detail === '' ? '' : `\n${detail}`}`,
+  }
+}
+
+function tail(output: unknown): string {
+  if (typeof output !== 'string') return ''
+  return output.replace(/\n$/, '').split('\n').slice(-TAIL_LINES).join('\n')
+}

package/scripts/core/bootstrap.sh

@@ -1,86 +0,0 @@
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
-
-source "$PROJECT_ROOT/scripts/lib/ui.sh"
-
-ZSHRC="${ZDOTDIR:-$HOME}/.zshrc"
-MARKER_OPEN="# >>> canon aliases >>>"
-MARKER_CLOSE="# <<< canon aliases <<<"
-
-check_dependencies() {
-  command -v bun >/dev/null 2>&1 || log_error "bun is not installed. See https://bun.sh, then re-run."
-}
-
-install_cli() {
-  log_step "Installing the canon CLI"
-  bun install --cwd "$PROJECT_ROOT" >/dev/null
-  bun link --cwd "$PROJECT_ROOT" >/dev/null
-  log_info "Dependencies installed and canon linked"
-}
-
-alias_block() {
-  cat <<EOF
-$MARKER_OPEN
-TOOLKIT="$PROJECT_ROOT"
-export CLAUDE_CODE_ENABLE_TODO_TOOLS=1
-
-alias cl='claude'
-alias clr='cl -r'
-alias clc='cl -c'
-alias clw='cl -w'
-alias cls='cl --model sonnet'
-
-alias clp='claude --plugin-dir \$TOOLKIT/claude'
-alias clpc='clp -c'
-alias clps='clp --model sonnet'
-alias clpa='clp agents'
-alias clpac='clpa --cwd .'
-$MARKER_CLOSE
-EOF
-}
-
-install_aliases() {
-  log_step "Installing Claude Code shell aliases"
-  log_info "This step manages a marked alias block in $ZSHRC, the only file outside the repo this script writes."
-  log_info "Delete the block and its two marker comments to remove the aliases. Re-running never adds a second copy."
-
-  if [ -f "$ZSHRC" ] && grep -qF "$MARKER_OPEN" "$ZSHRC"; then
-    log_info "Aliases already present in $ZSHRC, skipping"
-    return
-  fi
-
-  if [ -f "$ZSHRC" ] && grep -qE "^alias clp=" "$ZSHRC"; then
-    log_warn "An unmanaged clp alias is already in $ZSHRC. Leaving it untouched."
-    log_warn "Remove it and re-run to switch to the managed block."
-    return
-  fi
-
-  printf '\n%s\n' "$(alias_block)" >>"$ZSHRC"
-  log_add "Appended canon alias block to $ZSHRC"
-  log_info "Run 'source $ZSHRC' or open a new shell to load them"
-}
-
-verify_cli() {
-  log_step "Verifying the install"
-  if canon --help >/dev/null 2>&1; then
-    log_info "canon resolves on PATH"
-  else
-    log_warn "canon not on PATH yet. Ensure \$BUN_INSTALL/bin is exported, then re-open your shell."
-  fi
-}
-
-main() {
-  open_timeline "canon bootstrap"
-  trap close_timeline EXIT
-
-  check_dependencies
-  install_cli
-  install_aliases
-  verify_cli
-}
-
-main "$@"