@erclx/canon 5.7.0 → 5.9.0

package/src/commands/pr.ts

@@ -26,6 +26,7 @@ import {
   withMergeState,
 } from '@/pr/checks'
 import {
+  findEvidenceCaseCount,
   findEvidenceChecklist,
   findEvidenceCommentId,
   findEvidenceLocal,
@@ -173,20 +174,21 @@ const PULL_REFUSALS: Record<PullRefusal | HeadRefusal, string> = {
 type EvidenceRefusal =
   | 'gh-failed'
   | 'no-base'
-  | 'unreadable-tree'
   | 'unreadable-changes'
   | 'unreadable-checklist'
+  | 'would-empty'
 
 const EVIDENCE_REFUSALS: Record<EvidenceRefusal, string> = {
   'gh-failed':
     'gh could not answer for this repository. Name the pull request number.',
   'unreadable-checklist':
     'The file named by --checklist could not be read, or holds nothing. Rendering without it would drop the only copy, since the caller deletes the handoff once a post reports success.',
-  'no-base': 'No base resolves against the trunk. Fetch origin and re-run.',
-  'unreadable-tree':
-    'git could not read the tree at the base commit, so no path could be judged added or changed.',
+  'no-base':
+    'GitHub reported no merge base for this pull request, so no path could be judged added or changed.',
   'unreadable-changes':
-    'git could not list what this branch changed, so the set is unknown.',
+    'GitHub could not list what this pull request changed, so the set is unknown.',
+  'would-empty':
+    'This render holds no cases and the marked comment holds some, so posting it would replace a comparison with an empty one. Edit the comment by hand if every case was removed on purpose.',
 }
 
 /** Why the read produced no comparison, ahead of the ones the compare owns. */
@@ -427,11 +429,13 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Compares the merge base with the trunk against the current head, never',
-        'the previous push against the new one, so the comment never claims more',
-        'than the branch currently shows. A path counts as evidence when one of',
-        'its segments is literally `evidence` and the filename carries an image',
-        'extension (png, jpg, jpeg, gif, webp, avif, svg). A README, a capture',
+        "Compares the pull request's merge base against its head, both read over",
+        'the API for the number named, so the record is the same from any',
+        'checkout. It never compares the previous push against the new one, so',
+        'the comment never claims more than the pull request currently shows.',
+        'A path counts as evidence when one of its segments is literally',
+        '`evidence` and the filename carries an image extension (png, jpg,',
+        'jpeg, gif, webp, avif, svg). A README, a capture',
         'script, or a raw data file kept beside the images is left out rather',
         'than rendered as a broken embed.',
         '',
@@ -440,6 +444,8 @@ export function register(program: Command): void {
         '               comment already exists and should be edited in place',
         '  no-evidence  nothing in the diff carries an evidence/ segment, which',
         '               is an ordinary, silent no-op rather than a refusal',
+        '  would-empty  the render holds no cases and the marked comment holds',
+        '               some, so no body is printed and a person edits the comment',
         '',
         "--preview puts the address on the body's first line. With no evidence",
         'in the diff, the body is that line and the marker alone, reported as',
@@ -1346,21 +1352,63 @@ async function runReviewState(
 }
 
 /**
- * Every path `git ls-tree` reports for `ref`, or undefined when the read
- * failed. One call for the whole tree rather than one `cat-file -e` per
- * evidence path, since existence at base is checked once per changed path and
- * a batch read is one round trip instead of many.
+ * The paths a pull request changed that still exist at its head, each tagged
+ * with whether the pull request added it, read through the paginated files
+ * endpoint so the set is the same from any checkout and never capped at the
+ * first view. `renamed` and `copied` count as added, since the new path has no
+ * counterpart at the merge base. Returns undefined when the read fails, which
+ * refuses rather than rendering a short set.
  */
-async function listTreePaths(
-  root: string,
-  ref: string,
-): Promise<Set<string> | undefined> {
-  const result = await $`git -C ${root} ls-tree -r --name-only ${ref}`
-    .env(gitEnv())
-    .quiet()
-    .nothrow()
-  if (result.exitCode !== 0) return undefined
-  return new Set(result.text().split('\n').filter(Boolean))
+async function listPullFiles(
+  cwd: string,
+  number: number,
+): Promise<ReadonlyMap<string, boolean> | undefined> {
+  const stdout = await gh(cwd, [
+    'api',
+    '--paginate',
+    `repos/{owner}/{repo}/pulls/${number}/files`,
+    '--jq',
+    '.[] | "\(.status)\t\(.filename)"',
+  ])
+  if (stdout === null) return undefined
+  const files = new Map<string, boolean>()
+  for (const line of stdout.split('\n').filter(Boolean)) {
+    const [status, path] = line.split('\t')
+    if (status === undefined || path === undefined || status === 'removed') {
+      continue
+    }
+    files.set(path, status !== 'modified' && status !== 'changed')
+  }
+  return files
+}
+
+/**
+ * The commit the pull request diverged from its base at, from the compare
+ * endpoint, since a checkout on another branch resolves its own trunk tip
+ * instead and the base image links would then describe the wrong commit.
+ */
+async function readPullMergeBase(
+  cwd: string,
+  number: number,
+  head: string,
+): Promise<string | undefined> {
+  const baseRef = await gh(cwd, [
+    'pr',
+    'view',
+    String(number),
+    '--json',
+    'baseRefName',
+    '--jq',
+    '.baseRefName',
+  ])
+  if (baseRef === null || baseRef.trim() === '') return undefined
+  const sha = await gh(cwd, [
+    'api',
+    `repos/{owner}/{repo}/compare/${baseRef.trim()}...${head}`,
+    '--jq',
+    '.merge_base_commit.sha',
+  ])
+  return sha === null || sha.trim() === '' ? undefined : sha.trim()
 }
 
 async function runEvidence(
@@ -1404,16 +1452,20 @@ async function runEvidence(
     )
   }
 
-  const base = await resolveBaseRef(root)
-  if (base === undefined) {
-    return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
+  if (identity.number === undefined) {
+    return refuseWith(
+      'gh-failed',
+      EVIDENCE_REFUSALS['gh-failed'],
+      emitJson,
+      root,
+    )
   }
 
-  const [changed, baseTree] = await Promise.all([
-    listChangedFiles(root, base),
-    listTreePaths(root, base),
+  const [pullFiles, base] = await Promise.all([
+    listPullFiles(root, identity.number),
+    readPullMergeBase(root, identity.number, identity.head),
   ])
-  if (changed === undefined) {
+  if (pullFiles === undefined) {
     return refuseWith(
       'unreadable-changes',
       EVIDENCE_REFUSALS['unreadable-changes'],
@@ -1421,61 +1473,57 @@ async function runEvidence(
       root,
     )
   }
-  if (baseTree === undefined) {
-    return refuseWith(
-      'unreadable-tree',
-      EVIDENCE_REFUSALS['unreadable-tree'],
-      emitJson,
-      root,
-    )
+  if (base === undefined) {
+    return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
   }
 
-  const grouped = await groupEvidence(changed, async (path) =>
-    baseTree.has(path),
+  const grouped = await groupEvidence(
+    [...pullFiles.keys()],
+    async (path) => pullFiles.get(path) === false,
   )
 
+  let existingCases = 0
   let commentId: number | undefined
   let carriedPreview: string | undefined
   let carriedChecklist: string | undefined
   let carriedLocal: string | undefined
-  if (identity.number !== undefined) {
-    const commentsRow = await gh(root, [
-      'pr',
-      'view',
-      String(identity.number),
-      '--json',
-      'comments',
-    ])
-    // An unread thread refuses rather than rendering, since a body built
-    // without it knows neither the comment to edit nor the preview address
-    // to carry, and posting it would duplicate the comment and drop the link.
-    // It refuses ahead of no-evidence too, so that record never reports an
-    // absent field it did not read.
-    let comments: readonly { url?: string; body: string }[] | undefined
-    if (commentsRow !== null) {
-      try {
-        comments = (
-          JSON.parse(commentsRow) as {
-            comments?: readonly { url?: string; body: string }[]
-          }
-        ).comments
-      } catch {
-        comments = undefined
-      }
-    }
-    if (comments === undefined) {
-      return refuseWith(
-        'gh-failed',
-        EVIDENCE_REFUSALS['gh-failed'],
-        emitJson,
-        root,
-      )
+  const commentsRow = await gh(root, [
+    'pr',
+    'view',
+    String(identity.number),
+    '--json',
+    'comments',
+  ])
+  // An unread thread refuses rather than rendering, since a body built
+  // without it knows neither the comment to edit nor the preview address
+  // to carry, and posting it would duplicate the comment and drop the link.
+  // It refuses ahead of no-evidence too, so that record never reports an
+  // absent field it did not read.
+  let comments: readonly { url?: string; body: string }[] | undefined
+  if (commentsRow !== null) {
+    try {
+      comments = (
+        JSON.parse(commentsRow) as {
+          comments?: readonly { url?: string; body: string }[]
+        }
+      ).comments
+    } catch {
+      comments = undefined
     }
-    commentId = findEvidenceCommentId(comments)
-    carriedPreview = findEvidencePreview(comments)
-    carriedChecklist = findEvidenceChecklist(comments)
-    carriedLocal = findEvidenceLocal(comments)
   }
+  if (comments === undefined) {
+    return refuseWith(
+      'gh-failed',
+      EVIDENCE_REFUSALS['gh-failed'],
+      emitJson,
+      root,
+    )
+  }
+  commentId = findEvidenceCommentId(comments)
+  existingCases = findEvidenceCaseCount(comments)
+  carriedPreview = findEvidencePreview(comments)
+  carriedChecklist = findEvidenceChecklist(comments)
+  carriedLocal = findEvidenceLocal(comments)
 
   // What the marked comment already shows a reviewer, kept apart from the
   // flags this call passed so a reader learns what is posted.
@@ -1543,6 +1591,28 @@ async function runEvidence(
 
   const caseCount = states.reduce((n, s) => n + s.items.length, 0)
 
+  // A render with no cases cannot tell a removal from a short read, so it
+  // never replaces a comment that carries some. The record keeps the comment
+  // id and the carried fields so the caller can still edit by hand.
+  if (caseCount === 0 && existingCases > 0) {
+    logStep('Refused')
+    logWarn(EVIDENCE_REFUSALS['would-empty'])
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          number: identity.number,
+          reason: 'would-empty',
+          message: EVIDENCE_REFUSALS['would-empty'],
+          ...(commentId !== undefined && { commentId }),
+          ...carried,
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
   logStep('Scope')
   logInfo(
     `${plural(caseCount, 'case')} across ${plural(states.length, 'state')}`,

package/src/commands/standards.ts

@@ -1,11 +1,11 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
-import { registerPassThroughVerbs } from '@/commands/pass-through'
 import {
   auditExitCode,
   auditStandards,
   type StandardsAudit,
 } from '@/standards/audit'
+import { listStandardEntries } from '@/standards/list'
 import { listStandards, readStandard, resolveStandard } from '@/standards/read'
 import {
   frameError,
@@ -19,6 +19,10 @@ import {
   plural,
 } from '@/ui'
 
+interface StandardsListOptions {
+  readonly json?: boolean
+}
+
 interface StandardsAuditOptions {
   readonly json?: boolean
   readonly arrivalsOnly?: boolean
@@ -57,7 +61,14 @@ export function register(program: Command): void {
       process.exitCode = print(name)
     })
 
-  registerPassThroughVerbs(standards, 'standards', ['list'])
+  standards
+    .command('list')
+    .description('List the standards with their descriptions and jurisdiction')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit machine-readable JSON')
+    .action((opts: StandardsListOptions) => {
+      process.exitCode = runStandardsList(opts)
+    })
 
   standards
     .command('audit')
@@ -95,6 +106,26 @@ export function register(program: Command): void {
     })
 }
 
+/**
+ * Reads the working root first, the way `canon standards <name>` does, so a
+ * project's own standards list beside the package corpus. The `--json` record
+ * is the one thing on stdout and the frame opens only on the text path.
+ */
+function runStandardsList(opts: StandardsListOptions): number {
+  const standards = listStandardEntries(process.cwd())
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ standards })}\n`)
+    return 0
+  }
+
+  intro('canon standards')
+  logStep('Standards')
+  for (const each of standards) logInfo(`${each.name} : ${each.description}`)
+  outro()
+  return 0
+}
+
 /**
  * Writes the standard to stdout and every frame line to stderr, so a caller
  * capturing the output with `$(...)` receives the document alone.

package/src/commands/tasks.ts

@@ -10,9 +10,11 @@ import {
   type CitationOutcome,
   type DeclineOutcome,
   declineTask,
+  type InboundRelink,
   type PlanCitations,
   type PlanMove,
   planCitations,
+  type RelinkFailure,
 } from '@/tasks/archive'
 import {
   type LabelOutcome,
@@ -1493,6 +1495,7 @@ function report(
     logInfo('retargeted the Ready: line')
   }
   if (outcome.priorityRowRemoved) logInfo('cleared the ordering row')
+  logRelinked(outcome.relinked, outcome.relinkFailed, root)
   if (outcome.indexRegenerated) logInfo('regenerated index.md')
   if (outcome.cut > 0) logInfo(`${outcome.cut} outcome(s) cut`)
   outro()
@@ -1508,6 +1511,43 @@ function logPlanMoves(plans: readonly PlanMove[], root: string): void {
   if (plans.length > 0) logInfo('retargeted the Plan: line')
 }
 
+function logRelinked(
+  relinked: readonly InboundRelink[],
+  failed: readonly RelinkFailure[],
+  root: string,
+): void {
+  if (relinked.length > 0) {
+    const links = relinked.reduce((sum, entry) => sum + entry.links, 0)
+    logInfo(`repointed ${links} link(s) in ${relinked.length} file(s)`)
+  }
+
+  for (const failure of failed) {
+    logWarn(
+      `could not repoint ${relative(root, failure.file)}: ${failure.message}`,
+    )
+  }
+}
+
+function relinkFailedFor(
+  failed: readonly RelinkFailure[],
+  root: string,
+): readonly { readonly file: string; readonly message: string }[] {
+  return failed.map((failure) => ({
+    file: relative(root, failure.file),
+    message: failure.message,
+  }))
+}
+
+function relinkedFor(
+  relinked: readonly InboundRelink[],
+  root: string,
+): readonly { readonly file: string; readonly links: number }[] {
+  return relinked.map((entry) => ({
+    file: relative(root, entry.file),
+    links: entry.links,
+  }))
+}
+
 function planMovesFor(
   plans: readonly PlanMove[],
   root: string,
@@ -1547,6 +1587,8 @@ function recordFor(
       : null,
     closed: outcome.closed,
     cut: outcome.cut,
+    relinked: relinkedFor(outcome.relinked, root),
+    relinkFailed: relinkFailedFor(outcome.relinkFailed, root),
   }
 }
 
@@ -1639,6 +1681,7 @@ function reportDecline(
   logPlanMoves(outcome.plans, root)
   if (outcome.priorityRowRemoved) logInfo('cleared the ordering row')
   if (outcome.backlogRowRemoved) logInfo('cleared the backlog row')
+  logRelinked(outcome.relinked, outcome.relinkFailed, root)
   if (outcome.indexRegenerated) logInfo('regenerated index.md')
   outro()
 
@@ -1667,5 +1710,7 @@ function declineRecordFor(
     backlogRowRemoved: outcome.backlogRowRemoved,
     indexRegenerated: outcome.indexRegenerated,
     plans: planMovesFor(outcome.plans, root),
+    relinked: relinkedFor(outcome.relinked, root),
+    relinkFailed: relinkFailedFor(outcome.relinkFailed, root),
   }
 }

package/src/commands/tooling.ts

@@ -19,7 +19,7 @@ import {
 } from '@/tooling/manifest'
 import { readReference, resolveReference } from '@/tooling/read'
 import { scan, type ScanResult } from '@/tooling/scan'
-import { recordToolingChain } from '@/tooling/stamp'
+import { recordedStacks, recordToolingChain } from '@/tooling/stamp'
 import { subfolderPath } from '@/tooling/subfolder'
 import {
   intro,
@@ -228,7 +228,7 @@ export function register(program: Command): void {
  *
  * The frame opens after the `--json` return. The bash emitted a closing `└`
  * from its EXIT trap with no `┌` above it, because the hand-rolled
- * pass-through loop below skips the `intro` the shared helper carries.
+ * pass-through loop below opens no frame before it runs the script.
  */
 function runList(opts: ListOptions): number {
   // The warning is a frame-interior line, so it goes out after `intro` on the
@@ -485,7 +485,7 @@ async function stampChain(chain: Manifest[], target: string): Promise<void> {
   )
 
   if (recorded) {
-    logInfo(`Recorded chain: ${chain.map((entry) => entry.name).join(' < ')}`)
+    logInfo(`Recorded chain: ${recordedStacks(chain).join(' < ')}`)
     return
   }
 

package/src/commands/upgrade.ts

@@ -37,7 +37,7 @@ interface UpgradeRecord {
   readonly reason?: string
   /**
    * One rendered line for a caller that reports the outcome without parsing
-   * the rest of the record, such as `.husky/post-merge`. `current` reuses
+   * the rest of the record, such as the base stack's post-merge hook. `current` reuses
    * `describeSkew` verbatim so its wording never drifts from the line `canon
    * sync --check` and `canon claude skills drift` already report.
    */
@@ -312,7 +312,8 @@ function emit(opts: UpgradeOptions, record: UpgradeRecord): void {
 /**
  * `message` is the one field carrying arbitrary text: `describeSkew`'s
  * `unknown` branch embeds a registry error verbatim, and a registry answering
- * with HTML produces one already carrying a double quote. `.husky/post-merge`
+ * with HTML produces one already carrying a double quote. The base stack's
+ * post-merge hook, and any hook installed before `canon hooks post-merge`,
  * reads this field with a pattern rather than a parser, so a quote makes it
  * through `JSON.stringify` as an escaped `\"` that the pattern stops at,
  * truncating the line it prints. Collapsing whitespace and swapping the quote

package/src/commands/worktrees.ts

@@ -35,10 +35,11 @@ interface ReclaimCommandOptions {
 /**
  * What a caller reads instead of the frame.
  *
- * `.husky/post-merge` is the first caller that is not a person, and it branches
+ * The post-merge hooks are the callers that are not a person, and they branch
  * on a parsed field rather than on the exit code, since a shell profile
- * wrapping `canon` in a function flattens every status to zero. It reads the
- * record with a pattern rather than a parser, so every field it branches on is
+ * wrapping `canon` in a function flattens every status to zero. The base
+ * stack's hook, and any hook installed before `canon hooks post-merge`, reads
+ * the record with a pattern rather than a parser, so every field it branches on is
  * a number or a fixed word, and `outcomes` sits last so a greedy pattern
  * anchored on a scalar never reaches into it.
  */

package/src/docs/list.ts

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  CONTEXT_ROOTS,
+  DOCS_ROOT,
+  walkEntries,
+  type WalkedEntry,
+} from '@/docs/read'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
+
+/** The categories a target-facing doc declares, which no workflow doc does. */
+const TARGET_CATEGORIES: readonly string[] = [
+  'Agent surface',
+  'Domain references',
+]
+
+/** Domain context a target has no use for, so the catalog leaves it out. */
+const INTERNAL_TOPICS: readonly string[] = ['ci', 'development', 'sandbox']
+
+export interface DocEntry {
+  readonly name: string
+  readonly description: string
+  readonly category: string
+  readonly target: string
+}
+
+export interface DocsCatalog {
+  readonly docs: DocEntry[]
+  readonly context: DocEntry[]
+  /** False in a registry install, which ships `docs/` without a context root. */
+  readonly hasContext: boolean
+}
+
+/**
+ * A split folder is described by its generated index, which carries `subtitle`
+ * where a sibling file or a sub-area file carries `description`.
+ */
+function describe(root: string, entry: WalkedEntry): [string, string] {
+  const fields = parseFrontmatter(readFileSync(join(root, entry.rel), 'utf8'))
+  const key = entry.kind === 'folder' ? 'subtitle' : 'description'
+
+  return [readField(fields, 'category') ?? '', readField(fields, key) ?? '']
+}
+
+function byName(a: DocEntry, b: DocEntry): number {
+  if (a.name === b.name) return a.target < b.target ? -1 : 1
+  return a.name < b.name ? -1 : 1
+}
+
+/**
+ * A folder declares its category on its own index, since the allowlist is what
+ * separates a target-facing doc from a workflow one and a split domain is not
+ * exempt from it. A sub-area file declares its own, which keeps a page's
+ * listing membership unchanged by the folder it moves into.
+ */
+function collectDocs(root: string): DocEntry[] {
+  return walkEntries(root, DOCS_ROOT)
+    .flatMap((entry): DocEntry[] => {
+      const [category, description] = describe(root, entry)
+      if (!TARGET_CATEGORIES.includes(category)) return []
+
+      return [{ name: entry.name, description, category, target: entry.rel }]
+    })
+    .sort(byName)
+}
+
+/**
+ * Stops at the folder where `listTopics` goes on to name each sub-area file.
+ * This is the downstream catalog and that one answers what a caller could have
+ * typed, so a reachable name absent here is the same divergence the internal
+ * topics already carry. A name present at more than one surface root lists
+ * once, at the first.
+ */
+function collectContext(root: string): DocEntry[] {
+  const seen = new Set<string>()
+  const entries: DocEntry[] = []
+
+  for (const dir of CONTEXT_ROOTS) {
+    for (const entry of walkEntries(root, dir)) {
+      if (entry.kind === 'leaf') continue
+      if (INTERNAL_TOPICS.includes(entry.name) || seen.has(entry.name)) continue
+
+      seen.add(entry.name)
+      const [, description] = describe(root, entry)
+      entries.push({
+        name: entry.name,
+        description,
+        category: '',
+        target: entry.rel,
+      })
+    }
+  }
+
+  return entries.sort(byName)
+}
+
+export function listDocs(root: string): DocsCatalog {
+  return {
+    docs: collectDocs(root),
+    context: collectContext(root),
+    hasContext: CONTEXT_ROOTS.some((dir) => existsSync(join(root, dir))),
+  }
+}