@erclx/canon 5.61.0 → 5.62.0

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
 

package/src/tooling/scan.ts

@@ -1,6 +1,13 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { resolveSurfacePath } from '@/roots/surface'
+import {
+  type Disposition,
+  hashFile,
+  readStamp,
+  stampedDispositions,
+  stampedHashes,
+} from '@/sync/stamp'
 import { mergeSections } from '@/tooling/gitignore'
 import {
   ancestorsFirst,
@@ -19,10 +26,14 @@ import {
 } from '@/tooling/package'
 import { isSubfolderTarget, isWithheldInSubfolder } from '@/tooling/subfolder'
 
+export type DriftCause = 'stale' | 'edited' | 'unattributed'
+
+/** `cause` is set on a drifted config alone. */
 export interface ConfigState {
   readonly rel: string
   readonly stack: string
   readonly state: 'new' | 'drifted' | 'matching'
+  readonly cause?: DriftCause
 }
 
 export interface SeedState {
@@ -41,9 +52,24 @@ export interface WithheldState {
   readonly present: boolean
 }
 
+/**
+ * A golden file the project declined or customized, which every write skips.
+ * `moved` is set on a customized config alone, true once the golden copy no
+ * longer hashes to the one the project took.
+ */
+export interface DispositionState {
+  readonly rel: string
+  readonly stack: string
+  readonly kind: 'config' | 'seed'
+  readonly disposition: Disposition
+  readonly present: boolean
+  readonly moved?: boolean
+}
+
 export interface ScanResult {
   readonly configs: readonly ConfigState[]
   readonly withheld: readonly WithheldState[]
+  readonly dispositions: readonly DispositionState[]
   readonly seeds: readonly SeedState[]
   readonly scripts: readonly ScriptState[]
   readonly deps: readonly DepState[]
@@ -53,6 +79,17 @@ export interface ScanResult {
   readonly totalChanges: number
 }
 
+/**
+ * Why a drifted config differs, which decides whether a write may replace it.
+ * A copy still at the hash the last write recorded is `stale`, since canon
+ * moved and the project did not. A copy off it is `edited`, and a copy with no
+ * recorded hash is `unattributed`, since nothing says who changed it.
+ */
+function driftCause(recorded: string | undefined, dest: string): DriftCause {
+  if (recorded === undefined) return 'unattributed'
+  return hashFile(dest) === recorded ? 'stale' : 'edited'
+}
+
 function isIdentical(a: string, b: string): boolean {
   if (!existsSync(b)) return false
   return readFileSync(a).equals(readFileSync(b))
@@ -72,11 +109,19 @@ function isIdentical(a: string, b: string): boolean {
  * GitHub reads only at the root moves to `withheld` and counts as no change.
  * The scope is read here so every caller of `scan` agrees without passing a
  * flag.
+ *
+ * A path the project declined or customized moves to `dispositions` ahead of
+ * the subfolder test, so it is listed once. The record is read here for the
+ * same reason as the scope.
  */
 export function scan(chain: readonly Manifest[], target: string): ScanResult {
   const isSubfolder = isSubfolderTarget(target)
+  const stamp = readStamp(target)
+  const held = stampedDispositions(stamp, 'tooling')
+  const recorded = stampedHashes(stamp, 'tooling')
   const configs: ConfigState[] = []
   const withheld: WithheldState[] = []
+  const dispositions: DispositionState[] = []
   const seenConfigs = new Set<string>()
 
   for (const manifest of chain) {
@@ -87,18 +132,38 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
       const source = join(manifest.configsDir, rel)
       const dest = join(target, rel)
 
+      const entry = held[rel]
+      if (entry !== undefined) {
+        dispositions.push({
+          rel,
+          stack: manifest.name,
+          kind: 'config',
+          disposition: entry.disposition,
+          present: existsSync(dest),
+          ...(entry.disposition === 'customized'
+            ? { moved: hashFile(source) !== entry.base }
+            : {}),
+        })
+        continue
+      }
+
       if (isSubfolder && isWithheldInSubfolder(rel)) {
         withheld.push({ rel, stack: manifest.name, present: existsSync(dest) })
         continue
       }
 
-      const state = !existsSync(dest)
-        ? 'new'
-        : isIdentical(source, dest)
-          ? 'matching'
-          : 'drifted'
-
-      configs.push({ rel, stack: manifest.name, state })
+      if (!existsSync(dest)) {
+        configs.push({ rel, stack: manifest.name, state: 'new' })
+      } else if (isIdentical(source, dest)) {
+        configs.push({ rel, stack: manifest.name, state: 'matching' })
+      } else {
+        configs.push({
+          rel,
+          stack: manifest.name,
+          state: 'drifted',
+          cause: driftCause(recorded[rel], dest),
+        })
+      }
     }
   }
 
@@ -110,6 +175,18 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
       if (seenSeeds.has(rel)) continue
       seenSeeds.add(rel)
 
+      const entry = held[rel]
+      if (entry !== undefined) {
+        dispositions.push({
+          rel,
+          stack: manifest.name,
+          kind: 'seed',
+          disposition: entry.disposition,
+          present: existsSync(resolveSurfacePath(target, rel)),
+        })
+        continue
+      }
+
       if (isSubfolder && isWithheldInSubfolder(rel)) {
         withheld.push({
           rel,
@@ -144,6 +221,7 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
   const totalChanges =
     (newManifest ? 1 : 0) +
     configs.filter((entry) => entry.state !== 'matching').length +
+    dispositions.filter((entry) => entry.moved === true).length +
     seeds.filter((entry) => entry.state === 'missing').length +
     scripts.filter((entry) => entry.state !== 'matching').length +
     deps.filter((entry) => entry.state === 'missing').length +
@@ -152,6 +230,7 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
   return {
     configs,
     withheld,
+    dispositions,
     seeds,
     scripts,
     deps,

package/src/tooling/stamp.ts

@@ -1,7 +1,19 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { readStamp, stampedChain, writeChainStamp } from '@/sync/stamp'
-import { isWholeStack, loadManifest, type Manifest } from '@/tooling/manifest'
+import {
+  type DomainHashes,
+  hashFile,
+  readStamp,
+  stampedChain,
+  stampedHashes,
+  writeChainStamp,
+} from '@/sync/stamp'
+import {
+  configFiles,
+  isWholeStack,
+  loadManifest,
+  type Manifest,
+} from '@/tooling/manifest'
 import { readPackage } from '@/tooling/package'
 
 /**
@@ -32,15 +44,47 @@ export async function recordToolingChain(
 ): Promise<string[] | undefined> {
   if (isWorkspaceRoot(target)) return undefined
 
-  const merged = mergeAddOns(
-    toolkitRoot,
-    stampedChain(readStamp(target), 'tooling'),
-    chain,
+  const stamp = readStamp(target)
+  const merged = mergeAddOns(toolkitRoot, stampedChain(stamp, 'tooling'), chain)
+  await writeChainStamp(
+    target,
+    { domain: 'tooling', toolkitRoot },
+    merged,
+    now,
+    matchedHashes(chain, target, stampedHashes(stamp, 'tooling')),
   )
-  await writeChainStamp(target, { domain: 'tooling', toolkitRoot }, merged, now)
   return merged
 }
 
+/**
+ * The golden hash of every config the target now matches, over the hashes an
+ * earlier run recorded. A config the target holds a different copy of keeps
+ * its previous hash, so a held edit still reads as edited on the next run
+ * rather than as a stale copy the write may replace.
+ */
+function matchedHashes(
+  chain: readonly Manifest[],
+  target: string,
+  previous: DomainHashes,
+): DomainHashes {
+  const hashes: Record<string, string> = { ...previous }
+  const seen = new Set<string>()
+
+  for (const manifest of chain) {
+    for (const rel of configFiles(manifest)) {
+      if (seen.has(rel)) continue
+      seen.add(rel)
+
+      const dest = join(target, rel)
+      if (!existsSync(dest)) continue
+      const golden = hashFile(join(manifest.configsDir, rel))
+      if (hashFile(dest) === golden) hashes[rel] = golden
+    }
+  }
+
+  return hashes
+}
+
 /**
  * An add-on stands alone beside a core chain, so syncing one must not displace
  * the chain it layers onto. Base extends nothing and still heads a core chain.