@erclx/canon 4.71.0 → 4.72.0

package/src/commands/tasks.ts

@@ -14,6 +14,12 @@ import {
   planCitations,
 } from '@/tasks/archive'
 import { type LabelOutcome, nextLabel } from '@/tasks/label'
+import {
+  type Claim,
+  type Holder,
+  planReach,
+  type ReachOutcome,
+} from '@/tasks/reach'
 import {
   type CloseOutcome,
   closeOutcomes,
@@ -84,6 +90,12 @@ interface BranchCommandOptions {
   readonly root?: string
 }
 
+interface ReachCommandOptions {
+  readonly base?: string
+  readonly json?: boolean
+  readonly root?: string
+}
+
 interface PullRequestCommandOptions {
   readonly json?: boolean
   readonly plan?: string
@@ -326,6 +338,45 @@ export function register(program: Command): void {
       process.exitCode = await runBranch(plan, opts)
     })
 
+  tasks
+    .command('plan-reach')
+    .description('Read a branch back against what was declared about it')
+    .argument('<plan>', 'Plan path or its slug, as in dispatch-answer-gate')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--base <ref>', 'Far side of the range, defaulting to the trunk')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the reach was read and no other track claims a changed path',
+        '  1  refused as no-plan, archived, bad-input, no-base, or no-diff',
+        '  2  read, and another live plan or Run now row claims a path',
+        '',
+        'It reports claimed first and undeclared second. A claimed path is one',
+        'another track holds and is the half worth acting on; an undeclared one',
+        'is a path this plan never named, which the ship chain writes on nearly',
+        'every branch. It reports and never gates, so branch on the record',
+        'rather than on the exit code, which a shell function wrapping canon',
+        'can flatten to zero.',
+        '',
+        'The range is read at the current directory and the plans and board at',
+        'the board root, so a linked worktree reads its own branch against the',
+        'shared records. It reads only what is written down, so the plan and',
+        'row counts say how much was there to compare against.',
+        '',
+        'Examples:',
+        '  canon tasks plan-reach dispatch-answer-gate',
+        '  canon tasks plan-reach dispatch-answer-gate --base origin/main --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (plan: string, opts: ReachCommandOptions) => {
+      process.exitCode = await runReach(plan, opts)
+    })
+
   tasks
     .command('pull-request')
     .description('Record a pull request number on the task a branch closes')
@@ -961,6 +1012,109 @@ function reportBranch(
   return EXIT_FINDINGS
 }
 
+async function runReach(
+  plan: string,
+  opts: ReachCommandOptions,
+): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  // The range belongs to the checkout the caller stands in, which is the linked
+  // worktree holding the branch on every dispatched run. The board root is the
+  // main worktree, where reading a range measures the trunk against itself.
+  const outcome = await planReach(root, plan, {
+    repo: process.cwd(),
+    ref: opts.base,
+  })
+
+  return reportReach(outcome, opts.json ?? false, root)
+}
+
+/**
+ * Names a holder, the declaration it matched on when that is wider than the
+ * path, and whether a holding plan carries a dispatch row. A plan with no row
+ * is the shape a plan nobody archived takes, which is what sends a reader to
+ * check the holder rather than treating the claim as a live collision.
+ */
+function describeHolder(claim: Claim, holder: Holder): string {
+  const under =
+    holder.declaration === claim.path ? '' : `, under ${holder.declaration}`
+  const rowed = holder.source === 'plan' && !holder.rowed ? ', no row' : ''
+
+  return `${holder.name} (${holder.source}${under}${rowed})`
+}
+
+function describeReachClaim(claim: Claim): string {
+  const holders = claim.holders
+    .map((holder) => describeHolder(claim, holder))
+    .join(' and ')
+
+  return `${claim.path} is held by ${holders}`
+}
+
+/**
+ * Leads with the claimed list because it is the short one. Over the wave this
+ * verb was filed against, undeclared paths ran 22 of 26 on one branch and 18 of
+ * 25 on another, so a report opening on that list is noise a reader skips past
+ * and the crossing underneath it goes with them.
+ */
+function reportReach(
+  outcome: ReachOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
+      )
+      return 1
+    }
+
+    intro('canon tasks plan-reach')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ ...outcome, root })}\n`)
+    return outcome.claimed.length === 0 ? 0 : EXIT_FINDINGS
+  }
+
+  intro('canon tasks plan-reach')
+
+  logStep(outcome.claimed.length === 0 ? 'Uncontested' : 'Claimed')
+  if (outcome.claimed.length === 0) {
+    logInfo('no other live plan or Run now row holds a path this branch wrote')
+  } else {
+    for (const claim of outcome.claimed) logWarn(describeReachClaim(claim))
+  }
+
+  logStep('Undeclared')
+  if (outcome.undeclared.length === 0) {
+    logInfo(
+      `${outcome.plan} declared every one of the ${outcome.changed} paths`,
+    )
+  } else {
+    for (const path of outcome.undeclared) logInfo(path)
+    logInfo(
+      `${outcome.undeclared.length} of ${outcome.changed} path(s) this plan did not name, which the ship chain's own steps account for on most branches`,
+    )
+  }
+
+  // The counts are the report's own bound. A verb reading what is written down
+  // sees no hand-launched track and no track without a plan, so a clear reading
+  // over nothing compared against would otherwise read as a proof.
+  logStep('Compared against')
+  logInfo(
+    `${outcome.plans} other live plan(s) and ${outcome.rows} Run now row(s)${outcome.board ? '' : ', with no board on disk to read'}`,
+  )
+
+  outro()
+
+  return outcome.claimed.length === 0 ? 0 : EXIT_FINDINGS
+}
+
 function reportValidation(
   outcome: ValidateOutcome,
   emitJson: boolean,

package/src/git-files.ts

@@ -68,6 +68,75 @@ export async function listChangedFiles(
   return [...new Set(paths.filter(Boolean))].sort()
 }
 
+/** A file's old and new path across a git-detected rename. */
+export interface RenamePair {
+  readonly from: string
+  readonly to: string
+}
+
+/**
+ * Every rename `base..working tree` carries, read through the same similarity
+ * detection `git diff -M` applies by default (50%).
+ *
+ * A move heavy enough on rewritten content to fall under that floor reports
+ * as a plain delete and add rather than a rename, which is not a defect this
+ * reads around: the diff genuinely does not carry the file a claim citing the
+ * old path describes.
+ *
+ * Returns undefined when git cannot answer, matching `listChangedFiles`.
+ */
+export async function listRenames(
+  root: string,
+  base: string,
+): Promise<RenamePair[] | undefined> {
+  const output = await git(root, ['diff', '--name-status', '-M', base])
+  if (output === undefined) return undefined
+
+  const renames: RenamePair[] = []
+  for (const line of output.split('\n')) {
+    if (line === '') continue
+    const [status, from, to] = line.split('\t')
+    if (status === undefined || !status.startsWith('R')) continue
+    if (from === undefined || to === undefined) continue
+    renames.push({ from, to })
+  }
+  return renames
+}
+
+/**
+ * Added, non-comment lines from a unified diff hunk touching `.gitignore`.
+ *
+ * Shared between a local `git diff` and a patch string GitHub returns inline
+ * for the same file, so the two evidence sources read one pattern the same
+ * way.
+ */
+export function parseIgnoreAdditions(diffText: string): string[] {
+  const patterns: string[] = []
+  for (const line of diffText.split('\n')) {
+    if (!line.startsWith('+') || line.startsWith('+++')) continue
+    const pattern = line.slice(1).trim()
+    if (pattern === '' || pattern.startsWith('#')) continue
+    patterns.push(pattern)
+  }
+  return patterns
+}
+
+/**
+ * Every pattern a branch added to `.gitignore` since `base`.
+ *
+ * `-U0` keeps the hunk to changed lines alone, which is all a claim needs.
+ *
+ * Returns undefined when git cannot answer, matching `listChangedFiles`.
+ */
+export async function listIgnoreAdditions(
+  root: string,
+  base: string,
+): Promise<string[] | undefined> {
+  const output = await git(root, ['diff', '-U0', base, '--', '.gitignore'])
+  if (output === undefined) return undefined
+  return parseIgnoreAdditions(output)
+}
+
 /**
  * Lists the files under `root`: tracked, plus untracked files git does not
  * ignore. The untracked half is what keeps a file added on this branch in scope

package/src/pr/bijection.ts

@@ -1,3 +1,4 @@
+import type { RenamePair } from '@/git-files'
 import { extractKeyChangePaths, KEY_CHANGES, type PathClaim } from '@/pr/paths'
 
 /**
@@ -53,6 +54,14 @@ export interface BijectionReport {
    * branch author.
    */
   readonly incidental: readonly string[]
+  /**
+   * True when the rename or `.gitignore`-addition evidence could not be read.
+   *
+   * A claim `unmet` would otherwise carry is downgraded to `unresolved`
+   * instead, since the unread evidence might have credited it and this
+   * comparison has no way to tell a stale claim from one it could not check.
+   */
+  readonly evidenceUnread: boolean
 }
 
 export type Bijection =
@@ -66,6 +75,20 @@ export interface BijectionInput {
   readonly roots: ReadonlySet<string>
   readonly head?: string
   readonly title?: string
+  /** A rename's source path credits a claim naming it, without ever counting as a changed file. */
+  readonly renames?: readonly RenamePair[]
+  /** A pattern newly added to `.gitignore`, crediting a claim naming it as the `.gitignore` change it is. */
+  readonly ignoreAdditions?: readonly string[]
+  /**
+   * True when the caller could not read the rename or ignore-addition
+   * evidence, rather than reading it and finding neither.
+   *
+   * The two states produce the same empty `renames`/`ignoreAdditions`, so
+   * this is the only way `compareKeyChanges` can tell a claim that is
+   * genuinely stale from one the evidence might have credited had the read
+   * succeeded.
+   */
+  readonly evidenceUnread?: boolean
 }
 
 /**
@@ -94,6 +117,28 @@ function owesNoBullet(path: string): boolean {
   return INCIDENTAL.some((pattern) => pattern.test(path))
 }
 
+/** Drops a directory claim's trailing slash so it compares against a raw `.gitignore` pattern. */
+function withoutTrailingSlash(path: string): string {
+  return path.endsWith('/') ? path.slice(0, -1) : path
+}
+
+/**
+ * Whether a claim names a pattern newly added to `.gitignore`.
+ *
+ * Compared with the trailing slash both sides may or may not carry stripped,
+ * since a bullet spells a folder pattern the way `.gitignore` itself does
+ * (`web/screenshots/`) and the diff line carries the identical text.
+ */
+function coversIgnoreAddition(
+  claim: PathClaim,
+  ignoreAdditions: readonly string[],
+): boolean {
+  const named = withoutTrailingSlash(claim.path)
+  return ignoreAdditions.some(
+    (pattern) => withoutTrailingSlash(pattern) === named,
+  )
+}
+
 /**
  * Whether one changed path is the file, or a file under the folder, a claim
  * names.
@@ -147,6 +192,10 @@ export function compareKeyChanges(input: BijectionInput): Bijection {
     return { kind: 'refused', reason: 'no-section' }
   if (read.claims.length === 0) return { kind: 'refused', reason: 'no-claims' }
 
+  const renames = input.renames ?? []
+  const ignoreAdditions = input.ignoreAdditions ?? []
+  const evidenceUnread = input.evidenceUnread ?? false
+
   const unmet: PathClaim[] = []
   const unresolved: PathClaim[] = []
   const named = new Set<string>()
@@ -155,7 +204,15 @@ export function compareKeyChanges(input: BijectionInput): Bijection {
     const hits = input.changed.filter((path) => covers(claim, path))
     for (const path of hits) named.add(path)
     if (hits.length > 0) continue
-    if (claim.anchored && claim.leading) unmet.push(claim)
+
+    if (renames.some((rename) => covers(claim, rename.from))) continue
+
+    if (coversIgnoreAddition(claim, ignoreAdditions)) {
+      named.add('.gitignore')
+      continue
+    }
+
+    if (claim.anchored && claim.leading && !evidenceUnread) unmet.push(claim)
     else unresolved.push(claim)
   }
 
@@ -170,6 +227,7 @@ export function compareKeyChanges(input: BijectionInput): Bijection {
     unresolved,
     unnamed: reached.filter((path) => !owesNoBullet(path)),
     incidental: reached.filter(owesNoBullet),
+    evidenceUnread,
   }
 }