@erclx/canon 4.0.0

package/src/inventory/subjects.ts

@@ -0,0 +1,114 @@
+/**
+ * The readers an inventory can run, one per treatment.
+ *
+ * A reader runs inside the page rather than here, so each one is serialized to
+ * source and evaluated by the browser. That is why every helper a reader needs
+ * is declared inside its own body: a reference to anything at module scope
+ * survives typechecking and throws once the page tries to call it.
+ *
+ * `focus` is the first and, for now, the only subject. The four sibling
+ * instruments this shape was lifted from differ only in their element query and
+ * the property they read, which is what makes a subject a row here rather than
+ * a command of its own.
+ */
+
+/** One element as a reader saw it, before any grouping. */
+export interface SubjectReading {
+  readonly selector: string
+  readonly treatment: string
+}
+
+export interface Subject {
+  readonly name: string
+  /** What the listing means, printed above the rows so a count reads correctly. */
+  readonly summary: string
+  readonly read: (query: string) => SubjectReading[]
+}
+
+/**
+ * Reports what each element changes about itself when it takes focus, which is
+ * the reading `governance/rules/ui/410-a11y.md` states three rules against and
+ * nothing measures.
+ *
+ * The difference between rest and focus is the treatment, rather than the
+ * focused style on its own. A card carrying a resting shadow computes a shadow
+ * either way, so reading only the focused state would report a ring on an
+ * element whose appearance never moves.
+ *
+ * An element the browser refuses to focus is named as such rather than folded
+ * into the no-treatment row, since a disabled control and a control with no
+ * ring are different findings with different remedies.
+ */
+function readFocusTreatments(query: string): SubjectReading[] {
+  const PROPERTIES = [
+    'outlineStyle',
+    'outlineWidth',
+    'outlineColor',
+    'outlineOffset',
+    'boxShadow',
+    'borderColor',
+    'backgroundColor',
+    'color',
+  ] as const
+
+  const describe = (element: Element): string => {
+    const tag = element.tagName.toLowerCase()
+    if (element.id) return `${tag}#${element.id}`
+    const className = element.getAttribute('class')?.trim().split(/\s+/)[0]
+    return className ? `${tag}.${className}` : tag
+  }
+
+  const snapshot = (element: Element): Record<string, string> => {
+    const computed = getComputedStyle(element)
+    const values: Record<string, string> = {}
+    for (const property of PROPERTIES) values[property] = computed[property]
+    return values
+  }
+
+  const rows: SubjectReading[] = []
+
+  // The walk presses Tab before this runs, which leaves one element focused.
+  // Reading that element's rest state while it holds focus reports no
+  // difference and hides whatever ring it actually draws, so the page starts
+  // from nothing focused and every element is blurred again after its turn.
+  const entryFocus = document.activeElement
+  if (entryFocus instanceof HTMLElement) entryFocus.blur()
+
+  for (const element of Array.from(document.querySelectorAll(query))) {
+    if (!(element instanceof HTMLElement)) continue
+
+    const rest = snapshot(element)
+    element.focus()
+    if (document.activeElement !== element) {
+      rows.push({ selector: describe(element), treatment: 'not focusable' })
+      continue
+    }
+
+    const focused = snapshot(element)
+    const changed = PROPERTIES.filter(
+      (property) => rest[property] !== focused[property],
+    ).map((property) => `${property} ${focused[property]}`)
+
+    rows.push({
+      selector: describe(element),
+      treatment:
+        changed.length === 0 ? 'no visible change' : changed.join(', '),
+    })
+    element.blur()
+  }
+
+  return rows
+}
+
+const FOCUS: Subject = {
+  name: 'focus',
+  summary: 'what each element changes about itself when it takes focus',
+  read: readFocusTreatments,
+}
+
+export const SUBJECTS: readonly Subject[] = [FOCUS]
+
+/** Resolves a subject by name, so an unknown one is the caller's to report. */
+export function findSubject(name: string): Subject | undefined {
+  return SUBJECTS.find((subject) => subject.name === name)
+}

package/src/inventory/walk.ts

@@ -0,0 +1,129 @@
+import { chromium } from 'playwright-core'
+import type { Browser } from 'playwright-core'
+import { isBrowserMissing } from '@/browser/engine'
+import { routeUrl } from '@/inventory/config'
+import type { Reading } from '@/inventory/group'
+import type { Subject } from '@/inventory/subjects'
+
+/**
+ * Walks a running application and reads one property off every element a
+ * subject names. Every browser reference the inventory feature adds lives here,
+ * and `src/commands/inventory.ts` reaches it through a dynamic import so no
+ * other command resolves the engine at startup.
+ *
+ * Like `@/demo/drive` and unlike `@/capture/render`, this module ships, because
+ * a command whose whole purpose is running inside someone else's project cannot
+ * stay toolkit-only.
+ */
+
+/**
+ * The reader and the query arrive apart because they come from different
+ * owners. The toolkit ships the reader and the project declares which elements
+ * it runs over, which is what keeps the walk answering to the target rather
+ * than to a fixed selector nobody there chose.
+ */
+export interface WalkOptions {
+  readonly baseUrl: string
+  readonly routes: readonly string[]
+  readonly subject: Subject
+  readonly query: string
+}
+
+/** A route that answered, and the elements read off it. */
+export interface RouteReading {
+  readonly route: string
+  readonly elements: number
+}
+
+export type WalkRefusal =
+  | 'browser-missing'
+  | 'server-unreachable'
+  | 'walk-failed'
+
+export type WalkResult =
+  | {
+      readonly status: 'read'
+      readonly readings: readonly Reading[]
+      readonly routes: readonly RouteReading[]
+      readonly durationMs: number
+    }
+  | {
+      readonly status: 'failed'
+      readonly reason: WalkRefusal
+      readonly message: string
+    }
+
+function failed(reason: WalkRefusal, error: unknown): WalkResult {
+  return {
+    status: 'failed',
+    reason,
+    message: error instanceof Error ? error.message : String(error),
+  }
+}
+
+/**
+ * Separates a server nobody started from a page that failed for its own
+ * reasons. The first is the precondition this command cannot create, and
+ * reporting it as an empty listing would say the site gives no answers when
+ * nothing was ever asked.
+ */
+function isServerUnreachable(error: unknown): boolean {
+  const text = error instanceof Error ? error.message : String(error)
+  return /ERR_CONNECTION_REFUSED|ERR_NAME_NOT_RESOLVED|ERR_CONNECTION_RESET|ERR_EMPTY_RESPONSE/i.test(
+    text,
+  )
+}
+
+export async function walk(options: WalkOptions): Promise<WalkResult> {
+  const started = Date.now()
+
+  let browser: Browser
+  try {
+    browser = await chromium.launch()
+  } catch (error) {
+    return failed(
+      isBrowserMissing(error) ? 'browser-missing' : 'walk-failed',
+      error,
+    )
+  }
+
+  const readings: Reading[] = []
+  const routes: RouteReading[] = []
+
+  try {
+    const page = await browser.newPage()
+
+    for (const route of options.routes) {
+      await page.goto(routeUrl(options.baseUrl, route), {
+        waitUntil: 'domcontentloaded',
+      })
+
+      // Puts the page in keyboard modality before anything is focused, because
+      // a `:focus-visible` ring is the treatment a pointer never reveals and
+      // programmatic focus alone does not match it.
+      await page.keyboard.press('Tab')
+
+      const rows = await page.evaluate(options.subject.read, options.query)
+      for (const row of rows) readings.push({ route, ...row })
+      routes.push({ route, elements: rows.length })
+    }
+  } catch (error) {
+    return failed(
+      isServerUnreachable(error) ? 'server-unreachable' : 'walk-failed',
+      error,
+    )
+  } finally {
+    // The rejection is dropped rather than propagated, because a close that
+    // fails beside a walk that already failed would replace the refusal the
+    // caller was about to receive with a reason about teardown. Nothing the
+    // caller does depends on the browser having closed cleanly.
+    await browser.close().catch(() => undefined)
+  }
+
+  return {
+    status: 'read',
+    readings,
+    routes,
+    durationMs: Date.now() - started,
+  }
+}

package/src/labels/audit.ts

@@ -0,0 +1,82 @@
+import { listChangedFiles, resolveBaseRef } from '@/git-files'
+import { type Coverage, resolveCoverage } from '@/labels/coverage'
+import { type MapRefusal, readLabelMap } from '@/labels/map'
+
+/**
+ * Why an audit produced no reading.
+ *
+ * `no-map` travels through from the map reader and stays an answer rather than
+ * a fault. The git reasons are the opposite: a range this check asked for and
+ * could not get, which is a broken invocation rather than a project that
+ * declared nothing.
+ *
+ * A named ref that will not resolve is its own reason. Folding it into
+ * `no-base` sends the caller who already passed `--base` a message telling
+ * them to pass `--base`.
+ */
+export type LabelAuditRefusal =
+  | MapRefusal
+  | 'no-base'
+  | 'bad-base'
+  | 'unreadable-changes'
+
+export type LabelAudit =
+  | {
+      readonly kind: 'measured'
+      /** Absent when the caller supplied the changed set rather than a range. */
+      readonly base?: string
+      readonly changed: readonly string[]
+      readonly coverage: Coverage
+    }
+  | { readonly kind: 'refused'; readonly reason: LabelAuditRefusal }
+
+export interface LabelAuditOptions {
+  /** Far side of the range, defaulting to the merge base against the trunk. */
+  readonly base?: string
+  /** A changed set the caller already holds, which skips git entirely. */
+  readonly paths?: readonly string[]
+}
+
+/**
+ * Resolves a changed set against the map a project declares, and reports both
+ * what it earns and what it leaves uncovered.
+ *
+ * One verb for two readers by design. `git-pr` reads the labels at open time
+ * and the audit aggregate reads the uncovered count, and a verb shaped for the
+ * first alone returns nothing the second can retain.
+ */
+export async function auditLabels(
+  root: string,
+  options: LabelAuditOptions = {},
+): Promise<LabelAudit> {
+  const map = readLabelMap(root)
+  if (map.kind === 'refused') return { kind: 'refused', reason: map.reason }
+
+  if (options.paths !== undefined) {
+    return {
+      kind: 'measured',
+      changed: [...options.paths],
+      coverage: resolveCoverage(map, options.paths),
+    }
+  }
+
+  const base = await resolveBaseRef(root, options.base)
+  if (base === undefined) {
+    return {
+      kind: 'refused',
+      reason: options.base === undefined ? 'no-base' : 'bad-base',
+    }
+  }
+
+  const changed = await listChangedFiles(root, base)
+  if (changed === undefined) {
+    return { kind: 'refused', reason: 'unreadable-changes' }
+  }
+
+  return {
+    kind: 'measured',
+    base,
+    changed,
+    coverage: resolveCoverage(map, changed),
+  }
+}

package/src/labels/coverage.ts

@@ -0,0 +1,79 @@
+import type { LabelMap } from '@/labels/map'
+
+/** A path a row leaves unlabelled on purpose, carrying the reason it gives. */
+export interface DeclinedPath {
+  readonly path: string
+  readonly reason: string
+}
+
+export interface Coverage {
+  /** Distinct labels the whole set earns, ordered as the map declares them. */
+  readonly labels: readonly string[]
+  /**
+   * Paths a `[declined]` row covers, which are a decision rather than a gap.
+   *
+   * Kept apart from `uncovered` because the response to the two differs. A
+   * surface nobody has gotten to wants a row, and one somebody decided against
+   * wants nothing, so a report folding them together is useful about neither.
+   */
+  readonly declined: readonly DeclinedPath[]
+  /** Paths no row of either table reaches, which is the finding. */
+  readonly uncovered: readonly string[]
+}
+
+/**
+ * Prefix-anchored, matching what the map's own comment describes and what the
+ * census behind its 41 prefixes was measured against.
+ *
+ * A glob would reach every existing prefix and invalidate that measurement, so
+ * the rule stays a `startsWith` even where a glob would read more naturally.
+ */
+function matches(path: string, prefixes: readonly string[]): boolean {
+  return prefixes.some((prefix) => path.startsWith(prefix))
+}
+
+/**
+ * Resolves what a changed set earns from a map, and what it leaves behind.
+ *
+ * One pass answers both readers. `git-pr` wants the labels to apply, and the
+ * audit wants the paths that earned none, and a function shaped for the first
+ * alone returns nothing the second can count.
+ */
+export function resolveCoverage(
+  map: Extract<LabelMap, { kind: 'map' }>,
+  paths: readonly string[],
+): Coverage {
+  const earned = new Set<string>()
+  const declined: DeclinedPath[] = []
+  const uncovered: string[] = []
+
+  for (const path of paths) {
+    const labels = map.domains.filter((row) => matches(path, row.prefixes))
+
+    // A label wins over a decline. A path both tables claim already carries a
+    // subject, so reporting it as deliberately unlabelled would contradict the
+    // label the same run is about to apply.
+    if (labels.length > 0) {
+      for (const row of labels) earned.add(row.label)
+      continue
+    }
+
+    const row = map.declined.find((entry) => matches(path, entry.prefixes))
+    if (row !== undefined) {
+      declined.push({ path, reason: row.reason })
+      continue
+    }
+
+    uncovered.push(path)
+  }
+
+  return {
+    // Read back off the map rather than out of the set, so two runs over one
+    // branch produce one order and one string.
+    labels: map.domains
+      .map((row) => row.label)
+      .filter((label) => earned.has(label)),
+    declined,
+    uncovered,
+  }
+}

package/src/labels/map.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Where a project declares its pull request label map, spelled once.
+ *
+ * The file has already moved once, and that relocation rewrote every mention
+ * across four surfaces. Nothing in code spells it anywhere else, so the next
+ * move is one edit here rather than a sweep.
+ */
+export const MAP_REL = join('.claude', 'canon', 'pr-labels.toml')
+
+/** A label name and the path prefixes that earn it, in the map's own order. */
+export interface DomainRow {
+  readonly label: string
+  readonly prefixes: readonly string[]
+}
+
+/** A reason a path is deliberately unlabelled, and the prefixes it covers. */
+export interface DeclinedRow {
+  readonly reason: string
+  readonly prefixes: readonly string[]
+}
+
+/**
+ * Why a map could not be read, which is never the same as a map with no rows.
+ *
+ * `no-map` is an answer rather than a fault. A project declaring no map is
+ * labelled silently by design, so a refusal read as a break would make the map
+ * mandatory for every target, which that decision declined. The other two are
+ * a file that exists and cannot be used, which is a defect in the map itself.
+ */
+export type MapRefusal = 'no-map' | 'unreadable-map' | 'no-domains'
+
+export type LabelMap =
+  | {
+      readonly kind: 'map'
+      readonly domains: readonly DomainRow[]
+      readonly declined: readonly DeclinedRow[]
+    }
+  | { readonly kind: 'refused'; readonly reason: MapRefusal }
+
+/**
+ * Reads a TOML table of string arrays into rows, dropping any key whose value
+ * carries no usable prefix.
+ *
+ * A malformed row is skipped rather than refused, because both tables are
+ * authored by hand and one bad entry should not blind the check to the other
+ * forty. What it costs is that a typo reads as a row nobody wrote, which the
+ * uncovered report surfaces from the other side.
+ */
+function readRows(table: unknown): { key: string; prefixes: string[] }[] {
+  if (typeof table !== 'object' || table === null || Array.isArray(table)) {
+    return []
+  }
+
+  const rows: { key: string; prefixes: string[] }[] = []
+  for (const [key, value] of Object.entries(table)) {
+    if (!Array.isArray(value)) continue
+    const prefixes = value.filter(
+      (entry): entry is string => typeof entry === 'string' && entry !== '',
+    )
+    if (prefixes.length > 0) rows.push({ key, prefixes })
+  }
+
+  return rows
+}
+
+/** Parses map text, so a caller holding the bytes skips the filesystem. */
+export function parseLabelMap(source: string): LabelMap {
+  let parsed: Record<string, unknown>
+  try {
+    parsed = Bun.TOML.parse(source) as Record<string, unknown>
+  } catch {
+    return { kind: 'refused', reason: 'unreadable-map' }
+  }
+
+  const domains = readRows(parsed.domains)
+  if (domains.length === 0) return { kind: 'refused', reason: 'no-domains' }
+
+  return {
+    kind: 'map',
+    domains: domains.map(({ key, prefixes }) => ({ label: key, prefixes })),
+    declined: readRows(parsed.declined).map(({ key, prefixes }) => ({
+      reason: key,
+      prefixes,
+    })),
+  }
+}
+
+/** Reads the map a project declares at `root`, or says why it could not. */
+export function readLabelMap(root: string): LabelMap {
+  let source: string
+  try {
+    source = readFileSync(join(root, MAP_REL), 'utf8')
+  } catch {
+    return { kind: 'refused', reason: 'no-map' }
+  }
+
+  return parseLabelMap(source)
+}

package/src/labels/phase.ts

@@ -0,0 +1,95 @@
+import { linesOutsideFences, maskCodeSpans } from '@/markdown/scan'
+
+/**
+ * The two version namespaces `standards/versioning.md` keeps apart, and why a
+ * pull request cannot be sorted between them by pattern alone.
+ *
+ * A phase label (`v68.5`) and a semver reference (`v3.44`) both match
+ * `v<digits>(.<digits>){1,2}`, so a shape-only scan cannot tell them apart. The
+ * first measurement of this defect tried exactly that and returned 28 of 60
+ * correct. What separates the two is not the token but the pull request: a
+ * release-please pull request legitimately carries version numbers in its
+ * generated body, and every other pull request does not.
+ */
+export interface PhaseScanInput {
+  readonly title: string
+  readonly body: string
+  readonly headRefName: string
+}
+
+export interface PhaseScanResult {
+  /** Whether this pull request is release-please's own, per its fixed shape. */
+  readonly cutsRelease: boolean
+  readonly phaseLabels: readonly string[]
+  readonly semverTags: readonly string[]
+}
+
+const VERSION_TOKEN = /\bv\d+(?:\.\d+){1,2}\b/g
+
+/**
+ * The head branch release-please opens every release pull request under.
+ *
+ * `release-please-config.json` names the package `canon`, so the observed
+ * branch is `release-please--branches--main--components--canon`. The prefix
+ * stops short of the component segment, since that segment moves with the
+ * package name and the branch segment does not.
+ */
+const RELEASE_HEAD_PREFIX = 'release-please--branches--main'
+
+const RELEASE_TITLE_PREFIX = 'chore(main): release '
+
+/**
+ * Two fixed signals rather than one, because either alone is a string an
+ * author's own pull request could reproduce. A title starting with the
+ * release commit type is plain conventional-commit text, and a head branch is
+ * exactly what a PR renamed for review would want to imitate to slip a real
+ * phase label past this check. Together they name release-please's own act of
+ * opening the pull request, which nothing else on the remote can perform.
+ */
+function isReleasePullRequest(input: PhaseScanInput): boolean {
+  return (
+    input.headRefName.startsWith(RELEASE_HEAD_PREFIX) &&
+    input.title.startsWith(RELEASE_TITLE_PREFIX)
+  )
+}
+
+/**
+ * Drops a fenced block outright and blanks a code span inside what remains,
+ * so a token quoted rather than written is read the way a reader reads it:
+ * shown, not asserted.
+ *
+ * `canon markdown audit` excludes a fenced block and a code span from its own
+ * ban scan over the same kind of text, and this reuses that reading rather
+ * than inventing a second one. `#1208` is the corpus case that forced it: a
+ * backticked span quoting a test fixture's own version-shaped name, which the
+ * shape-only scan below cannot tell from a leak on its own.
+ *
+ * A link destination stays unmasked, unlike the ban scan's own reading. A
+ * release-please body's real semver reference sits inside the generated
+ * compare link's URL, and masking it would empty `semverTags` on the one
+ * pull request this check exists to pass, trading the corpus's one code-span
+ * leak for a hole in every release.
+ */
+function readable(text: string): string {
+  return linesOutsideFences(text).map(maskCodeSpans).join('\n')
+}
+
+/**
+ * Reads a title and a body for version-shaped tokens and sorts every one
+ * found into the namespace this pull request is allowed to carry.
+ *
+ * The split runs on the pull request rather than on each token. A release
+ * pull request's tokens are read as the semver references its generated body
+ * legitimately carries, and every other pull request's tokens are read as
+ * leaked phase labels, which is what `standards/versioning.md` names the
+ * defect this exists to catch.
+ */
+export function scanPhaseLabels(input: PhaseScanInput): PhaseScanResult {
+  const text = readable(`${input.title}\n${input.body}`)
+  const tokens = [...new Set(text.match(VERSION_TOKEN) ?? [])]
+  const cutsRelease = isReleasePullRequest(input)
+
+  return cutsRelease
+    ? { cutsRelease, phaseLabels: [], semverTags: tokens }
+    : { cutsRelease, phaseLabels: tokens, semverTags: [] }
+}

package/src/markdown/bans.ts

@@ -0,0 +1,94 @@
+import type { BanSets } from '@/markdown/scan'
+
+/**
+ * Single characters `markdown.md` bans under `## Punctuation`.
+ *
+ * The parenthetical-aside ban in that section is absent because it quotes a
+ * whole clause, and a literal match built from a clause reports the compliant
+ * text and reaches none of the violations.
+ */
+const CHARACTERS = ['—', ';'] as const
+
+/**
+ * Single lowercase words `markdown.md` bans under `## Language`.
+ *
+ * A multi-word ban is absent by the same test the character set applies. The
+ * standard bans a pattern like `It's not X, it's Y` with a placeholder standing
+ * in for the rest of the sentence, so no literal match reaches it and the
+ * phrase bans stay a reader's judgment.
+ */
+const WORDS = [
+  'seamless',
+  'robust',
+  'powerful',
+  'revolutionary',
+  'enhanced',
+  'allows',
+  'leverage',
+  'simply',
+  'just',
+  'easily',
+  'quickly',
+  'very',
+  'really',
+] as const
+
+/**
+ * British spellings of the American examples `markdown.md` lists.
+ *
+ * The set is carried whole rather than derived from a suffix rule, because a
+ * suffix pattern run over prose produced 46 of the 58 false positives measured
+ * during intake: `exercises`, `promises`, and `revised` all end in `-ise` and
+ * none is a British spelling. Matching whole words reaches none of them.
+ *
+ * `analyse` is absent because the standard's example is `analyze`, which ends
+ * in `-yze` rather than the `-ize` its rule states. The set records what the
+ * standard reaches rather than what a reader would extend it to, so adding the
+ * spelling here would widen the check past the prose it answers to.
+ */
+const SPELLINGS = [
+  'organise',
+  'summarise',
+  'recognise',
+  'behaviour',
+  'colour',
+  'centre',
+] as const
+
+/**
+ * The three closed sets the audit measures, owned here rather than harvested
+ * from the standards stating them.
+ *
+ * Parsing the prose was the alternative and it put a parser contract on two
+ * documents authored for people, which the prose standard had to carry a
+ * paragraph of its own to protect. The sets are a prior an author already
+ * knows rather than a filter: measured at `60fc97bf` on 2026-08-19, these 21
+ * terms ran across 483 markdown files for a clean exit, and every one of the
+ * 70 occurrences of a banned word sat inside the ban list itself or inside an
+ * example demonstrating the ban.
+ *
+ * The set is closed rather than extensible. Enumeration cannot close the gap
+ * it aims at, and each addition costs a false-positive class, since `just`,
+ * `allows`, and `very` have honest uses no literal match separates. A project
+ * wanting its own vocabulary is asking for a different feature than this one.
+ */
+export const BAN_SETS: BanSets = {
+  characters: CHARACTERS,
+  words: WORDS,
+  spellings: SPELLINGS,
+}
+
+/**
+ * Names any set that arrived empty, so a run measuring nothing says so.
+ *
+ * Empty is not the same state as finding no hit. A scan with no terms reports
+ * a clean file having looked for nothing, which is the silence the audit
+ * refused to ship back when a standard could go missing. The sets ship with
+ * the package now, so the only way one empties is an edit to this file, and
+ * the guard is what keeps that edit loud rather than quiet.
+ */
+export function emptyBanSets(sets: BanSets = BAN_SETS): string[] {
+  return (['characters', 'words', 'spellings'] as const).filter(
+    (name) => sets[name].length === 0,
+  )
+}