@erclx/canon 5.60.0 → 5.62.0

package/src/gov/splits.ts

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Held rule basename to the basenames its moved bullets now live in. */
+export type Splits = ReadonlyMap<string, readonly string[]>
+
+function splitsPath(root: string): string {
+  return join(root, 'governance', 'splits.toml')
+}
+
+/**
+ * Reads the shipped split ledger. A toolkit without one declares no splits,
+ * which leaves every sync silent about partners, the way it was before the
+ * ledger existed.
+ */
+export function loadSplits(root: string): Splits {
+  const path = splitsPath(root)
+  if (!existsSync(path)) return new Map()
+
+  const parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+    string,
+    unknown
+  >
+  const table = parsed.split
+  if (typeof table !== 'object' || table === null) return new Map()
+
+  const entries: [string, string[]][] = []
+  for (const [held, value] of Object.entries(table)) {
+    if (!Array.isArray(value)) continue
+    const partners = value.filter(
+      (partner): partner is string => typeof partner === 'string',
+    )
+    if (partners.length > 0) entries.push([held, partners])
+  }
+  return new Map(entries)
+}

package/src/markdown/structure.ts

@@ -422,6 +422,9 @@ export function longestRun(
  * continuing a bullet do fold in, so a heavy bullet cannot fall under the
  * checkpoint by being wrapped across two source lines. A fenced line closes the
  * open bullet, which keeps a bullet from absorbing the example below it.
+ *
+ * A bullet is measured without its list marker, the way the `bullet-length`
+ * gate measures it, so the count and the gate agree at the checkpoint.
  */
 export function heavyBullets(
   lines: readonly BodyLine[],
@@ -470,7 +473,7 @@ function foldBullets(
       close()
       open = {
         line: line.number,
-        characters: visibleText(text).length,
+        characters: visibleText(text.replace(LIST_ITEM, '')).length,
         text,
         indent: item[1].length,
       }

package/src/migrate/records.ts

@@ -56,14 +56,21 @@ export function destinationPath(entry: string): string {
  * shorter entry can claim its prefix, and each entry is escaped because two of
  * them carry a dot.
  */
+const ENTRY_ALTERNATION = [...MOVED_ENTRIES]
+  .sort((left, right) => right.length - left.length)
+  .map(escape)
+  .join('|')
+
 const CITATION = new RegExp(
-  `${escape(FROM_ROOT)}/(${[...MOVED_ENTRIES]
-    .sort((left, right) => right.length - left.length)
-    .map(escape)
-    .join('|')})(?![A-Za-z0-9._-])`,
+  `${escape(FROM_ROOT)}/(${ENTRY_ALTERNATION})(?![A-Za-z0-9._-])`,
   'g',
 )
 
+/** A gitignore line that is wholly an entry for one moved folder or file. */
+const IGNORE_ENTRY = new RegExp(
+  `^/?${escape(FROM_ROOT)}/(?:${ENTRY_ALTERNATION})/?$`,
+)
+
 function escape(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
@@ -386,6 +393,30 @@ export function scanText(text: string): {
   return { rewritten, kept, globs, crossRepo, dated }
 }
 
+/**
+ * Deletes each live line that is wholly an entry for a moved folder, counting
+ * them. Only a root `.gitignore` that already ignores `.canon/` may be handed
+ * here, since the dropped line is redundant only under that entry. Splitting on
+ * `\n` and matching the trimmed line leaves CRLF endings and a missing final
+ * newline on the lines that stay.
+ */
+export function dropCoveredIgnoreLines(text: string): {
+  readonly text: string
+  readonly dropped: number
+} {
+  const lines = text.split('\n')
+  const frontmatterEndIndex = frontmatterEnd(lines)
+  const kept = lines.filter(
+    (line, index) =>
+      !(
+        IGNORE_ENTRY.test(line.trim()) &&
+        classifyLine(lines, index, frontmatterEndIndex) === 'live'
+      ),
+  )
+
+  return { text: kept.join('\n'), dropped: lines.length - kept.length }
+}
+
 /** Where a citation sits, so a reader can judge it before `--write` runs. */
 export interface CitationLine {
   readonly line: number
@@ -503,6 +534,7 @@ export interface CitationEntry {
   readonly text: string
   readonly rewritten: number
   readonly kept: number
+  readonly dropped: number
 }
 
 /** One file whose frontmatter `paths:` glob names a moved root, held rather than rewritten. */
@@ -533,6 +565,7 @@ export interface RecordsPlan {
   readonly crossRepoCitations: readonly CrossRepoCitationEntry[]
   readonly datedCitations: readonly DatedCitationEntry[]
   readonly rewritten: number
+  readonly dropped: number
   readonly kept: number
   readonly globs: number
   readonly crossRepo: number
@@ -578,7 +611,11 @@ export function planRecordsMove(
       continue
     }
 
-    const counts = scanText(source.text)
+    const swept =
+      source.path === '.gitignore' && ignoresDestination(source.text)
+        ? dropCoveredIgnoreLines(source.text)
+        : { text: source.text, dropped: 0 }
+    const counts = scanText(swept.text)
     kept += counts.kept
     globs += counts.globs
     crossRepo += counts.crossRepo
@@ -599,15 +636,16 @@ export function planRecordsMove(
     if (dates.length > 0)
       datedCitations.push({ path: source.path, lines: dates })
 
-    if (counts.rewritten === 0) continue
+    if (counts.rewritten === 0 && swept.dropped === 0) continue
 
     if (referencesExcluded(source.text)) coupled.push(source.path)
 
     entries.push({
       path: source.path,
-      text: rewriteText(source.text),
+      text: rewriteText(swept.text),
       rewritten: counts.rewritten,
       kept: counts.kept,
+      dropped: swept.dropped,
     })
   }
 
@@ -621,6 +659,7 @@ export function planRecordsMove(
     crossRepoCitations,
     datedCitations,
     rewritten: entries.reduce((sum, entry) => sum + entry.rewritten, 0),
+    dropped: entries.reduce((sum, entry) => sum + entry.dropped, 0),
     kept,
     globs,
     crossRepo,

package/src/records/stale-canonical.ts

@@ -5,8 +5,8 @@ import { relative } from 'node:path'
 import { gitEnv } from '@/git/env'
 import { surfaceDir } from '@/roots/surface'
 
-/** The record whose drift is identity rather than a stale path. */
-const CANONICAL_DOCS = ['REQUIREMENTS.md'] as const
+/** The records carrying a `reviewed:` review point, whose drift is how far the project moved since they were read whole. */
+const CANONICAL_DOCS = ['REQUIREMENTS.md', 'DESIGN.md'] as const
 
 export interface CanonicalDoc {
   /** Relative to the root, at whichever surface root carries the doc. */

package/src/sync/check.ts

@@ -105,8 +105,13 @@ export interface UpstreamCommit {
 }
 
 /** Pending changes per category, from the same scan `canon tooling sync` reads. */
+/**
+ * `customized` counts a customization whose golden copy moved, which no write
+ * touches, so a caller points at `canon tooling lift` rather than `--write`.
+ */
 export interface ToolingCounts {
   readonly configs: number
+  readonly customized: number
   readonly seeds: number
   readonly scripts: number
   readonly deps: number
@@ -137,6 +142,7 @@ const UNMEASURED_TOOLING: ToolingReport = {
   chain: [],
   counts: {
     configs: 0,
+    customized: 0,
     seeds: 0,
     scripts: 0,
     deps: 0,
@@ -257,6 +263,8 @@ export function buildToolingReport(
     counts: {
       configs: result.configs.filter((entry) => entry.state !== 'matching')
         .length,
+      customized: result.dispositions.filter((entry) => entry.moved === true)
+        .length,
       seeds: result.seeds.filter((entry) => entry.state === 'missing').length,
       scripts: result.scripts.filter((entry) => entry.state !== 'matching')
         .length,
@@ -275,7 +283,7 @@ export function buildToolingReport(
  * skipped stack still shipped. The re-resolution is kept only when its whole
  * stacks are exactly the recorded ones.
  */
-function resolveRecorded(
+export function resolveRecorded(
   toolkitRoot: string,
   recorded: readonly string[],
 ): Manifest[] {

package/src/sync/stamp.ts

@@ -12,7 +12,8 @@ import { readInstalled } from '@/version/installed'
 /**
  * Domains the stamp can record. Governance attributes file by file through
  * the sync engine. Tooling runs its own inject and manifest machinery, so it
- * records the stack chain it resolved instead and carries no file hashes.
+ * records the stack chain it resolved, and hashes only the configs a target
+ * matched, which is what lets a later write tell a stale copy from an edit.
  *
  * A stamp written before the standards or snippets install channel closed
  * still carries a `standards` or `snippets` record, and one written before the
@@ -34,6 +35,23 @@ export interface StampSource {
 /** Target-relative posix path to content hash, for one domain. */
 export type DomainHashes = Readonly<Record<string, string>>
 
+export const DISPOSITIONS = ['declined', 'customized'] as const
+
+export type Disposition = (typeof DISPOSITIONS)[number]
+
+/**
+ * What a project decided about one golden file. `base` is the golden hash a
+ * customized file was taken from, so a later scan can tell the copy moved.
+ */
+export interface DispositionEntry {
+  readonly disposition: Disposition
+  readonly base?: string
+  readonly reason?: string
+}
+
+/** Golden posix path to the project's decision about it, for one domain. */
+export type DomainDispositions = Readonly<Record<string, DispositionEntry>>
+
 /**
  * One domain's record. The anchor sits here rather than at the top level
  * because domains sync independently, and a shared anchor would let a gov sync
@@ -61,6 +79,12 @@ export interface DomainStamp {
    * ancestors internally and a reader needs only the leaf to ask it again.
    */
   readonly chain?: readonly string[]
+  /**
+   * Golden files the project declined or customized. Validated apart from the
+   * record, so a malformed map reads as empty rather than failing the stamp
+   * and costing every other domain its record.
+   */
+  readonly dispositions?: DomainDispositions
 }
 
 export interface Stamp {
@@ -199,7 +223,7 @@ 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
+    if (record !== undefined) domains[domain] = withValidDispositions(record)
   }
 
   const covers = Array.isArray(stamp.covers)
@@ -245,6 +269,14 @@ export function stampedChain(
   return stamp?.domains[domain]?.chain ?? []
 }
 
+/** The golden files a domain's project declined or customized. */
+export function stampedDispositions(
+  stamp: Stamp | undefined,
+  domain: StampDomain,
+): DomainDispositions {
+  return stamp?.domains[domain]?.dispositions ?? {}
+}
+
 /**
  * Replaces one domain's file hashes and leaves the others, including that
  * domain's own chain, untouched. Domains install and sync independently but
@@ -261,24 +293,61 @@ export async function writeStamp(
 }
 
 /**
- * Records the stack chain an install resolved and leaves that domain's file
- * hashes untouched. Tooling calls this with no files ever recorded, since
- * `src/tooling/` never runs the sync engine and the chain is its whole record.
- * Governance calls it alongside `writeStamp`, since it records both.
+ * Records the stack chain an install resolved, and leaves that domain's file
+ * hashes untouched unless `files` is passed. Tooling passes the golden hash of
+ * each config the target matches, since it never runs the sync engine.
+ * Governance calls it alongside `writeStamp`, since that records its files.
  */
 export async function writeChainStamp(
   target: string,
   source: StampSource,
   chain: readonly string[],
   now: Date,
+  files?: DomainHashes,
+): Promise<void> {
+  await putDomain(
+    target,
+    source,
+    {
+      chain: [...chain],
+      ...(files === undefined ? {} : { files: sortKeys(files) }),
+    },
+    now,
+  )
+}
+
+/**
+ * Replaces one domain's dispositions and leaves the rest of its record as it
+ * was, sync anchor included, since declining a file is not a sync. A domain
+ * with no record yet gets one through the ordinary write.
+ */
+export async function writeDispositions(
+  target: string,
+  source: StampSource,
+  dispositions: DomainDispositions,
+  now: Date,
 ): Promise<void> {
-  await putDomain(target, source, { chain: [...chain] }, now)
+  const previous = readStamp(target)
+  const previousRecord = previous?.domains[source.domain]
+  if (previousRecord === undefined) {
+    await putDomain(target, source, { dispositions }, now)
+    return
+  }
+
+  const { dispositions: _replaced, ...rest } = previousRecord
+  await persist(
+    target,
+    previous,
+    source.domain,
+    { ...rest, ...dispositionsField(dispositions) },
+    now,
+  )
 }
 
 async function putDomain(
   target: string,
   source: StampSource,
-  payload: Partial<Pick<DomainStamp, 'files' | 'chain'>>,
+  payload: Partial<Pick<DomainStamp, 'files' | 'chain' | 'dispositions'>>,
   now: Date,
 ): Promise<void> {
   const previous = readStamp(target)
@@ -292,11 +361,24 @@ async function putDomain(
     syncedAt: now.toISOString(),
     files: payload.files ?? previousRecord?.files ?? {},
     ...resolveChainField(payload.chain, previousRecord?.chain),
+    ...dispositionsField(
+      payload.dispositions ?? previousRecord?.dispositions ?? {},
+    ),
   }
 
+  await persist(target, previous, source.domain, record, now)
+}
+
+async function persist(
+  target: string,
+  previous: Stamp | undefined,
+  domain: StampDomain,
+  record: DomainStamp,
+  now: Date,
+): Promise<void> {
   const domains = sortDomains({
     ...previous?.domains,
-    [source.domain]: record,
+    [domain]: record,
   })
 
   const stamp: Stamp = {
@@ -434,10 +516,52 @@ function resolveChainField(
   return resolved === undefined ? {} : { chain: resolved }
 }
 
+/** An empty map is left out of the file, as an unrecorded chain is. */
+function dispositionsField(
+  dispositions: DomainDispositions,
+): Pick<DomainStamp, 'dispositions'> {
+  return Object.keys(dispositions).length === 0
+    ? {}
+    : { dispositions: sortKeys(dispositions) }
+}
+
+/**
+ * Keeps each well-formed entry and drops the rest, so one bad entry costs only
+ * itself, and a map that is not an object costs only the map.
+ */
+function withValidDispositions(record: DomainStamp): DomainStamp {
+  const { dispositions, ...rest } = record
+  const raw: unknown = dispositions
+  if (raw === undefined) return record
+  if (!isRecord(raw)) return rest
+
+  return {
+    ...rest,
+    ...dispositionsField(
+      Object.fromEntries(
+        Object.entries(raw).filter(([, entry]) => isDispositionEntry(entry)),
+      ) as DomainDispositions,
+    ),
+  }
+}
+
+function isDispositionEntry(value: unknown): value is DispositionEntry {
+  if (!isRecord(value)) return false
+  if (!(DISPOSITIONS as readonly unknown[]).includes(value.disposition)) {
+    return false
+  }
+  if (value.base !== undefined && typeof value.base !== 'string') return false
+  return value.reason === undefined || typeof value.reason === 'string'
+}
+
 /** Deterministic key order keeps a re-sync diff empty and a merge conflict local. */
-function sortKeys(hashes: DomainHashes): DomainHashes {
+function sortKeys<T>(
+  entries: Readonly<Record<string, T>>,
+): Readonly<Record<string, T>> {
   return Object.fromEntries(
-    Object.entries(hashes).sort(([left], [right]) => left.localeCompare(right)),
+    Object.entries(entries).sort(([left], [right]) =>
+      left.localeCompare(right),
+    ),
   )
 }
 

package/src/tooling/disposition.ts

@@ -0,0 +1,167 @@
+import { join, posix } from 'node:path'
+import {
+  type DomainDispositions,
+  hashFile,
+  readStamp,
+  stampedDispositions,
+} from '@/sync/stamp'
+import { configFiles, type Manifest, seedFiles } from '@/tooling/manifest'
+
+/** A golden file as the chain ships it: the stack that wins, and that copy's hash. */
+export interface GoldenPath {
+  readonly rel: string
+  readonly stack: string
+  readonly kind: 'config' | 'seed'
+  readonly hash: string
+}
+
+export type Transition =
+  | { readonly ok: true; readonly dispositions: DomainDispositions }
+  | { readonly ok: false; readonly reason: string; readonly message: string }
+
+export function readDispositions(target: string): DomainDispositions {
+  return stampedDispositions(readStamp(target), 'tooling')
+}
+
+/**
+ * The posix key a target-relative path is recorded under, or undefined for a
+ * path that leaves the target, since no golden file lives there.
+ */
+export function normalizeGoldenPath(input: string): string | undefined {
+  const rel = posix.normalize(input.split('\\').join('/'))
+  if (rel === '.' || rel === '' || posix.isAbsolute(rel)) return undefined
+  if (rel === '..' || rel.startsWith('../')) return undefined
+  return rel
+}
+
+/**
+ * Resolves a path the way `scan` and the injectors do: nearest stack first,
+ * and a config shadows a seed at the same path. The hash is of the copy
+ * `injectConfigs` writes last, which is the nearest stack's.
+ */
+export function resolveGolden(
+  chain: readonly Manifest[],
+  rel: string,
+): GoldenPath | undefined {
+  for (const manifest of chain) {
+    if (configFiles(manifest).includes(rel)) {
+      return golden(manifest, rel, 'config', manifest.configsDir)
+    }
+  }
+  for (const manifest of chain) {
+    if (seedFiles(manifest).includes(rel)) {
+      return golden(manifest, rel, 'seed', manifest.seedsDir)
+    }
+  }
+  return undefined
+}
+
+function golden(
+  manifest: Manifest,
+  rel: string,
+  kind: GoldenPath['kind'],
+  dir: string,
+): GoldenPath {
+  return { rel, stack: manifest.name, kind, hash: hashFile(join(dir, rel)) }
+}
+
+export function decline(
+  dispositions: DomainDispositions,
+  path: GoldenPath | undefined,
+  reason?: string,
+): Transition {
+  if (path === undefined) return NOT_GOLDEN
+  const { rel } = path
+  const held = refuseHeld(dispositions, rel)
+  if (held !== undefined) return held
+
+  return {
+    ok: true,
+    dispositions: {
+      ...dispositions,
+      [rel]: {
+        disposition: 'declined',
+        ...(reason === undefined ? {} : { reason }),
+      },
+    },
+  }
+}
+
+/**
+ * A seed is copy-once, so the target already owns it and a customization
+ * would record nothing a sync does not already respect.
+ */
+export function customize(
+  dispositions: DomainDispositions,
+  path: GoldenPath | undefined,
+  present: boolean,
+): Transition {
+  if (path === undefined) return NOT_GOLDEN
+  const { rel, kind, hash } = path
+  const held = refuseHeld(dispositions, rel)
+  if (held !== undefined) return held
+
+  if (kind === 'seed') {
+    return {
+      ok: false,
+      reason: 'seed-not-customizable',
+      message: `${rel} is a seed, which sync never overwrites. Decline it instead to keep sync from restoring it.`,
+    }
+  }
+  if (!present) {
+    return {
+      ok: false,
+      reason: 'missing-file',
+      message: `${rel} is not in the target, so there is no copy to keep. Decline it instead.`,
+    }
+  }
+
+  return {
+    ok: true,
+    dispositions: {
+      ...dispositions,
+      [rel]: { disposition: 'customized', base: hash },
+    },
+  }
+}
+
+/**
+ * Lifts by key alone, so a path the chain stopped shipping can still be
+ * cleared from the record.
+ */
+export function lift(
+  dispositions: DomainDispositions,
+  rel: string,
+): Transition {
+  if (dispositions[rel] === undefined) {
+    return {
+      ok: false,
+      reason: 'not-held',
+      message: `${rel} is neither declined nor customized.`,
+    }
+  }
+
+  const { [rel]: _lifted, ...rest } = dispositions
+  return { ok: true, dispositions: rest }
+}
+
+const NOT_GOLDEN: Transition = {
+  ok: false,
+  reason: 'not-golden',
+  message:
+    'No stack in the recorded chain ships that path. Pass it relative to the target, as `canon tooling diff` lists it.',
+}
+
+function refuseHeld(
+  dispositions: DomainDispositions,
+  rel: string,
+): Transition | undefined {
+  const held = dispositions[rel]
+  if (held === undefined) return undefined
+
+  return {
+    ok: false,
+    reason: 'already-held',
+    message: `${rel} is already ${held.disposition}. Run \`canon tooling lift ${rel}\` first to change it.`,
+  }
+}

package/src/tooling/inject.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
 import { copyPreservingMode } from '@/sync/copy'
+import { readDispositions } from '@/tooling/disposition'
 import { type InstallResult, installDevDependencies } from '@/tooling/install'
 import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
 import { resolveSurfacePath } from '@/roots/surface'
@@ -24,16 +25,27 @@ import {
 import { isSubfolderTarget, isWithheldInSubfolder } from '@/tooling/subfolder'
 import { logAdd, logRemove, logStep, logWarn } from '@/cli/ui'
 
+/**
+ * Skips every path the project declined or customized, which is what makes
+ * the record hold for `sync --write` and `inject` alike. `hold` names the
+ * further paths a caller decided this write must leave, which `sync` derives
+ * from the scan and `inject`, writing without one, never passes.
+ */
 export async function injectConfigs(
   chain: readonly Manifest[],
   target: string,
+  hold: ReadonlySet<string> = new Set(),
 ): Promise<string[]> {
   const applied: string[] = []
   const isSubfolder = isSubfolderTarget(target)
+  const held = readDispositions(target)
 
   for (const manifest of ancestorsFirst(chain)) {
     const files = configFiles(manifest).filter(
-      (rel) => !(isSubfolder && isWithheldInSubfolder(rel)),
+      (rel) =>
+        held[rel] === undefined &&
+        !hold.has(rel) &&
+        !(isSubfolder && isWithheldInSubfolder(rel)),
     )
     if (files.length === 0) continue
 
@@ -83,11 +95,14 @@ export async function injectSeeds(
   const applied: string[] = []
   const isSubfolder = isSubfolderTarget(target)
   const shadowed = configPaths(chain)
+  const held = readDispositions(target)
 
   for (const manifest of ancestorsFirst(chain)) {
     const files = seedFiles(manifest).filter(
       (rel) =>
-        !shadowed.has(rel) && !(isSubfolder && isWithheldInSubfolder(rel)),
+        !shadowed.has(rel) &&
+        held[rel] === undefined &&
+        !(isSubfolder && isWithheldInSubfolder(rel)),
     )
     if (files.length === 0) continue