@erclx/canon 5.60.0 → 5.62.0

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.