@erclx/canon 4.66.0 → 4.68.0

package/src/design/css.ts

@@ -1,4 +1,6 @@
+import type { Component } from '@/design/components'
 import { COMPONENTS } from '@/design/components'
+import type { FontFace } from '@/design/fonts'
 import { FONT_FACES } from '@/design/fonts'
 import type { DesignTokens } from '@/design/tokens'
 import { TOKENS } from '@/design/tokens'
@@ -113,39 +115,52 @@ ${pairs}
 }`
 }
 
-function componentBlock(): string {
-  return COMPONENTS.map(
-    (component) => `/* ${component.name}
+function componentBlock(components: readonly Component[]): string {
+  return components
+    .map(
+      (component) => `/* ${component.name}
    ${component.note} */
 
 ${component.rules}`,
-  ).join('\n\n')
+    )
+    .join('\n\n')
 }
 
 /**
- * `@font-face` rules carrying the mono stack's primary family as base64, so a
- * stylesheet renders in the same typeface everywhere regardless of what the
- * reader's machine has installed. Only the teach stylesheet opts in today.
+ * `@font-face` rules carrying a font list as base64, so a stylesheet renders
+ * in the same typeface everywhere regardless of what the reader's machine has
+ * installed. Defaults to the mono stack's primary family; teach passes its own
+ * three faces instead of widening this default for every consumer.
  */
-function fontFaceBlock(): string {
-  return FONT_FACES.map(
-    (face) => `@font-face {
+function fontFaceBlock(faces: readonly FontFace[]): string {
+  return faces
+    .map(
+      (face) => `@font-face {
   font-family: '${face.family}';
   font-weight: ${face.weight};
   font-style: normal;
   font-display: swap;
   src: url(data:font/woff2;base64,${face.base64}) format('woff2');
 }`,
-  ).join('\n\n')
+    )
+    .join('\n\n')
 }
 
 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. */
-  readonly components?: boolean
-  /** Off by default. Embeds the mono stack's faces as base64 `@font-face` rules. */
-  readonly embedFonts?: boolean
+  /**
+   * Component rules ride along by default; a token-only consumer opts out
+   * with `false`. Pass an explicit list, such as teach's own chrome set, to
+   * emit those instead of the generic default.
+   */
+  readonly components?: boolean | readonly Component[]
+  /**
+   * Off by default. `true` embeds the mono stack's faces as base64
+   * `@font-face` rules. Pass an explicit list, such as teach's three faces,
+   * to embed those instead.
+   */
+  readonly embedFonts?: boolean | readonly FontFace[]
 }
 
 export function buildDesignCss(
@@ -155,10 +170,22 @@ export function buildDesignCss(
   const banner =
     options.banner === undefined ? '' : `/* ${options.banner} */\n\n`
   const root = [':root {', ...tokenProperties(tokens), '}'].join('\n')
-  const parts = options.embedFonts ? [fontFaceBlock(), root] : [root]
+  const faces =
+    options.embedFonts === true
+      ? FONT_FACES
+      : Array.isArray(options.embedFonts)
+        ? options.embedFonts
+        : undefined
+  const parts = faces ? [fontFaceBlock(faces), root] : [root]
   parts.push(lightBlock(tokens))
 
-  if (options.components !== false) parts.push(componentBlock())
+  const components =
+    options.components === false
+      ? undefined
+      : Array.isArray(options.components)
+        ? options.components
+        : COMPONENTS
+  if (components) parts.push(componentBlock(components))
 
   return `${banner}${parts.join('\n\n')}\n`
 }

package/src/design/tokens.ts

@@ -354,7 +354,7 @@ export const TOKENS: DesignTokens = {
     'Motion is not used. No transition, animation, or keyframe declaration appears on any rendered surface, and the capture pipeline screenshots a static frame.',
 
   iconography:
-    "No icon library is installed. `assets/brand/mark.svg` is the one authored icon, embedded inline in the hero topbar, and the surfaces otherwise draw literal glyph characters: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing. The same mark also ships as a favicon on every rendered surface, as three independently-maintained copies that track different accents by design rather than by drift: `regen-hero.sh` derives one from the live SVG colored with whatever `--color-accent` (`#e0724b`) the fetched token CSS carries, `src/design/render.ts` carries the path data as a hardcoded literal colored via `colorValue('light-accent')` (`#a4471c`), since a data URI has no CSS context and that page renders on light chrome, and `claude-teach`'s `SKILL.md` names one in prose colored `rgb(224,114,75)`, the same value as the dark accent written as decimal rather than hex to clear the shipped-references gate's commit-sha check. Unifying the three or repairing the one that looks drifted would break the fit each was chosen for.",
+    "No icon library is installed. `assets/brand/mark.svg` is the one authored icon, embedded inline in the hero topbar, and the surfaces otherwise draw literal glyph characters: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing. The same mark also ships as a favicon on every rendered surface, as three independently-maintained copies that track different accents by design rather than by drift: `regen-hero.sh` derives one from the live SVG colored with whatever `--color-accent` (`#e0724b`) the fetched token CSS carries, `src/design/render.ts` carries the path data as a hardcoded literal colored via `colorValue('light-accent')` (`#a4471c`), since a data URI has no CSS context and that page renders on light chrome, and `teach-workspace`'s `SKILL.md` names one in prose colored `rgb(224,114,75)`, the same value as the dark accent written as decimal rather than hex to clear the shipped-references gate's commit-sha check. Unifying the three or repairing the one that looks drifted would break the fit each was chosen for.",
 }
 
 /** A role's value, or `undefined` where the record declares no such role. */

package/src/gov/restated.ts

@@ -24,7 +24,7 @@ export const RULES_REL = join('governance', 'rules')
 /**
  * Path pairs whose duplication is deliberate and already recorded.
  *
- * The seed is authored from the always-loaded file and `claude-seed-sync`
+ * The seed is authored from the always-loaded file and `seed-sync`
  * exists to reconcile the two, so a bullet appearing in both is the design
  * rather than a defect. Excluding by pair rather than by content is what the
  * plan settled on: the duplication is a location fact this repository already
@@ -574,7 +574,7 @@ function authorityFor(
   if (candidate.kind === 'seed') {
     return {
       authority: 'claude-md',
-      reason: `${INSTRUCTIONS_REL} is authored first and the seed carries it to a target, so an edit starts there and reaches the seed through claude-seed-sync`,
+      reason: `${INSTRUCTIONS_REL} is authored first and the seed carries it to a target, so an edit starts there and reaches the seed through seed-sync`,
     }
   }
 

package/src/markdown/structure.ts

@@ -26,7 +26,7 @@ const HEADING = /^#{1,6}\s/
  * run and a false one shortens every run around it until the measure stops
  * reporting, which is the dearer of the two.
  *
- * A colon ends most markers and not all of them. `claude-pr-review` writes
+ * A colon ends most markers and not all of them. `review-pr` writes
  * three colon-less ones into every body it posts and a bold path heading for
  * each file it reviews, so requiring the colon held a real seam out. Two
  * signals stand in where the colon is absent, because the shape a marker has to

package/src/migrate/plan.ts

@@ -1,6 +1,7 @@
 import {
   isExcludedPath,
   renamePath,
+  type RenameRules,
   renameText,
   scanText,
 } from '@/migrate/rename'
@@ -59,20 +60,27 @@ export function isToolkitOwned(path: string): boolean {
  * 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.
+ *
+ * The rules arrive as an argument rather than being read from a module, since
+ * this planner serves every rename the engine compiles and the four calls
+ * below have no other way to say which one they mean.
  */
-export function planRename(sources: readonly RenameSource[]): RenamePlan {
+export function planRename(
+  sources: readonly RenameSource[],
+  rules: RenameRules,
+): RenamePlan {
   const entries: RenameEntry[] = []
   const excluded: string[] = []
 
   for (const source of sources) {
-    if (isExcludedPath(source.path)) {
+    if (isExcludedPath(source.path, rules)) {
       excluded.push(source.path)
       continue
     }
 
-    const movesTo = renamePath(source.path)
-    const rewritten = renameText(source.text)
-    const counts = scanText(source.text)
+    const movesTo = renamePath(source.path, rules)
+    const rewritten = renameText(source.text, rules)
+    const counts = scanText(source.text, rules)
     const moved = movesTo !== source.path
     const changed = rewritten !== source.text
 

package/src/migrate/rename.ts

@@ -1,98 +1,154 @@
 /**
- * The token rewrite behind the `aitk` to `canon` rename.
+ * The token rewrite behind a mechanical 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.
+ *
+ * The token map, the protected forms, and the exclusion set are a parameter
+ * rather than module state, so one engine serves more than one rename. Two
+ * sweeps sharing a module constant would have to agree on a single map, and
+ * the second rename this repository needed shares nothing with the first
+ * except the scanning discipline above.
  */
 
 /**
- * Forms carrying the token that name something other than this tool, matched
- * ahead of the token itself so they pass through untouched.
+ * An article whose agreement the rename breaks.
  *
- * `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.
+ * Stated as a pattern and a replacement rather than a function so a preset is
+ * data a test can read back. It runs against the already-rewritten line, which
+ * is what keeps it clear of the protected forms: a form the scanner passed
+ * through still spells the old token afterward, so it never matches here.
  */
-const PROTECTED = ['aitk-sandbox'] as const
+export interface ArticleFixup {
+  readonly pattern: RegExp
+  readonly replacement: string
+}
+
+/** One rename's rules, as an author states them. */
+export interface RenameRuleSpec {
+  /** Every spelling of the token, and what each becomes. */
+  readonly replacements: Readonly<Record<string, string>>
+  /** Marks a line that names a retired spelling on purpose. */
+  readonly keepMarker: string
+  /** Forms carrying a token that name something the rename leaves alone. */
+  readonly protectedForms?: readonly string[]
+  /** Files whose content is left alone entirely. */
+  readonly excludedPaths?: readonly string[]
+  /** Path prefixes whose files are left alone entirely. */
+  readonly excludedPrefixes?: readonly string[]
+  readonly articleFixups?: readonly ArticleFixup[]
+  /**
+   * Whether a token has to end where the word ends.
+   *
+   * A rename whose tokens are whole names wants this, and one whose tokens are
+   * word stems cannot have it. `aitk` is a stem that legitimately carries a
+   * suffix, as in `aitk-allow-superseded`, so requiring a boundary there would
+   * leave every hyphenated form behind. A skill name is not a stem, and the
+   * spelling below is the pre-rename one on purpose (canon-keep-retired):
+   * `claude-worktree` inside `claude-worktrees` is a different subject, the
+   * wiki page about the harness feature, which the rename must not move.
+   */
+  readonly wholeToken?: boolean
+}
 
 /**
- * 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.
+ * A spec with its scanner compiled and its alternatives ordered.
+ *
+ * `tokenOrder` is reported rather than kept private because the ordering is a
+ * correctness property a caller has to be able to assert. A token containing a
+ * shorter token has to be tried first, and reading that off the rewritten
+ * string only works when the two happen to share a destination, which is
+ * correctness by accident rather than by rule.
  */
-const REPLACEMENT: Readonly<Record<string, string>> = {
-  aitk: 'canon',
-  AITK: 'CANON',
-  Aitk: 'Canon',
+export interface RenameRules {
+  readonly replacements: Readonly<Record<string, string>>
+  readonly keepMarker: string
+  readonly protectedForms: readonly string[]
+  readonly tokenOrder: readonly string[]
+  readonly excludedPaths: readonly string[]
+  readonly excludedPrefixes: readonly string[]
+  readonly articleFixups: readonly ArticleFixup[]
+  readonly scan: RegExp
 }
 
 /**
- * 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.
+ * A branch that can never take, standing in for an empty protected list.
+ *
+ * The scanner reads a protected match off capture group 1, so a preset that
+ * protects nothing still has to emit that group or every later group shifts by
+ * one. An empty alternation would match the empty string at every position
+ * instead, which reports a protected hit on every character.
  */
-const SCAN = new RegExp(
-  `(${PROTECTED.join('|')})|(${Object.keys(REPLACEMENT).join('|')})`,
-  'g',
-)
+const NEVER_MATCHES = '(?!)'
 
 /**
- * Files whose content is left alone entirely.
+ * What may not follow a token when a preset asks for whole tokens.
  *
- * 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.
+ * A plain word boundary rejects a following letter and accepts a following
+ * hyphen, since `\b` reads a hyphen as the end of a word. That leaves
+ * `plan-intake` matching inside `plan-intake-answer`, with the ordering of
+ * the alternation the only thing standing between them. Naming the characters
+ * that continue an identifier holds on both, so the ordering and the boundary
+ * each cover what the other could miss, and a slash, a dot, or a backtick
+ * still ends a token.
  */
+const TOKEN_TAIL = '(?![A-Za-z0-9_-])'
+
+function escapeForPattern(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
 /**
- * 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.
+ * Longest first, so a token is never consumed by a shorter token it contains.
+ *
+ * The sort is stable, so alternatives of equal length keep the order the
+ * author wrote them in and a preset whose tokens are all one length compiles
+ * to the alternation it already had.
  */
-const EXCLUDED_PREFIXES: readonly string[] = [
-  'src/migrate/',
-  'scripts/eval/result-',
-]
+function longestFirst(values: readonly string[]): readonly string[] {
+  return [...values].sort((left, right) => right.length - left.length)
+}
 
 /**
- * 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.
+ * 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 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',
-]
+function compileScan(
+  protectedForms: readonly string[],
+  tokenOrder: readonly string[],
+  wholeToken: boolean,
+): RegExp {
+  const guarded =
+    protectedForms.length > 0
+      ? protectedForms.map(escapeForPattern).join('|')
+      : NEVER_MATCHES
 
-export interface ScanCount {
-  readonly renamed: number
-  readonly protectedCount: number
+  const tail = wholeToken ? TOKEN_TAIL : ''
+
+  return new RegExp(
+    `(${guarded})|(${tokenOrder.map(escapeForPattern).join('|')})${tail}`,
+    'g',
+  )
 }
 
-export function isExcludedPath(path: string): boolean {
-  if (EXCLUDED_PATHS.includes(path)) return true
-  return EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix))
+export function defineRenameRules(spec: RenameRuleSpec): RenameRules {
+  const protectedForms = longestFirst(spec.protectedForms ?? [])
+  const tokenOrder = longestFirst(Object.keys(spec.replacements))
+
+  return {
+    replacements: spec.replacements,
+    keepMarker: spec.keepMarker,
+    protectedForms,
+    tokenOrder,
+    excludedPaths: spec.excludedPaths ?? [],
+    excludedPrefixes: spec.excludedPrefixes ?? [],
+    articleFixups: spec.articleFixups ?? [],
+    scan: compileScan(protectedForms, tokenOrder, spec.wholeToken === true),
+  }
 }
 
 /**
@@ -100,54 +156,114 @@ export function isExcludedPath(path: string): boolean {
  * 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.
+ * `an aitk` in the corpus reads wrong the moment the token moves.
  *
  * 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
+const AITK_ARTICLE = /\b([Aa])n(\s+`?)(canon|CANON|Canon)(?![A-Za-z])/g
 
 /**
- * Marks a line that names the retired spelling on purpose.
+ * The `aitk` to `canon` rename.
  *
- * 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.
+ * `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.
+ *
+ * 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.
+ *
+ * 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. An eval result is a transcript on the same argument, recording the
+ * commands a session actually ran under whatever name was current then.
+ *
+ * The sweep's own source is the other excluded member, and it is not a
+ * preference. This module states the `aitk` 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.
+ *
+ * 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 KEEP_MARKER = 'canon-keep-retired'
+export const AITK_RULES: RenameRules = defineRenameRules({
+  replacements: {
+    aitk: 'canon',
+    AITK: 'CANON',
+    Aitk: 'Canon',
+  },
+  keepMarker: 'canon-keep-retired',
+  protectedForms: ['aitk-sandbox'],
+  excludedPrefixes: ['src/migrate/', 'scripts/eval/result-'],
+  excludedPaths: [
+    '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',
+  ],
+  articleFixups: [{ pattern: AITK_ARTICLE, replacement: '$1$2$3' }],
+})
+
+export interface ScanCount {
+  readonly renamed: number
+  readonly protectedCount: number
+}
+
+export function isExcludedPath(path: string, rules: RenameRules): boolean {
+  if (rules.excludedPaths.includes(path)) return true
+  return rules.excludedPrefixes.some((prefix) => path.startsWith(prefix))
+}
 
 /** Rewrites every unprotected spelling of the token. */
-export function renameText(text: string): string {
+export function renameText(text: string, rules: RenameRules): string {
   const lines = text.split('\n')
   const rewritten = lines.map((line, index) =>
-    isKept(lines, index) ? line : renameLine(line),
+    isKept(lines, index, rules) ? line : renameLine(line, rules),
   )
 
   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)
+/**
+ * Whether a line names a 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 a 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.
+ */
+function isKept(
+  lines: readonly string[],
+  index: number,
+  rules: RenameRules,
+): boolean {
+  if (lines[index]?.includes(rules.keepMarker)) return true
+  return index > 0 && (lines[index - 1]?.includes(rules.keepMarker) ?? false)
 }
 
-function renameLine(line: string): string {
-  const replaced = line.replace(SCAN, (match, guarded: string | undefined) =>
-    guarded === undefined ? REPLACEMENT[match] : guarded,
+function renameLine(line: string, rules: RenameRules): string {
+  const replaced = line.replace(
+    rules.scan,
+    (match, guarded: string | undefined) =>
+      guarded === undefined ? rules.replacements[match] : guarded,
   )
 
-  return replaced.replace(
-    ARTICLE,
-    (_match, article: string, gap: string, token: string) =>
-      `${article}${gap}${token}`,
+  return rules.articleFixups.reduce(
+    (text, fixup) => text.replace(fixup.pattern, fixup.replacement),
+    replaced,
   )
 }
 
@@ -156,15 +272,15 @@ function renameLine(line: string): string {
  * 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 {
+export function scanText(text: string, rules: RenameRules): ScanCount {
   let renamed = 0
   let protectedCount = 0
   const lines = text.split('\n')
 
   for (const [index, line] of lines.entries()) {
-    if (isKept(lines, index)) continue
+    if (isKept(lines, index, rules)) continue
 
-    for (const [, guarded] of line.matchAll(SCAN)) {
+    for (const [, guarded] of line.matchAll(rules.scan)) {
       if (guarded === undefined) renamed += 1
       else protectedCount += 1
     }
@@ -178,6 +294,6 @@ export function scanText(text: string): ScanCount {
  * 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)
+export function renamePath(path: string, rules: RenameRules): string {
+  return renameText(path, rules)
 }