@erclx/canon 5.32.0 → 5.34.0

package/src/gov/standard-rules.ts

@@ -1,179 +0,0 @@
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
-import { mkdir, rm, writeFile } from 'node:fs/promises'
-import { basename, join, relative } from 'node:path'
-import { listRuleSourcePaths, rulesSourceDir } from '@/gov/install'
-import { parseFrontmatter } from '@/indexes/frontmatter'
-
-const STANDARDS_REL = 'standards'
-
-/** The band the generated rules ship in, named for what they point at. */
-export const STANDARD_RULES_BAND = 'standards'
-
-export type StandardRulesResult =
-  | { readonly ok: true; readonly written: readonly string[] }
-  | { readonly ok: false; readonly reason: string }
-
-interface StandardRule {
-  readonly name: string
-  readonly sourceRel: string
-  readonly title: string
-  readonly description: string
-  readonly paths: readonly string[]
-  readonly bullets: readonly string[]
-}
-
-export function standardRulesDir(root: string): string {
-  return join(rulesSourceDir(root), STANDARD_RULES_BAND)
-}
-
-/**
- * Generates one path-scoped rule per standard whose frontmatter carries
- * `paths:`. The standard owns the glob and the operative bullets, so the rule
- * is output, committed beside the authored bands so every reader of
- * `governance/rules/` sees it as an ordinary file.
- *
- * Every standard is read and checked before anything is written, so a refusal
- * leaves the previous output whole rather than half cleared.
- */
-export async function regenStandardRules(
-  root: string,
-): Promise<StandardRulesResult> {
-  const standardsDir = join(root, STANDARDS_REL)
-  if (!existsSync(standardsDir)) return { ok: true, written: [] }
-
-  const reserved = reservedNames(root)
-  const rules: StandardRule[] = []
-
-  for (const file of readdirSync(standardsDir).sort()) {
-    if (!file.endsWith('.md')) continue
-    const read = readStandard(root, file, reserved)
-    if (typeof read === 'string') return { ok: false, reason: read }
-    if (read !== undefined) rules.push(read)
-  }
-
-  const dir = standardRulesDir(root)
-  await rm(dir, { recursive: true, force: true })
-  if (rules.length > 0) await mkdir(dir, { recursive: true })
-
-  const written: string[] = []
-  for (const rule of rules) {
-    const dest = join(dir, `${rule.name}.md`)
-    await writeFile(dest, renderStandardRule(rule))
-    written.push(relative(root, dest))
-  }
-
-  return { ok: true, written }
-}
-
-/**
- * Band folders and authored rule basenames. A bare-word rule name equal to a
- * band would install the whole band through `--add`, and one equal to an
- * authored rule would shadow it in the name index.
- */
-function reservedNames(root: string): {
-  readonly bands: ReadonlySet<string>
-  readonly rules: ReadonlySet<string>
-} {
-  const bands = new Set<string>([STANDARD_RULES_BAND])
-  const rules = new Set<string>()
-
-  for (const rel of listRuleSourcePaths(root)) {
-    const segments = rel.split('/')
-    if (segments.length > 1) bands.add(segments[0])
-    if (segments[0] === STANDARD_RULES_BAND) continue
-    rules.add(basename(rel, '.md'))
-  }
-
-  return { bands, rules }
-}
-
-/** A rule to render, `undefined` for a standard with no `paths:`, or a reason. */
-function readStandard(
-  root: string,
-  file: string,
-  reserved: ReturnType<typeof reservedNames>,
-): StandardRule | string | undefined {
-  const sourceRel = `${STANDARDS_REL}/${file}`
-  const fields = parseFrontmatter(
-    readFileSync(join(root, STANDARDS_REL, file), 'utf8'),
-  )?.fields
-  if (fields === undefined || fields.paths === undefined) return undefined
-
-  const name = basename(file, '.md')
-  if (!isStringList(fields.paths)) {
-    return `${sourceRel}: paths must be a list of strings`
-  }
-  if (fields.rule !== undefined && !isStringList(fields.rule)) {
-    return `${sourceRel}: rule must be a list of strings`
-  }
-  if (reserved.bands.has(name)) {
-    return `${sourceRel}: name collides with a rule band folder`
-  }
-  if (reserved.rules.has(name)) {
-    return `${sourceRel}: name collides with an authored rule`
-  }
-
-  return {
-    name,
-    sourceRel,
-    title: typeof fields.title === 'string' ? fields.title : name,
-    description:
-      typeof fields.description === 'string' ? fields.description : '',
-    paths: fields.paths,
-    bullets: fields.rule ?? [],
-  }
-}
-
-function isStringList(value: unknown): value is string[] {
-  return (
-    Array.isArray(value) && value.every((entry) => typeof entry === 'string')
-  )
-}
-
-function renderStandardRule(rule: StandardRule): string {
-  const scope = rule.description.replace(/\.$/, '')
-  const pointer = [
-    `Follow the ${rule.name} standard for ${lowerFirst(scope)}.`,
-    'It is the single source.',
-    `Read it with \`canon standards ${rule.name}\`.`,
-  ].join(' ')
-
-  return [
-    '---',
-    `# Generated by \`canon gov regen\` from ${rule.sourceRel}. Edit that frontmatter, not this file.`,
-    `description: ${yamlScalar(rule.description)}`,
-    'paths:',
-    ...rule.paths.map((glob) => `  - ${yamlQuoted(glob)}`),
-    '---',
-    '',
-    `# ${rule.title.replace(/\breference$/, 'standards')}`,
-    '',
-    '## Authority',
-    '',
-    ...[pointer, ...rule.bullets].map((bullet) => `- ${bullet}`),
-    '',
-  ].join('\n')
-}
-
-function lowerFirst(text: string): string {
-  return text.charAt(0).toLowerCase() + text.slice(1)
-}
-
-/** Plain when YAML would read it back unchanged, single-quoted otherwise. */
-function yamlScalar(text: string): string {
-  const isPlain =
-    text !== '' &&
-    !/^[-?:,[\]{}#&*!|>'"%@`\s]/.test(text) &&
-    !/: |\s#|:$|\s$/.test(text)
-  return isPlain ? text : yamlQuoted(text)
-}
-
-/**
- * Quoted the way Prettier's `singleQuote` leaves YAML, so the drift check
- * never fights the formatter: single quotes unless the text holds one and
- * double quotes would need no escape.
- */
-function yamlQuoted(text: string): string {
-  if (text.includes("'") && !/["\\]/.test(text)) return `"${text}"`
-  return `'${text.replaceAll("'", "''")}'`
-}

package/src/records/migrate.ts

@@ -1,78 +0,0 @@
-import { parseFrontmatter, readField } from '@/indexes/frontmatter'
-import {
-  CATEGORY_BY_TYPE,
-  type FindingRemedy,
-  MEMORY_NAME,
-  memoryType,
-} from '@/records/validate'
-
-export const MIGRATE_REFUSALS = ['field-unrecoverable'] as const
-
-export type MigrateRefusal = (typeof MIGRATE_REFUSALS)[number]
-
-export interface MigrateRepair {
-  readonly ok: true
-  readonly text: string
-}
-
-export interface MigrateRefused {
-  readonly ok: false
-  readonly reason: MigrateRefusal
-  readonly message: string
-}
-
-export type MigrateOutcome = MigrateRepair | MigrateRefused
-
-function refuse(message: string): MigrateRefused {
-  return { ok: false, reason: 'field-unrecoverable', message }
-}
-
-/**
- * Repairs the one recoverable shape of `frontmatter-incomplete`: a memory
- * record missing `category` alone. The value sits in the filename's type
- * prefix already, which is the same fact `checkMemory` derives it from, so a
- * repair here writes back what the record already states rather than a value
- * a transform invented. It re-reads the file rather than trusting a value
- * carried on the `Finding`, so a transform and the check it repairs cannot
- * drift apart.
- */
-function categoryFromName(name: string, text: string): MigrateOutcome {
-  const frontmatter = parseFrontmatter(text)
-  if (!frontmatter) {
-    return refuse(`${name} carries no frontmatter block to add category to.`)
-  }
-
-  if (readField(frontmatter, 'category')) {
-    return refuse(`${name} already carries a category.`)
-  }
-
-  const match = MEMORY_NAME.exec(name)
-  const type = match ? memoryType(match[1]) : undefined
-  if (!type) {
-    return refuse(
-      `${name} is not named <type>-<slug>.md, so category has no type to derive from.`,
-    )
-  }
-
-  const rewritten = frontmatter.raw.replace(
-    /\n---$/,
-    `\ncategory: ${CATEGORY_BY_TYPE[type]}\n---`,
-  )
-
-  return { ok: true, text: rewritten + text.slice(frontmatter.raw.length) }
-}
-
-const TRANSFORMS: Readonly<
-  Record<FindingRemedy, (name: string, text: string) => MigrateOutcome>
-> = {
-  'category-from-name': categoryFromName,
-}
-
-/** Applies the transform a finding's `remedy` names against its own text. */
-export function migrateRecord(
-  remedy: FindingRemedy,
-  name: string,
-  text: string,
-): MigrateOutcome {
-  return TRANSFORMS[remedy](name, text)
-}

package/src/records/stale.ts

@@ -1,243 +0,0 @@
-import { existsSync } from 'node:fs'
-import { readdir, readFile } from 'node:fs/promises'
-import { join, relative } from 'node:path'
-import { parseFrontmatter, readField } from '@/indexes/frontmatter'
-import {
-  CREATION_ROOT,
-  RECORD_ROOTS,
-  recordDir,
-  SCRATCH,
-  spell,
-} from '@/roots/record'
-
-/** The window after which a reviewed entry is due again, in days. */
-export const DEFAULT_REVIEW_DAYS = 30
-
-const DAY_MS = 24 * 60 * 60 * 1000
-
-const MEMORY_INDEX = 'index.md'
-
-export interface StaleEntry {
-  /** The filename stem, which is what a review names an entry by. */
-  readonly name: string
-  readonly category: string | null
-  /** `YYYY-MM-DD`, or null when the entry carries no readable review date. */
-  readonly reviewed: string | null
-  /** The raw value of a `reviewed` field that is not a date, present only then. */
-  readonly invalidReviewed?: string
-  readonly due: boolean
-  /** Backticked paths the entry cites that the project root does not hold. */
-  readonly unresolved: readonly string[]
-}
-
-export interface StaleReport {
-  readonly ok: true
-  readonly root: string
-  /** The pen read, relative to the root. */
-  readonly folder: string
-  readonly days: number
-  readonly total: number
-  readonly due: number
-  readonly entries: readonly StaleEntry[]
-}
-
-export const STALE_REFUSALS = ['no-folder'] as const
-
-export type StaleRefusal = (typeof STALE_REFUSALS)[number]
-
-export interface StaleRefused {
-  readonly ok: false
-  readonly reason: StaleRefusal
-  readonly message: string
-}
-
-export type StaleOutcome = StaleReport | StaleRefused
-
-const REVIEWED_FIELD = /^reviewed:[ \t]*(.*?)[ \t]*$/m
-const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
-const RAW_FRONTMATTER = /^---\n([\s\S]*?)\n---/
-
-/**
- * Reads `reviewed` off the raw block rather than the parsed fields, for the
- * reason `hasOpeningDate` in the validator gives: a YAML parser resolves a
- * bare `YYYY-MM-DD` to a date on one schema and a string on another.
- *
- * A value that is not a calendar date reads as never reviewed and is carried
- * back so the review can see it, rather than throwing over one hand edit.
- */
-export function readReviewed(
-  text: string,
-): Pick<StaleEntry, 'reviewed' | 'invalidReviewed'> {
-  const block = RAW_FRONTMATTER.exec(text)?.[1]
-  const match = block ? REVIEWED_FIELD.exec(block) : null
-  if (!match) return { reviewed: null }
-
-  const value = match[1].replace(/^(['"])(.*)\1$/, '$2')
-  const parsed = Date.parse(`${value}T00:00:00Z`)
-  const isDate =
-    ISO_DATE.test(value) &&
-    Number.isFinite(parsed) &&
-    new Date(parsed).toISOString().slice(0, 10) === value
-
-  return isDate
-    ? { reviewed: value }
-    : { reviewed: null, invalidReviewed: value }
-}
-
-/**
- * Tokens that name a session record, scratch at either root, or a checkout,
- * none of which a tree commits. The scratch spellings come from `spell` so the
- * legacy root's variant is stated in one place.
- */
-const UNTRACKED_PREFIXES = [
-  ...RECORD_ROOTS.map((at) => `${at}/${spell(at, SCRATCH)}/`),
-  `${CREATION_ROOT}/`,
-  '.claude/worktrees/',
-]
-
-const INLINE_CODE = /`([^`\n]+)`/g
-const LINE_ANCHOR = /:\d+(?:[-:]\d+)*$/
-const FILE_EXTENSION = /\.[A-Za-z0-9]+$/
-
-/**
- * Reduces one backticked token to the repository path it cites, or undefined
- * when it cites none.
- *
- * A path is a token carrying a `/` and ending in a file extension once any
- * line or heading anchor is stripped. A placeholder, an elided path, a glob, a
- * variable, a URL, and a path outside the project all look like paths and
- * resolve against nothing in the tree, so each is dropped rather than reported.
- */
-function toCitedPath(token: string): string | undefined {
-  if (/\s/.test(token) || token.includes('://')) return undefined
-  if (/[<*{$]/.test(token) || token.includes('...')) return undefined
-  if (/^(?:\/|~|\.\.\/)/.test(token)) return undefined
-
-  const path = token
-    .replace(/#.*$/, '')
-    .replace(LINE_ANCHOR, '')
-    .replace(/^\.\//, '')
-
-  if (!path.includes('/') || !FILE_EXTENSION.test(path)) return undefined
-  if (UNTRACKED_PREFIXES.some((prefix) => path.startsWith(prefix)))
-    return undefined
-
-  return path
-}
-
-/** Every distinct repository path a body cites in inline code, in order. */
-export function citedPaths(body: string): string[] {
-  const paths = new Set<string>()
-
-  for (const match of body.matchAll(INLINE_CODE)) {
-    const path = toCitedPath(match[1])
-    if (path) paths.add(path)
-  }
-
-  return [...paths]
-}
-
-function isDue(reviewed: string | null, days: number, now: number): boolean {
-  if (reviewed === null) return true
-  return now - Date.parse(`${reviewed}T00:00:00`) > days * DAY_MS
-}
-
-async function readEntry(
-  root: string,
-  dir: string,
-  file: string,
-  days: number,
-  now: number,
-): Promise<StaleEntry> {
-  const text = (await readFile(join(dir, file), 'utf8')).replaceAll(
-    '\r\n',
-    '\n',
-  )
-  const frontmatter = parseFrontmatter(text)
-  const review = readReviewed(text)
-  const body = text.slice(RAW_FRONTMATTER.exec(text)?.[0].length ?? 0)
-
-  return {
-    name: file.replace(/\.md$/, ''),
-    category: readField(frontmatter, 'category') ?? null,
-    ...review,
-    due: isDue(review.reviewed, days, now),
-    unresolved: citedPaths(body).filter(
-      (path) => !existsSync(join(root, path)),
-    ),
-  }
-}
-
-/**
- * The order a review takes a batch in: due entries first, and among them the
- * ones citing a tree that moved, then the longest unreviewed, then by name so
- * two runs over one pen agree.
- */
-function compareEntries(left: StaleEntry, right: StaleEntry): number {
-  if (left.due !== right.due) return left.due ? -1 : 1
-
-  const leftMoved = left.unresolved.length > 0
-  const rightMoved = right.unresolved.length > 0
-  if (leftMoved !== rightMoved) return leftMoved ? -1 : 1
-
-  if (left.reviewed !== right.reviewed) {
-    if (left.reviewed === null) return -1
-    if (right.reviewed === null) return 1
-    return left.reviewed < right.reviewed ? -1 : 1
-  }
-
-  return left.name.localeCompare(right.name)
-}
-
-/**
- * Reports each memory entry's review state and the paths it cites that the
- * project no longer holds, ordered so a caller takes the first N as a batch.
- *
- * It reads the top level of the pen alone. `review/` holds receipts and
- * `archive/` holds retirements, and neither is an entry a review would queue.
- * Paths resolve against the project root rather than the entry's folder, since
- * an entry cites the tree it was written about. It reports and never writes.
- *
- * `now` is a parameter so a test can pin the window against fixture dates.
- */
-export async function staleMemory(
-  root: string,
-  days: number = DEFAULT_REVIEW_DAYS,
-  now: number = Date.now(),
-): Promise<StaleOutcome> {
-  const dir = recordDir(root, 'memory')
-
-  if (!existsSync(dir)) {
-    return {
-      ok: false,
-      reason: 'no-folder',
-      message: `No memory folder at ${dir}, so there are no entries to read.`,
-    }
-  }
-
-  const listed = await readdir(dir, { withFileTypes: true })
-  const files = listed
-    .filter(
-      (entry) =>
-        entry.isFile() &&
-        entry.name.endsWith('.md') &&
-        entry.name !== MEMORY_INDEX,
-    )
-    .map((entry) => entry.name)
-
-  const entries = (
-    await Promise.all(
-      files.map((file) => readEntry(root, dir, file, days, now)),
-    )
-  ).toSorted(compareEntries)
-
-  return {
-    ok: true,
-    root,
-    folder: relative(root, dir),
-    days,
-    total: entries.length,
-    due: entries.filter((entry) => entry.due).length,
-    entries,
-  }
-}

package/src/sandbox/hooks.ts

@@ -1,128 +0,0 @@
-import { spawnSync } from 'node:child_process'
-import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { PROJECT_ROOT } from '@/roots/project'
-
-/**
- * The bash entry a scenario's hooks run through. Scenarios and the library they
- * call stay bash, so this contract is the whole of what the TypeScript harness
- * knows about one: which hooks it declares and what `use_config` exports.
- */
-const HOOK_SCRIPT = join(PROJECT_ROOT, 'scripts', 'sandbox-hook.sh')
-
-const ANCHOR_RECORD = '@anchor='
-
-export interface Probe {
-  readonly exports: Readonly<Record<string, string>>
-  readonly isAnchor: boolean
-}
-
-export type ProbeResult =
-  | ({ readonly ok: true } & Probe)
-  | { readonly ok: false; readonly status: number }
-
-/**
- * Reads the NUL-separated `NAME=value` pairs the probe prints. NUL rather than a
- * newline, since an exported value can hold one. The anchor record closes every
- * well-formed probe, so output missing it is a probe that did not finish.
- */
-export function parseProbe(stdout: string): Probe {
-  const { exports, anchor } = parsePairs(stdout)
-  if (anchor === undefined)
-    throw new Error('the probe printed no anchor record')
-
-  return { exports, isAnchor: anchor === '1' }
-}
-
-function parsePairs(text: string): {
-  exports: Record<string, string>
-  anchor: string | undefined
-} {
-  const exports: Record<string, string> = {}
-  let anchor: string | undefined
-
-  for (const record of text.split('\0')) {
-    if (record.startsWith(ANCHOR_RECORD)) {
-      anchor = record.slice(ANCHOR_RECORD.length)
-      continue
-    }
-    const split = record.indexOf('=')
-    if (split > 0) exports[record.slice(0, split)] = record.slice(split + 1)
-  }
-
-  return { exports, anchor }
-}
-
-/**
- * Runs `use_config` and `use_anchor` in a child and returns what they exported.
- * Stderr is inherited by default, so a hook that fails narrates into the same
- * frame the harness writes. A non-zero status passes through rather than being
- * flattened, since the harness exits with it.
- */
-export function probeScenario(
-  file: string,
-  env: NodeJS.ProcessEnv,
-  stderr: 'inherit' | 'pipe' = 'inherit',
-): ProbeResult {
-  const result = spawnSync('bash', [HOOK_SCRIPT, 'probe', file], {
-    env,
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', stderr],
-  })
-  const status = result.status ?? 1
-  if (status !== 0) return { ok: false, status }
-
-  return { ok: true, ...parseProbe(result.stdout) }
-}
-
-/**
- * How `stage_setup` ended. The retired dispatcher ran it in its own shell, so
- * an `exit` there ended provisioning through the frame-closing trap, and an
- * `exec` replaced the harness outright, leaving its program's frame as the last
- * one written. The harness reproduces both from this.
- */
-export type StageEnding = 'returned' | 'exited' | 'replaced'
-
-export interface StageResult {
-  readonly status: number
-  readonly ending: StageEnding
-  readonly exports: Readonly<Record<string, string>>
-}
-
-const EXITED_RECORD = '@exited'
-
-/**
- * Runs `stage_setup` inside the tree with every stream inherited, so a scenario
- * prompting through `select_or_route_scenario` still reaches a terminal and its
- * narration lands in order with the harness's own.
- *
- * The exports `stage_setup` changed come back through a file rather than a
- * pipe. Stdout belongs to the scenario, and a background process a scenario
- * starts would hold an extra pipe open past the child's exit.
- */
-export function stageScenario(
-  file: string,
-  env: NodeJS.ProcessEnv,
-  stdio: 'inherit' | 'ignore' = 'inherit',
-): StageResult {
-  const scratch = mkdtempSync(join(tmpdir(), 'canon-sandbox-hook-'))
-  const report = join(scratch, 'exports')
-
-  try {
-    const result = spawnSync('bash', [HOOK_SCRIPT, 'stage', file, report], {
-      env,
-      stdio,
-    })
-    const status = result.status ?? 1
-    if (!existsSync(report)) return { status, ending: 'replaced', exports: {} }
-
-    const text = readFileSync(report, 'utf8')
-    if (text.split('\0').includes(EXITED_RECORD))
-      return { status, ending: 'exited', exports: {} }
-
-    return { status, ending: 'returned', exports: parsePairs(text).exports }
-  } finally {
-    rmSync(scratch, { recursive: true, force: true })
-  }
-}