@erclx/canon 5.59.0 → 5.61.0

package/src/gate/measures.ts

@@ -590,10 +590,16 @@ export const recordIdempotence: Measure = async (ctx) => {
   }
 
   const record = parseJson(run.stdout) as
-    | { moves?: unknown; rewritten?: unknown; paths?: unknown }
+    | {
+        moves?: unknown
+        rewritten?: unknown
+        dropped?: unknown
+        paths?: unknown
+      }
     | undefined
   const moves = record?.moves
   const rewritten = record?.rewritten
+  const dropped = typeof record?.dropped === 'number' ? record.dropped : 0
 
   if (!Array.isArray(moves) || typeof rewritten !== 'number') {
     return {
@@ -613,14 +619,14 @@ export const recordIdempotence: Measure = async (ctx) => {
     }
   }
 
-  if (rewritten > 0) {
+  if (rewritten + dropped > 0) {
     return {
       // The payload already names every file, so listing them here is what
       // separates a count a reader has to go and reproduce from a remedy they
       // can act on. A malformed `paths` costs the list and not the finding,
       // since the count above it was read from a field of its own.
       emissions: citedPaths(record).map((path) => warn(path)),
-      failure: `The records are at .canon/ and ${rewritten} citation(s) still name the old root, so a second run of canon migrate records would rewrite them. Repoint each one, or mark it canon-keep-record-root where the sentence has to keep the old spelling.`,
+      failure: `The records are at .canon/ and ${rewritten + dropped} citation(s) still name the old root, so a second run of canon migrate records would rewrite or drop them. Repoint each one, or mark it canon-keep-record-root where the sentence has to keep the old spelling.`,
     }
   }
 

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/stamp.ts

@@ -16,9 +16,10 @@ import { readInstalled } from '@/version/installed'
  *
  * A stamp written before the standards or snippets install channel closed
  * still carries a `standards` or `snippets` record, and one written before the
- * design install retired carries a `design` record. `isStamp` ignores the key
- * and `sortDomains` drops it on the next write, so the target loses a domain
- * nothing can refresh rather than losing the whole file.
+ * design install retired carries a `design` record. `isStamp` ignores the key,
+ * `readStamp` drops it from what it returns, and `sortDomains` drops it from
+ * the file on the next write, so the target loses a domain nothing can refresh
+ * rather than losing the whole file.
  */
 export const STAMP_DOMAINS = ['governance', 'tooling'] as const
 
@@ -183,12 +184,31 @@ function readStampFile(path: string): Stamp | undefined {
 
   try {
     const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
-    return isStamp(parsed) ? parsed : undefined
+    return isStamp(parsed) ? withoutRetired(parsed) : undefined
   } catch {
     return undefined
   }
 }
 
+/**
+ * A stamp written before a domain retired still names it until the next write.
+ * Filtering here keeps a report on a target that has not synced since from
+ * listing a domain nothing can refresh. The file itself is left as it is.
+ */
+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
+  }
+
+  const covers = Array.isArray(stamp.covers)
+    ? stamp.covers.filter((domain) => STAMP_DOMAINS.includes(domain))
+    : []
+
+  return { covers, domains }
+}
+
 /** The newest canon release that has written this domain, when one was recorded. */
 export function stampedVersion(
   stamp: Stamp | undefined,

package/src/tooling/inject.ts

@@ -1,8 +1,8 @@
 import { existsSync } from 'node:fs'
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
-import { $ } from 'bun'
 import { copyPreservingMode } from '@/sync/copy'
+import { type InstallResult, installDevDependencies } from '@/tooling/install'
 import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
 import { resolveSurfacePath } from '@/roots/surface'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'
@@ -165,7 +165,7 @@ export async function pruneGitignore(
 export async function injectManifest(
   chain: readonly Manifest[],
   target: string,
-): Promise<void> {
+): Promise<InstallResult> {
   const packagePath = join(target, 'package.json')
 
   if (!existsSync(packagePath) && declaresInstalls(chain)) {
@@ -183,7 +183,8 @@ export async function injectManifest(
 
     if (missing.length > 0) {
       logStep('Installing missing dependencies')
-      await $`bun add -D ${missing}`.cwd(target)
+      const installed = await installDevDependencies(missing, target)
+      if (!installed.ok) return installed
       for (const spec of missing) logAdd(spec)
     }
 
@@ -202,6 +203,8 @@ export async function injectManifest(
   await injectGitignore(chain, target)
 
   if (!pkg) warnUnreadablePackage(chain, target)
+
+  return { ok: true }
 }
 
 /**

package/src/tooling/install.ts

@@ -0,0 +1,55 @@
+import { execa } from 'execa'
+
+export const INSTALL_TIMEOUT_MS = 120_000
+const TAIL_LINES = 20
+
+export type InstallResult =
+  | { ok: true }
+  | {
+      ok: false
+      reason: 'install-timeout' | 'install-failed'
+      message: string
+    }
+
+/**
+ * Runs `bun add -D` for the specs and bounds it, since a registry that accepts
+ * a connection and never answers would otherwise hang the caller for good. A
+ * stall or a failure comes back as a refusal naming the packages and the tail
+ * of the output, never as a thrown error.
+ */
+export async function installDevDependencies(
+  specs: readonly string[],
+  cwd: string,
+  timeoutMs: number = INSTALL_TIMEOUT_MS,
+): Promise<InstallResult> {
+  const tried = specs.join(', ')
+  const result = await execa('bun', ['add', '-D', ...specs], {
+    cwd,
+    all: true,
+    reject: false,
+    stdin: 'ignore',
+    timeout: timeoutMs,
+  })
+
+  if (!result.failed) return { ok: true }
+
+  if (result.timedOut) {
+    return {
+      ok: false,
+      reason: 'install-timeout',
+      message: `Install timed out after ${Math.round(timeoutMs / 1000)}s. Tried: ${tried}`,
+    }
+  }
+
+  const detail = tail(result.all) || String(result.shortMessage ?? '')
+  return {
+    ok: false,
+    reason: 'install-failed',
+    message: `Install failed. Tried: ${tried}${detail === '' ? '' : `\n${detail}`}`,
+  }
+}
+
+function tail(output: unknown): string {
+  if (typeof output !== 'string') return ''
+  return output.replace(/\n$/, '').split('\n').slice(-TAIL_LINES).join('\n')
+}