@erclx/canon 5.44.0 → 5.46.0

package/src/context/coverage.ts

@@ -0,0 +1,210 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import type { AuditedFolder } from '@/context/folders'
+
+/** Where a project declares the code roots its context entries must cover. */
+export const CONTEXT_CONFIG_REL = join('canon', 'config', 'context.toml')
+
+/** The root assumed when a project declares none and carries the folder. */
+export const DEFAULT_ROOT = 'src'
+
+/**
+ * The roots a project asked the coverage check to measure.
+ *
+ * `none` says the project carries no declaration and no `src/`, which reports
+ * and never gates so a seed tree audited at its own root keeps passing.
+ * `opted-out` is an explicit `roots = []`. `invalid` is a declaration that
+ * exists and cannot be used, which gates rather than falling back to `src`,
+ * since a project that wrote one meant it.
+ */
+export type RootDeclaration =
+  | { readonly kind: 'roots'; readonly patterns: readonly string[] }
+  | { readonly kind: 'opted-out' }
+  | { readonly kind: 'none' }
+  | { readonly kind: 'invalid'; readonly reason: string }
+
+export interface DoubleClaim {
+  readonly folder: string
+  readonly rels: readonly string[]
+}
+
+export interface CoverageFinding {
+  /** Folders under a declared root that no entry's Layout names. */
+  readonly unnamed: readonly string[]
+  /** Folders taking a Layout H3 in more than one entry. */
+  readonly doubled: readonly DoubleClaim[]
+  /** Declared roots or globs that matched no folder on disk. */
+  readonly missingRoots: readonly string[]
+}
+
+export type CoverageReport =
+  | {
+      readonly kind: 'measured'
+      readonly roots: readonly string[]
+      readonly findings: CoverageFinding
+    }
+  | { readonly kind: 'opted-out' }
+  | { readonly kind: 'no-root' }
+  | { readonly kind: 'invalid'; readonly reason: string }
+
+/** Reads the declaration, falling back to `src` when that folder exists. */
+export function readRoots(root: string): RootDeclaration {
+  const path = join(root, CONTEXT_CONFIG_REL)
+
+  if (existsSync(path)) {
+    let parsed: Record<string, unknown>
+    try {
+      parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+        string,
+        unknown
+      >
+    } catch {
+      return {
+        kind: 'invalid',
+        reason: `${CONTEXT_CONFIG_REL} is not valid TOML`,
+      }
+    }
+
+    const declared = parsed.roots
+    if (
+      !Array.isArray(declared) ||
+      !declared.every((entry) => typeof entry === 'string' && entry !== '')
+    ) {
+      return {
+        kind: 'invalid',
+        reason: `${CONTEXT_CONFIG_REL} needs roots as a list of folder or glob strings`,
+      }
+    }
+
+    return declared.length === 0
+      ? { kind: 'opted-out' }
+      : { kind: 'roots', patterns: declared as string[] }
+  }
+
+  return isDirectory(join(root, DEFAULT_ROOT))
+    ? { kind: 'roots', patterns: [DEFAULT_ROOT] }
+    : { kind: 'none' }
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/** Expands each pattern to the folders it matches, relative to `root`. */
+function expandRoots(root: string, patterns: readonly string[]) {
+  const roots: string[] = []
+  const missing: string[] = []
+
+  for (const pattern of patterns) {
+    const matched = [
+      ...new Bun.Glob(pattern).scanSync({ cwd: root, onlyFiles: false }),
+    ]
+      .map((path) => path.replace(/\/$/, ''))
+      .filter((path) => isDirectory(join(root, path)))
+      .sort()
+
+    if (matched.length === 0) missing.push(pattern)
+    roots.push(...matched)
+  }
+
+  return { roots: [...new Set(roots)], missing }
+}
+
+/** Lists folders directly under a root, skipping hidden ones and `node_modules`. */
+function listFolders(root: string, rel: string): string[] {
+  return readdirSync(join(root, rel), { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() &&
+        !entry.name.startsWith('.') &&
+        entry.name !== 'node_modules',
+    )
+    .map((entry) => `${rel}/${entry.name}`)
+    .sort()
+}
+
+function layoutSection(source: string): string {
+  const lines = source.split('\n')
+  const start = lines.findIndex((line) => /^##\s+Layout\s*$/.test(line))
+  if (start === -1) return ''
+
+  const end = lines.findIndex(
+    (line, index) => index > start && /^##\s/.test(line),
+  )
+  return lines.slice(start + 1, end === -1 ? undefined : end).join('\n')
+}
+
+function backtickedPaths(text: string): string[] {
+  return [...text.matchAll(/`([^`\s]+)`/g)].map((match) =>
+    match[1].replace(/\/$/, ''),
+  )
+}
+
+/**
+ * Measures the folders under the declared roots against the Layout sections.
+ *
+ * A folder is named when any Layout text cites it in backticks, a bullet
+ * included, and claimed when it is an H3 title. Only the H3 counts toward
+ * uniqueness, since a bullet legitimately cites another domain's folder and a
+ * grep cannot tell a citation from a claim.
+ */
+export function measureCoverage(
+  root: string,
+  declaration: RootDeclaration,
+  folders: readonly AuditedFolder[],
+): CoverageReport {
+  if (declaration.kind === 'opted-out') return { kind: 'opted-out' }
+  if (declaration.kind === 'none') return { kind: 'no-root' }
+  if (declaration.kind === 'invalid') {
+    return { kind: 'invalid', reason: declaration.reason }
+  }
+
+  const named = new Set<string>()
+  const claims = new Map<string, Set<string>>()
+
+  for (const folder of folders) {
+    for (const entry of folder.entries) {
+      const rel = relative(root, entry)
+      const layout = layoutSection(readFileSync(entry, 'utf8'))
+
+      for (const path of backtickedPaths(layout)) named.add(path)
+
+      for (const line of layout.split('\n')) {
+        const heading = line.match(/^###\s+`([^`\s]+)`\s*$/)
+        if (!heading) continue
+        const path = heading[1].replace(/\/$/, '')
+        claims.set(path, (claims.get(path) ?? new Set()).add(rel))
+      }
+    }
+  }
+
+  const { roots, missing } = expandRoots(root, declaration.patterns)
+  const onDisk = roots.flatMap((rel) => listFolders(root, rel))
+
+  return {
+    kind: 'measured',
+    roots,
+    findings: {
+      unnamed: onDisk.filter((path) => !named.has(path)),
+      doubled: onDisk
+        .filter((path) => (claims.get(path)?.size ?? 0) > 1)
+        .map((folder) => ({
+          folder,
+          rels: [...(claims.get(folder) ?? [])].sort(),
+        })),
+      missingRoots: missing,
+    },
+  }
+}
+
+/** Whether the report holds a finding that should fail a widened gate. */
+export function hasCoverageFindings(report: CoverageReport): boolean {
+  if (report.kind === 'invalid') return true
+  if (report.kind !== 'measured') return false
+  const { unnamed, doubled, missingRoots } = report.findings
+  return unnamed.length > 0 || doubled.length > 0 || missingRoots.length > 0
+}

package/src/context/gate.ts

@@ -3,6 +3,7 @@ import type {
   SectionFinding,
   ShapeFinding,
 } from '@/context/audit'
+import { type CoverageReport, hasCoverageFindings } from '@/context/coverage'
 import type { FolderDrift } from '@/context/index-drift'
 
 export interface GateInput {
@@ -25,6 +26,12 @@ export interface GateInput {
    */
   readonly shape: readonly ShapeFinding[]
   readonly drift: readonly FolderDrift[]
+  /**
+   * Folders under the declared code roots that no Layout names or two entries
+   * claim, gating under `--gate` alone. A project with no code root reads as
+   * not measured and never gates.
+   */
+  readonly coverage: CoverageReport
   /**
    * Whether the caller asked for the widened gate. False leaves a missing
    * section and a drifted index advisory, which is what the project-root stage
@@ -48,8 +55,8 @@ export function hasDrift(drift: readonly FolderDrift[]): boolean {
  * for itself, which makes it a fact rather than a threshold a reader weighs.
  * The findings `--gate` adds are the ones answerable from the file itself: a
  * required section it does not declare, an H2 outside the closed set, a shape
- * break in a folder rebuilt to the shape, and an index disagreeing with its
- * folder. Entry length, depth, bullet, table, provenance, and the record's
+ * break in a folder rebuilt to the shape, an index disagreeing with its
+ * folder, and a code folder no entry names or two entries claim. Entry length, depth, bullet, table, provenance, and the record's
  * claim coverage are judgments, so they stay out under both modes.
  */
 export function isGating({
@@ -59,6 +66,7 @@ export function isGating({
   extraSections,
   shape,
   drift,
+  coverage,
   widened,
 }: GateInput): boolean {
   if (unresolvedCitations > 0) return true
@@ -69,6 +77,7 @@ export function isGating({
     sections.length > 0 ||
     extraSections.length > 0 ||
     shape.some((finding) => finding.gated) ||
-    hasDrift(drift)
+    hasDrift(drift) ||
+    hasCoverageFindings(coverage)
   )
 }

package/src/design/components.ts

@@ -520,7 +520,7 @@ html.sb-shut .pane { border-left: 0; }
 }
 
 /* A bar link is its own tap target rather than a line of text, so it carries
-   the 24 pixel minimum the a11y rule sets. */
+   the 24 pixel minimum the keyboard rule sets. */
 .mast a,
 .mast summary {
   min-height: 1.6rem;

package/src/gate/stages.ts

@@ -334,7 +334,7 @@ export const STAGES: readonly Stage[] = [
         kind: 'cli',
         argv: ['context', 'audit', '--gate'],
         failure:
-          'A cited context path does not resolve, an entry lacks a required section or carries an H2 outside Overview, Layout, and Gotchas, an entry under a shape-gated folder breaks the section shape, or an index disagrees with its folder. Run bun src/cli.ts context audit --gate.',
+          'A cited context path does not resolve, an entry lacks a required section or carries an H2 outside Overview, Layout, and Gotchas, an entry under a shape-gated folder breaks the section shape, an index disagrees with its folder, or a code folder is named in no Layout or claimed by two entries. Run bun src/cli.ts context audit --gate.',
       },
     ],
     success: 'Context citations resolve',

package/src/gov/audit.ts

@@ -36,6 +36,21 @@ export const RULE_GATED_FOLDERS: readonly string[] = [
   join('governance', 'rules', 'framework') + sep,
   join('governance', 'rules', 'writing') + sep,
   join('internal', 'rules') + sep,
+  join('governance', 'rules', 'lang') + sep,
+  join('governance', 'rules', 'lib') + sep,
+  join('governance', 'rules', 'ui') + sep,
+  join('governance', 'rules', 'tooling') + sep,
+]
+
+/**
+ * Rule files in a gated folder whose findings `--gate` still passes, one path
+ * each and never a folder, so a new rule beside one is gated the day it lands.
+ *
+ * `ui/canvas.md` carries a shape finding and no ledger, and v149.2 removes the
+ * rule, so this entry goes with it.
+ */
+export const RULE_GATE_EXEMPT: readonly string[] = [
+  join('governance', 'rules', 'ui', 'canvas.md'),
 ]
 
 /** The folders whose rules claim outside practice, so each carries a ledger. */
@@ -429,13 +444,18 @@ export function hasFinding(reading: RuleReading): boolean {
  */
 export function auditExit(
   report: Extract<RuleAuditReport, { kind: 'measured' }>,
-  options: { readonly gate: boolean; readonly gated: readonly string[] },
+  options: {
+    readonly gate: boolean
+    readonly gated: readonly string[]
+    readonly exempt?: readonly string[]
+  },
 ): number {
   const failing = report.rules.filter(
     (reading) =>
       hasFinding(reading) &&
       (!options.gate ||
-        options.gated.some((prefix) => reading.file.startsWith(prefix))),
+        (options.gated.some((prefix) => reading.file.startsWith(prefix)) &&
+          !options.exempt?.includes(reading.file))),
   )
   return failing.length > 0 ? 2 : 0
 }

package/src/init/plan.ts

@@ -1,4 +1,4 @@
-export const SKIPPABLE_DOMAINS = ['wiki', 'governance', 'records'] as const
+export const SKIPPABLE_DOMAINS = ['governance', 'records'] as const
 
 export type SkippableDomain = (typeof SKIPPABLE_DOMAINS)[number]
 
@@ -97,13 +97,6 @@ export function planInit(flags: InitFlags): InitPlan {
     })
   }
 
-  if (!flags.skip.skipped.has('wiki')) {
-    preview.push({
-      level: 'info',
-      text: 'wiki (.claude/wiki/ with a stub index)',
-    })
-  }
-
   if (!flags.skip.skipped.has('records')) {
     preview.push({
       level: 'info',

package/src/init/steps.ts

@@ -1,5 +1,7 @@
+import { logInfo, logWarn, plural } from '@/cli/ui'
 import { type InitFlags, resolveStack } from '@/init/plan'
 import type { DomainStep } from '@/init/run'
+import { GATED_CONFIG_REL, gateScopeRoots } from '@/markdown/gated'
 
 /** Builds the child-process invocation for one domain. */
 export type RunFactory = (args: readonly string[]) => () => Promise<boolean>
@@ -55,13 +57,15 @@ export function buildSteps(
     })
   }
 
-  if (!flags.skip.skipped.has('wiki')) {
-    steps.push({
-      kind: 'run',
-      label: 'Wiki',
-      run: child(['wiki', 'init', resolved]),
-    })
-  }
+  // In-process rather than a child verb, since the audit reads the working
+  // directory and every child here is handed the target as an argument. It
+  // runs after every seeding domain so the roots it measures hold what they
+  // will ship with.
+  steps.push({
+    kind: 'run',
+    label: 'Markdown gating',
+    run: () => gateMarkdown(resolved),
+  })
 
   if (!flags.skip.skipped.has('records')) {
     // `skip` here means there is nothing to run non-interactively, not that
@@ -76,6 +80,39 @@ export function buildSteps(
   return steps
 }
 
+/**
+ * Starts a new project with every density root gated that passes now. A root
+ * with a finding is named and left out, since gating it would fail the first
+ * push on prose a scaffolder wrote.
+ */
+async function gateMarkdown(root: string): Promise<boolean> {
+  const result = await gateScopeRoots(root)
+
+  if (result.kind === 'exists') {
+    logInfo(`${GATED_CONFIG_REL} already exists, so its list is kept.`)
+    return true
+  }
+
+  // A scaffold such as `npm create vite` makes no repository, and nothing else
+  // in init needs one, so this is a skip rather than a failed domain.
+  if (result.kind === 'unavailable') {
+    logWarn(
+      "Skipped: not a git repository, so no root was measured or gated. Run 'canon markdown gated add <prefix>' once it is one.",
+    )
+    return true
+  }
+
+  logInfo(
+    `Gated ${result.gated.length === 0 ? 'nothing' : result.gated.join(', ')} in ${GATED_CONFIG_REL}.`,
+  )
+  for (const { prefix, findings } of result.left) {
+    logWarn(
+      `Left ${prefix} ungated with ${plural(findings, 'finding')}. Repair it, then run 'canon markdown gated add ${prefix}'.`,
+    )
+  }
+  return true
+}
+
 /**
  * Builds the `gov install` argv. The run and the recovery command a skip prints
  * come from here both, so the command a caller is told to paste installs what

package/src/intake/items.ts

@@ -44,6 +44,10 @@ export interface IntakeItem {
   readonly answerLine: number | undefined
   /** Text in the slot, absent when the slot is empty and the item is unread. */
   readonly answer: string | undefined
+  /** What is wrong today, absent when the item carries no `Problem:` line. */
+  readonly problem: string | undefined
+  /** The one change proposed, absent when the item carries no `Fix:` line. */
+  readonly fix: string | undefined
   readonly open: string | undefined
   readonly suggested: string | undefined
   readonly worth: string | undefined
@@ -55,6 +59,8 @@ interface Draft {
   line: number
   answerLine: number | undefined
   answer: string | undefined
+  problem: string | undefined
+  fix: string | undefined
   open: string | undefined
   suggested: string | undefined
   worth: string | undefined
@@ -89,6 +95,8 @@ export function readItems(text: string): IntakeItem[] {
         line: line.number,
         answerLine: undefined,
         answer: undefined,
+        problem: undefined,
+        fix: undefined,
         open: undefined,
         suggested: undefined,
         worth: undefined,
@@ -114,6 +122,12 @@ export function readItems(text: string): IntakeItem[] {
         draft.answerLine = line.number
         draft.answer = value === '' ? undefined : value
         break
+      case 'problem':
+        draft.problem = value
+        break
+      case 'fix':
+        draft.fix = value
+        break
       case 'open':
         draft.open = value
         break

package/src/inventory/subjects.ts

@@ -27,7 +27,7 @@ export interface Subject {
 
 /**
  * Reports what each element changes about itself when it takes focus, which is
- * the reading `governance/rules/ui/a11y.md` states three rules against and
+ * the reading `governance/rules/ui/keyboard.md` states three rules against and
  * nothing measures.
  *
  * The difference between rest and focus is the treatment, rather than the

package/src/labels/closing.ts

@@ -0,0 +1,46 @@
+import { linesOutsideFences, maskCodeSpans } from '@/markdown/scan'
+
+/**
+ * The keywords GitHub reads as closing an issue on merge, each with its
+ * tenses. The keyword must start a word, so `disclosed #12` closes nothing,
+ * and GitHub reads only the one number that follows it, so `Closes #12, #13`
+ * closes #12 alone.
+ */
+const CLOSING =
+  /(?<!\w)(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?):?[ \t]+#(\d+)/gi
+
+export interface ClosingCheck {
+  /** Expected issues the body carries no closing reference for. */
+  readonly missing: readonly number[]
+  /** Issues the body closes that the expectation did not name. */
+  readonly stray: readonly number[]
+}
+
+/**
+ * Reads the issue numbers a body closes, in order and deduped. A code span and
+ * a fence quote a keyword rather than use it, and GitHub ignores both.
+ */
+export function readClosingReferences(body: string): readonly number[] {
+  const numbers = new Set<number>()
+
+  for (const line of linesOutsideFences(body)) {
+    for (const match of maskCodeSpans(line).matchAll(CLOSING)) {
+      numbers.add(Number(match[1]))
+    }
+  }
+
+  return [...numbers]
+}
+
+/** Compares the issues a body closes to the issues it should. */
+export function checkClosing(
+  body: string,
+  expected: readonly number[],
+): ClosingCheck {
+  const found = readClosingReferences(body)
+
+  return {
+    missing: expected.filter((number) => !found.includes(number)),
+    stray: found.filter((number) => !expected.includes(number)),
+  }
+}