@erclx/canon 5.33.0 → 5.34.0

package/src/feedback/body.ts

@@ -18,13 +18,18 @@ export const REQUIRED_FIELDS = ['Surface', 'Observed', 'Proposed fix'] as const
  * retire, and the validator would then enforce nothing.
  */
 const FIELD_HEADING = /^###\s+(.+?)\s*$/
-const FENCE = /^\s*(```|~~~)/
+const FENCE = /^\s*(`{3,}|~{3,})(.*)$/
+
+interface OpenFence {
+  readonly marker: string
+  readonly length: number
+}
 
 export function parseSections(body: string): Map<string, string> {
   const sections = new Map<string, string>()
   let heading: string | undefined
   let lines: string[] = []
-  let fenced = false
+  let fence: OpenFence | undefined
 
   const flush = (): void => {
     if (heading === undefined) return
@@ -34,9 +39,25 @@ export function parseSections(body: string): Map<string, string> {
   for (const line of body.split('\n')) {
     // A Repro field routinely carries a fenced block, and a `###` comment
     // inside one is shell rather than the next field. Reading it as a heading
-    // splits the section and drops everything under it.
-    if (FENCE.test(line)) fenced = !fenced
-    const match = fenced ? null : line.match(FIELD_HEADING)
+    // splits the section and drops everything under it. A Suggested shape
+    // wraps a template that holds its own fence in a longer one, so a fence
+    // closes only on the same marker at least as long, per CommonMark.
+    const fenceMatch = line.match(FENCE)
+    const run = fenceMatch?.[1]
+    if (run !== undefined) {
+      const marker = run.charAt(0)
+      const isBare = (fenceMatch?.[2] ?? '').trim() === ''
+      if (fence === undefined) {
+        fence = { marker, length: run.length }
+      } else if (
+        isBare &&
+        marker === fence.marker &&
+        run.length >= fence.length
+      ) {
+        fence = undefined
+      }
+    }
+    const match = fence ? null : line.match(FIELD_HEADING)
     if (match?.[1] === undefined) {
       lines.push(line)
       continue

package/src/gate/measures.ts

@@ -104,28 +104,6 @@ const info = (text: string): Emission => ({ kind: 'info', text })
 const warn = (text: string): Emission => ({ kind: 'warn', text })
 const output = (text: string): Emission => ({ kind: 'output', text })
 
-/**
- * Rules no stack reaches, sorted the way `canon gov list` emits them.
- * `260-shadcn` and `320-tanstack-query` are opt-in libraries a project may not
- * want.
- *
- * `130-go`, `140-php`, `335-testing-go`, and `336-testing-php` are opt-in by
- * `--add` until a Go or PHP stack ships, which `target-setup` reaches by
- * matching a detected language against each rule's description.
- *
- * All are recorded here rather than in a config file: the list is what a
- * reader compares a new arrival against, and a config file would absorb the
- * arrival silently.
- */
-export const GOV_EXPECTED_UNREFERENCED = [
-  '130-go',
-  '140-php',
-  '260-shadcn',
-  '320-tanstack-query',
-  '335-testing-go',
-  '336-testing-php',
-]
-
 /**
  * Scenarios declaring no expectation, taken from `canon sandbox coverage`
  * against a clean tree. Raising it is a deliberate edit that says which
@@ -170,16 +148,19 @@ function parseJson(payload: string): unknown {
 }
 
 /**
- * A rule no stack names is a report rather than a gate. All three standing
- * findings ship that way on purpose, so failing would fail every push over the
- * deliberate case and teach a reader to route around the stage.
+ * A rule no stack reaches arrives at a project only through `canon gov
+ * detect`, so each one needs a `governance/detect.toml` entry or nothing ever
+ * proposes it. A key naming a retired rule fails too, since it would hide from
+ * the rename sweep that keys the file by basename.
+ *
+ * The check replaced a fixed list of expected unreferenced rules. Once the
+ * stacks are thin, that list is most of the catalog and would be rewritten on
+ * every new rule, which is a list nobody reads.
  *
- * The catalog is parsed here rather than piped through `bun --eval`, which the
- * script this replaces had to do and had to guard: that interpreter exits 0
- * when its script throws while stdin is a pipe, so a payload that is not JSON
- * printed nothing and exited clean, and empty already means every rule is
- * reached. A sentinel string carried success past that. Parsing in process
- * leaves the two states distinguishable with nothing to carry.
+ * The catalog is parsed here rather than piped through `bun --eval`, whose
+ * interpreter exits 0 when its script throws while stdin is a pipe, so a
+ * payload that is not JSON would print nothing and read as every rule
+ * reached. Parsing in process keeps the two states distinguishable.
  */
 export const unreferencedRules: Measure = async (ctx) => {
   const { exitCode, stdout } = await ctx.cli(['gov', 'list', '--json'])
@@ -190,34 +171,67 @@ export const unreferencedRules: Measure = async (ctx) => {
     }
   }
 
-  const record = parseJson(stdout) as { unreferenced?: unknown } | undefined
-  if (!Array.isArray(record?.unreferenced)) {
+  const record = parseJson(stdout) as
+    | { unreferenced?: unknown; rules?: unknown; staleDetect?: unknown }
+    | undefined
+  if (
+    !Array.isArray(record?.unreferenced) ||
+    !Array.isArray(record?.rules) ||
+    !Array.isArray(record?.staleDetect)
+  ) {
     return {
       emissions: [],
       unmeasured:
-        'The governance catalog carried no readable unreferenced list.',
+        'The governance catalog carried no readable unreferenced, rules, or staleDetect list.',
     }
   }
 
+  const detected = new Set(
+    record.rules
+      .filter(
+        (rule): rule is { name: string; detect: unknown } =>
+          typeof rule === 'object' &&
+          rule !== null &&
+          typeof (rule as { name?: unknown }).name === 'string',
+      )
+      .filter((rule) => rule.detect !== null && rule.detect !== undefined)
+      .map((rule) => rule.name),
+  )
   const unreferenced = record.unreferenced.map(String)
-  if (unreferenced.length === 0) {
-    return { emissions: [info('Every rule is reached by a stack')] }
+  const undetected = unreferenced.filter((rule) => !detected.has(rule))
+  const stale = record.staleDetect.map(String)
+
+  const emissions: Emission[] = []
+  if (undetected.length > 0) {
+    emissions.push(
+      warn(
+        `Reached by no stack and proposed by nothing: ${undetected.join(' ')}`,
+      ),
+      warn(
+        'Name each in a stack, or add a table to governance/detect.toml with the deps or files that mark a project as wanting it.',
+      ),
+    )
+  }
+  if (stale.length > 0) {
+    emissions.push(
+      warn(`governance/detect.toml names no live rule: ${stale.join(' ')}`),
+      warn('Rename the key to the rule it became, or delete the table.'),
+    )
   }
 
-  const listed = unreferenced.join(' ')
-  if (listed === GOV_EXPECTED_UNREFERENCED.join(' ')) {
+  if (emissions.length > 0) {
     return {
-      emissions: [
-        info(`Reached by no stack: ${listed} (each recorded above with why)`),
-      ],
+      emissions,
+      failure: 'An opt-in rule has no route to a project',
     }
   }
 
   return {
     emissions: [
-      warn(`Reached by no stack: ${listed}`),
-      warn(
-        `Expected: ${GOV_EXPECTED_UNREFERENCED.join(' ')}. Name the new rule in a stack, or update GOV_EXPECTED_UNREFERENCED in src/gate/measures.ts and say why it reaches no stack.`,
+      info(
+        unreferenced.length === 0
+          ? 'Every rule is reached by a stack'
+          : `${plural(unreferenced.length, 'rule')} reached by no stack, each proposed by governance/detect.toml`,
       ),
     ],
   }

package/src/gate/stages.ts

@@ -328,10 +328,9 @@ export const STAGES: readonly Stage[] = [
     success: 'Capability seeding clean',
   },
   {
-    // A stack entry naming a rule folder takes every rule in it, which is what
-    // stops a new rule from needing a second edit to reach a target. The
-    // failure it leaves open is a rule authored into a folder no stack names,
-    // which `canon gov install` never reaches on its own.
+    // A rule no stack names reaches a target only when `canon gov detect`
+    // proposes it, so every such rule needs a governance/detect.toml entry,
+    // and every key there has to name a live rule.
     id: 'unreferenced-rules',
     label: 'Unreferenced rules',
     checks: [{ kind: 'measure', measure: unreferencedRules }],

package/src/gov/detect.ts

@@ -0,0 +1,301 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { listRepositoryFiles } from '@/git/files'
+import { indexRuleSources } from '@/gov/install'
+import { resolveRules } from '@/gov/stacks'
+
+/** One table of `governance/detect.toml`. */
+export interface DetectEntry {
+  readonly rule: string
+  readonly deps: readonly string[]
+  readonly files: readonly string[]
+}
+
+/**
+ * What matched for one proposal. `path` is the manifest a dependency was read
+ * from, or the path a file glob matched, so a reader can open the evidence.
+ */
+export interface Evidence {
+  readonly kind: 'dep' | 'file'
+  readonly match: string
+  readonly path: string
+}
+
+export interface Proposal {
+  readonly rule: string
+  readonly evidence: readonly Evidence[]
+}
+
+export type DetectResult =
+  | { readonly ok: true; readonly proposals: readonly Proposal[] }
+  | { readonly ok: false; readonly missingStack: string }
+
+/** How deep detection reads, matching `target-setup`'s marker walk. */
+const MAX_DIRS = 2
+
+/** Trees an outside-git walk skips, since each carries manifests of its own. */
+const SKIPPED_DIRS = new Set(['.git', 'node_modules', 'vendor', '.venv'])
+
+export function detectFilePath(root: string): string {
+  return join(root, 'governance', 'detect.toml')
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === 'string')
+    : []
+}
+
+/** Reads every table in file order. An absent file reads as no entries. */
+export function loadDetectEntries(root: string): DetectEntry[] {
+  const path = detectFilePath(root)
+  if (!existsSync(path)) return []
+
+  const parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+    string,
+    unknown
+  >
+
+  return Object.entries(parsed).flatMap(([rule, table]) => {
+    if (typeof table !== 'object' || table === null) return []
+    const fields = table as Record<string, unknown>
+    return [
+      { rule, deps: stringList(fields.deps), files: stringList(fields.files) },
+    ]
+  })
+}
+
+/** Keys naming no rule under `governance/rules/`, sorted. */
+export function staleDetectKeys(root: string): string[] {
+  const live = indexRuleSources(root)
+  return loadDetectEntries(root)
+    .map((entry) => entry.rule)
+    .filter((rule) => !live.has(rule))
+    .sort()
+}
+
+function depth(path: string): number {
+  return path.split('/').length - 1
+}
+
+/** Files to depth two when the target is not a git checkout. */
+function walkFiles(target: string): string[] {
+  const files: string[] = []
+
+  const visit = (rel: string): void => {
+    const abs = rel === '' ? target : join(target, rel)
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      const child = rel === '' ? entry.name : `${rel}/${entry.name}`
+      if (entry.isDirectory()) {
+        if (SKIPPED_DIRS.has(entry.name)) continue
+        if (depth(child) < MAX_DIRS + 1) visit(child)
+      } else if (entry.isFile()) {
+        files.push(child)
+      }
+    }
+  }
+
+  visit('')
+  return files.sort()
+}
+
+/**
+ * The paths a file glob is matched against: every file to depth two, plus
+ * every folder on the way to any listed file, so an evidence folder such as
+ * `.github/workflows` matches without naming the file inside it.
+ */
+async function candidatePaths(target: string): Promise<string[]> {
+  const listed = (await listRepositoryFiles(target)) ?? walkFiles(target)
+  const paths = new Set<string>()
+
+  for (const file of listed) {
+    let dir = dirname(file)
+    while (dir !== '.') {
+      if (depth(dir) <= MAX_DIRS) paths.add(dir)
+      dir = dirname(dir)
+    }
+    if (depth(file) <= MAX_DIRS) paths.add(file)
+  }
+
+  return [...paths].sort()
+}
+
+/** A PEP 508 requirement's distribution name, normalized per PEP 503. */
+function pythonName(requirement: string): string {
+  const name = requirement.trim().split(/[\s<>=!~;[(@,]/)[0] ?? ''
+  return name.toLowerCase().replace(/[_.]+/g, '-')
+}
+
+function objectKeys(value: unknown): string[] {
+  return typeof value === 'object' && value !== null ? Object.keys(value) : []
+}
+
+function packageJsonDeps(text: string): string[] {
+  const parsed = JSON.parse(text) as Record<string, unknown>
+  return [
+    ...objectKeys(parsed.dependencies),
+    ...objectKeys(parsed.devDependencies),
+  ]
+}
+
+function composerDeps(text: string): string[] {
+  const parsed = JSON.parse(text) as Record<string, unknown>
+  return [...objectKeys(parsed.require), ...objectKeys(parsed['require-dev'])]
+}
+
+function pyprojectDeps(text: string): string[] {
+  const parsed = Bun.TOML.parse(text) as Record<string, unknown>
+  const project = (parsed.project ?? {}) as Record<string, unknown>
+  const requirements = [
+    ...stringList(project.dependencies),
+    ...Object.values(
+      (project['optional-dependencies'] ?? {}) as Record<string, unknown>,
+    ).flatMap(stringList),
+    ...Object.values(
+      (parsed['dependency-groups'] ?? {}) as Record<string, unknown>,
+    ).flatMap(stringList),
+  ]
+
+  const poetry = ((parsed.tool ?? {}) as Record<string, unknown>).poetry as
+    | Record<string, unknown>
+    | undefined
+  const groups = (poetry?.group ?? {}) as Record<string, unknown>
+  const poetryNames = [
+    ...objectKeys(poetry?.dependencies),
+    ...objectKeys(poetry?.['dev-dependencies']),
+    ...Object.values(groups).flatMap((group) =>
+      objectKeys((group as Record<string, unknown>)?.dependencies),
+    ),
+  ]
+
+  return [...requirements, ...poetryNames].map(pythonName)
+}
+
+function goModDeps(text: string): string[] {
+  const names: string[] = []
+  let inBlock = false
+
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/\/\/.*$/, '').trim()
+    if (inBlock) {
+      if (line === ')') inBlock = false
+      else if (line !== '') names.push(line.split(/\s+/)[0] ?? '')
+    } else if (/^require\s*\($/.test(line)) {
+      inBlock = true
+    } else if (line.startsWith('require ')) {
+      names.push(line.split(/\s+/)[1] ?? '')
+    }
+  }
+
+  return names.filter(Boolean)
+}
+
+/** Python names are normalized on read, so `detect.toml` lists them lowercase. */
+const READERS: Readonly<Record<string, (text: string) => string[]>> = {
+  'package.json': packageJsonDeps,
+  'composer.json': composerDeps,
+  'pyproject.toml': pyprojectDeps,
+  'go.mod': goModDeps,
+}
+
+/**
+ * Every dependency name a manifest to depth two declares, mapped to the
+ * manifests declaring it. A manifest that does not parse contributes nothing
+ * rather than failing the run, since one broken fixture folder should not cost
+ * a project every other proposal.
+ */
+function readDependencies(
+  target: string,
+  paths: readonly string[],
+): Map<string, string[]> {
+  const deps = new Map<string, string[]>()
+
+  for (const path of paths) {
+    const reader = READERS[basename(path)]
+    if (reader === undefined) continue
+
+    let declared: string[]
+    try {
+      declared = reader(readFileSync(join(target, path), 'utf8'))
+    } catch {
+      continue
+    }
+
+    for (const dep of declared) {
+      const holders = deps.get(dep) ?? []
+      if (!holders.includes(path)) holders.push(path)
+      deps.set(dep, holders)
+    }
+  }
+
+  return deps
+}
+
+/** A glob carrying no wildcard names one path rather than a pattern. */
+function isLiteral(pattern: string): boolean {
+  return !/[*?[\]{}]/.test(pattern)
+}
+
+/**
+ * A literal pattern is also tested on disk, since evidence such as
+ * `.canon/canvas` sits in a folder a target's own `.gitignore` excludes, and
+ * the git listing never carries it.
+ */
+function matchEntry(
+  entry: DetectEntry,
+  target: string,
+  deps: ReadonlyMap<string, readonly string[]>,
+  paths: readonly string[],
+): Evidence[] {
+  const evidence: Evidence[] = []
+
+  for (const dep of entry.deps) {
+    const holders = deps.get(dep) ?? []
+    for (const path of holders) evidence.push({ kind: 'dep', match: dep, path })
+  }
+
+  for (const pattern of entry.files) {
+    const glob = new Bun.Glob(pattern)
+    const hit =
+      paths.find((path) => glob.match(path)) ??
+      (isLiteral(pattern) && existsSync(join(target, pattern))
+        ? pattern
+        : undefined)
+    if (hit !== undefined)
+      evidence.push({ kind: 'file', match: pattern, path: hit })
+  }
+
+  return evidence
+}
+
+/**
+ * Proposes each opt-in rule whose evidence the target holds. A rule `stack`
+ * already resolves is left out, since proposing it would install nothing, and
+ * a key naming no live rule is skipped rather than proposed, which the
+ * `unreferenced-rules` gate stage reports on the toolkit side.
+ */
+export async function detectRules(
+  root: string,
+  target: string,
+  stack?: string,
+): Promise<DetectResult> {
+  let covered = new Set<string>()
+  if (stack !== undefined) {
+    const resolution = resolveRules(root, stack)
+    if (!resolution.ok) return resolution
+    covered = new Set(resolution.rules)
+  }
+
+  const live = indexRuleSources(root)
+  const paths = await candidatePaths(target)
+  const deps = readDependencies(target, paths)
+
+  const proposals = loadDetectEntries(root)
+    .filter((entry) => live.has(entry.rule) && !covered.has(entry.rule))
+    .flatMap((entry) => {
+      const evidence = matchEntry(entry, target, deps, paths)
+      return evidence.length === 0 ? [] : [{ rule: entry.rule, evidence }]
+    })
+
+  return { ok: true, proposals }
+}

package/src/gov/list.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { basename, join } from 'node:path'
+import { loadDetectEntries, staleDetectKeys } from '@/gov/detect'
 import { listRuleSourcePaths, rulesSourceDir } from '@/gov/install'
 import {
   expandStackEntry,
@@ -15,17 +16,26 @@ export interface StackEntry {
   readonly rules: string[]
 }
 
+/** The evidence `governance/detect.toml` records for one opt-in rule. */
+export interface RuleDetect {
+  readonly deps: readonly string[]
+  readonly files: readonly string[]
+}
+
 export interface RuleEntry {
   readonly name: string
   readonly domain: string
   readonly description: string
   readonly paths: string[] | null
+  readonly detect: RuleDetect | null
 }
 
 export interface GovCatalog {
   readonly stacks: StackEntry[]
   readonly rules: RuleEntry[]
   readonly unreferenced: string[]
+  /** `detect.toml` keys naming no live rule, which the gate fails on. */
+  readonly staleDetect: string[]
 }
 
 /**
@@ -64,24 +74,34 @@ export function buildStackEntries(root: string): StackEntry[] {
 
 /**
  * Reads the catalog straight off the source tree. A rule's domain is the
- * subdirectory it sits in, which is the band grouping install preserves.
+ * subdirectory it sits in, which is the band grouping install preserves, and
+ * its `detect` entry is the evidence that proposes it, null for a rule
+ * `detect.toml` does not name.
  */
 export function buildRuleEntries(root: string): RuleEntry[] {
   const rulesRoot = rulesSourceDir(root)
+  const detect = new Map(
+    loadDetectEntries(root).map((entry) => [
+      entry.rule,
+      { deps: entry.deps, files: entry.files },
+    ]),
+  )
 
   return listRuleSourcePaths(root).map((rel) => {
     const frontmatter = parseFrontmatter(
       readFileSync(join(rulesRoot, rel), 'utf8'),
     )
     const paths = frontmatter?.fields.paths
+    const name = basename(rel, '.md')
 
     return {
-      name: basename(rel, '.md'),
+      name,
       domain: rel.includes('/') ? rel.slice(0, rel.indexOf('/')) : '',
       description: readField(frontmatter, 'description') ?? '',
       paths: Array.isArray(paths)
         ? paths.filter((entry): entry is string => typeof entry === 'string')
         : null,
+      detect: detect.get(name) ?? null,
     }
   })
 }
@@ -91,6 +111,7 @@ export function buildGovCatalog(root: string): GovCatalog {
     stacks: buildStackEntries(root),
     rules: buildRuleEntries(root),
     unreferenced: unreferencedRules(root),
+    staleDetect: staleDetectKeys(root),
   }
 }
 

package/src/gov/stacks.ts

@@ -207,3 +207,12 @@ export function mergeExtraRules(
 
   return merged
 }
+
+/**
+ * Resolves `--add` names with no stack under them. It runs the same merge as
+ * the stack path against an empty list, so an add with no stack and a layered one
+ * split and dedupe their names identically.
+ */
+export function resolveExtraRules(add: string): string[] {
+  return mergeExtraRules([], add)
+}