@erclx/canon 5.45.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/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/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,6 +57,16 @@ export function buildSteps(
     })
   }
 
+  // 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
     // the caller opted out, unlike every other push of this kind above.
@@ -68,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/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)),
+  }
+}

package/src/markdown/gated.ts

@@ -0,0 +1,250 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { listRepositoryFiles } from '@/git/files'
+import { densityFindings, type DensityKind } from '@/markdown/density'
+import { referenceShapeGates } from '@/markdown/gate'
+import {
+  type ReferenceShapeKind,
+  referenceShapeFindings,
+} from '@/markdown/reference-shape'
+import { bodyLines } from '@/markdown/scan'
+import {
+  densityGates,
+  GATED_PATHS,
+  GATED_SCOPE_ROOTS,
+  inDensityScope,
+} from '@/markdown/scope'
+import { isOwnCheckout } from '@/roots/project'
+
+/** Where a target keeps the prefixes its density findings gate under. */
+export const GATED_CONFIG_REL = join('canon', 'config', 'markdown.toml')
+
+/**
+ * An absent file is today's target default and gates nothing. A malformed one
+ * refuses rather than reading as empty, since an empty list would silently
+ * drop every gate a project had turned on.
+ */
+export type GatedConfig =
+  | { readonly kind: 'absent' }
+  | { readonly kind: 'listed'; readonly prefixes: readonly string[] }
+  | { readonly kind: 'malformed'; readonly message: string }
+
+export function readGatedConfig(root: string): GatedConfig {
+  const path = join(root, GATED_CONFIG_REL)
+  if (!existsSync(path)) return { kind: 'absent' }
+
+  let parsed: Record<string, unknown>
+  try {
+    parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+      string,
+      unknown
+    >
+  } catch (error) {
+    return {
+      kind: 'malformed',
+      message: `${GATED_CONFIG_REL} is not valid TOML: ${error instanceof Error ? error.message : String(error)}`,
+    }
+  }
+
+  const table = parsed.markdown
+  if (table === undefined) return { kind: 'listed', prefixes: [] }
+  if (typeof table !== 'object' || table === null || Array.isArray(table)) {
+    return {
+      kind: 'malformed',
+      message: `${GATED_CONFIG_REL}: [markdown] is not a table`,
+    }
+  }
+
+  const gated = (table as Record<string, unknown>).gated
+  if (gated === undefined) return { kind: 'listed', prefixes: [] }
+  if (
+    !Array.isArray(gated) ||
+    !gated.every((each): each is string => typeof each === 'string')
+  ) {
+    return {
+      kind: 'malformed',
+      message: `${GATED_CONFIG_REL}: markdown.gated is not a list of strings`,
+    }
+  }
+
+  return { kind: 'listed', prefixes: gated }
+}
+
+/**
+ * Whether `prefix` can be listed. A folder ends in a slash, since a bare
+ * `docs` would also gate `docs-old/`. A path without one has to name an
+ * existing file, which is how a requirement gates by its own path.
+ */
+export function prefixShapeError(
+  root: string,
+  prefix: string,
+): string | undefined {
+  if (prefix === '' || prefix.startsWith('/') || prefix.includes('..')) {
+    return `${prefix || '(empty)'} is not a repository-relative path`
+  }
+  // A listed prefix is a `startsWith` match against repository paths, so either
+  // shape below matches no file and would gate nothing while reading as clean.
+  if (prefix.includes('//')) {
+    return `${prefix} carries a doubled slash, so it matches no file`
+  }
+  const path = join(root, prefix.replace(/\/$/, ''))
+  const isFile = existsSync(path) && !statSync(path).isDirectory()
+  if (prefix.endsWith('/')) {
+    return isFile
+      ? `${prefix} names a file, so drop the trailing slash`
+      : undefined
+  }
+  if (isFile) return undefined
+  return `${prefix} names no file. End a folder prefix with a slash.`
+}
+
+/**
+ * Appends `prefix` to the target's list, creating the file when absent. A
+ * prefix already listed writes nothing. Preserves an existing file's mode.
+ */
+export function appendGatedPrefix(
+  root: string,
+  current: readonly string[],
+  prefix: string,
+): 'appended' | 'present' {
+  if (current.includes(prefix)) return 'present'
+  writeGatedList(root, [...current, prefix])
+  return 'appended'
+}
+
+/** Written by hand rather than serialized, the way `classifier.toml` is. */
+function writeGatedList(root: string, prefixes: readonly string[]): void {
+  const path = join(root, GATED_CONFIG_REL)
+  const mode = existsSync(path) ? statSync(path).mode : undefined
+  const lines = prefixes.map((each) => `  ${JSON.stringify(each)},`)
+
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `[markdown]\ngated = [\n${lines.join('\n')}\n]\n`)
+  if (mode !== undefined) chmodSync(path, mode)
+}
+
+/** The prefixes a root gates under, and whether a bullet run gates unlisted. */
+export interface GatedList {
+  readonly prefixes: readonly string[]
+  readonly alwaysGated: boolean
+}
+
+export type GatedResolution =
+  | {
+      readonly kind: 'resolved'
+      readonly source: 'canon' | 'config' | 'absent'
+      readonly list: GatedList
+    }
+  | { readonly kind: 'malformed'; readonly message: string }
+
+/**
+ * The list a root gates under: `GATED_PATHS` in canon's own checkout, which
+ * tracks its rewrite progress, and the target's config everywhere else.
+ */
+export function resolveGatedList(
+  root: string,
+  own: boolean = isOwnCheckout(root),
+): GatedResolution {
+  if (own) {
+    return {
+      kind: 'resolved',
+      source: 'canon',
+      list: { prefixes: GATED_PATHS, alwaysGated: true },
+    }
+  }
+
+  const config = readGatedConfig(root)
+  if (config.kind === 'malformed') return config
+  return {
+    kind: 'resolved',
+    source: config.kind === 'absent' ? 'absent' : 'config',
+    list: {
+      prefixes: config.kind === 'listed' ? config.prefixes : [],
+      alwaysGated: false,
+    },
+  }
+}
+
+export interface BlockingFinding {
+  readonly path: string
+  readonly kind: DensityKind | ReferenceShapeKind
+  readonly line: number
+}
+
+/**
+ * Every density and reference shape finding that would gate once `prefix` is
+ * listed, read from the files the audit reads. An absent folder carries none.
+ * Undefined when the tree cannot be listed, since an empty answer there would
+ * gate a corpus nobody measured.
+ */
+export async function findingsUnder(
+  root: string,
+  prefix: string,
+): Promise<BlockingFinding[] | undefined> {
+  const listed = await listRepositoryFiles(root)
+  if (!listed) return undefined
+
+  const under = listed.filter(
+    (rel) => rel.endsWith('.md') && rel.startsWith(prefix),
+  )
+  const found = await Promise.all(
+    under.map(async (rel) => {
+      const source = await readFile(join(root, rel), 'utf8')
+      const density = inDensityScope(rel)
+        ? densityFindings(bodyLines(source)).filter((finding) =>
+            densityGates(rel, finding.kind, [prefix], false),
+          )
+        : []
+      const shape = referenceShapeGates(rel, [prefix])
+        ? referenceShapeFindings(source)
+        : []
+      return [...density, ...shape].map((finding) => ({
+        path: rel,
+        kind: finding.kind,
+        line: finding.line,
+      }))
+    }),
+  )
+
+  return found.flat()
+}
+
+export type ScopeRootsResult =
+  | { readonly kind: 'exists' }
+  | { readonly kind: 'unavailable' }
+  | {
+      readonly kind: 'gated'
+      readonly gated: readonly string[]
+      readonly left: readonly { prefix: string; findings: number }[]
+    }
+
+/**
+ * Gates each of `GATED_SCOPE_ROOTS` that carries no finding, for a new
+ * project. A root with one is left out and named, since gating it would fail
+ * the first push on prose a scaffolder wrote. An existing config is a list
+ * someone chose, so it is never touched.
+ */
+export async function gateScopeRoots(root: string): Promise<ScopeRootsResult> {
+  if (existsSync(join(root, GATED_CONFIG_REL))) return { kind: 'exists' }
+
+  const gated: string[] = []
+  const left: { prefix: string; findings: number }[] = []
+
+  for (const prefix of GATED_SCOPE_ROOTS) {
+    const findings = await findingsUnder(root, prefix)
+    if (!findings) return { kind: 'unavailable' }
+    if (findings.length === 0) gated.push(prefix)
+    else left.push({ prefix, findings: findings.length })
+  }
+
+  writeGatedList(root, gated)
+  return { kind: 'gated', gated, left }
+}