@erclx/canon 5.66.0 → 5.67.0

package/src/intake/drive-check.ts

@@ -0,0 +1,355 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { basename, isAbsolute, join, normalize } from 'node:path'
+import {
+  changedSince,
+  readWorktreeStatus,
+  type StatusEntry,
+} from '@/git/status'
+import { extractOrdinal, type IntakeRefused, openFolder } from '@/intake/folder'
+import { requirementsRel } from '@/context/requirements'
+import { bodyLines } from '@/markdown/scan'
+
+/** The record a drive leaves in its intake folder, which this check reads. */
+export const DRIVE_RECORD = 'drive.json'
+
+/** The one folder inside an intake folder that evidence may live in. */
+export const EVIDENCE_DIR = 'evidence'
+
+const SCRATCH = join('.canon', 'tmp', 'app-drive')
+
+/**
+ * The refusals this check adds to the folder lookup's own, which reach a
+ * caller unchanged as an `IntakeRefused`.
+ */
+export const DRIVE_REFUSALS = [
+  'bad-input',
+  'no-record',
+  'bad-record',
+  'no-requirements',
+  'no-baseline',
+  'unreadable-tree',
+] as const
+
+export type DriveRefusal = (typeof DRIVE_REFUSALS)[number]
+
+export interface DriveRefused {
+  readonly ok: false
+  readonly reason: DriveRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+export interface BaselineRecorded {
+  readonly ok: true
+  readonly slug: string
+  readonly path: string
+  readonly entries: number
+}
+
+/** Each list names what failed, and an empty list is a clean axis. */
+export interface DriveFindings {
+  /** Goals the record carries no entry for. */
+  readonly unmapped: readonly string[]
+  /** Goals marked `not-driven` with no reason given. */
+  readonly unreasoned: readonly string[]
+  /** Entries naming a goal the requirements record does not hold. */
+  readonly unknown: readonly string[]
+  /** Paths in the main checkout that differ from the baseline. */
+  readonly changed: readonly string[]
+  /** Evidence paths that resolve outside the folder's `evidence/`. */
+  readonly strayEvidence: readonly string[]
+  /** Evidence paths inside `evidence/` that hold no file. */
+  readonly missingEvidence: readonly string[]
+  /** The drive's worktree, when the record names one still on disk. */
+  readonly worktreeLeft: readonly string[]
+}
+
+export interface DriveChecked {
+  readonly ok: true
+  readonly slug: string
+  readonly reason: 'clean' | 'failed'
+  readonly goals: number
+  readonly findings: DriveFindings
+}
+
+export type BaselineOutcome = BaselineRecorded | DriveRefused
+export type CheckOutcome = DriveChecked | DriveRefused | IntakeRefused
+
+type GoalStatus = 'driven' | 'not-driven'
+
+interface DriveGoal {
+  readonly goal: string
+  readonly status: GoalStatus
+  readonly reason?: string
+}
+
+interface DriveRecord {
+  readonly goals: readonly DriveGoal[]
+  readonly evidence: readonly string[]
+  readonly worktree?: string
+}
+
+function refuse(
+  reason: DriveRefusal,
+  message: string,
+  detail: readonly string[] = [],
+): DriveRefused {
+  return { ok: false, reason, message, detail }
+}
+
+/**
+ * A goal as both sides compare it: a leading bold label and a trailing period
+ * dropped, and whitespace collapsed. Requirements records carry no goal ids,
+ * so the text is the identity, and stripping the label lets a drive record
+ * paste the bullet whole or name the sentence alone.
+ */
+function normalizeGoal(text: string): string {
+  return text
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^\*\*[^*]+\*\*\s*/, '')
+    .replace(/\.$/, '')
+    .trim()
+}
+
+/**
+ * Every top-level bullet under `## Goals`, through any H3 grouping, up to the
+ * next H2. A wrapped bullet's indented continuation joins it, and a nested
+ * bullet is detail of its parent rather than a goal of its own.
+ */
+export function readGoals(source: string): string[] {
+  const goals: string[] = []
+  let inGoals = false
+  let current: string | undefined
+  let appending = false
+
+  const close = () => {
+    if (current !== undefined) goals.push(normalizeGoal(current))
+    current = undefined
+    appending = false
+  }
+
+  for (const line of bodyLines(source)) {
+    if (line.fenced) continue
+    const text = line.text
+
+    if (/^#{1,2}\s/.test(text)) {
+      close()
+      inGoals = /^##\s+Goals\s*$/.test(text)
+      continue
+    }
+    if (!inGoals) continue
+
+    const bullet = /^[-*]\s+(.*)$/.exec(text)
+    if (bullet) {
+      close()
+      current = bullet[1]
+      appending = true
+    } else if (/^\s+[-*]\s/.test(text) || text.trim() === '') {
+      appending = false
+    } else if (appending && /^\s+\S/.test(text)) {
+      current = `${current} ${text.trim()}`
+    } else if (/^#{3,}\s/.test(text)) {
+      appending = false
+    }
+  }
+  close()
+
+  return goals
+}
+
+function parseRecord(raw: string): DriveRecord | string {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return `${DRIVE_RECORD} does not parse as JSON.`
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    return `${DRIVE_RECORD} is not an object.`
+  }
+
+  const { goals, evidence, worktree } = parsed as Record<string, unknown>
+  if (!Array.isArray(goals)) {
+    return `${DRIVE_RECORD} carries no "goals" list.`
+  }
+
+  const entries: DriveGoal[] = []
+  for (const [index, entry] of goals.entries()) {
+    const { goal, status, reason } = (entry ?? {}) as Record<string, unknown>
+    if (typeof goal !== 'string' || goal.trim() === '') {
+      return `${DRIVE_RECORD} goals[${index}] carries no "goal" text.`
+    }
+    if (status !== 'driven' && status !== 'not-driven') {
+      return `${DRIVE_RECORD} goals[${index}] has a "status" other than "driven" or "not-driven".`
+    }
+    entries.push({
+      goal,
+      status,
+      ...(typeof reason === 'string' && { reason }),
+    })
+  }
+
+  if (
+    evidence !== undefined &&
+    (!Array.isArray(evidence) ||
+      !evidence.every((item): item is string => typeof item === 'string'))
+  ) {
+    return `${DRIVE_RECORD} carries an "evidence" field that is not a list of paths.`
+  }
+  if (worktree !== undefined && typeof worktree !== 'string') {
+    return `${DRIVE_RECORD} carries a "worktree" that is not a path.`
+  }
+
+  return {
+    goals: entries,
+    evidence: evidence ?? [],
+    ...(worktree !== undefined && { worktree }),
+  }
+}
+
+function isEvidencePath(path: string): boolean {
+  if (isAbsolute(path)) return false
+  const segments = normalize(path).split(/[\\/]/)
+  return (
+    segments[0] === EVIDENCE_DIR &&
+    segments.length > 1 &&
+    !segments.includes('..')
+  )
+}
+
+/**
+ * The scratch key for a topic, with any ordinal dropped, so a baseline taken
+ * before the intake folder is numbered and a check naming the numbered folder
+ * meet at one file. Undefined for a slug that could leave scratch.
+ */
+function bareSlug(slug: string): string | undefined {
+  if (!/^[a-z0-9][a-z0-9.-]*$/i.test(slug) || slug.includes('..')) {
+    return undefined
+  }
+  const ordinal = extractOrdinal(slug)
+  return ordinal === '' ? slug : slug.slice(ordinal.length + 1)
+}
+
+function baselinePath(root: string, bare: string): string {
+  return join(root, SCRATCH, bare, 'baseline.json')
+}
+
+function badSlug(slug: string): DriveRefused {
+  return refuse(
+    'bad-input',
+    `Not an intake slug: ${slug}. Pass the folder's topic, as in app-drive-1-0.`,
+  )
+}
+
+/**
+ * Stores the main checkout's status before a drive, so the check can tell a
+ * write the drive made from one already in the tree. Scratch rather than the
+ * intake folder, since the baseline is safe to lose once the check passes and
+ * the folder holds findings alone. A second call replaces the first.
+ */
+export async function recordBaseline(
+  root: string,
+  slug: string,
+): Promise<BaselineOutcome> {
+  const bare = bareSlug(slug)
+  if (bare === undefined) return badSlug(slug)
+
+  const status = await readWorktreeStatus(root)
+  if (status === undefined) {
+    return refuse('unreadable-tree', `git cannot read the status of ${root}.`)
+  }
+
+  const path = baselinePath(root, bare)
+  await mkdir(join(path, '..'), { recursive: true })
+  await writeFile(path, `${JSON.stringify(status)}\n`)
+
+  return { ok: true, slug: bare, path, entries: status.length }
+}
+
+/**
+ * Checks a finished drive against its intake folder's `drive.json`: every
+ * goal mapped or skipped with a reason, the main checkout unchanged since the
+ * baseline, the evidence inside the folder's `evidence/`, and the drive's
+ * worktree gone. It reports what failed and never reverts a changed path,
+ * since only the operator knows which of them to keep.
+ */
+export async function checkDrive(
+  root: string,
+  slug: string,
+): Promise<CheckOutcome> {
+  const bare = bareSlug(slug)
+  if (bare === undefined) return badSlug(slug)
+
+  const folder = await openFolder(root, slug)
+  if (typeof folder !== 'string') return folder
+
+  const recordPath = join(folder, DRIVE_RECORD)
+  if (!existsSync(recordPath)) {
+    return refuse(
+      'no-record',
+      `No ${DRIVE_RECORD} in ${basename(folder)}, so no drive was recorded.`,
+    )
+  }
+  const record = parseRecord(await readFile(recordPath, 'utf8'))
+  if (typeof record === 'string') return refuse('bad-record', record)
+
+  const requirements = join(root, requirementsRel(root))
+  if (!existsSync(requirements)) {
+    return refuse(
+      'no-requirements',
+      `No requirements record at ${requirementsRel(root)}, so no goal can be checked.`,
+    )
+  }
+  const goals = readGoals(await readFile(requirements, 'utf8'))
+
+  let baseline: readonly StatusEntry[]
+  try {
+    baseline = JSON.parse(await readFile(baselinePath(root, bare), 'utf8'))
+  } catch {
+    return refuse(
+      'no-baseline',
+      `No baseline for ${bare}. Run canon intake drive-check ${bare} --baseline before the drive.`,
+    )
+  }
+  const current = await readWorktreeStatus(root)
+  if (current === undefined) {
+    return refuse('unreadable-tree', `git cannot read the status of ${root}.`)
+  }
+
+  const entries = new Map(
+    record.goals.map((entry) => [normalizeGoal(entry.goal), entry]),
+  )
+  const known = new Set(goals)
+  const unreasoned = goals.filter((goal) => {
+    const entry = entries.get(goal)
+    return entry?.status === 'not-driven' && !entry.reason?.trim()
+  })
+
+  const findings: DriveFindings = {
+    unmapped: goals.filter((goal) => !entries.has(goal)),
+    unreasoned,
+    unknown: record.goals
+      .filter((entry) => !known.has(normalizeGoal(entry.goal)))
+      .map((entry) => entry.goal),
+    changed: changedSince(baseline, current),
+    strayEvidence: record.evidence.filter((path) => !isEvidencePath(path)),
+    missingEvidence: record.evidence.filter(
+      (path) => isEvidencePath(path) && !existsSync(join(folder, path)),
+    ),
+    worktreeLeft:
+      record.worktree !== undefined && existsSync(record.worktree)
+        ? [record.worktree]
+        : [],
+  }
+  const failed = Object.values(findings).some((list) => list.length > 0)
+
+  return {
+    ok: true,
+    slug: basename(folder),
+    reason: failed ? 'failed' : 'clean',
+    goals: goals.length,
+    findings,
+  }
+}

package/src/intake/folder.ts

@@ -142,7 +142,7 @@ export function extractOrdinal(name: string): string {
   return /^\d{2,}-/.exec(name)?.[0].slice(0, -1) ?? ''
 }
 
-async function openFolder(
+export async function openFolder(
   root: string,
   slug: string,
 ): Promise<string | IntakeRefused> {

package/src/markdown/scan.ts

@@ -122,6 +122,16 @@ export function bodyLines(source: string): BodyLine[] {
   )
 }
 
+/**
+ * Counts whitespace-delimited tokens, the unit a record's word cap is stated
+ * in. A code span counts as the tokens it holds, so a line citing a long path
+ * pays for it the way a reader does. A caller gating on the count hands in
+ * prose with fenced lines already dropped.
+ */
+export function wordCount(text: string): number {
+  return text.match(/\S+/g)?.length ?? 0
+}
+
 /**
  * Drops every fenced block from raw text, frontmatter included as content.
  *

package/src/pr/drive-copy.ts

@@ -1,8 +1,12 @@
-import { createHash } from 'node:crypto'
-import { cpSync, existsSync, readFileSync, rmSync, statSync } from 'node:fs'
-import { isAbsolute, join } from 'node:path'
-import { $ } from 'bun'
-import { gitEnv } from '@/git/env'
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+} from 'node:fs'
+import { isAbsolute, join, relative, sep } from 'node:path'
 
 /** Where a project names the folders its running preview saves into. */
 export const PREVIEW_CONFIG_REL = join('canon', 'config', 'preview.json')
@@ -28,6 +32,8 @@ const BRANCH_TYPES = new Set([
 export interface PreviewConfig {
   readonly writes: readonly string[]
   readonly env: string
+  /** Paths inside a declared path that a rebuild leaves as the server wrote them. */
+  readonly keep: readonly string[]
 }
 
 export type PreviewConfigRead =
@@ -39,13 +45,6 @@ export type PreviewConfigRead =
       readonly detail: string
     }
 
-export interface StatusEntry {
-  readonly path: string
-  readonly status: string
-  /** The content digest, or null where no regular file stands at the path. */
-  readonly digest: string | null
-}
-
 /**
  * The branch-to-slug transform every branch-derived name shares: a leading
  * type segment comes off when a further segment follows it, and each
@@ -68,12 +67,25 @@ function isContained(path: string): boolean {
   )
 }
 
+/** Whether `path` is `parent` or stands below it, both relative to one root. */
+function isWithin(path: string, parent: string): boolean {
+  const rel = relative(join('/', parent), join('/', path))
+  return (
+    rel === '' ||
+    (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+  )
+}
+
 /**
- * Reads `canon/config/preview.json` as `{ "writes": [...], "env": "<NAME>" }`.
+ * Reads `canon/config/preview.json` as
+ * `{ "writes": [...], "keep": [...], "env": "<NAME>" }`.
  * A file that does not parse refuses rather than reading as absent, since a
  * typo there would otherwise drive the real folders while the pass reports a
- * copy. A `writes` path that is absolute or climbs with `..` refuses, so the
- * copy never reads or writes outside its two roots.
+ * copy. A `writes` or `keep` path that is absolute or climbs with `..`
+ * refuses, so the copy never reads or writes outside its two roots, and a
+ * `keep` path outside every `writes` path refuses, since the rebuild would
+ * never reach it, and so does one equal to a `writes` path, which would be
+ * declared both reset and kept.
  */
 export function loadPreviewConfig(worktree: string): PreviewConfigRead {
   const path = join(worktree, PREVIEW_CONFIG_REL)
@@ -97,7 +109,7 @@ export function loadPreviewConfig(worktree: string): PreviewConfigRead {
     }
   }
 
-  const { writes, env } = parsed as Record<string, unknown>
+  const { writes, env, keep = [] } = parsed as Record<string, unknown>
   if (
     !Array.isArray(writes) ||
     !writes.every((item): item is string => typeof item === 'string')
@@ -108,6 +120,16 @@ export function loadPreviewConfig(worktree: string): PreviewConfigRead {
       detail: `${PREVIEW_CONFIG_REL} carries no "writes" list of paths.`,
     }
   }
+  if (
+    !Array.isArray(keep) ||
+    !keep.every((item): item is string => typeof item === 'string')
+  ) {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} names a "keep" that is not a list of paths.`,
+    }
+  }
   if (env !== undefined && (typeof env !== 'string' || env === '')) {
     return {
       kind: 'refused',
@@ -116,7 +138,7 @@ export function loadPreviewConfig(worktree: string): PreviewConfigRead {
     }
   }
 
-  const unsafe = writes.find((item) => !isContained(item))
+  const unsafe = [...writes, ...keep].find((item) => !isContained(item))
   if (unsafe !== undefined) {
     return {
       kind: 'refused',
@@ -125,94 +147,85 @@ export function loadPreviewConfig(worktree: string): PreviewConfigRead {
     }
   }
 
+  const stray = keep.find(
+    (item) => !writes.some((path) => isWithin(item, path)),
+  )
+  if (stray !== undefined) {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} keeps "${stray}", which no "writes" path holds.`,
+    }
+  }
+
+  const clash = keep.find((item) =>
+    writes.some((path) => isWithin(item, path) && isWithin(path, item)),
+  )
+  if (clash !== undefined) {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} keeps "${clash}", which is also a "writes" path, so the rebuild would never reset it.`,
+    }
+  }
+
   return {
     kind: 'read',
-    config: { writes, env: env ?? DEFAULT_PREVIEW_ENV },
+    config: { writes, env: env ?? DEFAULT_PREVIEW_ENV, keep },
   }
 }
 
 /**
- * Replaces the copy root with a fresh copy of each declared path, so the last
- * pass's drives never reach the next one. A path the worktree does not hold
- * is named rather than failing the copy.
+ * Removes `target` except the `keep` paths at or below it, where `rel` is
+ * `target` relative to the root `keep` is read against. A folder holding a
+ * kept path is emptied around it rather than removed.
+ */
+function clearAround(
+  target: string,
+  rel: string,
+  keep: readonly string[],
+): void {
+  if (keep.includes(rel)) return
+  const stat = lstatSync(target, { throwIfNoEntry: false })
+  if (stat === undefined) return
+  if (!stat.isDirectory() || !keep.some((path) => isWithin(path, rel))) {
+    rmSync(target, { recursive: true, force: true })
+    return
+  }
+  for (const entry of readdirSync(target)) {
+    clearAround(join(target, entry), join(rel, entry), keep)
+  }
+}
+
+/**
+ * Resets each declared path in the copy from the worktree, so the last pass's
+ * drives never reach the next one, and leaves everything else under the copy
+ * root as it is. A `keep` path inside a declared path is neither cleared nor
+ * copied, since the server running on the copy owns it. A path the worktree
+ * does not hold has its stale copy removed and is named rather than failing
+ * the copy.
  */
 export function buildDriveCopy(
   worktree: string,
   copyRoot: string,
   writes: readonly string[],
+  keep: readonly string[] = [],
 ): { readonly copied: readonly string[]; readonly missing: readonly string[] } {
-  rmSync(copyRoot, { recursive: true, force: true })
+  const kept = keep.map((path) => relative(worktree, join(worktree, path)))
   const copied: string[] = []
   const missing: string[] = []
   for (const path of writes) {
     const source = join(worktree, path)
+    clearAround(join(copyRoot, path), relative(worktree, source), kept)
     if (!existsSync(source)) {
       missing.push(path)
       continue
     }
-    cpSync(source, join(copyRoot, path), { recursive: true })
+    cpSync(source, join(copyRoot, path), {
+      recursive: true,
+      filter: (item) => !kept.includes(relative(worktree, item)),
+    })
     copied.push(path)
   }
   return { copied, missing }
 }
-
-function digestOf(path: string): string | null {
-  try {
-    if (!statSync(path).isFile()) return null
-    return createHash('sha1').update(readFileSync(path)).digest('hex')
-  } catch {
-    return null
-  }
-}
-
-/**
- * Every entry `git status` reports, untracked files listed one by one so a
- * file a drive adds inside a tracked folder names itself, each with a content
- * digest so a file already dirty at the baseline still reads as changed when
- * a drive writes it again. Undefined when git cannot read the tree.
- */
-export async function readWorktreeStatus(
-  worktree: string,
-): Promise<readonly StatusEntry[] | undefined> {
-  const result =
-    await $`git -C ${worktree} status --porcelain=v1 -z --untracked-files=all`
-      .env(gitEnv())
-      .quiet()
-      .nothrow()
-  if (result.exitCode !== 0) return undefined
-
-  const tokens = result.stdout.toString().split('\0')
-  const entries: StatusEntry[] = []
-  for (let index = 0; index < tokens.length; index++) {
-    const token = tokens[index] ?? ''
-    if (token.length < 4) continue
-    const status = token.slice(0, 2)
-    const path = token.slice(3)
-    // A rename or copy carries its source as the next token.
-    if (status.includes('R') || status.includes('C')) index++
-    entries.push({ path, status, digest: digestOf(join(worktree, path)) })
-  }
-  return entries
-}
-
-/**
- * The paths whose status or content differs from the baseline, in the order
- * git reports them. An entry gone since the baseline is not reported, since a
- * worker committing its own edit mid-pass clears it the same way.
- */
-export function changedSince(
-  baseline: readonly StatusEntry[],
-  current: readonly StatusEntry[],
-): readonly string[] {
-  const before = new Map(baseline.map((entry) => [entry.path, entry]))
-  return current
-    .filter((entry) => {
-      const prior = before.get(entry.path)
-      return (
-        prior === undefined ||
-        prior.status !== entry.status ||
-        prior.digest !== entry.digest
-      )
-    })
-    .map((entry) => entry.path)
-}