@erclx/canon 5.17.0 → 5.19.0

package/src/commands/teach.ts

@@ -1,12 +1,16 @@
-import { isAbsolute, relative, resolve, sep } from 'node:path'
+import { readdirSync, statSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
 import type { Command } from 'commander'
+import { LiveStream } from '@/serve/live'
 import {
   logServing,
   parsePort,
   serveFields,
   waitForInterrupt,
 } from '@/serve/report'
-import { DEFAULT_PORT, startServer } from '@/serve/static'
+import { DEFAULT_PORT, LIVE_EVENTS_PATH, startServer } from '@/serve/static'
+import { compileScript } from '@/teach/browser/compile'
+import { reload } from '@/teach/browser/reload'
 import { type LessonOutcome, planLesson } from '@/teach/lesson'
 import { type NavGenerated, type NavOutcome, generateNav } from '@/teach/nav'
 import type { RenderOutcome } from '@/teach/render'
@@ -942,8 +946,17 @@ async function runUp(
       ? 'index.html'
       : relative(dir, resolve(root, contents)).split(sep).join('/')
 
-  const served = startServer(dir, { port, entry })
+  const stream = refreshOnChange(root, dir, topic, emitJson)
+  const served = startServer(dir, {
+    port,
+    entry,
+    live: {
+      stream,
+      script: compileScript(reload, [LIVE_EVENTS_PATH]),
+    },
+  })
   if (!served.ok) {
+    stream.close()
     // A serve refusal carries a reason the teach refusals do not list, so it
     // is written here in the teach record's shape rather than through one.
     if (emitJson) {
@@ -970,10 +983,105 @@ async function runUp(
     logServing(served)
   }
 
-  await waitForInterrupt(served.stop)
+  await waitForInterrupt(async () => {
+    stream.close()
+    await served.stop()
+  })
   return 0
 }
 
+/**
+ * An editor's swap or backup file, or anything under a dot folder. It changes
+ * nothing a page shows, so it neither starts a pass nor counts as served.
+ */
+function isScratch(path: string): boolean {
+  return path
+    .split(/[\\/]/)
+    .some((segment) => segment.startsWith('.') || segment.endsWith('~'))
+}
+
+/**
+ * What the served folder holds, as each file's path, size, and mtime. A pass
+ * whose `nav` wrote nothing leaves it unchanged, which is how the echo of a
+ * pass's own writes settles without a second reload.
+ */
+function servedState(dir: string): string {
+  return readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => relative(dir, join(entry.parentPath, entry.name)))
+    .filter((path) => !isScratch(path))
+    .sort()
+    .map((path) => {
+      const stat = statSync(join(dir, path), { throwIfNoEntry: false })
+      return `${path}:${stat?.size}:${stat?.mtimeMs}`
+    })
+    .join('\n')
+}
+
+/**
+ * Re-runs `nav` on each settled change under the teach folder and tells every
+ * open page to reload once a pass changed what is served. Passes run one at a
+ * time, since `nav` is not reentrant over the files it rewrites, and a change
+ * arriving mid-pass is coalesced into exactly one more. A refused or failed
+ * pass sends no reload, so a page never reloads onto a half-written state.
+ */
+function refreshOnChange(
+  root: string,
+  dir: string,
+  topic: string | undefined,
+  emitJson: boolean,
+): LiveStream<string> {
+  let isRunning = false
+  let isDirty = false
+  let state = servedState(dir)
+
+  const report = (message: string, isWarning: boolean) => {
+    if (emitJson) process.stderr.write(`${message}\n`)
+    else if (isWarning) logWarn(message)
+    else logInfo(message)
+  }
+
+  const pass = async (): Promise<void> => {
+    const nav = await generateNav(root, topic)
+    if (!nav.ok) {
+      report(`Refresh refused: ${nav.message}`, true)
+      return
+    }
+    const next = servedState(dir)
+    if (next === state) return
+    state = next
+    stream.send({ reload: true })
+    report(`Refreshed ${nav.lessons} lessons, reloading open pages`, false)
+  }
+
+  const schedule = async (): Promise<void> => {
+    if (isRunning) {
+      isDirty = true
+      return
+    }
+    isRunning = true
+    do {
+      isDirty = false
+      // A throw, such as the teach folder removed mid-pass, is reported and
+      // the loop carries on, since a rejection left here would end the
+      // process and a stuck flag would end every later refresh.
+      try {
+        await pass()
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code ?? String(error)
+        report(`Refresh failed: ${code}`, true)
+      }
+    } while (isDirty)
+    isRunning = false
+  }
+
+  const stream = new LiveStream<string>(dir, {
+    map: (path) => (isScratch(path) ? undefined : path),
+    onChange: () => void schedule(),
+  })
+  return stream
+}
+
 function reportRefusal(
   title: string,
   refused: TeachRefused,

package/src/context/architecture.ts

@@ -1,7 +1,7 @@
 import { access, readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
 import { AUDITS } from '@/audits/catalog'
-import { bodyLines } from '@/markdown/scan'
+import { type BodyLine, bodyLines } from '@/markdown/scan'
 import { surfaceDir } from '@/surface-root'
 
 /**
@@ -58,9 +58,9 @@ export interface DecisionReport {
    */
   readonly checks: readonly string[]
   /**
-   * The entry's own word count, read alongside the weight judgment the
-   * standard asks a session to make by reading the file rather than counting
-   * it. Never gates, per `standards/architecture.md`'s `## Length` section.
+   * The entry's prose word count, its heading and fenced lines left out. Gates
+   * only against a per-decision cap the record states, so the report and the
+   * stage read one number.
    */
   readonly words: number
   /**
@@ -82,6 +82,12 @@ export interface ArchitectureReport {
    * only what is still open, so its weight is read the same way the file's is.
    */
   readonly risksWords?: number
+  /**
+   * List items in the Risks section, nested ones included, since a nested
+   * bullet is weight the reader pays for. Absent alongside `risksWords`, so a
+   * record with no section never reads as one holding zero bullets.
+   */
+  readonly risksBullets?: number
   /** What the record declared, absent when it states no length rule. */
   readonly allowances?: Allowances
   /** The frame plus the per-decision allowance, absent alongside it. */
@@ -92,6 +98,10 @@ export interface ArchitectureReport {
    * project that never adopted a cap is measured and never gated.
    */
   readonly entryCap?: number
+  /** The most words a decision may hold, absent when the record states none. */
+  readonly wordCap?: number
+  /** The most Risks bullets the record allows, absent when it states none. */
+  readonly riskCap?: number
   /**
    * Whether the record states that every decision closes with a revisit
    * sentence. Declared by the record for the reason the cap is, so a record
@@ -103,7 +113,9 @@ export interface ArchitectureReport {
 
 const DECISION_HEADING = /^###\s+(.+?)\s*$/
 const SECTION_HEADING = /^##\s+\S/
-/** The one H2 the standard's `## Length` section asks to be weighed by words. */
+/** A markdown list item at any depth, which is what a risk bullet is. */
+const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s+\S/
+/** The H2 whose bullets the standard's `## Caps` section counts. */
 const RISKS_HEADING = /^##\s+Risks\s*\/\s*open questions\s*$/i
 const CODE_SPAN = /`[^`]*`/g
 /** Dropped ahead of the figure scan, since an anchor date is not a claim. */
@@ -291,13 +303,12 @@ export function splitDecisions(source: string): RawDecision[] {
 }
 
 /**
- * Counts whitespace-delimited tokens, which is the unit the standard's
- * `## Length` section reads alongside the weight judgment a session makes by
- * reading the file. It is a report figure rather than a gate, so a fenced
- * example or a code span inflating the count costs nothing a reader corrects
- * for by reading, the same trade the line count above it already takes.
+ * Counts whitespace-delimited tokens, the unit a record's word caps are stated
+ * in. A code span counts as the tokens it holds, so a decision citing a long
+ * path pays for it the way a reader does. A caller gating on the count hands
+ * in prose with fenced lines already dropped.
  */
-function wordCount(text: string): number {
+export function wordCount(text: string): number {
   return text.match(/\S+/g)?.length ?? 0
 }
 
@@ -310,14 +321,30 @@ function wordCount(text: string): number {
  * when the section is last, which is where the standard's template puts it.
  */
 export function risksSection(source: string): string | undefined {
-  const lines = bodyLines(source)
-  const body: string[] = []
+  return risksLines(source)
+    ?.map((line) => line.text)
+    .join('\n')
+}
+
+/**
+ * Counts the list items in the Risks section, nested ones included, or
+ * nothing when the record carries no such heading. A fenced line is skipped,
+ * since a template bullet is not a risk.
+ */
+export function riskBullets(source: string): number | undefined {
+  return risksLines(source)?.filter(
+    (line) => !line.fenced && LIST_ITEM.test(line.text),
+  ).length
+}
+
+function risksLines(source: string): BodyLine[] | undefined {
+  const body: BodyLine[] = []
   let capturing = false
   let found = false
 
-  for (const line of lines) {
+  for (const line of bodyLines(source)) {
     if (line.fenced) {
-      if (capturing) body.push(line.text)
+      if (capturing) body.push(line)
       continue
     }
 
@@ -332,10 +359,10 @@ export function risksSection(source: string): string | undefined {
       continue
     }
 
-    if (capturing) body.push(line.text)
+    if (capturing) body.push(line)
   }
 
-  return found ? body.join('\n') : undefined
+  return found ? body : undefined
 }
 
 /** Cardinals a record spells rather than writes, which the corpus does for both. */
@@ -376,6 +403,14 @@ const ENTRY_CAP_CLAUSE = new RegExp(
   String.raw`\bat\s+most\s+${CARDINAL}\s+decisions?\b`,
   'i',
 )
+const WORD_CAP_CLAUSE = new RegExp(
+  String.raw`\bat\s+most\s+${CARDINAL}\s+words\s+a\s+decision\b`,
+  'i',
+)
+const RISK_CAP_CLAUSE = new RegExp(
+  String.raw`\bat\s+most\s+${CARDINAL}\s+risk\s+bullets?\b`,
+  'i',
+)
 
 function readCardinal(token: string | undefined): number | undefined {
   if (token === undefined) return undefined
@@ -413,6 +448,20 @@ export function readEntryCap(source: string): number | undefined {
   return readCardinal(source.match(ENTRY_CAP_CLAUSE)?.[1])
 }
 
+/**
+ * Reads the per-decision word cap a record declares, spelled `at most <n>
+ * words a decision`, or nothing. One spelling, the way the line allowance
+ * reads `<n> lines a decision`, so a drift falls back to reporting.
+ */
+export function readWordCap(source: string): number | undefined {
+  return readCardinal(source.match(WORD_CAP_CLAUSE)?.[1])
+}
+
+/** Reads the Risks cap a record declares, spelled `at most <n> risk bullets`. */
+export function readRiskCap(source: string): number | undefined {
+  return readCardinal(source.match(RISK_CAP_CLAUSE)?.[1])
+}
+
 const REVISIT_CLAUSE =
   /\bevery\s+decision\s+closes\s+with\s+a\s+revisit\s+sentence\b/i
 /**
@@ -486,6 +535,8 @@ export async function measureArchitecture(
 
   const allowances = readAllowances(source)
   const entryCap = readEntryCap(source)
+  const wordCap = readWordCap(source)
+  const riskCap = readRiskCap(source)
   const revisitRequired = readRevisitRule(source)
   const raw = splitDecisions(source)
   const decisions = await Promise.all(
@@ -498,13 +549,14 @@ export async function measureArchitecture(
         figures,
         ...(quantified !== undefined && { quantified }),
         checks: await namedChecks(root, entry.body),
-        words: wordCount(entry.body),
+        words: wordCount(entry.prose),
         revisit: hasRevisitSentence(entry.prose),
       }
     }),
   )
 
   const risks = risksSection(source)
+  const bullets = riskBullets(source)
 
   return {
     rel,
@@ -515,11 +567,14 @@ export async function measureArchitecture(
         .join('\n'),
     ),
     ...(risks !== undefined && { risksWords: wordCount(risks) }),
+    ...(bullets !== undefined && { risksBullets: bullets }),
     ...(allowances !== undefined && {
       allowances,
       ceiling: ceilingFor(allowances, raw.length),
     }),
     ...(entryCap !== undefined && { entryCap }),
+    ...(wordCap !== undefined && { wordCap }),
+    ...(riskCap !== undefined && { riskCap }),
     revisitRequired,
     decisions,
   }
@@ -538,6 +593,31 @@ export function isOverCount(report: ArchitectureReport): boolean {
   )
 }
 
+/**
+ * The decisions holding more prose words than the cap the record states.
+ *
+ * Empty for a record stating no word cap, for the reason `isOverCount` gives.
+ */
+export function overWords(report: ArchitectureReport): DecisionReport[] {
+  const cap = report.wordCap
+  if (cap === undefined) return []
+  return report.decisions.filter((entry) => entry.words > cap)
+}
+
+/**
+ * Whether the Risks section holds more bullets than the cap the record states.
+ *
+ * False for a record stating no cap, and false for one carrying no Risks
+ * section, which the stage reports as absent rather than as zero bullets.
+ */
+export function isOverRisks(report: ArchitectureReport): boolean {
+  return (
+    report.riskCap !== undefined &&
+    report.risksBullets !== undefined &&
+    report.risksBullets > report.riskCap
+  )
+}
+
 /**
  * The headings of decisions lacking a revisit sentence the record requires.
  *

package/src/context/gate.ts

@@ -25,6 +25,19 @@ export interface GateInput {
    * same two cases, plus a record stating no such clause.
    */
   readonly recordMissingRevisit: boolean
+  /**
+   * Whether a decision holds more words than the cap the record states, which
+   * gates under the same two modes and is false in the same two cases, plus a
+   * record stating no word cap.
+   */
+  readonly recordOverWords: boolean
+  /** The same reading for the Risks section's bullet cap. */
+  readonly recordOverRisks: boolean
+  /**
+   * Whether the requirements record holds more words than the cap it states,
+   * which gates for the reason the architecture record's caps do.
+   */
+  readonly requirementsOverWords: boolean
   readonly sections: readonly SectionFinding[]
   readonly drift: readonly FolderDrift[]
   /**
@@ -79,8 +92,10 @@ export function hasSketchWithEvidence(
  * Whether the audit found something that should fail the caller.
  *
  * An unresolved citation is a broken pointer and gates unconditionally, and so
- * does a record past its own ceiling or its own entry cap, or missing a
- * revisit sentence it requires: the record states each rule for itself, which makes those the measures here that are facts
+ * does a record past its own ceiling, entry cap, word cap, or bullet cap, or
+ * missing a revisit sentence it requires, and a requirements record past its
+ * own word cap: each record states its rules for itself, which makes those the
+ * measures here that are facts
  * rather than thresholds a reader weighs. The findings `--gate` adds are
  * the ones answerable from the file itself: a required section it does not
  * declare, an index disagreeing with its folder, and a wireframe's States
@@ -95,13 +110,25 @@ export function isGating({
   recordOverLength,
   recordOverCount,
   recordMissingRevisit,
+  recordOverWords,
+  recordOverRisks,
+  requirementsOverWords,
   sections,
   drift,
   wireframes,
   widened,
 }: GateInput): boolean {
   if (unresolvedCitations > 0) return true
-  if (recordOverLength || recordOverCount || recordMissingRevisit) return true
+  if (
+    recordOverLength ||
+    recordOverCount ||
+    recordMissingRevisit ||
+    recordOverWords ||
+    recordOverRisks ||
+    requirementsOverWords
+  ) {
+    return true
+  }
   if (!widened) return false
 
   return sections.length > 0 || hasDrift(drift) || hasStatesMismatch(wireframes)

package/src/context/requirements.ts

@@ -0,0 +1,77 @@
+import { readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { wordCount } from '@/context/architecture'
+import { bodyLines } from '@/markdown/scan'
+import { surfaceDir } from '@/surface-root'
+
+/**
+ * The record this measures, relative to `root`, resolved at either surface
+ * root for the reason `architectureRel` gives.
+ */
+export function requirementsRel(root: string): string {
+  return relative(root, surfaceDir(root, 'REQUIREMENTS.md'))
+}
+
+export interface RequirementsReport {
+  readonly rel: string
+  /** The whole record's word count, frontmatter left out. */
+  readonly words: number
+  /**
+   * The most words the record says it holds, absent when it states no cap.
+   * Declared by the record rather than held here, so a project that never
+   * adopted a cap is measured and never gated.
+   */
+  readonly wordCap?: number
+}
+
+const WORD_CAP_CLAUSE = /\bat\s+most\s+(\d+)\s+words\b/i
+
+/**
+ * Reads the word cap a record declares, spelled `at most <n> words`, or
+ * nothing. Digits only, since a cap in the hundreds is never spelled out.
+ */
+export function readRequirementsWordCap(source: string): number | undefined {
+  const digits = source.match(WORD_CAP_CLAUSE)?.[1]
+  return digits === undefined ? undefined : Number.parseInt(digits, 10)
+}
+
+function isMissing(error: unknown): boolean {
+  const code = (error as { code?: unknown }).code
+  return code === 'ENOENT' || code === 'ENOTDIR'
+}
+
+/**
+ * Measures the record, or reports nothing when the project carries none.
+ *
+ * Absent rather than zeroed, for the reason `measureArchitecture` gives, and a
+ * record present and unreadable propagates the same way.
+ */
+export async function measureRequirements(
+  root: string,
+): Promise<RequirementsReport | undefined> {
+  const rel = requirementsRel(root)
+
+  let source: string
+  try {
+    source = await readFile(join(root, rel), 'utf8')
+  } catch (error) {
+    if (!isMissing(error)) throw error
+    return undefined
+  }
+
+  const wordCap = readRequirementsWordCap(source)
+  return {
+    rel,
+    words: wordCount(
+      bodyLines(source)
+        .map((line) => line.text)
+        .join('\n'),
+    ),
+    ...(wordCap !== undefined && { wordCap }),
+  }
+}
+
+/** Whether the record holds more words than the cap it states. */
+export function isOverWordCap(report: RequirementsReport): boolean {
+  return report.wordCap !== undefined && report.words > report.wordCap
+}

package/src/gate/measures.ts

@@ -10,9 +10,12 @@ import {
 import {
   isOverCount,
   isOverLength,
+  isOverRisks,
   measureArchitecture,
   missingRevisit,
+  overWords,
 } from '@/context/architecture'
+import { isOverWordCap, measureRequirements } from '@/context/requirements'
 import {
   auditSkills,
   PRACTICE_LEDGER,
@@ -246,42 +249,80 @@ function citedPaths(record: { paths?: unknown } | undefined): string[] {
 }
 
 /**
- * The architecture record against the three rules it states for itself: the
- * line ceiling its allowances derive, the entry cap, and the revisit sentence
- * closing each decision.
+ * The canonical records against the caps each states for itself. The
+ * architecture record carries five: the line ceiling its allowances derive,
+ * the entry cap, the revisit sentence closing each decision, the words a
+ * decision may hold, and the bullets its Risks section may hold. The
+ * requirements record carries one, its own word count.
  *
  * Read in-process rather than through `context audit`, whose one gating stage
- * here runs `--citations-only` and never opens the record, which is why the
- * line ceiling went unenforced by `bun run check` until this stage. A project
- * carrying no record, or a record stating none of the three, passes, since
- * each rule belongs to the record rather than to the toolkit.
+ * here runs `--citations-only` and never opens either record, which is why
+ * the line ceiling went unenforced by `bun run check` until this stage. A
+ * project carrying neither record, or records stating none of the caps,
+ * passes, since each rule belongs to the record rather than to the toolkit.
  */
-export const architectureRecord: Measure = async (ctx) => {
-  const report = await measureArchitecture(ctx.root)
+export const canonicalRecords: Measure = async (ctx) => {
+  const [report, requirements] = await Promise.all([
+    measureArchitecture(ctx.root),
+    measureRequirements(ctx.root),
+  ])
+
+  const failures: string[] = []
+  const emissions: Emission[] = []
+
   if (report === undefined) {
-    return { emissions: [info('No architecture record to measure')] }
+    emissions.push(info('No architecture record to measure'))
+  } else {
+    const decisions = report.decisions.length
+    const lackingRevisit = missingRevisit(report)
+    const longDecisions = overWords(report)
+    failures.push(
+      ...[
+        isOverCount(report) &&
+          `${decisions} decisions against a cap of ${report.entryCap}. Merge two or retire one in ${report.rel}, never compress.`,
+        isOverLength(report) &&
+          `${report.lines} lines against a ceiling of ${report.ceiling} in ${report.rel}.`,
+        lackingRevisit.length > 0 &&
+          `No revisit sentence in ${lackingRevisit.map((heading) => `"${heading}"`).join(', ')}. Close each with one opening "Revisit when" in ${report.rel}.`,
+        longDecisions.length > 0 &&
+          `${longDecisions.map((entry) => `"${entry.heading}" (${entry.words})`).join(', ')} past ${report.wordCap} words a decision in ${report.rel}. Cut the reasoning to the trade, never split one decision across two headings.`,
+        isOverRisks(report) &&
+          `${report.risksBullets} risk bullets against a cap of ${report.riskCap} in ${report.rel}. Drop what is no longer open.`,
+      ].filter((failure): failure is string => typeof failure === 'string'),
+    )
+
+    const cap =
+      report.entryCap === undefined
+        ? 'no entry cap stated'
+        : `a cap of ${report.entryCap}`
+    emissions.push(info(`${decisions} decisions against ${cap}`))
+    if (report.riskCap !== undefined && report.risksBullets === undefined) {
+      emissions.push(
+        info(
+          `No Risks section to count against a cap of ${report.riskCap} in ${report.rel}`,
+        ),
+      )
+    }
   }
 
-  const decisions = report.decisions.length
-  const lackingRevisit = missingRevisit(report)
-  const failures = [
-    isOverCount(report) &&
-      `${decisions} decisions against a cap of ${report.entryCap}. Merge two or retire one in ${report.rel}, never compress.`,
-    isOverLength(report) &&
-      `${report.lines} lines against a ceiling of ${report.ceiling} in ${report.rel}.`,
-    lackingRevisit.length > 0 &&
-      `No revisit sentence in ${lackingRevisit.map((heading) => `"${heading}"`).join(', ')}. Close each with one opening "Revisit when" in ${report.rel}.`,
-  ].filter((failure): failure is string => typeof failure === 'string')
+  if (requirements === undefined) {
+    emissions.push(info('No requirements record to measure'))
+  } else if (isOverWordCap(requirements)) {
+    failures.push(
+      `${requirements.words} words against a cap of ${requirements.wordCap} in ${requirements.rel}.`,
+    )
+  } else {
+    const cap =
+      requirements.wordCap === undefined
+        ? 'no word cap stated'
+        : `a cap of ${requirements.wordCap}`
+    emissions.push(
+      info(`${requirements.words} requirements words against ${cap}`),
+    )
+  }
 
   if (failures.length > 0) return { emissions: [], failure: failures.join(' ') }
-
-  const cap =
-    report.entryCap === undefined
-      ? 'no entry cap stated'
-      : `a cap of ${report.entryCap}`
-  return {
-    emissions: [info(`${decisions} decisions against ${cap}`)],
-  }
+  return { emissions }
 }
 
 /**

package/src/gate/stages.ts

@@ -6,7 +6,7 @@ import {
   skillPaths,
 } from '@/gate/boundaries'
 import {
-  architectureRecord,
+  canonicalRecords,
   auditSet,
   captureStamps,
   clientCommandCitations,
@@ -346,11 +346,11 @@ export const STAGES: readonly Stage[] = [
     success: 'Context citations resolve',
   },
   {
-    // The record's three rules are facts it states about itself, unlike the
+    // Each record's caps are facts it states about itself, unlike the
     // judgment thresholds the stage above leaves out, so they gate here.
-    id: 'architecture-record',
-    label: 'Architecture record',
-    checks: [{ kind: 'measure', measure: architectureRecord }],
+    id: 'canonical-records',
+    label: 'Canonical records',
+    checks: [{ kind: 'measure', measure: canonicalRecords }],
   },
   {
     // Unscoped, since any branch can grow any document. A document past the