@erclx/canon 4.85.0 → 4.87.0

package/src/commands/migrate.ts

@@ -30,6 +30,13 @@ import {
   planSurfaceRootsMove,
   type SurfaceRootsPlan,
 } from '@/migrate/surface-roots'
+import {
+  applyRecordLayout,
+  planRecordLayout,
+  readRecordLayoutCorpus,
+  type RecordLayoutPlan,
+  walkRecordLayoutCorpus,
+} from '@/migrate/record-layout'
 import {
   applyScratchEvidence,
   planScratchEvidence,
@@ -664,7 +671,7 @@ interface ScratchEvidenceOptions {
 
 /**
  * Moves the nine cited-and-unwritten folders under `.canon/tmp/` to
- * `.canon/review/evidence/`, and repoints the citations that name them,
+ * `.canon/evidence/`, and repoints the citations that name them,
  * archives included.
  */
 async function runScratchEvidence(
@@ -746,6 +753,108 @@ function toScratchEvidenceRecord(
   }
 }
 
+interface RecordLayoutOptions {
+  readonly json?: boolean
+  readonly write?: boolean
+  readonly root?: string
+}
+
+/**
+ * Moves every row of `RECORD_LAYOUT_MOVES`: the memory pen's receipts and
+ * retired entries under `.canon/memory/`, and everything under
+ * `.canon/review/` that is not a review out to its own folder, then repoints
+ * the citations that name any of them.
+ */
+async function runRecordLayout(opts: RecordLayoutOptions): Promise<number> {
+  const root = opts.root ?? process.cwd()
+
+  const files = await walkRecordLayoutCorpus(root)
+  const sources = await readRecordLayoutCorpus(files)
+  const plan = planRecordLayout(root, sources)
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(toRecordLayoutRecord(plan, opts.write))}\n`,
+    )
+  }
+
+  reportRecordLayout(plan)
+
+  if (plan.collisions.length > 0) {
+    logError(
+      `${plural(plan.collisions.length, 'destination')} already occupied. Neither side moved.`,
+    )
+    for (const collision of plan.collisions) logError(`  ${collision}`)
+  }
+
+  if (plan.moves.length === 0 && plan.entries.length === 0) {
+    return plan.collisions.length > 0 ? 1 : 0
+  }
+
+  if (!opts.write) {
+    logWarn('Nothing was written. Pass --write to apply this plan.')
+    return 2
+  }
+
+  const applied = await applyRecordLayout(plan)
+  logStep(
+    `Moved ${plural(applied.moved, 'path')} and rewrote ${plural(applied.written, 'file')}.`,
+  )
+
+  if (applied.failed.length > 0) {
+    logError(`Could not write ${plural(applied.failed.length, 'file')}.`)
+    for (const path of applied.failed) logError(`  ${path}`)
+    return 1
+  }
+
+  return plan.collisions.length > 0 ? 1 : 0
+}
+
+function reportRecordLayout(plan: RecordLayoutPlan): void {
+  logInfo(`${plural(plan.moves.length, 'path')} to move.`)
+  for (const move of plan.moves) {
+    const label = move.classified === undefined ? '' : ` (${move.classified})`
+    logInfo(`  ${move.from} -> ${move.to}${label}`)
+  }
+
+  logInfo(
+    `${plural(plan.entries.length, 'file')} to change, ${plural(plan.rewritten, 'citation')} to rewrite.`,
+  )
+  for (const entry of plan.entries) {
+    logInfo(`  ${entry.path}: ${plural(entry.rewritten, 'citation')}`)
+  }
+
+  if (plan.strays.length > 0) {
+    logWarn(
+      `${plural(plan.strays.length, 'stray receipt')} at the flat review/ root. Not moved, move by hand into memory/review/.`,
+    )
+    for (const stray of plan.strays) logWarn(`  ${stray}`)
+  }
+}
+
+function toRecordLayoutRecord(
+  plan: RecordLayoutPlan,
+  wrote: boolean | undefined,
+): unknown {
+  return {
+    ok: true,
+    wrote: wrote === true,
+    moves: plan.moves.map((move) => ({
+      from: move.from,
+      to: move.to,
+      ...(move.classified === undefined ? {} : { classified: move.classified }),
+    })),
+    collisions: plan.collisions,
+    files: plan.entries.length,
+    rewritten: plan.rewritten,
+    strays: plan.strays,
+    paths: plan.entries.map((entry) => ({
+      path: entry.path,
+      rewritten: entry.rewritten,
+    })),
+  }
+}
+
 interface RuleLayoutOptions {
   readonly json?: boolean
   readonly write?: boolean
@@ -994,7 +1103,7 @@ export function register(program: Command): void {
 
   migrate
     .command('scratch-evidence')
-    .description('Promote cited measurement folders out of tmp into review')
+    .description('Promote cited measurement folders out of tmp into evidence')
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
     .option('--write', 'Apply the plan rather than reporting it')
@@ -1007,7 +1116,7 @@ export function register(program: Command): void {
       [
         '',
         'Moves nine folders cited as measurement evidence from .canon/tmp/ to',
-        '.canon/review/evidence/, which canon records push already backs, and',
+        '.canon/evidence/<nn>-<folder>/, numbered by first appearance, and',
         'repoints every citation that names one, live or archived.',
         '',
         'A promoted folder is one a durable record cites and no source file',
@@ -1031,6 +1140,62 @@ export function register(program: Command): void {
       process.exitCode = await runScratchEvidence(opts)
     })
 
+  migrate
+    .command('record-layout')
+    .description('Move record folders to their batch layout')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--write', 'Apply the plan rather than reporting it')
+    .option(
+      '--root <path>',
+      'Project root, defaulting to the working directory',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Moves review receipts from .canon/review/memory/ to',
+        '.canon/memory/review/, and retired entries from',
+        '.canon/tmp/memory-archive/ to .canon/memory/archive/, backed for',
+        'the first time.',
+        '',
+        'Leaves .canon/review/ holding only reviews:',
+        '  review/feedback/                -> feedback/',
+        '  review/{design,board,slides,diagrams}/ -> tmp/render/<kind>/',
+        '  review/references/              -> picks/references/',
+        '  review/branch/review-<slug>.md  -> review/branch-<slug>.md',
+        '  review/ui-checklist-<slug>.md   -> tmp/ui-checklist/<slug>.md',
+        '  review/evidence/<slug>/         -> picks/<slug>/ or evidence/<nn>-<slug>/',
+        '',
+        'An evidence folder is a pick when it directly holds an arm-<id>',
+        'capture or a design-handoff.md, and evidence otherwise. Evidence',
+        'folders are numbered by the oldest file each holds, continuing past',
+        'any ordinal evidence/ already carries. The dry run labels every',
+        'derived destination, so check the split before passing --write.',
+        '',
+        'A citation reaching into a moved folder or naming a moved file is',
+        'repointed, live or archived. A bare mention of an emptied folder, such',
+        'as review/evidence/ with no slug, matches no row and stays as written.',
+        '',
+        'A receipt sitting at the flat review/ root, the shape memory-review',
+        'wrote before review/memory/ existed, is reported rather than moved.',
+        '',
+        'Exit codes:',
+        '  0  nothing to move, or --write applied the whole plan',
+        '  1  a write failed, or an unresolved collision remains',
+        '  2  a plan exists and --write was not passed',
+        '',
+        'Examples:',
+        '  canon migrate record-layout',
+        '  canon migrate record-layout --write',
+        '  canon migrate record-layout --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RecordLayoutOptions) => {
+      process.exitCode = await runRecordLayout(opts)
+    })
+
   migrate
     .command('rename')
     .description('Rewrite every unprotected aitk token to canon')

package/src/commands/slides.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
-import { creationRel } from '@/record-root'
+import { creationRel, SCRATCH } from '@/record-root'
 import { LAYOUTS } from '@/slides/layouts'
 import { openDeck } from '@/slides/open'
 import { renderSlidesDoc } from '@/slides/render'
@@ -20,7 +20,7 @@ export function register(program: Command): void {
     .option(
       '-o, --out <path>',
       'Output directory',
-      creationRel(process.cwd(), 'review', 'slides'),
+      creationRel(process.cwd(), SCRATCH, 'render', 'slides'),
     )
     .option('-v, --variant <variant>', 'Override variant (light or dark)')
     .option(

package/src/design/board.ts

@@ -399,7 +399,7 @@ function isImage(name: string): boolean {
   return IMAGE_EXTENSIONS.some((ext) => name.toLowerCase().endsWith(ext))
 }
 
-/** Every image file directly inside an evidence arm folder, one level deep. */
+/** Every image file directly inside a pick folder, one level deep. */
 function imagesIn(dir: string): string[] {
   return readdirSync(dir, { withFileTypes: true })
     .filter((entry) => entry.isFile() && isImage(entry.name))
@@ -407,32 +407,39 @@ function imagesIn(dir: string): string[] {
     .sort()
 }
 
+/**
+ * The folder under `picks/` holding operator-supplied reference images, which
+ * the References panel reads. It sits beside the captures of the choices it
+ * fed, so the candidates panel steps over it rather than listing it as a pick.
+ */
+const REFERENCES_FOLDER = 'references'
+
 function writeCandidatesPanel(root: string, outDir: string): void {
   const dir = join(outDir, 'candidates')
   mkdirSync(dir, { recursive: true })
 
-  const evidenceDir = recordDir(root, 'review', 'evidence')
-  if (!existsSync(evidenceDir)) {
+  const picksDir = recordDir(root, 'picks')
+  if (!existsSync(picksDir)) {
     writeFileSync(
       join(dir, 'index.html'),
       panelPage(
         'Past candidates',
-        `<p class="empty">No ${relative(root, evidenceDir)} folder yet.</p>`,
+        `<p class="empty">No ${relative(root, picksDir)} folder yet.</p>`,
       ),
     )
     return
   }
 
-  const folders = readdirSync(evidenceDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
+  const folders = readdirSync(picksDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name !== REFERENCES_FOLDER)
     .map((entry) => entry.name)
     .sort()
 
   const found: Array<{ folder: string; images: string[] }> = []
   for (const folder of folders) {
-    const images = imagesIn(join(evidenceDir, folder))
+    const images = imagesIn(join(picksDir, folder))
     if (images.length > 0) {
-      cpSync(join(evidenceDir, folder), join(dir, folder), { recursive: true })
+      cpSync(join(picksDir, folder), join(dir, folder), { recursive: true })
       found.push({ folder, images })
     }
   }
@@ -442,7 +449,7 @@ function writeCandidatesPanel(root: string, outDir: string): void {
       join(dir, 'index.html'),
       panelPage(
         'Past candidates',
-        `<p class="empty">${folders.length} folders under ${relative(root, evidenceDir)}/ and none carries a draft-and-pick arm capture. The archival capture step has not run since it shipped.</p>`,
+        `<p class="empty">${folders.length} folders under ${relative(root, picksDir)}/ and none carries a draft-and-pick arm capture. The archival capture step has not run since it shipped.</p>`,
       ),
     )
     return
@@ -462,7 +469,7 @@ function writeReferencesPanel(root: string, outDir: string): void {
   const dir = join(outDir, 'references')
   mkdirSync(dir, { recursive: true })
 
-  const referencesDir = recordDir(root, 'review', 'references')
+  const referencesDir = recordDir(root, 'picks', REFERENCES_FOLDER)
   if (!existsSync(referencesDir)) {
     writeFileSync(
       join(dir, 'index.html'),

package/src/migrate/evidence-ordinal.ts

@@ -0,0 +1,79 @@
+/**
+ * How a folder under `.canon/evidence/` is numbered, shared by the two
+ * migrations that land folders there.
+ *
+ * A folder takes `<nn>-<slug>` in the order folders first appeared, and a new
+ * one continues past the highest ordinal already present. No record folder is
+ * tracked in git, so file modification times are the only history a target
+ * holds to order by.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { extractOrdinal } from '@/intake/folder'
+
+const ORDINAL_WIDTH = 2
+
+/**
+ * When a folder first appeared, read as the oldest modification time of any
+ * file under it. A folder holding no file falls back to its own.
+ */
+export function firstAppearance(dir: string): number {
+  let oldest = Number.POSITIVE_INFINITY
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name)
+    const time = entry.isDirectory()
+      ? firstAppearance(path)
+      : statSync(path).mtimeMs
+    oldest = Math.min(oldest, time)
+  }
+
+  return Number.isFinite(oldest) ? oldest : statSync(dir).mtimeMs
+}
+
+/** The folder names directly inside `dir`, sorted, or none when it is absent. */
+export function folderNames(dir: string): string[] {
+  if (!existsSync(dir)) return []
+
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+/** A folder name with any leading ordinal removed. */
+export function slugOf(name: string): string {
+  const ordinal = extractOrdinal(name)
+  return ordinal === '' ? name : name.slice(ordinal.length + 1)
+}
+
+/** The ordinal a new folder takes after every name already present. */
+export function nextOrdinal(existing: readonly string[]): number {
+  return (
+    existing
+      .map((name) => Number(extractOrdinal(name) || 0))
+      .reduce((carry, ordinal) => Math.max(carry, ordinal), 0) + 1
+  )
+}
+
+/** The folder name an ordinal and a slug make together. */
+export function numberedName(ordinal: number, slug: string): string {
+  return `${String(ordinal).padStart(ORDINAL_WIDTH, '0')}-${slug}`
+}
+
+/**
+ * Orders candidate folders by first appearance, breaking an exact tie on the
+ * name so two runs over one tree number it the same way.
+ */
+export function byFirstAppearance<T extends { name: string; dir: string }>(
+  folders: readonly T[],
+): T[] {
+  return folders
+    .map((folder) => ({ folder, appeared: firstAppearance(folder.dir) }))
+    .sort(
+      (a, b) =>
+        a.appeared - b.appeared || a.folder.name.localeCompare(b.folder.name),
+    )
+    .map(({ folder }) => folder)
+}