@erclx/canon 4.0.0

package/src/migrate/apply.ts

@@ -0,0 +1,115 @@
+import { $ } from 'bun'
+import { readFile, mkdir, rmdir, writeFile } from 'node:fs/promises'
+import { dirname, join, relative } from 'node:path'
+import { gitEnv } from '@/git-env'
+import type { RenamePlan, RenameSource } from '@/migrate/plan'
+
+/**
+ * A file whose bytes carry a NUL is read as binary and its content is left
+ * alone, which lets the path still move. Reporting the empty string rather
+ * than a flag keeps the planner pure: an unchanged content rewrite is already
+ * how it expresses "path only", so binary needs no branch of its own there.
+ */
+export async function readSources(
+  root: string,
+  paths: readonly string[],
+): Promise<RenameSource[]> {
+  const sources: RenameSource[] = []
+
+  for (const path of paths) {
+    const bytes = await readFile(join(root, path)).catch(() => undefined)
+    if (bytes === undefined) continue
+
+    const binary = bytes.includes(0)
+    sources.push({ path, text: binary ? '' : bytes.toString('utf8') })
+  }
+
+  return sources
+}
+
+export interface ApplyResult {
+  readonly written: number
+  readonly moved: number
+  readonly failed: readonly string[]
+}
+
+/**
+ * Writes the plan. Content lands first and the move follows, so a failed move
+ * leaves the rewrite on a path that still exists rather than stranding content
+ * at a destination nothing points at yet.
+ *
+ * `git mv` rather than a filesystem rename, so the history follows the file and
+ * a reviewer reading the pull request sees a rename instead of a delete beside
+ * an add.
+ */
+export async function applyRename(
+  root: string,
+  plan: RenamePlan,
+): Promise<ApplyResult> {
+  let written = 0
+  let moved = 0
+  const failed: string[] = []
+
+  for (const entry of plan.entries) {
+    if (entry.text !== undefined) {
+      await writeFile(join(root, entry.path), entry.text)
+      written += 1
+    }
+
+    if (entry.movesTo === undefined) continue
+
+    await mkdir(dirname(join(root, entry.movesTo)), { recursive: true })
+    const result = await $`git -C ${root} mv ${entry.path} ${entry.movesTo}`
+      .env(gitEnv())
+      .quiet()
+      .nothrow()
+
+    if (result.exitCode === 0) moved += 1
+    else failed.push(entry.path)
+  }
+
+  await pruneEmptyParents(
+    root,
+    plan.entries
+      .filter((entry) => entry.movesTo !== undefined)
+      .map((entry) => dirname(entry.path)),
+  )
+
+  return { written, moved, failed }
+}
+
+/**
+ * Removes the directories a move emptied.
+ *
+ * Git tracks files rather than directories, so moving the last file out of one
+ * leaves the directory on disk with nothing in it and nothing in the diff to
+ * say so. A renamed skill folder that keeps its old shell beside the new one
+ * reads to a person, and to a plugin loader walking the tree, as though the
+ * rename only half happened.
+ *
+ * `rmdir` refuses a directory that still holds anything, which is the guard:
+ * a folder with an untracked file in it stays, and the refusal is ignored
+ * rather than reported because it means the folder was not empty to begin
+ * with.
+ */
+async function pruneEmptyParents(
+  root: string,
+  directories: readonly string[],
+): Promise<void> {
+  const deepestFirst = [...new Set(directories)].sort(
+    (left, right) => right.length - left.length,
+  )
+
+  for (const directory of deepestFirst) {
+    let current = directory
+
+    while (current !== '.' && !current.startsWith('..')) {
+      const removed = await rmdir(join(root, current))
+        .then(() => true)
+        .catch(() => false)
+      if (!removed) break
+
+      current = relative(root, join(root, current, '..'))
+    }
+  }
+}

package/src/migrate/plan.ts

@@ -0,0 +1,103 @@
+import {
+  isExcludedPath,
+  renamePath,
+  renameText,
+  scanText,
+} from '@/migrate/rename'
+
+/** One tracked file, as the planner reads it. */
+export interface RenameSource {
+  readonly path: string
+  readonly text: string
+}
+
+/**
+ * One file the sweep touches. `text` is absent when only the path moves, so a
+ * caller writing the plan can tell a content rewrite from a pure move and
+ * leave a binary file's bytes alone.
+ */
+export interface RenameEntry {
+  readonly path: string
+  readonly movesTo?: string
+  readonly text?: string
+  readonly renamed: number
+  readonly protectedCount: number
+}
+
+export interface RenamePlan {
+  readonly entries: readonly RenameEntry[]
+  readonly excluded: readonly string[]
+  readonly renamed: number
+  readonly protectedCount: number
+  readonly moves: number
+}
+
+/**
+ * Folders a target receives from the toolkit and does not author.
+ *
+ * The rename may rewrite these in a consuming project, because their content
+ * came from here and a stale spelling in them is the toolkit's own defect.
+ * Everything else in a target is prose that project wrote, where a citation is
+ * reported for a person to decide rather than rewritten underneath them.
+ */
+const TOOLKIT_OWNED: readonly string[] = [
+  '.claude/aitk/',
+  '.claude/canon/',
+  '.claude/rules/',
+  '.claude/tooling/',
+]
+
+export function isToolkitOwned(path: string): boolean {
+  return TOOLKIT_OWNED.some((owned) => path.startsWith(owned))
+}
+
+/**
+ * What the sweep would do to a set of files.
+ *
+ * Pure, so the decision and the write are separable and the same plan can be
+ * reported or applied. A file whose content and path both stay put is dropped
+ * rather than carried as a no-op entry, which keeps the reported count equal
+ * to the number of files the sweep actually changes.
+ */
+export function planRename(sources: readonly RenameSource[]): RenamePlan {
+  const entries: RenameEntry[] = []
+  const excluded: string[] = []
+
+  for (const source of sources) {
+    if (isExcludedPath(source.path)) {
+      excluded.push(source.path)
+      continue
+    }
+
+    const movesTo = renamePath(source.path)
+    const rewritten = renameText(source.text)
+    const counts = scanText(source.text)
+    const moved = movesTo !== source.path
+    const changed = rewritten !== source.text
+
+    if (!moved && !changed) continue
+
+    entries.push({
+      path: source.path,
+      ...(moved ? { movesTo } : {}),
+      ...(changed ? { text: rewritten } : {}),
+      renamed: counts.renamed,
+      protectedCount: counts.protectedCount,
+    })
+  }
+
+  return {
+    entries,
+    excluded,
+    renamed: total(entries, (entry) => entry.renamed),
+    protectedCount: total(entries, (entry) => entry.protectedCount),
+    moves: entries.filter((entry) => entry.movesTo !== undefined).length,
+  }
+}
+
+function total(
+  entries: readonly RenameEntry[],
+  read: (entry: RenameEntry) => number,
+): number {
+  return entries.reduce((sum, entry) => sum + read(entry), 0)
+}

package/src/migrate/rename.ts

@@ -0,0 +1,183 @@
+/**
+ * The token rewrite behind the `aitk` to `canon` rename.
+ *
+ * The sweep is mechanical and its danger is entirely in what it must not
+ * touch, so the scanner is one pass with the protected forms tried first
+ * rather than a chain of replacements. A chain reprocesses its own output,
+ * which is how a protected form that contains the token gets rewritten by a
+ * later rule that cannot see it was already decided.
+ */
+
+/**
+ * Forms carrying the token that name something other than this tool, matched
+ * ahead of the token itself so they pass through untouched.
+ *
+ * `aitk-sandbox` is a separate repository that is not being renamed. It has to
+ * win against the bare token, and it also has to win against the owner-scoped
+ * spelling, since `erclx/aitk-sandbox` would otherwise rewrite to
+ * `erclx/canon-sandbox` and name a repository that does not exist.
+ */
+const PROTECTED = ['aitk-sandbox'] as const
+
+/**
+ * Every spelling of the token, and what each becomes. Case is carried in the
+ * map rather than derived, because the uppercase form is an environment
+ * variable prefix and the title-case form is a heading word, and a derived
+ * transform would have to guess which convention it was looking at.
+ */
+const REPLACEMENT: Readonly<Record<string, string>> = {
+  aitk: 'canon',
+  AITK: 'CANON',
+  Aitk: 'Canon',
+}
+
+/**
+ * One alternation so the engine decides each position once. Group 1 is a
+ * protected form and group 2 is a token to rewrite, and the protected branch
+ * sits first because a regex alternation is ordered.
+ */
+const SCAN = new RegExp(
+  `(${PROTECTED.join('|')})|(${Object.keys(REPLACEMENT).join('|')})`,
+  'g',
+)
+
+/**
+ * Files whose content is left alone entirely.
+ *
+ * The changelog is release history. Its entries record what shipped under the
+ * old name, so rewriting them falsifies the record, and the pull request links
+ * it carries keep resolving because GitHub redirects a renamed repository's
+ * old URLs.
+ *
+ * The sweep's own source is the other member, and it is not a preference. This
+ * module states the token map as literal keys, so rewriting it turns every key
+ * into its own replacement and leaves a rewriter that maps `canon` to `canon`
+ * and matches nothing. Its tests name both spellings on purpose for the same
+ * reason, and the command's help text documents the old name a caller is
+ * migrating off. Whatever these four files should say after the rename is
+ * written by hand, because the sweep cannot be the thing that decides it.
+ */
+/**
+ * An eval result is a transcript. It records the commands a session actually
+ * ran and the paths it actually opened, under whatever name was current when
+ * the run happened, so rewriting one makes it testify to a session that never
+ * took place. The changelog is excluded for the same reason and differs only
+ * in living at a fixed path.
+ */
+const EXCLUDED_PREFIXES: readonly string[] = [
+  'src/migrate/',
+  'scripts/eval/result-',
+]
+
+/**
+ * The four test files below exist to prove the retired spellings still
+ * resolve, so both names appear in each on purpose. Rewriting one is worse
+ * than a broken test: the retired-variable case would collapse into a copy of
+ * the current-variable case beside it and keep passing, reporting coverage for
+ * a fallback nothing exercises any more.
+ */
+const EXCLUDED_PATHS: readonly string[] = [
+  'CHANGELOG.md',
+  'src/commands/migrate.ts',
+  'src/sync/stamp.test.ts',
+  'src/targets/registry.test.ts',
+  'src/targets/sweep.test.ts',
+  'src/ui.test.ts',
+]
+
+export interface ScanCount {
+  readonly renamed: number
+  readonly protectedCount: number
+}
+
+export function isExcludedPath(path: string): boolean {
+  if (EXCLUDED_PATHS.includes(path)) return true
+  return EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix))
+}
+
+/**
+ * An indefinite article that agreed with the retired name and no longer
+ * agrees with the replacement.
+ *
+ * The old name opens on a vowel sound and the new one does not, so every
+ * `an aitk` in the corpus reads wrong the moment the token moves. This matches
+ * against the already-rewritten text rather than the source, which is what
+ * keeps it clear of the protected forms: `an aitk-sandbox` still says
+ * `aitk-sandbox` afterward, so it never matches here.
+ *
+ * The tail rejects a following letter rather than asking for a word boundary,
+ * which is what separates `an canonical` from `an CANON_STATE_DIR`. A boundary
+ * treats the underscore as part of the word and declines the environment
+ * variable, where the whole identifier is the token continuing.
+ */
+const ARTICLE = /\b([Aa])n(\s+`?)(canon|CANON|Canon)(?![A-Za-z])/g
+
+/**
+ * Marks a line that names the retired spelling on purpose.
+ *
+ * A fallback path, a retired environment variable, and a dictionary entry
+ * covering the record corpora all have to keep saying the old name, and a
+ * second run over an already-renamed tree would otherwise strip exactly the
+ * compatibility this rename shipped. The marker sits on the line itself or on
+ * the one above it, which is the same placement `canon-allow-superseded`
+ * already uses in this repository.
+ */
+const KEEP_MARKER = 'canon-keep-retired'
+
+/** Rewrites every unprotected spelling of the token. */
+export function renameText(text: string): string {
+  const lines = text.split('\n')
+  const rewritten = lines.map((line, index) =>
+    isKept(lines, index) ? line : renameLine(line),
+  )
+
+  return rewritten.join('\n')
+}
+
+function isKept(lines: readonly string[], index: number): boolean {
+  if (lines[index]?.includes(KEEP_MARKER)) return true
+  return index > 0 && (lines[index - 1]?.includes(KEEP_MARKER) ?? false)
+}
+
+function renameLine(line: string): string {
+  const replaced = line.replace(SCAN, (match, guarded: string | undefined) =>
+    guarded === undefined ? REPLACEMENT[match] : guarded,
+  )
+
+  return replaced.replace(
+    ARTICLE,
+    (_match, article: string, gap: string, token: string) =>
+      `${article}${gap}${token}`,
+  )
+}
+
+/**
+ * What `renameText` would do, without doing it. Reported rather than inferred
+ * from a diff so a run can say how much it protected, which is the number a
+ * reader needs to trust that the exclusions fired at all.
+ */
+export function scanText(text: string): ScanCount {
+  let renamed = 0
+  let protectedCount = 0
+  const lines = text.split('\n')
+
+  for (const [index, line] of lines.entries()) {
+    if (isKept(lines, index)) continue
+
+    for (const [, guarded] of line.matchAll(SCAN)) {
+      if (guarded === undefined) renamed += 1
+      else protectedCount += 1
+    }
+  }
+
+  return { renamed, protectedCount }
+}
+
+/**
+ * The path a file moves to. Runs the same scanner as the content rewrite, so
+ * a protected form appearing in a path is protected there too and the two
+ * halves of the sweep cannot disagree about what the token means.
+ */
+export function renamePath(path: string): string {
+  return renameText(path)
+}

package/src/pr/bijection.ts

@@ -0,0 +1,145 @@
+import { extractKeyChangePaths, KEY_CHANGES, type PathClaim } from '@/pr/paths'
+
+/**
+ * Why the comparison produced no reading.
+ *
+ * The three are apart because each names a different repair. `no-section` is a
+ * body missing the heading, `no-claims` is the extractor failing over a section
+ * full of prose, and `no-changes` is a pull request with no files. Folding any
+ * of them into a clean pass is the failure this check exists to prevent, since
+ * a reader cannot tell a check that found nothing from one that read nothing.
+ */
+export type BijectionRefusal = 'no-section' | 'no-claims' | 'no-changes'
+
+export interface BijectionReport {
+  readonly kind: 'measured'
+  /** The commit the changed set was read at, which a finding has to name. */
+  readonly head: string | undefined
+  readonly changed: readonly string[]
+  readonly claims: readonly PathClaim[]
+  /**
+   * Anchored claims no changed file answers, which is the graded direction. A
+   * bullet naming an untouched file is wrong more often than not, and this
+   * corpus reported zero of them across 23 correct bodies.
+   */
+  readonly unmet: readonly PathClaim[]
+  /**
+   * Claims whose first segment names no entry in the tree, so the comparison
+   * could not judge them either way. Reported so a run says what it declined
+   * rather than counting a partial spelling as met.
+   */
+  readonly unresolved: readonly PathClaim[]
+  /**
+   * Changed files no claim reaches. Reported without a severity, since the
+   * class covers a real omission and equally a lockfile, a generated asset, or
+   * a regenerated index that legitimately earns no bullet.
+   */
+  readonly unnamed: readonly string[]
+}
+
+export type Bijection =
+  | BijectionReport
+  | { readonly kind: 'refused'; readonly reason: BijectionRefusal }
+
+export interface BijectionInput {
+  readonly body: string
+  readonly changed: readonly string[]
+  /** Top-level entries the tree holds, which decides what counts as anchored. */
+  readonly roots: ReadonlySet<string>
+  readonly head?: string
+  readonly title?: string
+}
+
+/**
+ * Whether one changed path is the file, or a file under the folder, a claim
+ * names.
+ *
+ * An unanchored claim matches on a segment-anchored suffix, which is what lets
+ * `claude-worker/SKILL.md` credit `claude/skills/claude-worker/SKILL.md`. That
+ * asymmetry is deliberate: a partial spelling can confirm a changed file was
+ * named and never accuse one of being absent, because nothing here separates a
+ * path written short from a path written wrong.
+ */
+function covers(claim: PathClaim, path: string): boolean {
+  if (claim.directory) {
+    return claim.anchored
+      ? path.startsWith(claim.path)
+      : path.includes(`/${claim.path}`)
+  }
+  if (path === claim.path) return true
+  return !claim.anchored && path.endsWith(`/${claim.path}`)
+}
+
+/**
+ * Compares what a pull request body claims to have changed against what it
+ * actually changed, in both directions.
+ *
+ * The two directions are reported apart because they want different
+ * tolerances. A claim nobody made good on is a defect in the record that
+ * squash-merges onto the trunk, and a changed file nobody recorded is often
+ * correct. Merging them into one count would either grade the second or excuse
+ * the first.
+ *
+ * Pure, so the whole judgment is testable against a fixture. The caller reads
+ * the body, the changed set, and the tree roots and hands all three in.
+ */
+export function compareKeyChanges(input: BijectionInput): Bijection {
+  if (input.changed.length === 0)
+    return { kind: 'refused', reason: 'no-changes' }
+
+  const read = extractKeyChangePaths(
+    input.body,
+    input.roots,
+    input.title ?? KEY_CHANGES,
+  )
+  if (read.kind === 'no-section')
+    return { kind: 'refused', reason: 'no-section' }
+  if (read.claims.length === 0) return { kind: 'refused', reason: 'no-claims' }
+
+  const unmet: PathClaim[] = []
+  const unresolved: PathClaim[] = []
+  const named = new Set<string>()
+
+  for (const claim of read.claims) {
+    const hits = input.changed.filter((path) => covers(claim, path))
+    for (const path of hits) named.add(path)
+    if (hits.length > 0) continue
+    if (claim.anchored) unmet.push(claim)
+    else unresolved.push(claim)
+  }
+
+  return {
+    kind: 'measured',
+    head: input.head,
+    changed: [...input.changed],
+    claims: read.claims,
+    unmet,
+    unresolved,
+    unnamed: input.changed.filter((path) => !named.has(path)),
+  }
+}
+
+/**
+ * The top-level folders a claim may be anchored on: the first segment of every
+ * path the tree holds, plus the first segment of every changed path.
+ *
+ * The changed half is what admits a folder this branch created. Reading the
+ * tree alone would mark every claim under a new top-level directory unanchored,
+ * and an unanchored claim never accuses, so the first branch to open one would
+ * silently lose the graded direction.
+ *
+ * A path with no folder above it contributes nothing, since a claim carrying no
+ * slash never reaches the extractor's output and no root would ever be read
+ * against it.
+ */
+export function treeRoots(
+  tracked: readonly string[],
+  changed: readonly string[],
+): Set<string> {
+  const roots = new Set<string>()
+  for (const path of [...tracked, ...changed]) {
+    const at = path.indexOf('/')
+    if (at > 0) roots.add(path.slice(0, at))
+  }
+  return roots
+}