@erclx/canon 5.25.0 → 5.26.0

package/src/records/stale-canonical.ts

@@ -0,0 +1,146 @@
+import { $ } from 'bun'
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+import { gitEnv } from '@/git-env'
+import { readReviewed } from '@/records/stale'
+import { surfaceDir } from '@/surface-root'
+
+/** The two records whose drift is identity rather than a stale path. */
+const CANONICAL_DOCS = ['REQUIREMENTS.md', 'ARCHITECTURE.md'] as const
+
+export interface CanonicalDoc {
+  /** Relative to the root, at whichever surface root carries the doc. */
+  readonly path: string
+  /** `YYYY-MM-DD`, or null when the doc 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
+  /** Release tags merged into HEAD after the reviewed day, or null when never reviewed. */
+  readonly releasesSince: number | null
+  /** The newest release tag merged into HEAD, or null when there is none. */
+  readonly latestRelease: string | null
+}
+
+export interface CanonicalReport {
+  readonly ok: true
+  readonly root: string
+  /** False when HEAD has merged no tag, so a zero count measured nothing. */
+  readonly tagged: boolean
+  readonly docs: readonly CanonicalDoc[]
+}
+
+export interface CanonicalRefused {
+  readonly ok: false
+  readonly reason: 'unreadable-tags'
+  readonly message: string
+}
+
+export type CanonicalOutcome = CanonicalReport | CanonicalRefused
+
+interface Release {
+  readonly tag: string
+  readonly day: string
+}
+
+/**
+ * A tag ending in a dotted version, bare or behind a component prefix such as
+ * `canon-v2.1.0`. An eval, deploy, or snapshot tag on the trunk names no
+ * release and would otherwise inflate the count.
+ */
+const RELEASE_TAG = /(?:^|[-/@_])v?\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?$/
+
+/**
+ * A repository before its first commit has no HEAD for `--merged` to resolve,
+ * which git reports as a failed read. It has no tags either, so it reads as an
+ * empty history rather than an unreadable one.
+ */
+async function isUnborn(root: string): Promise<boolean> {
+  const [gitDir, head] = await Promise.all([
+    $`git -C ${root} rev-parse --git-dir`.env(gitEnv()).quiet().nothrow(),
+    $`git -C ${root} rev-parse --verify -q HEAD`
+      .env(gitEnv())
+      .quiet()
+      .nothrow(),
+  ])
+  return gitDir.exitCode === 0 && head.exitCode !== 0
+}
+
+/**
+ * Every release tag HEAD has merged, newest first, with the day it was created.
+ *
+ * The creator date is the tagging date on an annotated tag and the commit date
+ * on a lightweight one, so a history mixing both counts by two clocks.
+ */
+async function mergedReleases(root: string): Promise<Release[] | undefined> {
+  // Interpolated rather than inline, since Bun's shell parses the bare
+  // parentheses in `%(refname)` as syntax of its own.
+  const args = [
+    '--merged',
+    'HEAD',
+    '--sort=-creatordate',
+    '--format=%(creatordate:short) %(refname:short)',
+    'refs/tags',
+  ]
+  const result = await $`git -C ${root} for-each-ref ${args}`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return (await isUnborn(root)) ? [] : undefined
+
+  return result.stdout
+    .toString()
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      const [day, tag] = line.trim().split(' ')
+      return { day, tag }
+    })
+    .filter((release) => RELEASE_TAG.test(release.tag))
+}
+
+/**
+ * Reports when each canonical doc was last reviewed and how many releases
+ * have shipped since, read from an optional `reviewed:` frontmatter field.
+ *
+ * The review point is a date rather than a commit, since a commit written on a
+ * feature branch never reaches a trunk that squash-merges. A release tagged on
+ * the reviewed day itself is not counted, as the review is read as covering
+ * that day. It reports and never writes.
+ */
+export async function staleCanonical(root: string): Promise<CanonicalOutcome> {
+  const releases = await mergedReleases(root)
+
+  if (releases === undefined) {
+    return {
+      ok: false,
+      reason: 'unreadable-tags',
+      message: `Could not read the release tags at ${root}, so no count can be taken.`,
+    }
+  }
+
+  const latestRelease = releases[0]?.tag ?? null
+  const present = CANONICAL_DOCS.map((entry) => surfaceDir(root, entry)).filter(
+    (path) => existsSync(path),
+  )
+
+  const docs = await Promise.all(
+    present.map(async (path): Promise<CanonicalDoc> => {
+      const text = (await readFile(path, 'utf8')).replaceAll('\r\n', '\n')
+      const review = readReviewed(text)
+      const { reviewed } = review
+
+      return {
+        path: relative(root, path),
+        ...review,
+        releasesSince:
+          reviewed === null
+            ? null
+            : releases.filter((release) => release.day > reviewed).length,
+        latestRelease,
+      }
+    }),
+  )
+
+  return { ok: true, root, tagged: releases.length > 0, docs }
+}

package/src/records/stale.ts

@@ -65,7 +65,7 @@ const RAW_FRONTMATTER = /^---\n([\s\S]*?)\n---/
  * 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.
  */
-function readReviewed(
+export function readReviewed(
   text: string,
 ): Pick<StaleEntry, 'reviewed' | 'invalidReviewed'> {
   const block = RAW_FRONTMATTER.exec(text)?.[1]

package/src/sandbox/hooks.ts

@@ -0,0 +1,128 @@
+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 '@/project-root'
+
+/**
+ * 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 })
+  }
+}