@erclx/canon 5.16.0 → 5.18.0

package/src/commands/context.ts

@@ -24,8 +24,10 @@ import {
   coveredCount,
   isOverCount,
   isOverLength,
+  isOverRisks,
   measureArchitecture,
   missingRevisit,
+  overWords,
   testableCount,
 } from '@/context/architecture'
 import { auditCitations, type CitationReport } from '@/context/citations'
@@ -56,6 +58,12 @@ import {
   resolveFolders,
 } from '@/context/folders'
 import { isGating } from '@/context/gate'
+import {
+  isOverWordCap,
+  measureRequirements,
+  requirementsRel,
+  type RequirementsReport,
+} from '@/context/requirements'
 import { auditIndexes, type FolderDrift } from '@/context/index-drift'
 import {
   measureWireframeFolder,
@@ -96,7 +104,7 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report required sections, entry length, citations, reference form, catalog tables, provenance, index drift, the architecture record against its own ceiling, its own entry cap, and its word weight, and wireframe states against their evidence folders',
+      'Report required sections, entry length, citations, reference form, catalog tables, provenance, index drift, the architecture record against its own ceiling, entry cap, word cap, and risk cap, the requirements record against its own word cap, and wireframe states against their evidence folders',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -125,8 +133,10 @@ export function register(program: Command): void {
         'measures it. A record stating an entry cap gates the same way when',
         'it holds more decisions than the cap, and a record stating that',
         'every decision closes with a revisit sentence gates when one lacks',
-        'it. A record stating none of the three is reported and never',
-        'gated. --gate widens the gate to the other two',
+        'it. A record stating a word cap a decision or a risk bullet cap',
+        'gates past either, and a requirements record stating a word cap',
+        'gates past it. A record stating none of these is reported and',
+        'never gated. --gate widens the gate to the other two',
         'findings that are facts rather than judgments: a missing required',
         'section and index drift. A context entry requires Overview and',
         'Layout, and a wireframe requires Regions, States, Copy, and Not on',
@@ -658,6 +668,7 @@ async function runAudit(
   // record. A run that never looked and a project with nothing to look at are
   // different answers, and one value for both reports the second as the first.
   const record = gateOnly ? undefined : await measureArchitecture(root)
+  const requirements = gateOnly ? undefined : await measureRequirements(root)
   const wireframes = gateOnly
     ? []
     : (
@@ -681,6 +692,7 @@ async function runAudit(
     reportProvenance(entries, folders)
     reportDrift(drift)
     reportRecord(record, root)
+    reportRequirements(requirements, root)
     reportWireframeStates(wireframes)
     outro()
   }
@@ -719,6 +731,8 @@ async function runAudit(
         // target that never wrote one is entitled to. Absent says the run
         // never looked, which is `--citations-only`.
         architecture: gateOnly ? undefined : (record ?? null),
+        // The same three states for the requirements record.
+        requirements: gateOnly ? undefined : (requirements ?? null),
         // Absent under `--citations-only`, for the same reason as above. An
         // empty array under the ordinary run says the project carries no
         // wireframes folder or no entry carrying a States table, which is a
@@ -744,6 +758,10 @@ async function runAudit(
     recordOverCount: record !== undefined && isOverCount(record),
     recordMissingRevisit:
       record !== undefined && missingRevisit(record).length > 0,
+    recordOverWords: record !== undefined && overWords(record).length > 0,
+    recordOverRisks: record !== undefined && isOverRisks(record),
+    requirementsOverWords:
+      requirements !== undefined && isOverWordCap(requirements),
     sections,
     drift,
     wireframes,
@@ -1152,11 +1170,44 @@ function reportRecord(
   const { allowances } = report
 
   logInfo(
-    `${plural(report.words, 'word')} across ${plural(report.lines, 'line')}, read alongside the weight judgment a session makes by reading the file. This never gates.`,
+    `${plural(report.words, 'word')} across ${plural(report.lines, 'line')}. The whole file's count never gates.`,
   )
   if (report.risksWords !== undefined) {
     logInfo(
-      `\`## Risks / open questions\` holds ${plural(report.risksWords, 'word')}, weighed the same way and read alongside the same judgment.`,
+      `\`## Risks / open questions\` holds ${plural(report.risksWords, 'word')}.`,
+    )
+  }
+
+  const longDecisions = overWords(report)
+  if (report.wordCap === undefined) {
+    logInfo(
+      'No word cap a decision stated, so each decision word count is reported and never gated.',
+    )
+  } else if (longDecisions.length > 0) {
+    for (const entry of longDecisions) {
+      logError(
+        `"${entry.heading}" holds ${entry.words} words against a cap of ${report.wordCap} a decision.`,
+      )
+    }
+  } else {
+    logInfo(
+      `Every decision fits the cap of ${report.wordCap} words a decision.`,
+    )
+  }
+
+  if (report.riskCap === undefined) {
+    logInfo('No risk bullet cap stated, so the Risks section is never gated.')
+  } else if (report.risksBullets === undefined) {
+    logWarn(
+      `The record states a cap of ${report.riskCap} risk bullets and carries no \`## Risks / open questions\` section to count.`,
+    )
+  } else if (isOverRisks(report)) {
+    logError(
+      `${plural(report.risksBullets, 'risk bullet')} against a cap of ${report.riskCap}, nested bullets counted.`,
+    )
+  } else {
+    logInfo(
+      `${plural(report.risksBullets, 'risk bullet')} against a cap of ${report.riskCap}, nested bullets counted.`,
     )
   }
 
@@ -1257,6 +1308,35 @@ function reportRecord(
   )
 }
 
+/** Reports the requirements record against the word cap it states, if any. */
+function reportRequirements(
+  report: RequirementsReport | undefined,
+  root: string,
+): void {
+  logStep('Requirements record')
+
+  if (report === undefined) {
+    logInfo(
+      `Out of scope. The project carries no ${requirementsRel(root)}, so there was no record to measure.`,
+    )
+    return
+  }
+
+  if (report.wordCap === undefined) {
+    logInfo(
+      `${plural(report.words, 'word')} in ${report.rel} and no word cap stated, so the count is reported and never gated.`,
+    )
+  } else if (isOverWordCap(report)) {
+    logError(
+      `${plural(report.words, 'word')} against a cap of ${report.wordCap} in ${report.rel}.`,
+    )
+  } else {
+    logInfo(
+      `${plural(report.words, 'word')} against a cap of ${report.wordCap} in ${report.rel}.`,
+    )
+  }
+}
+
 function reportDrift(drift: readonly FolderDrift[]): void {
   logStep('Index drift')
 

package/src/commands/demo.ts

@@ -333,6 +333,7 @@ async function runDrive(planPath: string, opts: RunOptions): Promise<number> {
 
   if (result.videoPath) logInfo(display(result.videoPath))
   if (result.stillPath) logInfo(`${display(result.stillPath)}  still`)
+  if (result.timelinePath) logInfo(`${display(result.timelinePath)}  timeline`)
   logInfo(
     `${result.steps} steps in ${Math.round(result.durationMs / 100) / 10}s`,
   )
@@ -380,6 +381,7 @@ async function runDrive(planPath: string, opts: RunOptions): Promise<number> {
     mp4: mp4Path ?? null,
     gif: gifPath ?? null,
     still: result.stillPath ?? null,
+    timeline: result.timelinePath ?? null,
     steps: result.steps,
     durationMs: result.durationMs,
     ...(mp4Reason ? { mp4Reason } : {}),

package/src/commands/teach.ts

@@ -237,7 +237,9 @@ export function register(program: Command): void {
         'only place a later session reads that from.',
         '',
         'A URL already listed under either heading is refused rather than',
-        'repeated, because two entries split what rests on one source.',
+        'repeated, because two entries split what rests on one source. The one',
+        'exception is a --read URL listed under Leads, which moves to Read under',
+        'its new title.',
         '',
         'Examples:',
         '  canon teach resource regular-expressions --read "MDN regular expressions=https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions"',

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