@erclx/canon 5.25.0 → 5.27.0

package/src/gov/superseded.ts

@@ -1,8 +1,8 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { isBinary } from '@/binary'
-import { isMarked } from '@/exempt-marker'
-import { listRepositoryFiles } from '@/git-files'
+import { isBinary } from '@/sweep/binary'
+import { isMarked } from '@/sweep/exempt-marker'
+import { listRepositoryFiles } from '@/git/files'
 
 /**
  * The inline token exempting one line from this sweep, shaped on the

package/src/gov/test-order.ts

@@ -1,6 +1,6 @@
 import { execaSync } from 'execa'
-import { baseCandidates, isMergeBase } from '@/git-base'
-import { gitEnv } from '@/git-env'
+import { baseCandidates, isMergeBase } from '@/git/base'
+import { gitEnv } from '@/git/env'
 
 /**
  * The extensions this check can pair. A test sits beside its subject under one

package/src/help.ts

@@ -105,7 +105,7 @@ const EXAMPLES = [
   'canon canvas list --json',
   'canon slides render',
   'canon slides list --json',
-  'canon capture assets/captures/install.html --selector .window --out assets/evidence',
+  'canon capture assets/captures/install.html --selector .window --out assets/frames',
   'canon serve .canon/teach',
   'canon inventory focus --json',
   'canon drive http://localhost:4173 run.json --json',

package/src/hooks/post-merge.ts

@@ -1,5 +1,5 @@
 import { execa } from 'execa'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 
 /**
  * One child `canon` call. Each step runs as its own process rather than

package/src/indexes/walk.ts

@@ -1,6 +1,6 @@
 import { existsSync, statSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
-import { listIgnored } from '@/git-ignore'
+import { listIgnored } from '@/git/ignore'
 
 const INDEX_FILE = 'index.md'
 

package/src/labels/audit.ts

@@ -1,4 +1,4 @@
-import { listChangedFiles, resolveBaseRef } from '@/git-files'
+import { listChangedFiles, resolveBaseRef } from '@/git/files'
 import { type Coverage, resolveCoverage } from '@/labels/coverage'
 import { type MapRefusal, readLabelMap } from '@/labels/map'
 

package/src/markdown/ceiling.ts

@@ -8,7 +8,7 @@ import { CHECKPOINTS, documentHeight } from '@/markdown/structure'
  *
  * The whole line rather than anywhere on it, so a standard quoting the marker
  * inside a code span to document it does not exempt itself. A marker with no
- * reason does not count, for the reason `isMarked` in `src/exempt-marker.ts`
+ * reason does not count, for the reason `isMarked` in `src/sweep/exempt-marker.ts`
  * gives: a bare token reads as a line that meant to say something and did not.
  */
 const EXEMPT_MARKER = /^<!--\s*canon-length-exempt:[ \t]*(\S.*?)\s*-->$/

package/src/markdown/files.ts

@@ -1,6 +1,6 @@
 import { existsSync, statSync } from 'node:fs'
 import { relative, resolve } from 'node:path'
-import { listRepositoryFiles } from '@/git-files'
+import { listRepositoryFiles } from '@/git/files'
 
 const MARKDOWN = /\.md$/
 

package/src/migrate/apply.ts

@@ -1,7 +1,7 @@
 import { $ } from 'bun'
 import { readFile, mkdir, rename, rmdir, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import type { RenamePlan, RenameSource } from '@/migrate/plan'
 import { FROM_ROOT as OLD_ROOT, type RecordsPlan } from '@/migrate/records'
 

package/src/pr/bijection.ts

@@ -1,4 +1,4 @@
-import type { RenamePair } from '@/git-files'
+import type { RenamePair } from '@/git/files'
 import { extractKeyChangePaths, KEY_CHANGES, type PathClaim } from '@/pr/paths'
 
 /**

package/src/pr/evidence.ts

@@ -10,11 +10,20 @@ const SHORT_SHA_LENGTH = 7
 /** Prefix of the trailing marker this module writes and reads back. */
 const MARKER_PREFIX = '<!-- pr-evidence:'
 
-/** How the first line of a body names the branch's preview deployment. */
+/** How the address line names the branch's preview deployment. */
 const PREVIEW_PREFIX = '**Preview:**'
 
-/** How the opening block names the branch's server on the operator's own machine, under any hosted preview line. */
-export const LOCAL_PREFIX = '**Local preview:**'
+/** How the address line names the branch's server on the operator's own machine, after any hosted segment. */
+const LOCAL_PREFIX = '**Local preview:**'
+
+/** What joins the hosted and local segments on the one address line. */
+const ADDRESS_SEPARATOR = ' · '
+
+/** The heading every body opens with. */
+const EVIDENCE_HEADING = '## Evidence'
+
+/** How the visible commit line opens. */
+const BASE_PREFIX = '**Base:**'
 
 /** The heading the checklist sits under, printed outside the delimiters so a carried checklist never doubles it. */
 const CHECKLIST_HEADING = '## What to look at'
@@ -135,15 +144,15 @@ export function evidenceMarker(head: string): string {
  * pinned to a commit sha rather than a branch, so the comment keeps showing
  * what it claimed even after the branch moves.
  *
- * A preview address opens the body, and with no states it is the whole body
- * apart from the marker, so a pull request whose screenshots did not change
- * still gets one comment a later call can find and edit in place.
+ * The body opens with `## Evidence` and, under it, one address line joining
+ * whichever of the hosted and local previews apply, so the comment reads as
+ * evidence first and a preview never stands where the heading should. With no
+ * states the heading and the address are the whole body apart from the
+ * marker, so a pull request whose screenshots did not change still gets one
+ * comment a later call can find and edit in place.
  *
  * A checklist closes the body, below the comparison it annotates, so one
- * comment carries the preview address, the screenshots, and what to look at.
- *
- * A local address sits under the hosted one, never above it, so the hosted
- * line keeps the first-line position `findEvidencePreview` reads.
+ * comment carries the addresses, the screenshots, and what to look at.
  */
 export function renderEvidenceBody(
   states: readonly EvidenceState[],
@@ -154,11 +163,15 @@ export function renderEvidenceBody(
   checklist?: string,
   local?: string,
 ): string {
-  const addresses = [
+  const segments = [
     ...(preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`]),
     ...(local === undefined ? [] : [`${LOCAL_PREFIX} ${local}`]),
   ]
-  const opening = addresses.length === 0 ? [] : [...addresses, '']
+  const opening = [
+    EVIDENCE_HEADING,
+    '',
+    ...(segments.length === 0 ? [] : [segments.join(ADDRESS_SEPARATOR), '']),
+  ]
   const closing =
     checklist === undefined
       ? []
@@ -198,9 +211,7 @@ export function renderEvidenceBody(
 
   return [
     ...opening,
-    '## Evidence',
-    '',
-    `**Base:** \`${base.slice(0, SHORT_SHA_LENGTH)}\` · **Head:** \`${head.slice(0, SHORT_SHA_LENGTH)}\``,
+    `${BASE_PREFIX} \`${base.slice(0, SHORT_SHA_LENGTH)}\` · **Head:** \`${head.slice(0, SHORT_SHA_LENGTH)}\``,
     '',
     ...sections,
     '',
@@ -249,7 +260,8 @@ export interface OwedInput {
   readonly hasEvidenceChange: boolean
   readonly hasMarkedComment: boolean
   readonly carriedPreview: boolean
-  readonly deployWorkflowFound: boolean
+  /** A deploy workflow resolves and its push filter matches a path the pull request changed. */
+  readonly deployServesChange: boolean
 }
 
 /**
@@ -262,7 +274,7 @@ export function readOwed(input: OwedInput): OwedStep[] {
   if (input.hasEvidenceChange && !input.hasMarkedComment) owed.push('evidence')
   if (
     (input.hasMarkedComment || input.hasEvidenceChange) &&
-    input.deployWorkflowFound &&
+    input.deployServesChange &&
     !input.carriedPreview
   ) {
     owed.push('preview')
@@ -295,33 +307,78 @@ export function findEvidenceCaseCount(
   return marked === undefined ? 0 : countEvidenceCases(marked.body)
 }
 
+/** Lines that close the address region, being whatever a body carries below its addresses. */
+const REGION_ENDS = [
+  BASE_PREFIX,
+  CHECKLIST_HEADING,
+  '<details',
+  CHECKLIST_START,
+  MARKER_PREFIX,
+]
+
+export interface AddressReading {
+  /** Indexes of the lines carrying a hosted or local segment. */
+  readonly lines: readonly number[]
+  readonly preview?: string
+  readonly local?: string
+}
+
+function readSegment(segment: string, prefix: string): string | undefined {
+  return segment.startsWith(prefix)
+    ? segment.slice(prefix.length).trim() || undefined
+    : undefined
+}
+
 /**
- * The preview address the marked comment already opens with. A re-render
- * after a later push passes no address of its own, and carrying this one
- * forward keeps that edit from deleting the link a reviewer is using.
+ * Reads the addresses a body carries in the region above its commit line,
+ * checklist, comparison, or marker, matching each prefix wherever it sits in
+ * that region. One reader covers the layout that opens on the addresses as
+ * well as the one that opens on the heading, so an open pull request keeps
+ * its links across the first re-render, and a line quoted further down in a
+ * checklist is never taken for an address.
  */
-export function findEvidencePreview(
+export function readAddresses(body: string): AddressReading {
+  const lines: number[] = []
+  let preview: string | undefined
+  let local: string | undefined
+  const bodyLines = body.split('\n')
+  for (let index = 0; index < bodyLines.length; index += 1) {
+    const line = (bodyLines[index] ?? '').trim()
+    if (REGION_ENDS.some((end) => line.startsWith(end))) break
+    let isAddress = false
+    for (const segment of line.split(ADDRESS_SEPARATOR.trim())) {
+      const trimmed = segment.trim()
+      const hosted = readSegment(trimmed, PREVIEW_PREFIX)
+      const own = readSegment(trimmed, LOCAL_PREFIX)
+      if (hosted !== undefined) preview ??= hosted
+      if (own !== undefined) local ??= own
+      if (hosted !== undefined || own !== undefined) isAddress = true
+    }
+    if (isAddress) lines.push(index)
+  }
+  return {
+    lines,
+    ...(preview !== undefined && { preview }),
+    ...(local !== undefined && { local }),
+  }
+}
+
+function findMarked(
   comments: readonly EvidenceComment[],
-): string | undefined {
-  const marked = comments.find((comment) => hasEvidenceMarker(comment.body))
-  const first = marked?.body.split('\n')[0]?.trim() ?? ''
-  if (!first.startsWith(PREVIEW_PREFIX)) return undefined
-  return first.slice(PREVIEW_PREFIX.length).trim() || undefined
+): EvidenceComment | undefined {
+  return comments.find((comment) => hasEvidenceMarker(comment.body))
 }
 
 /**
- * Where the local address line sits in a body, searched only through the
- * opening block above the first blank line, so a line quoted further down in
- * a checklist is never taken for it. -1 when the block carries none.
+ * The preview address the marked comment already carries. A re-render after
+ * a later push passes no address of its own, and carrying this one forward
+ * keeps that edit from deleting the link a reviewer is using.
  */
-export function findLocalLineIndex(body: string): number {
-  const lines = body.split('\n')
-  for (let index = 0; index < lines.length; index += 1) {
-    const line = (lines[index] ?? '').trim()
-    if (line === '') return -1
-    if (line.startsWith(LOCAL_PREFIX)) return index
-  }
-  return -1
+export function findEvidencePreview(
+  comments: readonly EvidenceComment[],
+): string | undefined {
+  const marked = findMarked(comments)
+  return marked === undefined ? undefined : readAddresses(marked.body).preview
 }
 
 /**
@@ -331,12 +388,8 @@ export function findLocalLineIndex(body: string): number {
 export function findEvidenceLocal(
   comments: readonly EvidenceComment[],
 ): string | undefined {
-  const marked = comments.find((comment) => hasEvidenceMarker(comment.body))
-  if (marked === undefined) return undefined
-  const index = findLocalLineIndex(marked.body)
-  if (index === -1) return undefined
-  const line = marked.body.split('\n')[index]?.trim() ?? ''
-  return line.slice(LOCAL_PREFIX.length).trim() || undefined
+  const marked = findMarked(comments)
+  return marked === undefined ? undefined : readAddresses(marked.body).local
 }
 
 /**

package/src/pr/local.ts

@@ -1,4 +1,4 @@
-import { findLocalLineIndex } from '@/pr/evidence'
+import { readAddresses } from '@/pr/evidence'
 
 /**
  * The folder linked worktrees sit under. A listener there belongs to another
@@ -111,15 +111,21 @@ export function parseProcNetTcp(text: string): ProcSocket[] {
 }
 
 /**
- * Replaces the local address line of a marked body with `note`, leaving
- * every other byte in place so the trailing marker, the checklist delimiters,
- * and any ticked box survive. Undefined when the body carries no such line,
- * which is also what a second strip of the same body returns.
+ * Drops the address line of a marked body, hosted and local segments alike,
+ * since the close that runs this also deletes the branch's preview
+ * deployments and a link left behind points at nothing. Every other byte stays
+ * in place, so the trailing marker, the checklist delimiters, and any ticked
+ * box survive, and the blank line the address sat on is dropped with it so no
+ * gap doubles. Undefined when the body carries no address, which is also what
+ * a second drop of the same body returns.
  */
-export function stripLocalLine(body: string, note: string): string | undefined {
-  const index = findLocalLineIndex(body)
-  if (index === -1) return undefined
-  const lines = body.split('\n')
-  lines[index] = note
+export function dropAddressLine(body: string): string | undefined {
+  const { lines: indexes } = readAddresses(body)
+  const first = indexes[0]
+  if (first === undefined) return undefined
+  const dropped = new Set(indexes)
+  const lines = body.split('\n').filter((_, index) => !dropped.has(index))
+  const isGapAbove = first === 0 || (lines[first - 1] ?? '').trim() === ''
+  if (isGapAbove && (lines[first] ?? '').trim() === '') lines.splice(first, 1)
   return lines.join('\n')
 }

package/src/pr/preview.ts

@@ -16,6 +16,7 @@ const BRANCH_FENCE = '--branch=${{ github.ref_name }}'
 
 export type PreviewRefusal =
   | 'no-deploy'
+  | 'unserved'
   | 'unfenced'
   | 'no-alias'
   | 'gh-failed'
@@ -27,8 +28,77 @@ export interface WorkflowFile {
   readonly text: string
 }
 
+/**
+ * Which changed paths a deploy builds from, read off its own push trigger, so
+ * the workflow that decides when production deploys is also the one statement
+ * of what a branch preview serves.
+ */
+export type ServedFilter =
+  | { readonly kind: 'all' }
+  | { readonly kind: 'paths'; readonly patterns: readonly string[] }
+  | { readonly kind: 'paths-ignore'; readonly patterns: readonly string[] }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function readPatterns(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  return value.filter((entry): entry is string => typeof entry === 'string')
+}
+
+/**
+ * Reads `on.push.paths` or `on.push.paths-ignore`. A workflow with neither,
+ * with no push trigger, or that does not parse serves every change, since
+ * reading unserved by mistake stops every reader asking for a preview.
+ */
+export function readServedPaths(workflowText: string): ServedFilter {
+  let parsed: unknown
+  try {
+    parsed = Bun.YAML.parse(workflowText)
+  } catch {
+    return { kind: 'all' }
+  }
+  const on = isRecord(parsed) ? parsed.on : undefined
+  const push = isRecord(on) ? on.push : undefined
+  if (!isRecord(push)) return { kind: 'all' }
+
+  const paths = readPatterns(push.paths)
+  if (paths !== undefined) return { kind: 'paths', patterns: paths }
+  const ignored = readPatterns(push['paths-ignore'])
+  if (ignored !== undefined) return { kind: 'paths-ignore', patterns: ignored }
+  return { kind: 'all' }
+}
+
+/** Whether the patterns match a path, applied in order so a later `!` pattern overrides an earlier one, as GitHub applies them. */
+function matchesInOrder(patterns: readonly string[], path: string): boolean {
+  let isMatched = false
+  for (const pattern of patterns) {
+    const isNegated = pattern.startsWith('!')
+    const glob = new Bun.Glob(isNegated ? pattern.slice(1) : pattern)
+    if (glob.match(path)) isMatched = !isNegated
+  }
+  return isMatched
+}
+
+/** Whether a push carrying `changedPaths` would run the deploy, by the filter its trigger declares. */
+export function servesChange(
+  filter: ServedFilter,
+  changedPaths: readonly string[],
+): boolean {
+  if (filter.kind === 'all') return true
+  if (filter.kind === 'paths') {
+    return changedPaths.some((path) => matchesInOrder(filter.patterns, path))
+  }
+  return changedPaths.some((path) => !matchesInOrder(filter.patterns, path))
+}
+
 export type WorkflowPick =
-  | { readonly kind: 'found'; readonly path: string }
+  | {
+      readonly kind: 'found'
+      readonly path: string
+      readonly filter: ServedFilter
+    }
   | {
       readonly kind: 'refused'
       readonly reason: 'no-deploy' | 'unfenced' | 'no-alias'
@@ -36,6 +106,7 @@ export type WorkflowPick =
 
 interface WorkflowShape {
   readonly path: string
+  readonly text: string
   readonly deployLines: readonly string[]
   readonly isDispatchable: boolean
   readonly hasMarker: boolean
@@ -51,6 +122,7 @@ function readShape(file: WorkflowFile): WorkflowShape {
     .filter((line) => !line.trimStart().startsWith('#'))
   return {
     path: file.path,
+    text: file.text,
     deployLines: lines.filter((line) => line.includes('pages deploy')),
     isDispatchable: lines.some((line) => /^\s*workflow_dispatch:/.test(line)),
     hasMarker: lines.some((line) => line.includes(ALIAS_MARKER)),
@@ -80,7 +152,11 @@ export function findDeployWorkflow(
   const marked = fenced.find((shape) => shape.hasMarker)
   if (marked === undefined) return { kind: 'refused', reason: 'no-alias' }
 
-  return { kind: 'found', path: marked.path }
+  return {
+    kind: 'found',
+    path: marked.path,
+    filter: readServedPaths(marked.text),
+  }
 }
 
 export function readPreviewAlias(log: string): string | undefined {

package/src/record-root.ts

@@ -76,6 +76,7 @@ export const RECORD_ENTRIES: readonly string[] = [
   'proposals',
   'ready',
   'review',
+  'slides',
   'tasks',
   'teach',
   'transcripts',

package/src/records/backup.ts

@@ -1,7 +1,7 @@
 import { existsSync, lstatSync, readdirSync } from 'node:fs'
 import { basename, join, relative, resolve } from 'node:path'
 import { $ } from 'bun'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import { RECORD_ROOTS, recordRoot, SCRATCH } from '@/record-root'
 import { type BlockedPath, guardPayload } from '@/records/push-guard'
 
@@ -43,6 +43,7 @@ export const BACKED_FOLDERS = [
   'plans',
   'proposals',
   'review',
+  'slides',
   'tasks',
   'teach',
   'transcripts',

package/src/records/push-guard.ts

@@ -1,6 +1,6 @@
 import { lstat, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { isBinary } from '@/binary'
+import { isBinary } from '@/sweep/binary'
 import { scanText } from '@/secrets/scan'
 
 /**

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]