@erclx/canon 5.31.0 → 5.32.0

package/src/context/wireframe-states.ts

@@ -1,238 +0,0 @@
-import { readFile, readdir, stat } from 'node:fs/promises'
-import { basename, dirname, join, relative } from 'node:path'
-import type { AuditedFolder } from '@/context/folders'
-import { type BodyLine, bodyLines } from '@/markdown/scan'
-
-/** `standards/wireframes.md`'s `## States` heading, matched by text alone. */
-const STATES_HEADING = /^##\s+States\s*$/i
-const SECTION_HEADING = /^##\s+\S/
-const TABLE_ROW = /^\s*\|/
-const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
-
-/** The one exception the standard admits to the states/evidence bijection. */
-const NOT_CAPTURED = 'not captured'
-
-/** A fenced block's opening delimiter naming the `plaintext` info string. */
-const PLAINTEXT_FENCE = /^`{3,}\s*plaintext\s*$/i
-
-export interface StateRow {
-  readonly line: number
-  readonly state: string
-  /** The evidence cell as written, backticks and all. */
-  readonly evidence: string
-}
-
-export interface MissingFolderFinding {
-  readonly line: number
-  readonly state: string
-  /** The cited path, so a report names what to go create or fix. */
-  readonly path: string
-}
-
-export interface UnlistedFolderFinding {
-  /** The evidence root the folder sits under, cited by at least one row. */
-  readonly root: string
-  readonly folder: string
-}
-
-export interface WireframeStatesReport {
-  readonly rel: string
-  readonly rows: readonly StateRow[]
-  /** A row whose evidence cell names a path with no folder at it. */
-  readonly missingFolders: readonly MissingFolderFinding[]
-  /** A folder under a cited root that no row names. */
-  readonly unlistedFolders: readonly UnlistedFolderFinding[]
-  /** Line of the `plaintext` fence, absent from an entry carrying no sketch. */
-  readonly sketchLine?: number
-  /** Whether that sketch sits beside a state whose evidence already exists. */
-  readonly sketchWithEvidence: boolean
-}
-
-function cells(row: string): string[] {
-  const parts = row.split('|')
-  if ((parts[0] ?? '').trim() === '') parts.shift()
-  if ((parts[parts.length - 1] ?? '').trim() === '') parts.pop()
-  return parts.map((cell) => cell.trim())
-}
-
-function columnIndex(headers: readonly string[], name: string): number {
-  return headers.findIndex(
-    (header) => header.toLowerCase() === name.toLowerCase(),
-  )
-}
-
-/**
- * Reads the States table under the `## States` heading, matching its `State`
- * and `Evidence` columns by header text rather than position.
- *
- * Column order is the one part of the standard's own table the standard could
- * still move during its own review, per the plan this ships under. Matching
- * position would break silently on a reorder, where matching text breaks the
- * same way a renamed header would: visibly, by finding nothing.
- */
-export function parseStatesTable(lines: readonly BodyLine[]): StateRow[] {
-  let index = 0
-  while (index < lines.length && !STATES_HEADING.test(lines[index].text)) {
-    index++
-  }
-  if (index >= lines.length) return []
-  index++
-
-  while (index < lines.length && !SECTION_HEADING.test(lines[index].text)) {
-    const separator = lines[index + 1]
-    if (
-      TABLE_ROW.test(lines[index].text) &&
-      separator !== undefined &&
-      TABLE_SEPARATOR.test(separator.text)
-    ) {
-      break
-    }
-    index++
-  }
-  if (
-    index >= lines.length ||
-    SECTION_HEADING.test(lines[index].text) ||
-    !TABLE_ROW.test(lines[index].text)
-  ) {
-    return []
-  }
-
-  const headers = cells(lines[index].text)
-  const stateCol = columnIndex(headers, 'State')
-  const evidenceCol = columnIndex(headers, 'Evidence')
-  if (stateCol === -1 || evidenceCol === -1) return []
-
-  index += 2
-  const rows: StateRow[] = []
-  while (index < lines.length && TABLE_ROW.test(lines[index].text)) {
-    const row = cells(lines[index].text)
-    rows.push({
-      line: lines[index].number,
-      state: row[stateCol] ?? '',
-      evidence: row[evidenceCol] ?? '',
-    })
-    index++
-  }
-
-  return rows
-}
-
-/** Line of the first `plaintext`-fenced sketch, or nothing. */
-export function findSketchLine(lines: readonly BodyLine[]): number | undefined {
-  for (const line of lines) {
-    if (PLAINTEXT_FENCE.test(line.text.trim())) return line.number
-  }
-  return undefined
-}
-
-/**
- * Reads an evidence cell into the path it cites, or nothing for the one cell
- * value the standard exempts from having one.
- */
-function evidencePath(cell: string): string | undefined {
-  const stripped = cell.replace(/^`+|`+$/g, '').trim()
-  if (stripped.toLowerCase() === NOT_CAPTURED) return undefined
-  return stripped.replace(/\/+$/, '')
-}
-
-async function isDirectory(path: string): Promise<boolean> {
-  try {
-    return (await stat(path)).isDirectory()
-  } catch {
-    return false
-  }
-}
-
-async function subfolders(path: string): Promise<string[]> {
-  try {
-    const entries = await readdir(path, { withFileTypes: true })
-    return entries
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name)
-  } catch {
-    return []
-  }
-}
-
-/**
- * Measures one wireframe entry against its own States table.
- *
- * The evidence cell resolves as the literal path it names against `root`,
- * per the plan's operator answer, since the standard puts the path there and a
- * root guessed from convention reads wrong in a monorepo carrying more than
- * one evidence tree.
- *
- * An unlisted folder is reported only under a root at least one row already
- * cites, per the same operator answer, so a project holding evidence with no
- * states table at all reports nothing. `roots` is built from the rows this
- * loop already resolved rather than scanned separately, which is what keeps
- * the two readings in the same pass.
- */
-export async function measureWireframeStates(
-  root: string,
-  rel: string,
-  source: string,
-): Promise<WireframeStatesReport> {
-  const lines = bodyLines(source)
-  const rows = parseStatesTable(lines)
-  const sketchLine = findSketchLine(lines)
-
-  const missingFolders: MissingFolderFinding[] = []
-  const cited = new Map<string, Set<string>>()
-  let anyCaptured = false
-
-  for (const row of rows) {
-    const path = evidencePath(row.evidence)
-    if (path === undefined) continue
-
-    if (!(await isDirectory(join(root, path)))) {
-      missingFolders.push({ line: row.line, state: row.state, path })
-      continue
-    }
-
-    anyCaptured = true
-    const evidenceRoot = dirname(path)
-    const folder = basename(path)
-    const named = cited.get(evidenceRoot) ?? new Set<string>()
-    named.add(folder)
-    cited.set(evidenceRoot, named)
-  }
-
-  const unlistedFolders: UnlistedFolderFinding[] = []
-  for (const [evidenceRoot, named] of cited) {
-    for (const folder of await subfolders(join(root, evidenceRoot))) {
-      if (!named.has(folder)) {
-        unlistedFolders.push({ root: evidenceRoot, folder })
-      }
-    }
-  }
-
-  return {
-    rel,
-    rows,
-    missingFolders,
-    unlistedFolders,
-    ...(sketchLine !== undefined && { sketchLine }),
-    sketchWithEvidence: sketchLine !== undefined && anyCaptured,
-  }
-}
-
-/** Measures every wireframe entry in a resolved `wireframes` folder. */
-export async function measureWireframeFolder(
-  root: string,
-  folder: AuditedFolder,
-): Promise<WireframeStatesReport[]> {
-  const reports: WireframeStatesReport[] = []
-
-  for (const path of folder.entries) {
-    reports.push(
-      await measureWireframeStates(
-        root,
-        relative(root, path),
-        await readFile(path, 'utf8'),
-      ),
-    )
-  }
-
-  return reports
-}

package/src/repo/metadata.ts

@@ -1,206 +0,0 @@
-import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
-
-/**
- * What this run can compute from the tree alone. A field stays absent rather
- * than empty when nothing local resolves it, so a caller never reads
- * "nothing to propose" as "propose removing what is already there."
- */
-export interface MetadataProposal {
-  readonly description?: string
-  readonly homepage?: string
-  readonly topics?: readonly string[]
-}
-
-/** What the remote already carries, read by the caller rather than here. */
-export interface CurrentMetadata {
-  readonly description: string
-  readonly homepage: string
-  readonly topics: readonly string[]
-}
-
-export interface MetadataDiff {
-  readonly description?: { readonly current: string; readonly proposed: string }
-  readonly homepage?: { readonly current: string; readonly proposed: string }
-  readonly topics?: {
-    readonly added: readonly string[]
-    readonly removed: readonly string[]
-  }
-}
-
-/** GitHub's own cap on the About field. */
-const MAX_DESCRIPTION_LENGTH = 350
-
-/** GitHub's own cap on topics per repository. */
-const MAX_TOPICS = 20
-
-/** GitHub's own shape for a topic: lowercase, alphanumeric, internal hyphens. */
-const TOPIC_PATTERN = /^[a-z0-9][a-z0-9-]*$/
-
-/**
- * Whether an already-trimmed, already-lowercased string is a shape GitHub
- * accepts as a topic. Exported so a caller validating an operator-supplied
- * topic list checks against the same rule this reader silently filters
- * `package.json`'s `keywords` through, rather than reimplementing it against
- * a looser test such as non-emptiness alone.
- */
-export function isValidTopic(topic: string): boolean {
-  return TOPIC_PATTERN.test(topic)
-}
-
-/**
- * A bare image, or an image wrapped in a link, which is the shape a shields.io
- * badge takes. The wrapped alternative goes first, since the bare form would
- * otherwise match its inner image alone and leave the wrapping link behind.
- */
-const BADGE_TOKEN = /\[!\[[^\]]*\]\([^)]*\)\]\([^)]*\)|!\[[^\]]*\]\([^)]*\)/g
-
-/** True once every badge token is stripped and nothing remains. */
-function isBadgeLine(line: string): boolean {
-  return line.replace(BADGE_TOKEN, '').trim() === ''
-}
-
-function stripInlineMarkdown(line: string): string {
-  return line
-    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
-    .replace(/(\*\*|__)(.+?)\1/g, '$2')
-    .replace(/(\*|_|`)(.+?)\1/g, '$2')
-    .trim()
-}
-
-/**
- * The first prose line past the title and any badge row, stripped of inline
- * markdown and capped at GitHub's About field length.
- *
- * `undefined` only when the file carries nothing past its title and badges,
- * per the skill requirement's refusal boundary: a resolvable line that reads
- * as a title rather than a sentence is still proposed, since rejecting it is
- * a judgment for the person reading the proposal rather than for this reader.
- */
-export function extractOpeningLine(readme: string): string | undefined {
-  for (const raw of readme.split('\n')) {
-    const line = raw.trim()
-    if (line === '' || line.startsWith('#') || isBadgeLine(line)) continue
-
-    const stripped = stripInlineMarkdown(line)
-    if (stripped === '') continue
-
-    return stripped.length > MAX_DESCRIPTION_LENGTH
-      ? `${stripped.slice(0, MAX_DESCRIPTION_LENGTH - 1)}…`
-      : stripped
-  }
-  return undefined
-}
-
-/**
- * `package.json`'s `keywords` read as candidate topics, the field the wider
- * npm ecosystem already uses for this. Invalid entries are dropped silently
- * rather than refused, since a manifest mixing free-text keywords with
- * topic-shaped ones is ordinary and only the shaped half transfers.
- */
-function readTopics(keywords: unknown): readonly string[] | undefined {
-  if (!Array.isArray(keywords)) return undefined
-
-  const topics = new Set<string>()
-  for (const entry of keywords) {
-    if (typeof entry !== 'string') continue
-    const topic = entry.trim().toLowerCase()
-    if (isValidTopic(topic)) topics.add(topic)
-    if (topics.size === MAX_TOPICS) break
-  }
-  return [...topics]
-}
-
-interface PackageFields {
-  readonly homepage?: unknown
-  readonly keywords?: unknown
-}
-
-async function readManifest(root: string): Promise<PackageFields | undefined> {
-  try {
-    const parsed: unknown = JSON.parse(
-      await readFile(join(root, 'package.json'), 'utf8'),
-    )
-    return (parsed ?? undefined) as PackageFields | undefined
-  } catch {
-    return undefined
-  }
-}
-
-/**
- * Computes what this tree can propose for its own repository metadata, with
- * no network call: an About text from the README's opening line, and a
- * homepage and a topic set from `package.json`, the one manifest every
- * target project this ships to already carries.
- *
- * A field a target project declares nowhere stays absent rather than empty,
- * so the caller comparing this against the remote never treats a field this
- * reader has no opinion on as a proposal to clear it.
- */
-export async function proposeMetadata(root: string): Promise<MetadataProposal> {
-  const [readme, manifest] = await Promise.all([
-    readFile(join(root, 'README.md'), 'utf8').catch(() => undefined),
-    readManifest(root),
-  ])
-
-  const description =
-    readme === undefined ? undefined : extractOpeningLine(readme)
-
-  const homepage =
-    typeof manifest?.homepage === 'string' && manifest.homepage.trim() !== ''
-      ? manifest.homepage.trim()
-      : undefined
-
-  const topics = readTopics(manifest?.keywords)
-
-  return {
-    ...(description !== undefined && { description }),
-    ...(homepage !== undefined && { homepage }),
-    ...(topics !== undefined && topics.length > 0 && { topics }),
-  }
-}
-
-/**
- * Compares a computed proposal against what the remote already carries.
- *
- * A field the proposal has no opinion on is never diffed, which is what
- * keeps a target project with no `keywords` field from seeing every existing
- * topic reported as a removal.
- */
-export function compareMetadata(
-  current: CurrentMetadata,
-  proposed: MetadataProposal,
-): MetadataDiff {
-  const diff: {
-    description?: { current: string; proposed: string }
-    homepage?: { current: string; proposed: string }
-    topics?: { added: readonly string[]; removed: readonly string[] }
-  } = {}
-
-  if (
-    proposed.description !== undefined &&
-    proposed.description !== current.description
-  ) {
-    diff.description = {
-      current: current.description,
-      proposed: proposed.description,
-    }
-  }
-
-  if (
-    proposed.homepage !== undefined &&
-    proposed.homepage !== current.homepage
-  ) {
-    diff.homepage = { current: current.homepage, proposed: proposed.homepage }
-  }
-
-  if (proposed.topics !== undefined) {
-    const currentSet = new Set(current.topics)
-    const proposedSet = new Set(proposed.topics)
-    const added = proposed.topics.filter((topic) => !currentSet.has(topic))
-    const removed = current.topics.filter((topic) => !proposedSet.has(topic))
-    if (added.length > 0 || removed.length > 0) diff.topics = { added, removed }
-  }
-
-  return diff
-}

package/standards/architecture.md

@@ -1,127 +0,0 @@
----
-title: Architecture reference
-description: Shape and content rules for canon/ARCHITECTURE.md
-paths:
-  - 'canon/ARCHITECTURE.md'
-rule:
-  - "Add a decision here only when it fills one of the standard's slots, and write any other decision into the context entry for the domain it constrains. At the record's stated cap, merge or retire an entry before adding one."
----
-
-# Architecture reference
-
-Applies to `canon/ARCHITECTURE.md`. Describes the system shape and the decisions behind it, not a tutorial, setup guide, or implementation walkthrough. Pair it with `CLAUDE.md`: session behavior lives there, and the system's shape lives here. Update when a decision is made or a risk is resolved.
-
-## Scope
-
-Governs the system-shape document at `canon/ARCHITECTURE.md`: the overview, the decision entries, and the open risks.
-
-Does not govern:
-
-- Per-domain structure and narrative: `context.md`
-- Setup commands and install instructions: `readme.md`
-- Product scope, goals, and non-goals: `requirements.md`
-
-## What goes in
-
-- A high-level overview of how the system is structured and why
-- Key technical decisions as named H3 entries, each filling one of the five slots below: what was chosen and why over the alternatives
-- Risks and open questions still unresolved
-
-A decision belongs here only when it fills a slot:
-
-- Stack and runtime: the language, the runtime, and the major libraries the system is built on
-- Delivery: how the system's content or code reaches the place it runs
-- Enforced boundaries: a boundary the system checks mechanically, and what enforces it
-- Layout: how the project's top-level roots and context tiers divide what they hold
-- Build principles: a rule for how a behavior is built that changes work in more than one domain, stated in one sentence
-
-The slots come from a scale test. Ask whether the decision would still be in this file if the project were ten times its size. At that size an always-loaded file holding one entry per decision fits no context window, and what survives is the shape: the stack, the delivery, the boundaries, the layout, and the principles. A decision that fits no slot is a domain decision, and its home is that domain's `canon/context/<domain>.md` entry under `## Decisions`, however many domains its reasoning touches. Reach is not the test, since nearly every decision reaches a second domain.
-
-## What does not go in
-
-- How individual functions work line by line. The code carries its own behavior.
-- Full type definitions. They live in code. Reference the shape conceptually if needed.
-- A decision that fills no slot. It lives in the domain context entry it constrains, and this file carries at most one line pointing at it.
-- A measurement paragraph specific to one domain's own mechanism, even behind a slot decision. Route it to that domain's context entry and keep the choice, the alternative that lost, and one reason here.
-- The instances of a build principle. The principle takes one sentence here, and each instance lives in the domain entry where it applies.
-- The history of how a decision was reached or revised: rounds of candidates, a figure followed by its correction, a branch or change that moved a number. Cut it. Git and the change that introduced it keep the trail.
-
-## Sections
-
-Use `## Overview`, `## Key technical decisions` with one named H3 per decision, and `## Risks / open questions`. Name each decision and give the reasoning, especially for non-obvious choices. Skip entries where the rationale is self-evident.
-
-## Keeping it current
-
-- Rewrite a decision a later one changed rather than appending the change beside it. A reader should find the design that stands in one place, with the alternative that lost stated once.
-- Hold only what is open under `## Risks / open questions`. An entry leaves the section in the change that settles it, becoming a decision here when it fills a slot and moving to the domain context entry it constrains when it does not.
-- Carry an optional `reviewed: YYYY-MM-DD` frontmatter field naming the day someone last read the record whole for drift. Whoever finishes that review sets it as the review's last edit, and `canon records stale canonical` reads it to count the releases shipped since. A record with no field reads as never reviewed.
-
-## Verification anchors
-
-A decision's reasoning stays correct while the numbers it cites move. The anchor records what a measured claim was read against, so a reader can tell a number that was checked and held from one nobody has looked at since.
-
-- Close a decision entry whose reasoning cites a measured number with a trailing sentence naming the short commit SHA and the ISO date that number was read: `Measured at <short-sha> on <YYYY-MM-DD>.`
-- Name a commit, never a pull request number or a branch. A branch is gone after merge, and a pull request number resolves only on the forge.
-- Carry one anchor per figure. When a number is re-measured, rewrite the number and its anchor in place, and leave the old value to the change that moved it.
-- Point at a generated file that already records a figure and its commit, rather than copying the figure and anchoring the copy.
-- Anchor on the number alone. A decision citing none takes no anchor whatever its reasoning rests on, because a marker over a claim nobody can re-measure is one no reader can falsify.
-- Anchor a decision when writing it or when amending its reasoning. Leave an entry written before the rule unanchored rather than dating it by blame, which is archaeology for a marker nothing reads back.
-- Read an absent anchor as unchecked rather than as current. On an entry citing no number there is nothing to check. On one citing a number the number is due a read.
-- Do not edit a claim in the pass that first anchors it. The anchor states what the claim was measured against, so changing both at once leaves nothing to check the anchor against.
-- Refresh the anchor whenever the number is re-read, whether or not it moved. A confirmed number and an unread one are the same text without the date.
-
-## Revisit condition
-
-A decision says why it won and rarely says when that reason stops holding, so an entry can go stale while every word in it stays true. The revisit sentence names the finding that would show the harm the decision prevents has gone or moved.
-
-- Close each decision with one sentence of the form `Revisit when <finding>.` Name something a reader could notice, such as a platform release, a measured count crossing a line, or a dependency dropping a behavior.
-- Draft it from the harm the decision prevents, never from the mechanism it uses. A mechanism can keep working long after the reason for choosing it is gone, so re-checking it confirms the wrong fact.
-- Place the sentence after the reasoning and before any verification anchor, so the anchor stays the entry's last sentence.
-- Give a heading holding several principles one sentence, for the premise they share, rather than one per principle.
-- Adopt the requirement by stating the clause `Every decision closes with a revisit sentence.` in the record itself. The clause is the record's own, like the caps, so a checker reads it from the file and gates only a record that states it. A record stating none is reported and never gated.
-- A checker reads presence alone. A vacuous sentence passes it, so the sentence is only as useful as the finding it names.
-
-## Caps
-
-Every session pays for this file before any work starts, so a heavy read is a real cost. Weight comes from two places, too many decisions and decisions written too long, so the record caps both, and caps the open risks beside them.
-
-- State each cap in the record itself. A checker reads only these spellings, so a clause worded another way is reported and never gated:
-  - `This record holds at most <n> decisions.`
-  - `at most <n> words a decision`, counting a decision's prose below its heading, fenced lines left out
-  - `at most <n> risk bullets`, counting every list item under `## Risks / open questions`, nested ones included
-- The three can share one sentence, such as `This record holds at most 12 decisions, at most 150 words a decision, and at most 6 risk bullets.` Each cap is the record's own, so a record stating none is measured and never gated. The template and the seed a new project installs state all three, and a project loosens one by editing the number in its own record.
-- Set the decision cap near one decision per slot plus a small margin, the word cap near what one trade takes to state, about 150, and the risk cap at what a reader holds in mind at once, about 6.
-- At the decision cap, merge two decisions or retire one before adding another, and name which in the change that does it. Never pack two decisions under one heading, which the count cannot see.
-- At the word cap, cut a decision to the choice, the alternative that lost, the reason, and the revisit sentence. What it sheds is a mechanism or a measurement, which goes to the domain context entry it constrains, never under a second heading.
-- At the risk cap, drop what is no longer open before adding a risk.
-- Retire a decision by moving it to the domain context entry it constrains, not by deleting its reasoning.
-- The whole file's word count stays a report, read alongside the judgment, and never gates.
-- Yield to the paragraph weight checkpoint in `markdown.md`. A paragraph past the checkpoint is a defect no length guideline licenses.
-
-## Template
-
-The revisit sentence closes the reasoning of every decision. The anchor sentence follows it on a decision whose reasoning cites a measured number and is absent from one that cites none. Each heading below names a slot, so a record starts with one decision per slot and renames each heading to the choice it records.
-
-```markdown
-# Architecture
-
-## Overview
-
-This record holds at most 12 decisions, at most 150 words a decision, and at most 6 risk bullets. Every decision closes with a revisit sentence.
-
-## Key technical decisions
-
-### Stack and runtime
-
-What was chosen, the alternative that lost, and why. Revisit when <finding>. Measured at <short-sha> on <YYYY-MM-DD>.
-
-### Delivery
-
-### Enforced boundaries
-
-### Layout
-
-### Build principles
-
-## Risks / open questions
-```