@erclx/canon 5.31.0 → 5.33.0

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/repo/metadata.ts

@@ -1,206 +0,0 @@
-import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
-
-/**
- * What this run can compute from the tree alone. A field stays absent rather
- * than empty when nothing local resolves it, so a caller never reads
- * "nothing to propose" as "propose removing what is already there."
- */
-export interface MetadataProposal {
-  readonly description?: string
-  readonly homepage?: string
-  readonly topics?: readonly string[]
-}
-
-/** What the remote already carries, read by the caller rather than here. */
-export interface CurrentMetadata {
-  readonly description: string
-  readonly homepage: string
-  readonly topics: readonly string[]
-}
-
-export interface MetadataDiff {
-  readonly description?: { readonly current: string; readonly proposed: string }
-  readonly homepage?: { readonly current: string; readonly proposed: string }
-  readonly topics?: {
-    readonly added: readonly string[]
-    readonly removed: readonly string[]
-  }
-}
-
-/** GitHub's own cap on the About field. */
-const MAX_DESCRIPTION_LENGTH = 350
-
-/** GitHub's own cap on topics per repository. */
-const MAX_TOPICS = 20
-
-/** GitHub's own shape for a topic: lowercase, alphanumeric, internal hyphens. */
-const TOPIC_PATTERN = /^[a-z0-9][a-z0-9-]*$/
-
-/**
- * Whether an already-trimmed, already-lowercased string is a shape GitHub
- * accepts as a topic. Exported so a caller validating an operator-supplied
- * topic list checks against the same rule this reader silently filters
- * `package.json`'s `keywords` through, rather than reimplementing it against
- * a looser test such as non-emptiness alone.
- */
-export function isValidTopic(topic: string): boolean {
-  return TOPIC_PATTERN.test(topic)
-}
-
-/**
- * A bare image, or an image wrapped in a link, which is the shape a shields.io
- * badge takes. The wrapped alternative goes first, since the bare form would
- * otherwise match its inner image alone and leave the wrapping link behind.
- */
-const BADGE_TOKEN = /\[!\[[^\]]*\]\([^)]*\)\]\([^)]*\)|!\[[^\]]*\]\([^)]*\)/g
-
-/** True once every badge token is stripped and nothing remains. */
-function isBadgeLine(line: string): boolean {
-  return line.replace(BADGE_TOKEN, '').trim() === ''
-}
-
-function stripInlineMarkdown(line: string): string {
-  return line
-    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
-    .replace(/(\*\*|__)(.+?)\1/g, '$2')
-    .replace(/(\*|_|`)(.+?)\1/g, '$2')
-    .trim()
-}
-
-/**
- * The first prose line past the title and any badge row, stripped of inline
- * markdown and capped at GitHub's About field length.
- *
- * `undefined` only when the file carries nothing past its title and badges,
- * per the skill requirement's refusal boundary: a resolvable line that reads
- * as a title rather than a sentence is still proposed, since rejecting it is
- * a judgment for the person reading the proposal rather than for this reader.
- */
-export function extractOpeningLine(readme: string): string | undefined {
-  for (const raw of readme.split('\n')) {
-    const line = raw.trim()
-    if (line === '' || line.startsWith('#') || isBadgeLine(line)) continue
-
-    const stripped = stripInlineMarkdown(line)
-    if (stripped === '') continue
-
-    return stripped.length > MAX_DESCRIPTION_LENGTH
-      ? `${stripped.slice(0, MAX_DESCRIPTION_LENGTH - 1)}…`
-      : stripped
-  }
-  return undefined
-}
-
-/**
- * `package.json`'s `keywords` read as candidate topics, the field the wider
- * npm ecosystem already uses for this. Invalid entries are dropped silently
- * rather than refused, since a manifest mixing free-text keywords with
- * topic-shaped ones is ordinary and only the shaped half transfers.
- */
-function readTopics(keywords: unknown): readonly string[] | undefined {
-  if (!Array.isArray(keywords)) return undefined
-
-  const topics = new Set<string>()
-  for (const entry of keywords) {
-    if (typeof entry !== 'string') continue
-    const topic = entry.trim().toLowerCase()
-    if (isValidTopic(topic)) topics.add(topic)
-    if (topics.size === MAX_TOPICS) break
-  }
-  return [...topics]
-}
-
-interface PackageFields {
-  readonly homepage?: unknown
-  readonly keywords?: unknown
-}
-
-async function readManifest(root: string): Promise<PackageFields | undefined> {
-  try {
-    const parsed: unknown = JSON.parse(
-      await readFile(join(root, 'package.json'), 'utf8'),
-    )
-    return (parsed ?? undefined) as PackageFields | undefined
-  } catch {
-    return undefined
-  }
-}
-
-/**
- * Computes what this tree can propose for its own repository metadata, with
- * no network call: an About text from the README's opening line, and a
- * homepage and a topic set from `package.json`, the one manifest every
- * target project this ships to already carries.
- *
- * A field a target project declares nowhere stays absent rather than empty,
- * so the caller comparing this against the remote never treats a field this
- * reader has no opinion on as a proposal to clear it.
- */
-export async function proposeMetadata(root: string): Promise<MetadataProposal> {
-  const [readme, manifest] = await Promise.all([
-    readFile(join(root, 'README.md'), 'utf8').catch(() => undefined),
-    readManifest(root),
-  ])
-
-  const description =
-    readme === undefined ? undefined : extractOpeningLine(readme)
-
-  const homepage =
-    typeof manifest?.homepage === 'string' && manifest.homepage.trim() !== ''
-      ? manifest.homepage.trim()
-      : undefined
-
-  const topics = readTopics(manifest?.keywords)
-
-  return {
-    ...(description !== undefined && { description }),
-    ...(homepage !== undefined && { homepage }),
-    ...(topics !== undefined && topics.length > 0 && { topics }),
-  }
-}
-
-/**
- * Compares a computed proposal against what the remote already carries.
- *
- * A field the proposal has no opinion on is never diffed, which is what
- * keeps a target project with no `keywords` field from seeing every existing
- * topic reported as a removal.
- */
-export function compareMetadata(
-  current: CurrentMetadata,
-  proposed: MetadataProposal,
-): MetadataDiff {
-  const diff: {
-    description?: { current: string; proposed: string }
-    homepage?: { current: string; proposed: string }
-    topics?: { added: readonly string[]; removed: readonly string[] }
-  } = {}
-
-  if (
-    proposed.description !== undefined &&
-    proposed.description !== current.description
-  ) {
-    diff.description = {
-      current: current.description,
-      proposed: proposed.description,
-    }
-  }
-
-  if (
-    proposed.homepage !== undefined &&
-    proposed.homepage !== current.homepage
-  ) {
-    diff.homepage = { current: current.homepage, proposed: proposed.homepage }
-  }
-
-  if (proposed.topics !== undefined) {
-    const currentSet = new Set(current.topics)
-    const proposedSet = new Set(proposed.topics)
-    const added = proposed.topics.filter((topic) => !currentSet.has(topic))
-    const removed = current.topics.filter((topic) => !proposedSet.has(topic))
-    if (added.length > 0 || removed.length > 0) diff.topics = { added, removed }
-  }
-
-  return diff
-}

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 })
-  }
-}