@erclx/canon 5.7.0 → 5.9.0

package/src/docs/read.ts

@@ -12,10 +12,11 @@ const INDEX_TOPIC = 'index'
  * The context folder is read at every surface root, so a checkout the surface
  * move has not reached still resolves its own entries.
  */
-const ROOTS: readonly string[] = [
-  'docs',
-  ...SURFACE_ROOTS.map((root) => join(root, 'context')),
-]
+export const DOCS_ROOT = 'docs'
+export const CONTEXT_ROOTS: readonly string[] = SURFACE_ROOTS.map((root) =>
+  join(root, 'context'),
+)
+const ROOTS: readonly string[] = [DOCS_ROOT, ...CONTEXT_ROOTS]
 
 export interface ResolvedTopic {
   readonly path: string
@@ -96,14 +97,22 @@ function catalogedFolders(dir: string): string[] {
  * `resolveTopic` answers for and nothing else.
  */
 export function listTopics(root: string): string[] {
-  const named = ROOTS.map((dir) => collectNamed(root, dir))
-  const leaves = ROOTS.map((dir) => collectLeaves(root, dir))
+  const walked = ROOTS.map((dir) => walkEntries(root, dir))
 
-  const taken = new Set(named.flat())
+  const taken = new Set(
+    walked.flatMap((entries) =>
+      entries.filter((entry) => entry.kind !== 'leaf').map((e) => e.name),
+    ),
+  )
   const claimed = new Set<string>()
 
-  return ROOTS.flatMap((_, position) => {
-    const here = leaves[position] as string[]
+  return walked.flatMap((entries) => {
+    const named = entries
+      .filter((entry) => entry.kind !== 'leaf')
+      .map((entry) => entry.name)
+    const here = entries
+      .filter((entry) => entry.kind === 'leaf')
+      .map((entry) => entry.name)
     const reachable = [...new Set(here)].filter(
       (name) =>
         !taken.has(name) &&
@@ -112,25 +121,60 @@ export function listTopics(root: string): string[] {
     )
     for (const name of here) claimed.add(name)
 
-    return [...(named[position] as string[]), ...reachable].sort()
+    return [...named, ...reachable].sort()
   })
 }
 
-/** The sibling files and split folders of one root, which shadow every leaf. */
-function collectNamed(root: string, dir: string): string[] {
-  const cwd = join(root, dir)
-  if (!existsSync(cwd)) return []
+/**
+ * How an entry is named. A `file` is a sibling `<name>.md`, a `folder` is a
+ * split domain named by its folder and carried by its `index.md`, and a `leaf`
+ * is a sub-area file one level down, named by its bare filename.
+ */
+export type EntryKind = 'file' | 'folder' | 'leaf'
 
-  return [...markdownNames(cwd), ...catalogedFolders(cwd)]
+export interface WalkedEntry {
+  readonly name: string
+  readonly kind: EntryKind
+  /** The path under the project root, which is the catalog's `target`. */
+  readonly rel: string
 }
 
-/** One entry per occurrence, so a name carried twice is counted twice. */
-function collectLeaves(root: string, dir: string): string[] {
+/**
+ * Every entry one root offers, in the three kinds above, with a leaf counted
+ * once per occurrence so a name a folder pair both carry stays visible as a
+ * collision. A root that is absent offers nothing. This is the one reading of
+ * the tree, so `listTopics` and the docs catalog cannot disagree on membership.
+ */
+export function walkEntries(root: string, dir: string): WalkedEntry[] {
   const cwd = join(root, dir)
+  if (!existsSync(cwd)) return []
 
-  return catalogedFolders(cwd).flatMap((folder) =>
-    markdownNames(join(cwd, folder)),
+  const files = markdownNames(cwd).map(
+    (name): WalkedEntry => ({
+      name,
+      kind: 'file',
+      rel: join(dir, `${name}.md`),
+    }),
   )
+  const folders = catalogedFolders(cwd)
+  const split = folders.map(
+    (folder): WalkedEntry => ({
+      name: folder,
+      kind: 'folder',
+      rel: join(dir, folder, `${INDEX_TOPIC}.md`),
+    }),
+  )
+  const leaves = folders.flatMap((folder) =>
+    markdownNames(join(cwd, folder)).map(
+      (name): WalkedEntry => ({
+        name,
+        kind: 'leaf',
+        rel: join(dir, folder, `${name}.md`),
+      }),
+    ),
+  )
+
+  return [...files, ...split, ...leaves]
 }
 
 function markdownNames(dir: string): string[] {

package/src/gov/stacks.ts

@@ -94,7 +94,7 @@ export function expandStackEntry(root: string, entry: string): string[] {
 /**
  * Walks `extends` ancestors first, then the stack's own rules, deduped by
  * first appearance. Tooling's `resolveChain` returns full manifests nearest
- * first and carries `skipStack` truncation, so the two walks stay separate
+ * first and carries `skipStack` restriction, so the two walks stay separate
  * rather than fitting one shape to both.
  *
  * Dedupe runs on expanded names rather than on the entries, so a stack naming

package/src/help.ts

@@ -56,6 +56,7 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['records [cmd]', 'Session records (validate, size, push, pull)'],
       ['sessions [cmd]', 'Resolve live sessions to worktree and branch'],
       ['worktrees [cmd]', 'Reclaim worktrees whose branches merged'],
+      ['hooks [cmd]', 'Run the steps a git hook drives (post-merge)'],
       ['autoship [cmd]', 'Decide whether a changed set needs review'],
       ['pr [cmd]', 'Read a pull request (key-changes, head, checks)'],
       ['feedback', 'Write toolkit feedback from stdin'],
@@ -122,6 +123,7 @@ const EXAMPLES = [
   'canon sessions list --json',
   'canon worktrees list --json',
   'canon worktrees reclaim --dry-run',
+  'canon hooks post-merge',
   'canon secrets scan --json',
   'canon deps audit --json',
   'canon labels audit --json',

package/src/hooks/post-merge.ts

@@ -0,0 +1,331 @@
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/**
+ * One child `canon` call. Each step runs as its own process rather than
+ * in-process, so the plugin update after a reinstall runs the binary the
+ * upgrade just installed, and every verb keeps its own gates.
+ */
+export interface StepCall {
+  readonly args: readonly string[]
+  readonly cwd: string
+  readonly env: Record<string, string>
+}
+
+export interface StepResult {
+  readonly stdout: string
+  readonly exitCode: number
+}
+
+export type StepRunner = (call: StepCall) => Promise<StepResult>
+
+export interface PostMergeInput {
+  /** The main worktree root, where the board and the records live. */
+  readonly root: string
+  /** The worktree the pull happened in, which the reclaim refuses to remove. */
+  readonly cwd: string
+  readonly subjects: readonly string[]
+  /** Read for the `CANON_SKIP_*` switches. */
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly run: StepRunner
+  readonly write: (text: string) => void
+}
+
+/**
+ * The child verb each step runs, in run order. The command's help lists these
+ * and the landing page reads that help to say what a merge does, so the
+ * figure follows the steps this module actually runs.
+ */
+export const STEP_VERBS = {
+  archive: ['tasks', 'archive'],
+  push: ['records', 'push'],
+  reclaim: ['worktrees', 'reclaim'],
+  upgrade: ['upgrade'],
+  pluginUpdate: ['claude', 'plugin-update'],
+} as const satisfies Record<string, readonly string[]>
+
+type Fields = Record<string, unknown>
+
+const GIT_TIMEOUT_MS = 10_000
+
+/**
+ * Every pull request number the merge brought in. A squash carries `(#NNN)` at
+ * the end of its subject, and a release or a merge naming none yields nothing,
+ * which is what keeps the archive quiet on runs it has nothing to say about.
+ */
+export function pullRequestNumbers(subjects: readonly string[]): number[] {
+  return subjects.flatMap((subject) => {
+    const match = /\(#(\d+)\)\s*$/.exec(subject)
+    return match ? [Number(match[1])] : []
+  })
+}
+
+/**
+ * Every subject the pull brought in, not just the tip. One pull routinely
+ * fast-forwards over several merges, and reading HEAD alone would archive the
+ * last one's task and strand the rest. `git pull` sets ORIG_HEAD to the
+ * pre-merge tip, so the range is exactly what arrived, and a merge leaving no
+ * ORIG_HEAD falls back to the tip.
+ *
+ * A hook exports `GIT_DIR` and friends, which beat `-C`, so every read goes
+ * through `gitEnv()` to answer for the checkout `cwd` names.
+ */
+export async function readMergedSubjects(cwd: string): Promise<string[]> {
+  const options = {
+    reject: false,
+    timeout: GIT_TIMEOUT_MS,
+    env: gitEnv(),
+    extendEnv: false,
+  } as const
+
+  const origHead = await execa(
+    'git',
+    ['-C', cwd, 'rev-parse', '--verify', '--quiet', 'ORIG_HEAD'],
+    options,
+  )
+  const range = origHead.exitCode === 0 ? ['ORIG_HEAD..HEAD'] : ['-1', 'HEAD']
+  const log = await execa(
+    'git',
+    ['-C', cwd, 'log', ...range, '--pretty=%s', '--'],
+    options,
+  )
+  if (log.exitCode !== 0) return []
+
+  return log.stdout.split('\n').filter((line) => line.length > 0)
+}
+
+export const runCanon: StepRunner = async (call) => {
+  const result = await execa('canon', [...call.args], {
+    cwd: call.cwd,
+    env: call.env,
+    extendEnv: false,
+    reject: false,
+  })
+  return { stdout: result.stdout, exitCode: result.exitCode ?? 1 }
+}
+
+/**
+ * A child producing no parseable record is an older global binary carrying no
+ * such subcommand or flag, which stays quiet until a release lands.
+ */
+function parseRecord(stdout: string): Fields | undefined {
+  try {
+    const parsed: unknown = JSON.parse(stdout.trim())
+    return parsed !== null && typeof parsed === 'object'
+      ? (parsed as Fields)
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function text(fields: Fields, key: string): string | undefined {
+  const value = fields[key]
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function count(fields: Fields, key: string): number {
+  const value = fields[key]
+  return typeof value === 'number' ? value : 0
+}
+
+function archiveLines(
+  number: number,
+  result: StepResult,
+  fields: Fields,
+): string | undefined {
+  if (result.exitCode === 0) {
+    const task = text(fields, 'task')
+    if (task === undefined) return undefined
+
+    // A binary predating the relink pass carries no `relinkFailed`, which
+    // reads as empty.
+    const failed = Array.isArray(fields.relinkFailed)
+      ? fields.relinkFailed.flatMap((entry: unknown) =>
+          entry !== null &&
+          typeof entry === 'object' &&
+          typeof (entry as Fields).file === 'string'
+            ? [(entry as Fields).file as string]
+            : [],
+        )
+      : []
+    const relink =
+      failed.length > 0
+        ? `🔗 Links not repointed in: ${failed.join(',')}\n`
+        : ''
+    return `\n📦 Archived ${task}, closed by #${number}.\n${relink}\n`
+  }
+
+  // A refusal is ordinary here, since most merges close no task.
+  const reason = text(fields, 'reason')
+  if (reason === undefined || reason === 'no-match' || reason === 'no-board') {
+    return undefined
+  }
+  return (
+    `\n📋 Task not archived for #${number}: ${text(fields, 'message') ?? reason}\n` +
+    'Run /task-board to resolve it by hand.\n\n'
+  )
+}
+
+function pushLines(result: StepResult, fields: Fields): string | undefined {
+  if (result.exitCode === 0) {
+    const changed = count(fields, 'changed')
+    return changed > 0
+      ? `\n🗄️  Backed up ${changed} record path(s).\n\n`
+      : undefined
+  }
+
+  // No records history on this machine, which is every checkout that never
+  // ran the one-time setup.
+  const reason = text(fields, 'reason') ?? 'unknown'
+  if (reason === 'no-repository') return undefined
+  const hint =
+    reason === 'unsafe-payload'
+      ? 'Run canon records push to see the blocked paths.'
+      : 'Run canon records push when the remote is reachable.'
+  return `\n🗄️  Records not backed up: ${reason}\n${hint}\n\n`
+}
+
+/**
+ * The exit decides nothing here and the fields decide everything. A run that
+ * removes one worktree and fails on another exits 1 with a directory already
+ * deleted, so a report keyed on the exit would never name the removal.
+ */
+function reclaimLines(fields: Fields): string | undefined {
+  let lines = ''
+  const removed = count(fields, 'removed')
+  if (removed > 0) {
+    lines += `\n🧹 Reclaimed ${removed} worktree(s) whose pull request merged.\n\n`
+  }
+
+  // `gh-missing` answers on every merge forever on a machine without `gh`, so
+  // the hook header carries that gap rather than a line nobody acts on twice.
+  const reason = text(fields, 'reason')
+  const failed = count(fields, 'failed')
+  if (reason !== undefined && reason !== 'gh-missing') {
+    lines +=
+      `\n🧹 Worktrees not reclaimed: ${reason}\n` +
+      'Run canon worktrees list to read the state by hand.\n\n'
+  } else if (failed > 0) {
+    lines +=
+      `\n🧹 ${failed} worktree(s) could not be removed.\n` +
+      'Run canon worktrees reclaim to read which step failed.\n\n'
+  }
+  return lines.length > 0 ? lines : undefined
+}
+
+/**
+ * Shared by the binary reinstall and the plugin update. `current` is the
+ * ordinary outcome on most merges and stays quiet, and `quiet` names the
+ * refusal reasons that describe a permanent condition on the machine. `icon`
+ * carries its own trailing spacing, since the two glyphs render at different
+ * widths.
+ */
+function moveLines(
+  result: StepResult,
+  fields: Fields,
+  icon: string,
+  failure: string,
+  quiet: readonly string[],
+): string | undefined {
+  const message = text(fields, 'message')
+  if (message === undefined) return undefined
+
+  if (result.exitCode === 0) {
+    return fields.state === 'current' ? undefined : `\n${icon}${message}\n\n`
+  }
+
+  const reason = text(fields, 'reason')
+  if (reason !== undefined && quiet.includes(reason)) return undefined
+  return `\n${icon}${failure}: ${message}\n\n`
+}
+
+async function step(
+  input: PostMergeInput,
+  call: StepCall,
+  render: (result: StepResult, fields: Fields) => string | undefined,
+): Promise<void> {
+  let result: StepResult
+  try {
+    result = await input.run(call)
+  } catch {
+    return
+  }
+
+  const fields = parseRecord(result.stdout)
+  if (fields === undefined) return
+
+  const lines = render(result, fields)
+  if (lines !== undefined) input.write(lines)
+}
+
+/**
+ * Runs the five post-merge steps in order: archive, records push, reclaim,
+ * upgrade, plugin update. The reclaim sits before the upgrade, since the
+ * upgrade reinstalls the binary every later child runs under, and the two
+ * network-bound moves sit last so a slow registry delays nothing else.
+ *
+ * Never throws and reports nothing on the ordinary merge, since nobody is
+ * watching and a hook failing aborts nothing useful.
+ */
+export async function runPostMerge(input: PostMergeInput): Promise<void> {
+  const env = gitEnv()
+  const at = (args: string[], extra: Record<string, string> = {}) => ({
+    args,
+    cwd: input.cwd,
+    env: { ...env, ...extra },
+  })
+  const isSkipped = (name: string) => (input.env[name] ?? '').length > 0
+
+  for (const number of pullRequestNumbers(input.subjects)) {
+    await step(
+      input,
+      at([
+        ...STEP_VERBS.archive,
+        '--pull-request',
+        String(number),
+        '--root',
+        input.root,
+        '--json',
+      ]),
+      (result, fields) => archiveLines(number, result, fields),
+    )
+  }
+
+  await step(
+    input,
+    at([...STEP_VERBS.push, '--root', input.root, '--json']),
+    pushLines,
+  )
+
+  // No `--root` here, and that is load-bearing. The verb reads its own working
+  // directory to refuse the worktree it stands in, so a root would turn the
+  // running worktree into an ordinary candidate and let a pull inside a
+  // linked worktree delete the ground under itself.
+  if (!isSkipped('CANON_SKIP_RECLAIM')) {
+    await step(input, at([...STEP_VERBS.reclaim, '--json']), (_, fields) =>
+      reclaimLines(fields),
+    )
+  }
+
+  if (!isSkipped('CANON_SKIP_UPGRADE')) {
+    await step(
+      input,
+      at([...STEP_VERBS.upgrade, '--json'], { CANON_NON_INTERACTIVE: '1' }),
+      (result, fields) =>
+        moveLines(result, fields, '⬆️  ', 'CLI not upgraded', []),
+    )
+  }
+
+  if (!isSkipped('CANON_SKIP_PLUGIN_UPDATE')) {
+    await step(
+      input,
+      at([...STEP_VERBS.pluginUpdate, '--json']),
+      (result, fields) =>
+        moveLines(result, fields, '🔌 ', 'Plugin not updated', [
+          'no-claude',
+          'no-plugin',
+        ]),
+    )
+  }
+}

package/src/pr/evidence.ts

@@ -189,6 +189,19 @@ export function renderEvidenceBody(
   ].join('\n')
 }
 
+/**
+ * How many case rows a rendered body carries, read off the same row shape
+ * `renderEvidenceBody` writes. A row always ends in a head image, which a
+ * checklist line or a preview address never does.
+ */
+export function countEvidenceCases(body: string): number {
+  return (
+    body.match(
+      /^\| .+ \| (?:\*\(new\)\*|!\[\]\([^)]*\)) \| !\[\]\([^)]*\) \|$/gm,
+    )?.length ?? 0
+  )
+}
+
 export interface EvidenceComment {
   readonly url?: string
   readonly body: string
@@ -219,6 +232,14 @@ export function findEvidenceCommentId(
   return undefined
 }
 
+/** How many cases the marked comment already shows, zero when none is marked. */
+export function findEvidenceCaseCount(
+  comments: readonly EvidenceComment[],
+): number {
+  const marked = comments.find((comment) => hasEvidenceMarker(comment.body))
+  return marked === undefined ? 0 : countEvidenceCases(marked.body)
+}
+
 /**
  * The preview address the marked comment already opens with. A re-render
  * after a later push passes no address of its own, and carrying this one

package/src/records/validate.ts

@@ -7,6 +7,7 @@ import {
   recordDir as resolveRecordDir,
   recordDirs as resolveRecordDirs,
 } from '@/record-root'
+import { ATTRIBUTE_MARKER, governedPaths, readScope } from '@/standards/scope'
 import {
   TEACH_GLOSSARY,
   TEACH_MISSION,
@@ -1044,45 +1045,7 @@ function checkMemoryBody(
 const STANDARD_INDEX = 'index.md'
 const STANDARD_FIELDS = ['title', 'description'] as const
 
-const SCOPE_HEADING = /^##[ \t]+Scope[ \t]*$/
-const ANY_HEADING = /^#{1,6}[ \t]+\S/
 const DOES_NOT_GOVERN = 'Does not govern:'
-const ATTRIBUTE_MARKER = 'attribute standard'
-const CODE_SPAN = /`([^`]+)`/g
-
-interface Scope {
-  /** The first non-blank line under the heading, which is the statement. */
-  readonly statement: string
-  readonly lines: readonly string[]
-}
-
-export function readScope(text: string): Scope | undefined {
-  const lines = linesOutsideFences(text)
-  const opened = lines.findIndex((line) => SCOPE_HEADING.test(line.trim()))
-  if (opened === -1) return undefined
-
-  const body: string[] = []
-
-  for (const line of lines.slice(opened + 1)) {
-    if (ANY_HEADING.test(line.trim())) break
-    body.push(line)
-  }
-
-  const statement = body.find((line) => line.trim().length > 0)
-
-  return { statement: statement?.trim() ?? '', lines: body }
-}
-
-/**
- * The paths a scope statement declares, read the way `scripts/standards/list.sh`
- * reads them for the catalog's `appliesTo` field: backticked spans in the first
- * sentence alone. One sentence read two ways would let a standard pass here
- * while publishing a different jurisdiction to every consumer of the catalog.
- */
-export function governedPaths(statement: string): string[] {
-  const [sentence] = statement.split('. ')
-  return [...sentence.matchAll(CODE_SPAN)].map((match) => match[1])
-}
 
 /**
  * The words a governed path offers a filename. Each segment gives its own word

package/src/standards/list.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
+import { resolveAllStandards } from '@/standards/read'
+import { appliesTo } from '@/standards/scope'
+
+export interface StandardEntry {
+  readonly name: string
+  readonly description: string
+  readonly appliesTo: string[]
+  /** The whole file, frontmatter included. */
+  readonly content: string
+  /** The root-labeled path `canon standards <name>` would read. */
+  readonly source: string
+}
+
+/**
+ * Lists every standard a resolve reaches, the first root winning, so a project
+ * standard shows beside the toolkit's and a local override of a package name
+ * shows once, as the local copy.
+ */
+export function listStandardEntries(root: string): StandardEntry[] {
+  return resolveAllStandards(root).map(({ name, path, source }) => {
+    const content = readFileSync(path, 'utf8')
+
+    return {
+      name,
+      description: readField(parseFrontmatter(content), 'description') ?? '',
+      appliesTo: appliesTo(content),
+      content,
+      source,
+    }
+  })
+}

package/src/standards/read.ts

@@ -95,6 +95,19 @@ export function listStandards(root: string): string[] {
   return [...names].sort()
 }
 
+/**
+ * Pairs each listed name with the copy a resolve would read, so a catalog shows
+ * what `canon standards <name>` prints rather than every file a root holds.
+ */
+export function resolveAllStandards(
+  root: string,
+): Array<ResolvedStandard & { readonly name: string }> {
+  return listStandards(root).flatMap((name) => {
+    const resolved = resolveStandard(root, name)
+    return resolved ? [{ name, ...resolved }] : []
+  })
+}
+
 export function readStandard(standard: ResolvedStandard): string {
   return stripFrontmatter(readFileSync(standard.path, 'utf8'))
 }

package/src/standards/scope.ts

@@ -0,0 +1,56 @@
+import { linesOutsideFences } from '@/markdown/scan'
+
+const SCOPE_HEADING = /^##[ \t]+Scope[ \t]*$/
+const ANY_HEADING = /^#{1,6}[ \t]+\S/
+const CODE_SPAN = /`([^`]+)`/g
+
+/** What an attribute standard says of itself, since it names no path. */
+export const ATTRIBUTE_MARKER = 'attribute standard'
+
+export interface Scope {
+  /** The first non-blank line under the heading, which is the statement. */
+  readonly statement: string
+  readonly lines: readonly string[]
+}
+
+export function readScope(text: string): Scope | undefined {
+  const lines = linesOutsideFences(text)
+  const opened = lines.findIndex((line) => SCOPE_HEADING.test(line.trim()))
+  if (opened === -1) return undefined
+
+  const body: string[] = []
+
+  for (const line of lines.slice(opened + 1)) {
+    if (ANY_HEADING.test(line.trim())) break
+    body.push(line)
+  }
+
+  const statement = body.find((line) => line.trim().length > 0)
+
+  return { statement: statement?.trim() ?? '', lines: body }
+}
+
+/**
+ * The paths a scope statement declares: backticked spans in the first sentence
+ * alone. The catalog's `appliesTo` field and the records gate both read the
+ * statement through this, since one sentence read two ways would let a standard
+ * pass the gate while publishing a different jurisdiction to every consumer.
+ */
+export function governedPaths(statement: string): string[] {
+  const [sentence] = statement.split('. ')
+  return [...sentence.matchAll(CODE_SPAN)].map((match) => match[1])
+}
+
+/**
+ * The jurisdiction a standard publishes. The marker is read only where the
+ * first sentence backticks nothing, so a statement naming a path publishes that
+ * path however the rest of it describes itself. An empty array means the
+ * statement did not parse, which consumers report rather than skip.
+ */
+export function appliesTo(text: string): string[] {
+  const statement = readScope(text)?.statement ?? ''
+  const paths = governedPaths(statement)
+
+  if (paths.length === 0 && statement.includes(ATTRIBUTE_MARKER)) return ['*']
+  return paths
+}