@erclx/canon 5.31.0 → 5.33.0

package/src/context/architecture.ts

@@ -1,654 +0,0 @@
-import { access, readFile } from 'node:fs/promises'
-import { join, relative } from 'node:path'
-import { AUDITS } from '@/audits/catalog'
-import { type BodyLine, bodyLines } from '@/markdown/scan'
-import { surfaceDir } from '@/roots/surface'
-
-/**
- * The record this measures, relative to `root`.
- *
- * A function rather than a fixed constant, because the path now resolves at
- * either surface root and a constant naming one of them would be believed to
- * be true of a project that has moved. One fixed name rather than a folder
- * walk otherwise, because the standard governing it names one document, and
- * the length rule this measures is stated by whichever record sits there
- * rather than by the standard or by this file.
- */
-export function architectureRel(root: string): string {
-  return relative(root, surfaceDir(root, 'ARCHITECTURE.md'))
-}
-
-/**
- * The line allowances a record states for itself, absent when it states none.
- *
- * No standard sets a length rule for this document, so the numbers belong to
- * whichever record declares them rather than to the toolkit. Holding a pair in
- * code and gating every project against it audits a target against a rule it
- * never adopted, which is the failure `canResolveAtRoot` already answers on the
- * folder side. A record stating no rule is measured and never gated.
- */
-export interface Allowances {
-  readonly frame: number
-  readonly perDecision: number
-}
-
-/**
- * What a machine could do with the entry's reasoning, which is a candidate
- * rather than a verdict.
- *
- * - `countable`: carries a figure over a tree, so a run could recompute it.
- * - `invariant`: quantifies over a named tree, so a walk could falsify it.
- * - `neither`: says why a choice was made, which nothing tests.
- */
-export type ClaimKind = 'countable' | 'invariant' | 'neither'
-
-export interface DecisionReport {
-  readonly heading: string
-  /** Line of the `###` heading, so a report line opens at the entry. */
-  readonly line: number
-  readonly claim: ClaimKind
-  /** The digit-spelled figures behind a `countable` reading, in order. */
-  readonly figures: readonly string[]
-  /** The first sentence behind an `invariant` reading, absent otherwise. */
-  readonly quantified?: string
-  /**
-   * Executable checks the entry names, which is the only coverage signal the
-   * record carries. Empty on an entry that names none, including one whose
-   * claim some check happens to cover without the entry saying so.
-   */
-  readonly checks: readonly string[]
-  /**
-   * 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
-  /**
-   * Whether a sentence outside code opens with `Revisit when`. Read on every
-   * record and required only by one stating the clause, so a project that
-   * never adopted it sees the reading without failing on it.
-   */
-  readonly revisit: boolean
-}
-
-export interface ArchitectureReport {
-  readonly rel: string
-  readonly lines: number
-  /** The whole record's word count, reported for the same reason. */
-  readonly words: number
-  /**
-   * Word count of the `## Risks / open questions` section, absent when the
-   * record carries no such heading. The standard asks that section to hold
-   * 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. */
-  readonly ceiling?: number
-  /**
-   * The most decisions the record says it holds, absent when it states no
-   * cap. Declared by the record for the reason the allowances are, so a
-   * 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
-   * that never wrote the clause is reported and never gated.
-   */
-  readonly revisitRequired: boolean
-  readonly decisions: readonly DecisionReport[]
-}
-
-const DECISION_HEADING = /^###\s+(.+?)\s*$/
-const SECTION_HEADING = /^##\s+\S/
-/** 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. */
-const ISO_DATE = /\b\d{4}-\d{2}-\d{2}\b/g
-const FIGURE = /\b\d+(?:,\d{3})*\b/g
-const SENTENCE_SPLIT = /(?<=[.])\s+/
-
-/** A code span naming a path, which is what a quantifier has to govern. */
-const PATH_SPAN = String.raw`\`[^\`]*(?:/|\.md|\.ts|\.sh|\.json)[^\`]*\``
-const QUANTIFIER = String.raw`\b(?:every|each|no|nothing|any|all|never|only)\b`
-/** Six words is the widest gap the corpus puts between the two. */
-const WINDOW = String.raw`(?:\s+\S+){0,6}?\s+`
-
-const QUANTIFIES_PATH = new RegExp(
-  `${QUANTIFIER}${WINDOW}${PATH_SPAN}|${PATH_SPAN}${WINDOW}${QUANTIFIER}`,
-  'i',
-)
-
-/**
- * A code span naming a check this repository could run: a shell script, or a
- * gate module whose measures read the tree in-process.
- */
-const SCRIPT_SPAN = /^(?:scripts\/[\w./-]+\.sh|src\/gate\/[\w./-]+\.ts)$/
-/** A code span invoking the CLI, which may or may not name a registered audit. */
-const CANON_SPAN = /^canon\s+(.+)$/
-
-/**
- * The audit invocations a decision could name, spelled as a reader writes them.
- *
- * Read off the catalog rather than listed, so a verb renamed at its source
- * stops matching here instead of going on matching a string nobody maintains.
- */
-const AUDIT_INVOCATIONS: readonly string[] = AUDITS.map((audit) =>
-  audit.argv.filter((arg) => arg !== '--json').join(' '),
-)
-
-function codeSpans(text: string): string[] {
-  return (text.match(CODE_SPAN) ?? []).map((span) => span.slice(1, -1))
-}
-
-/**
- * Names the executable checks an entry spells.
- *
- * A script has to exist on disk and a `canon` invocation has to match a
- * registered audit, because an entry naming a check that was removed is an
- * uncovered claim wearing a covered one's words.
- */
-async function namedChecks(root: string, body: string): Promise<string[]> {
-  const spans = [...new Set(codeSpans(body))]
-
-  const verbs = spans.filter((span) => {
-    const invocation = span.match(CANON_SPAN)?.[1]
-    return invocation !== undefined && AUDIT_INVOCATIONS.includes(invocation)
-  })
-
-  const scripts = spans.filter((span) => SCRIPT_SPAN.test(span))
-  const present = await Promise.all(
-    scripts.map((span) =>
-      access(join(root, span)).then(
-        () => true,
-        () => false,
-      ),
-    ),
-  )
-
-  return [...verbs, ...scripts.filter((_, index) => present[index])]
-}
-
-/**
- * Reads the figures a decision carries, which is the countable-claim signal.
- *
- * Digits alone. A cardinal spelled in words reads as pronominal far more often
- * than as measured in this corpus, where "the alternative and it is one nobody
- * passes" outnumbers "eleven copies", and admitting the spelled form classified
- * 22 of 24 entries as countable, which distinguishes nothing. The cost is that
- * a measured claim written in words reads as uncounted, which the report says.
- */
-function figuresIn(body: string): string[] {
-  return body.replace(ISO_DATE, ' ').replace(CODE_SPAN, ' ').match(FIGURE) ?? []
-}
-
-/**
- * The first sentence quantifying over a named tree, or undefined.
- *
- * The quantifier has to sit within a short window of the path so a sentence
- * mentioning both without relating them does not read as a claim about the
- * tree. Both orders are matched, since the corpus writes the property before
- * the path as readily as after it.
- */
-function quantifiedSentence(body: string): string | undefined {
-  return body
-    .replace(ISO_DATE, ' ')
-    .split(SENTENCE_SPLIT)
-    .map((sentence) => sentence.replace(/\n/g, ' ').trim())
-    .find((sentence) => QUANTIFIES_PATH.test(sentence))
-}
-
-/**
- * Classifies one entry, with the countable reading taking precedence.
- *
- * An entry carrying both a figure and a quantified tree is recomputable, which
- * is the stronger test, and the two readings are reported as one kind because
- * the coverage split a reader wants is testable against unverifiable rather
- * than a per-entry inventory of every claim in it.
- */
-export function classifyDecision(body: string): {
-  claim: ClaimKind
-  figures: string[]
-  quantified?: string
-} {
-  const figures = figuresIn(body)
-  if (figures.length > 0) return { claim: 'countable', figures }
-
-  const quantified = quantifiedSentence(body)
-  if (quantified !== undefined) {
-    return { claim: 'invariant', figures: [], quantified }
-  }
-
-  return { claim: 'neither', figures: [] }
-}
-
-interface RawDecision {
-  readonly heading: string
-  readonly line: number
-  readonly body: string
-  /** The body with its fenced lines dropped, which is where prose is read. */
-  readonly prose: string
-}
-
-/**
- * Splits the record into its `###` entries.
- *
- * A heading inside a fenced block is skipped, since the seed template shows the
- * shape it asks a project to write and a template entry is not a decision.
- *
- * A heading carrying several decisions counts once, so the total reads low by
- * however many it holds. The report states that rather than parsing for it,
- * because splitting a decision from its heading needs a marker the standard
- * does not ask a record to carry.
- */
-export function splitDecisions(source: string): RawDecision[] {
-  const lines = bodyLines(source)
-  const decisions: RawDecision[] = []
-  let open:
-    | { heading: string; line: number; body: string[]; prose: string[] }
-    | undefined
-
-  const close = (): void => {
-    if (!open) return
-    decisions.push({
-      heading: open.heading,
-      line: open.line,
-      body: open.body.join('\n'),
-      prose: open.prose.join('\n'),
-    })
-  }
-
-  for (const line of lines) {
-    if (line.fenced) {
-      open?.body.push(line.text)
-      continue
-    }
-
-    const heading = line.text.match(DECISION_HEADING)?.[1]
-    if (heading !== undefined) {
-      close()
-      open = { heading, line: line.number, body: [], prose: [] }
-      continue
-    }
-
-    // A decision runs to the next `###` or to the section that follows the
-    // decision list, so the risks below never read as the last entry's body.
-    if (SECTION_HEADING.test(line.text)) {
-      close()
-      open = undefined
-      continue
-    }
-
-    open?.body.push(line.text)
-    open?.prose.push(line.text)
-  }
-
-  close()
-  return decisions
-}
-
-/**
- * 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.
- */
-export function wordCount(text: string): number {
-  return text.match(/\S+/g)?.length ?? 0
-}
-
-/**
- * Extracts the `## Risks / open questions` section, or nothing when the
- * record carries no such heading.
- *
- * The section is read the same way `splitDecisions` reads a decision: capture
- * starts at the heading and stops at the next H2, or at the end of the file
- * when the section is last, which is where the standard's template puts it.
- */
-export function risksSection(source: string): string | undefined {
-  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 bodyLines(source)) {
-    if (line.fenced) {
-      if (capturing) body.push(line)
-      continue
-    }
-
-    if (RISKS_HEADING.test(line.text)) {
-      capturing = true
-      found = true
-      continue
-    }
-
-    if (capturing && SECTION_HEADING.test(line.text)) {
-      capturing = false
-      continue
-    }
-
-    if (capturing) body.push(line)
-  }
-
-  return found ? body : undefined
-}
-
-/** Cardinals a record spells rather than writes, which the corpus does for both. */
-const SPELLED: Record<string, number> = {
-  one: 1,
-  two: 2,
-  three: 3,
-  four: 4,
-  five: 5,
-  six: 6,
-  seven: 7,
-  eight: 8,
-  nine: 9,
-  ten: 10,
-  eleven: 11,
-  twelve: 12,
-  thirteen: 13,
-  fourteen: 14,
-  fifteen: 15,
-  sixteen: 16,
-  seventeen: 17,
-  eighteen: 18,
-  nineteen: 19,
-  twenty: 20,
-}
-
-// Longest first, so `fourteen` is tried ahead of the `four` it starts with.
-const SPELLED_ALTERNATION = Object.keys(SPELLED)
-  .sort((a, b) => b.length - a.length)
-  .join('|')
-const CARDINAL = String.raw`(\d+|${SPELLED_ALTERNATION})`
-const FRAME_CLAUSE = new RegExp(String.raw`${CARDINAL}-line frame`, 'i')
-const PER_DECISION_CLAUSE = new RegExp(
-  String.raw`${CARDINAL}\s+lines?\s+a\s+decision`,
-  'i',
-)
-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
-  const spelled = SPELLED[token.toLowerCase()]
-  if (spelled !== undefined) return spelled
-
-  const digits = Number.parseInt(token, 10)
-  return Number.isNaN(digits) ? undefined : digits
-}
-
-/**
- * Reads the allowances a record declares for itself, or nothing.
- *
- * Both clauses have to be present, because half a formula is not one. A record
- * whose wording drifts past these clauses falls back to reporting rather than
- * to a stale ceiling held here, so the failure is visible in the run's own
- * output instead of gating a project on a rule nobody can point at.
- */
-export function readAllowances(source: string): Allowances | undefined {
-  const frame = readCardinal(source.match(FRAME_CLAUSE)?.[1])
-  const perDecision = readCardinal(source.match(PER_DECISION_CLAUSE)?.[1])
-
-  if (frame === undefined || perDecision === undefined) return undefined
-  return { frame, perDecision }
-}
-
-/**
- * Reads the entry cap a record declares for itself, or nothing.
- *
- * The clause is the record's own, like the allowances above, so a record
- * whose wording drifts past it falls back to reporting rather than to a cap
- * held here that no project wrote.
- */
-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
-/**
- * `Revisit when` opening a sentence: at the start of the text, after a line
- * break, or after a sentence's closing stop. Mid-sentence it is not the
- * sentence the standard asks for.
- */
-const REVISIT_SENTENCE = /(?:^|\n|[.!?]\s+)\s*(?:[-*]\s+)?Revisit when\b/
-
-/**
- * Whether the record states the revisit clause for itself, read off its prose
- * alone so a template quoting the clause inside a fence does not adopt it.
- *
- * The clause is the record's own, like the cap, so wording that drifts past it
- * falls back to reporting rather than to a requirement held here.
- */
-export function readRevisitRule(source: string): boolean {
-  const prose = bodyLines(source)
-    .filter((line) => !line.fenced)
-    .map((line) => line.text)
-    .join('\n')
-    .replace(CODE_SPAN, ' ')
-  return REVISIT_CLAUSE.test(prose)
-}
-
-/**
- * Whether a decision's prose carries a sentence opening `Revisit when`.
- *
- * Presence only, never content, so a vacuous sentence passes. A code span is
- * dropped first, since a standard quoting the form is not stating one.
- */
-export function hasRevisitSentence(prose: string): boolean {
-  return REVISIT_SENTENCE.test(prose.replace(CODE_SPAN, ' '))
-}
-
-/** Whether a read failed because nothing sits at the path. */
-function isMissing(error: unknown): boolean {
-  const code = (error as { code?: unknown }).code
-  return code === 'ENOENT' || code === 'ENOTDIR'
-}
-
-/** The ceiling the record's own formula derives from its decision count. */
-export function ceilingFor(allowances: Allowances, decisions: number): number {
-  return allowances.frame + allowances.perDecision * decisions
-}
-
-/**
- * Measures the record, or reports nothing when the project carries none.
- *
- * Absent rather than empty, for the reason the sibling checks state: a project
- * with no record and one whose record holds no decision are different answers,
- * and a zeroed report reads as the second.
- */
-export async function measureArchitecture(
-  root: string,
-): Promise<ArchitectureReport | undefined> {
-  const rel = architectureRel(root)
-  const path = join(root, rel)
-
-  let source: string
-  try {
-    source = await readFile(path, 'utf8')
-  } catch (error) {
-    // Only a record that is not there reads as absent. A record present and
-    // unreadable propagates the way every sibling reader here lets one
-    // propagate, since swallowing it reports a project with no record and the
-    // length gate passes over a file nobody opened.
-    if (!isMissing(error)) throw error
-    return undefined
-  }
-
-  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(
-    raw.map(async (entry) => {
-      const { claim, figures, quantified } = classifyDecision(entry.body)
-      return {
-        heading: entry.heading,
-        line: entry.line,
-        claim,
-        figures,
-        ...(quantified !== undefined && { quantified }),
-        checks: await namedChecks(root, entry.body),
-        words: wordCount(entry.prose),
-        revisit: hasRevisitSentence(entry.prose),
-      }
-    }),
-  )
-
-  const risks = risksSection(source)
-  const bullets = riskBullets(source)
-
-  return {
-    rel,
-    lines: source.replace(/\n$/, '').split('\n').length,
-    words: wordCount(
-      bodyLines(source)
-        .map((line) => line.text)
-        .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,
-  }
-}
-
-/**
- * Whether the record holds more decisions than the cap it states.
- *
- * False for a record stating no cap, for the reason `isOverLength` gives. The
- * count is by heading, so a heading carrying several decisions counts once,
- * which is the undercount `splitDecisions` already names.
- */
-export function isOverCount(report: ArchitectureReport): boolean {
-  return (
-    report.entryCap !== undefined && report.decisions.length > report.entryCap
-  )
-}
-
-/**
- * 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.
- *
- * Empty for a record stating no clause, for the reason `isOverCount` gives.
- */
-export function missingRevisit(report: ArchitectureReport): string[] {
-  if (!report.revisitRequired) return []
-  return report.decisions
-    .filter((entry) => !entry.revisit)
-    .map((entry) => entry.heading)
-}
-
-/**
- * Whether the record is longer than the ceiling it derives for itself.
- *
- * False for a record declaring no allowances, which has no ceiling to be past.
- * That is the answer rather than a gap, since the length rule is the record's
- * own and a project that never wrote one owes nothing to it.
- */
-export function isOverLength(report: ArchitectureReport): boolean {
-  return report.ceiling !== undefined && report.lines > report.ceiling
-}
-
-/** How many entries carry a claim a machine could test. */
-export function testableCount(report: ArchitectureReport): number {
-  return report.decisions.filter((entry) => entry.claim !== 'neither').length
-}
-
-/** How many testable entries name a check that exists. */
-export function coveredCount(report: ArchitectureReport): number {
-  return report.decisions.filter(
-    (entry) => entry.claim !== 'neither' && entry.checks.length > 0,
-  ).length
-}