@erclx/canon 5.48.0 → 5.50.0

package/src/pr/drive-copy.ts

@@ -0,0 +1,218 @@
+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'
+
+/** Where a project names the folders its running preview saves into. */
+export const PREVIEW_CONFIG_REL = join('canon', 'config', 'preview.json')
+
+/** The variable a preview server reads for the copy root when the project names none. */
+export const DEFAULT_PREVIEW_ENV = 'CANON_PREVIEW_ROOT'
+
+/** The type vocabulary of `git-branch`'s branch standard, which the slug transform drops. */
+const BRANCH_TYPES = new Set([
+  'feat',
+  'fix',
+  'refactor',
+  'docs',
+  'chore',
+  'perf',
+  'test',
+  'style',
+  'build',
+  'ci',
+  'revert',
+])
+
+export interface PreviewConfig {
+  readonly writes: readonly string[]
+  readonly env: string
+}
+
+export type PreviewConfigRead =
+  | { readonly kind: 'absent' }
+  | { readonly kind: 'read'; readonly config: PreviewConfig }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'bad-config' | 'unsafe-path'
+      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
+ * remaining `/` becomes `-`. The worker reads its branch off the worktree and
+ * the reviewer off the pull request's head ref, so this one function is what
+ * lands both on the same folder.
+ */
+export function branchSlug(branch: string): string {
+  const segments = branch.split('/')
+  const rest =
+    segments.length > 1 && BRANCH_TYPES.has(segments[0] ?? '')
+      ? segments.slice(1)
+      : segments
+  return rest.join('-')
+}
+
+function isContained(path: string): boolean {
+  return (
+    path.length > 0 && !isAbsolute(path) && !path.split(/[\\/]/).includes('..')
+  )
+}
+
+/**
+ * Reads `canon/config/preview.json` as `{ "writes": [...], "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.
+ */
+export function loadPreviewConfig(worktree: string): PreviewConfigRead {
+  const path = join(worktree, PREVIEW_CONFIG_REL)
+  if (!existsSync(path)) return { kind: 'absent' }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} does not parse as JSON.`,
+    }
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} is not an object.`,
+    }
+  }
+
+  const { writes, env } = parsed as Record<string, unknown>
+  if (
+    !Array.isArray(writes) ||
+    !writes.every((item): item is string => typeof item === 'string')
+  ) {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} carries no "writes" list of paths.`,
+    }
+  }
+  if (env !== undefined && (typeof env !== 'string' || env === '')) {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} names an "env" that is not a variable name.`,
+    }
+  }
+
+  const unsafe = writes.find((item) => !isContained(item))
+  if (unsafe !== undefined) {
+    return {
+      kind: 'refused',
+      reason: 'unsafe-path',
+      detail: `${PREVIEW_CONFIG_REL} names "${unsafe}", which leaves the worktree.`,
+    }
+  }
+
+  return {
+    kind: 'read',
+    config: { writes, env: env ?? DEFAULT_PREVIEW_ENV },
+  }
+}
+
+/**
+ * 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.
+ */
+export function buildDriveCopy(
+  worktree: string,
+  copyRoot: string,
+  writes: readonly string[],
+): { readonly copied: readonly string[]; readonly missing: readonly string[] } {
+  rmSync(copyRoot, { recursive: true, force: true })
+  const copied: string[] = []
+  const missing: string[] = []
+  for (const path of writes) {
+    const source = join(worktree, path)
+    if (!existsSync(source)) {
+      missing.push(path)
+      continue
+    }
+    cpSync(source, join(copyRoot, path), { recursive: true })
+    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)
+}

package/src/pr/local.ts

@@ -64,3 +64,29 @@ export function dropAddressLine(body: string): string | undefined {
   if (isGapAbove && (lines[first] ?? '').trim() === '') lines.splice(first, 1)
   return lines.join('\n')
 }
+
+/**
+ * A loopback URL with any port and path, and the backticks or angle brackets a
+ * pass may have wrapped it in. These hosts resolve on one machine for one
+ * session, so no later reader of the thread can open them.
+ */
+const LOOPBACK_URL =
+  /[`<]?https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::\d+)?(?:\/[^\s`>,]*)?[`>]?/g
+
+/**
+ * Rewrites the loopback address on a UI review's `Driven at` line to "a local
+ * preview", keeping the head and the renderer. Only that line is read, so a
+ * loopback URL a box reason quotes from the page stays as content. Undefined
+ * when no line changes, which is also what a second mask of the same body
+ * returns.
+ */
+export function maskLocalAddress(body: string): string | undefined {
+  let changed = false
+  const lines = body.split('\n').map((line) => {
+    if (!line.startsWith('Driven at ')) return line
+    const masked = line.replace(LOOPBACK_URL, 'a local preview')
+    if (masked !== line) changed = true
+    return masked
+  })
+  return changed ? lines.join('\n') : undefined
+}

package/src/pr/rest.ts

@@ -25,6 +25,8 @@ export interface RestPull {
 
 /** One row of `repos/{owner}/{repo}/pulls/<n>/reviews`. */
 export interface RestReview {
+  /** The id the update call `pulls/<n>/reviews/<id>` names. */
+  readonly id?: number
   readonly body?: string | null
   readonly commit_id?: string | null
   readonly submitted_at?: string | null

package/src/records/structure.ts

@@ -0,0 +1,147 @@
+import { type DensityKind, densityFindings } from '@/markdown/density'
+import { bodyLines } from '@/markdown/scan'
+import { isSectionMarker } from '@/markdown/structure'
+
+/**
+ * The criteria `plan.md`'s `### Structure` states for every hand-written
+ * record. `S6`, a full path in a section a parser reads, is not here, since
+ * `canon tasks plan-reach` already reports a bare filename as unclaimed.
+ */
+export const STRUCTURE_CRITERIA = ['S1', 'S2', 'S3', 'S4', 'S5'] as const
+
+export type StructureCriterion = (typeof STRUCTURE_CRITERIA)[number]
+
+/** One place a record misses a criterion, or an intake field spilling past its line. */
+export interface StructureEntry {
+  readonly criterion: StructureCriterion | 'intake-spill'
+  /** The line as an editor numbers it, frontmatter included. */
+  readonly line: number
+  readonly message: string
+}
+
+/**
+ * The density limits a record criterion takes over. The paragraph limits are
+ * left out, since the record standard caps no paragraph and names no run.
+ */
+const CRITERION_OF: Partial<Record<DensityKind, StructureCriterion>> = {
+  'bullet-run': 'S2',
+  'h3-opening': 'S3',
+  'bullet-length': 'S4',
+  'heading-depth': 'S5',
+}
+
+const MESSAGE: Record<StructureCriterion, string> = {
+  S1: 'is a bold label standing alone as a section marker. Write it as an H2.',
+  S2: 'opens a run of more than 5 plain bullets. Group them under H3s.',
+  S3: 'opens with no lead sentence carrying what its bullets share.',
+  S4: 'is a bullet past 200 characters. Make it a short paragraph, or split it.',
+  S5: 'is an H4 or deeper. Fold it into its H3.',
+}
+
+/**
+ * Every place a record misses `S1` to `S5`, in line order.
+ *
+ * `S2` to `S5` are the markdown density limits read on the record's own
+ * terms, so a labeled field run stays exempt from `S2` here as it does there.
+ * `S1` is any line `isSectionMarker` reads as a bold section marker, which an
+ * old plan carries on every section and still parses through.
+ */
+export function structureFindings(text: string): StructureEntry[] {
+  const lines = bodyLines(text)
+  const found: StructureEntry[] = []
+
+  for (const line of lines) {
+    if (!line.fenced && isSectionMarker(line.text)) {
+      found.push({ criterion: 'S1', line: line.number, message: MESSAGE.S1 })
+    }
+  }
+
+  for (const density of densityFindings(lines)) {
+    const criterion = CRITERION_OF[density.kind]
+    if (criterion) {
+      found.push({ criterion, line: density.line, message: MESSAGE[criterion] })
+    }
+  }
+
+  return found.sort((a, b) => a.line - b.line)
+}
+
+/** An item heading, as `readItems` in `src/intake/items.ts` reads one. */
+const ITEM_HEADING = /^###\s+\d+[a-z]*\.\s/i
+
+/** A bolded field bullet, the one line `readItems` takes from a field. */
+const FIELD = /^-\s+\*\*([^*]+):\*\*/
+
+/** Any heading, which closes the item above it. */
+const SECTION = /^#{1,6}\s/
+
+/**
+ * Every block of content sitting under an intake field rather than on its
+ * line, one entry at the block's first line.
+ *
+ * `canon intake list` reads a field's own line and nothing under it, so a
+ * nested list or a paragraph below a field never reaches the operator
+ * answering in chat. A trailing paragraph after the last field is reported
+ * too, since it is dropped the same way.
+ */
+export function intakeSpill(text: string): StructureEntry[] {
+  const found: StructureEntry[] = []
+  let item: string | undefined
+  let field: string | undefined
+  let spilling = false
+
+  for (const line of bodyLines(text)) {
+    if (line.fenced) continue
+
+    const heading = ITEM_HEADING.exec(line.text)
+    if (heading || SECTION.test(line.text)) {
+      item = heading
+        ? line.text.replace(/^###\s+/, '').split('.')[0]
+        : undefined
+      field = undefined
+      spilling = false
+      continue
+    }
+
+    if (item === undefined || line.text.trim() === '') continue
+
+    const match = FIELD.exec(line.text)
+    if (match) {
+      field = match[1].trim()
+      spilling = false
+      continue
+    }
+
+    if (spilling) continue
+    spilling = true
+
+    const under = field ? `the ${field} field of item ${item}` : `item ${item}`
+    found.push({
+      criterion: 'intake-spill',
+      line: line.number,
+      message: `sits under ${under}, and canon intake list reads only a field's own line. Keep the content on the line, or split the item.`,
+    })
+  }
+
+  return found
+}
+
+/**
+ * The structure report for an intake cluster file. Item headings open on
+ * their fields by the template's design, so `S3` skips them, and a field
+ * carries its whole content on one line, so `S4` skips it.
+ */
+export function intakeStructure(text: string): StructureEntry[] {
+  const lines = text.split('\n')
+  const exempt = (entry: StructureEntry): boolean => {
+    const source = lines[entry.line - 1] ?? ''
+    if (entry.criterion === 'S3') return ITEM_HEADING.test(source)
+    if (entry.criterion === 'S4') return FIELD.test(source)
+    return false
+  }
+
+  return [
+    ...structureFindings(text).filter((entry) => !exempt(entry)),
+    ...intakeSpill(text),
+  ].sort((a, b) => a.line - b.line)
+}

package/src/records/validate.ts

@@ -3,6 +3,11 @@ import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { linesOutsideFences } from '@/markdown/scan'
+import {
+  intakeStructure,
+  type StructureEntry,
+  structureFindings,
+} from '@/records/structure'
 import {
   recordDir as resolveRecordDir,
   recordDirs as resolveRecordDirs,
@@ -27,7 +32,11 @@ export type RecordKind = (typeof RECORD_KINDS)[number]
  * union covering only what the walk returns would type a record the command can
  * emit as impossible.
  */
-export const VALIDATE_REFUSALS = ['no-folder', 'unknown-kind'] as const
+export const VALIDATE_REFUSALS = [
+  'no-folder',
+  'no-record',
+  'unknown-kind',
+] as const
 
 export type ValidateRefusal = (typeof VALIDATE_REFUSALS)[number]
 
@@ -61,11 +70,24 @@ export interface Finding {
   readonly message: string
 }
 
+/**
+ * A place a record misses a structure criterion. It sits apart from `Finding`
+ * so it never sets the exit, since every record written before the criteria
+ * misses `S1` and a gate on it would fail them all.
+ */
+export interface StructureFinding extends StructureEntry {
+  /** The record the entry sits in, relative to the validated folder. */
+  readonly record: string
+  /** The file inside a folder record, or the record itself for a plan. */
+  readonly subject: string
+}
+
 export interface ValidateReport {
   readonly ok: true
   readonly kind: RecordKind
   readonly records: number
   readonly findings: readonly Finding[]
+  readonly structure: readonly StructureFinding[]
 }
 
 export interface ValidateRefused {
@@ -267,7 +289,7 @@ export function sectionMarker(line: string): PlanSection | undefined {
 
 /** The spelling a finding names, which is the one the standard's template ships. */
 export function preferredMarker(section: PlanSection): string {
-  return section === 'Summary' ? '## Summary' : `**${section}:**`
+  return `## ${section}`
 }
 
 export function splitPlanSections(text: string): Map<string, string[]> {
@@ -915,6 +937,42 @@ const FOLDER_CHECK: Readonly<
   teach: checkWorkspace,
 }
 
+/**
+ * The files of a folder record the structure report reads. A groundwork
+ * track's `evidence/`, `scripts/`, and `clones/` sit below the top level and
+ * hold copies and raw output, so only its index and numbered files are read.
+ * An intake folder's reserved files hold no items, so only clusters are.
+ */
+const STRUCTURE_FILES: Readonly<
+  Partial<Record<RecordKind, (file: string) => boolean>>
+> = {
+  groundwork: (file) => file === GROUNDWORK_INDEX || NUMBERED_FILE.test(file),
+  intake: (file) => file !== INTAKE_INDEX && file !== INTAKE_HANDOFF,
+}
+
+async function folderStructure(
+  dir: string,
+  kind: RecordKind,
+  slug: string,
+): Promise<StructureFinding[]> {
+  const reads = STRUCTURE_FILES[kind]
+  if (!reads) return []
+
+  const report = kind === 'intake' ? intakeStructure : structureFindings
+  const files = (await listMarkdown(dir)).filter(reads)
+  const perFile = await Promise.all(
+    files.map(async (file) =>
+      report(await readFile(join(dir, file), 'utf8')).map((entry) => ({
+        ...entry,
+        record: slug,
+        subject: file,
+      })),
+    ),
+  )
+
+  return perFile.flat()
+}
+
 function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
   return { ok: false, reason, message }
 }
@@ -923,17 +981,42 @@ function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
 async function validateFiles(
   dir: string,
   kind: RecordKind,
+  files: readonly string[],
   check: (name: string, text: string) => Finding[],
 ): Promise<ValidateReport> {
-  const files = await listMarkdown(dir)
-
   const perFile = await Promise.all(
-    files.map(async (file) =>
-      check(file, await readFile(join(dir, file), 'utf8')),
-    ),
+    files.map(async (file) => {
+      const text = await readFile(join(dir, file), 'utf8')
+      return {
+        findings: check(file, text),
+        structure: structureFindings(text).map((entry) => ({
+          ...entry,
+          record: file,
+          subject: file,
+        })),
+      }
+    }),
   )
 
-  return { ok: true, kind, records: files.length, findings: perFile.flat() }
+  return {
+    ok: true,
+    kind,
+    records: files.length,
+    findings: perFile.flatMap((one) => one.findings),
+    structure: perFile.flatMap((one) => one.structure),
+  }
+}
+
+/**
+ * Narrows a listing to the one record a caller named, by a plan's stem or a
+ * folder's slug, so a writing skill reads its own record and not every old one.
+ */
+function narrow(
+  names: readonly string[],
+  record: string | undefined,
+): readonly string[] {
+  if (record === undefined) return names
+  return names.filter((name) => name === record || name === `${record}.md`)
 }
 
 /**
@@ -944,6 +1027,7 @@ async function validateFiles(
 export async function validateRecords(
   root: string,
   kind: RecordKind,
+  record?: string,
 ): Promise<ValidateOutcome> {
   const dir = recordsDir(root, kind)
 
@@ -954,13 +1038,30 @@ export async function validateRecords(
     )
   }
 
-  if (kind === 'plans') return validateFiles(dir, kind, checkPlan)
+  const names = narrow(
+    kind === 'plans' ? await listMarkdown(dir) : await listFolders(dir),
+    record,
+  )
+
+  if (record !== undefined && names.length === 0) {
+    return refuse('no-record', `No ${kind} record named ${record} in ${dir}.`)
+  }
+
+  if (kind === 'plans') return validateFiles(dir, kind, names, checkPlan)
 
-  const folders = await listFolders(dir)
   const check = FOLDER_CHECK[kind]
   const perFolder = await Promise.all(
-    folders.map((slug) => check(join(dir, slug), slug)),
+    names.map(async (slug) => ({
+      findings: await check(join(dir, slug), slug),
+      structure: await folderStructure(join(dir, slug), kind, slug),
+    })),
   )
 
-  return { ok: true, kind, records: folders.length, findings: perFolder.flat() }
+  return {
+    ok: true,
+    kind,
+    records: names.length,
+    findings: perFolder.flatMap((one) => one.findings),
+    structure: perFolder.flatMap((one) => one.structure),
+  }
 }