@erclx/canon 5.61.0 → 5.63.0

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
 

package/src/tooling/package.ts

@@ -17,7 +17,9 @@ export interface ScriptState {
 export interface DepState {
   readonly spec: string
   readonly name: string
-  readonly state: 'missing' | 'present'
+  readonly state: 'missing' | 'present' | 'ahead'
+  /** The spec the target records, set only when it is `ahead` of the pin. */
+  readonly installed?: string
 }
 
 export function readPackage(path: string): PackageJson | undefined {
@@ -89,18 +91,24 @@ function firstInteger(value: string): string | undefined {
 
 /**
  * Compares a manifest pin against what package.json records. A spec counts as
- * missing when absent, or when the pinned major differs from the installed
- * major. Anything looser than a major mismatch is left alone.
+ * missing when absent or on an earlier major than the pin, and ahead when it
+ * sits on a later one, which a write leaves alone. A spec with no integer to
+ * compare, such as `latest` or `workspace:*`, counts as present.
  */
-function isSatisfied(installed: string | undefined, pin: string): boolean {
-  if (installed === undefined) return false
-  if (pin === '') return true
+function compareSpec(
+  installed: string | undefined,
+  pin: string,
+): DepState['state'] {
+  if (installed === undefined) return 'missing'
+  if (pin === '') return 'present'
 
   const pinMajor = firstInteger(pin)
   const installedMajor = firstInteger(installed)
-  if (pinMajor === undefined) return true
+  if (pinMajor === undefined || installedMajor === undefined) return 'present'
 
-  return pinMajor === installedMajor
+  const delta = Number(installedMajor) - Number(pinMajor)
+  if (delta === 0) return 'present'
+  return delta > 0 ? 'ahead' : 'missing'
 }
 
 /**
@@ -121,11 +129,12 @@ export function collectDeps(
       if (name === '' || seen.has(name)) continue
       seen.add(name)
 
-      states.push({
-        spec,
-        name,
-        state: isSatisfied(installed[name], pin) ? 'present' : 'missing',
-      })
+      const state = compareSpec(installed[name], pin)
+      states.push(
+        state === 'ahead'
+          ? { spec, name, state, installed: installed[name] }
+          : { spec, name, state },
+      )
     }
   }