@erclx/aitk 0.104.0 → 0.105.0

package/src/gov/test-order.ts

@@ -0,0 +1,383 @@
+import { execaSync } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/**
+ * Preferred first, matching `src/tasks/trunk.ts`. A clone with no remote still
+ * answers off its local trunk, and a local `main` trailing the remote widens
+ * the range rather than narrowing it, which over-reports instead of hiding.
+ */
+const TRUNK_REFS = ['origin/main', 'main'] as const
+
+/**
+ * The extensions this check can pair. A test sits beside its subject under one
+ * name throughout this corpus, so the weakest assumption available is also the
+ * one the corpus already honors. Every other extension is read past and named,
+ * since a bash script and its test are related by nothing a filename carries.
+ */
+export const SOURCE_EXTENSIONS = ['.ts', '.tsx'] as const
+
+/** The suffix removed to derive the subject a test covers. */
+export const TEST_SUFFIXES = ['.test.ts', '.test.tsx'] as const
+
+/** A `%H` line, which is 40 hex characters under sha1 and 64 under sha256. */
+const COMMIT = /^[0-9a-f]{40,64}$/
+
+/** A `--name-status` line: a status letter, a tab, then one path. */
+const NAME_STATUS = /^([A-Z])\d*\t(.+)$/
+
+export type Verdict = 'satisfied' | 'implementation-first' | 'unclassified'
+
+export interface PairRecord {
+  /** The implementation path, which is what a subject is named by. */
+  readonly subject: string
+  /** The test paired to it, or `null` when the pairing found no partner. */
+  readonly test: string | null
+  readonly verdict: Verdict
+  readonly implementationCommit: string | null
+  readonly testCommit: string | null
+  /** Why the verdict reads the way it does, in the report's own words. */
+  readonly reason: string
+}
+
+export interface Scope {
+  readonly extensions: readonly string[]
+  readonly testSuffixes: readonly string[]
+}
+
+export type TestOrderReport =
+  | {
+      readonly kind: 'measured'
+      readonly base: string
+      readonly head: string
+      readonly scope: Scope
+      readonly satisfied: readonly PairRecord[]
+      readonly findings: readonly PairRecord[]
+      readonly unclassified: readonly PairRecord[]
+      /** Changed paths outside the pairing's reach, named rather than counted. */
+      readonly ignored: readonly string[]
+    }
+  | { readonly kind: 'unreadable'; readonly reason: string }
+
+export interface TestOrderOptions {
+  /** The far side of the range, defaulting to the merge base against the trunk. */
+  readonly base?: string
+}
+
+/** One path as one commit in the range touched it. */
+interface Change {
+  readonly path: string
+  readonly status: string
+  readonly commit: string
+  /** Position in the range, oldest first, which is what orders a pair. */
+  readonly order: number
+}
+
+/**
+ * Reads `--name-status` log output, oldest commit first, into one entry per
+ * path per commit.
+ *
+ * The order field rather than the commit is what a comparison reads, since two
+ * commits carry no ordering a caller can derive from their hashes alone.
+ */
+function parseChanges(output: string): Change[] {
+  const changes: Change[] = []
+  let commit = ''
+  let order = -1
+
+  for (const line of output.split('\n')) {
+    const trimmed = line.trimEnd()
+    if (trimmed === '') continue
+
+    if (COMMIT.test(trimmed)) {
+      commit = trimmed
+      order += 1
+      continue
+    }
+
+    const match = NAME_STATUS.exec(trimmed)
+    if (match === null || commit === '') continue
+
+    changes.push({ path: match[2], status: match[1], commit, order })
+  }
+
+  return changes
+}
+
+/** Whether a path is a test this check can derive a subject from. */
+function testSuffix(path: string): string | undefined {
+  return TEST_SUFFIXES.find((suffix) => path.endsWith(suffix))
+}
+
+/**
+ * The implementation a test covers, derived by removing the test suffix.
+ *
+ * A behavior split across two modules pairs wrongly or not at all under this,
+ * which is what the unclassified bucket exists to catch rather than hide.
+ */
+function subjectOf(path: string): string {
+  const suffix = testSuffix(path)
+  if (suffix === undefined) return path
+  return `${path.slice(0, -suffix.length)}${suffix.replace('.test', '')}`
+}
+
+/** The one test path that would cover `subject` under the beside convention. */
+function testPathFor(subject: string): string {
+  return subject.replace(/\.(tsx?)$/, '.test.$1')
+}
+
+/**
+ * Whether a path is an implementation this check can pair. A declaration file
+ * carries no behavior to test, so it is read past rather than reported as a
+ * module nothing covers.
+ */
+function isImplementation(path: string): boolean {
+  if (path.endsWith('.d.ts')) return false
+  if (testSuffix(path) !== undefined) return false
+  return SOURCE_EXTENSIONS.some((extension) => path.endsWith(extension))
+}
+
+/** The first commit in the range that added `path`, or `undefined`. */
+function introduction(
+  changes: readonly Change[],
+  path: string,
+): Change | undefined {
+  return changes.find((change) => change.path === path && change.status === 'A')
+}
+
+function classify(
+  changes: readonly Change[],
+  atBase: ReadonlySet<string>,
+): {
+  satisfied: PairRecord[]
+  findings: PairRecord[]
+  unclassified: PairRecord[]
+} {
+  const satisfied: PairRecord[] = []
+  const findings: PairRecord[] = []
+  const unclassified: PairRecord[] = []
+
+  // Keyed by subject so a module whose implementation and test both moved is
+  // one record rather than two, and so a test with no partner still reports
+  // under the implementation path a reader would go looking for.
+  const subjects = new Set<string>()
+  for (const change of changes) {
+    if (isImplementation(change.path)) subjects.add(change.path)
+    else if (testSuffix(change.path) !== undefined) {
+      subjects.add(subjectOf(change.path))
+    }
+  }
+
+  for (const subject of [...subjects].sort()) {
+    const candidate = testPathFor(subject)
+    const testChange = introduction(changes, candidate)
+    const testAtBase = atBase.has(candidate)
+    const test = testAtBase || testChange !== undefined ? candidate : undefined
+
+    const implementation = introduction(changes, subject)
+
+    if (implementation === undefined) {
+      unclassified.push({
+        subject,
+        test: test ?? null,
+        verdict: 'unclassified',
+        implementationCommit: null,
+        testCommit: null,
+        reason: atBase.has(subject)
+          ? 'the implementation predates the range, so a change to it cannot be separated from a refactor'
+          : 'no implementation reached the range beside this test',
+      })
+      continue
+    }
+
+    if (test === undefined) {
+      unclassified.push({
+        subject,
+        test: null,
+        verdict: 'unclassified',
+        implementationCommit: implementation.commit,
+        testCommit: null,
+        reason: 'no test names this module, so the ordering has no second side',
+      })
+      continue
+    }
+
+    // A paired test the range never added is one that already sat at the base
+    // commit, since those are the only two ways `test` gets a value at all.
+    if (testChange === undefined) {
+      satisfied.push({
+        subject,
+        test,
+        verdict: 'satisfied',
+        implementationCommit: implementation.commit,
+        testCommit: null,
+        reason: 'the test predates the range',
+      })
+      continue
+    }
+
+    // One commit carrying both sides counts as satisfied. The rule asks that
+    // the test not come after, and a single commit is the shape a small change
+    // takes here, so reporting it would flag most of the corpus.
+    const record: PairRecord = {
+      subject,
+      test,
+      verdict:
+        testChange.order <= implementation.order
+          ? 'satisfied'
+          : 'implementation-first',
+      implementationCommit: implementation.commit,
+      testCommit: testChange.commit,
+      reason:
+        testChange.order <= implementation.order
+          ? 'the test reached history no later than the implementation'
+          : 'the implementation reached history before the test covering it',
+    }
+
+    if (record.verdict === 'satisfied') satisfied.push(record)
+    else findings.push(record)
+  }
+
+  return { satisfied, findings, unclassified }
+}
+
+/**
+ * Where an implementation reached a commit ahead of the test covering it,
+ * between `base` and the current `HEAD` of the tree at `root`.
+ *
+ * This reports and never gates. Pairing a test to an implementation is a
+ * judgment, so a change the pairing cannot read lands in `unclassified` with
+ * its reason stated rather than being counted as a pass. Coverage is narrower
+ * than the rule the check answers to, and `scope` and `ignored` are what say so
+ * on every run.
+ */
+export function readTestOrder(
+  root: string,
+  options: TestOrderOptions = {},
+): TestOrderReport {
+  const head = revParse(root, 'HEAD')
+  if (head === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `No git history under ${root}. History is the only surface carrying the ordering, so there is nothing to read.`,
+    }
+  }
+
+  const base = resolveBase(root, options.base, head)
+  if (typeof base !== 'string') return base
+
+  const log = git(root, [
+    'log',
+    '--reverse',
+    '--name-status',
+    '--no-renames',
+    '--format=%H',
+    `${base}..${head}`,
+  ])
+
+  if (log === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `Reading history between ${base} and HEAD failed under ${root}.`,
+    }
+  }
+
+  const tree = git(root, ['ls-tree', '-r', '--name-only', base])
+  if (tree === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `Reading the tree at ${base} failed under ${root}. Without it a test written before the range reads as absent.`,
+    }
+  }
+
+  const changes = parseChanges(log)
+  const atBase = new Set(tree.split('\n').filter((line) => line !== ''))
+
+  const ignored = [
+    ...new Set(
+      changes
+        .map((change) => change.path)
+        .filter(
+          (path) => !isImplementation(path) && testSuffix(path) === undefined,
+        ),
+    ),
+  ].sort()
+
+  return {
+    kind: 'measured',
+    base,
+    head,
+    scope: { extensions: SOURCE_EXTENSIONS, testSuffixes: TEST_SUFFIXES },
+    ...classify(changes, atBase),
+    ignored,
+  }
+}
+
+/**
+ * The far side of the range. A ref the caller named has to resolve, since
+ * falling back to the trunk there would measure a range nobody asked for. With
+ * no ref named, the merge base against the trunk scopes the run to the branch,
+ * and a repository carrying no trunk falls back to the root commit rather than
+ * refusing.
+ */
+function resolveBase(
+  root: string,
+  ref: string | undefined,
+  head: string,
+): string | { kind: 'unreadable'; reason: string } {
+  if (ref !== undefined) {
+    const resolved = revParse(root, ref)
+    if (resolved === undefined) {
+      return {
+        kind: 'unreadable',
+        reason: `Ref ${ref} resolves to no commit in ${root}. Pass a commit this tree carries.`,
+      }
+    }
+    return resolved
+  }
+
+  for (const trunk of TRUNK_REFS) {
+    if (revParse(root, trunk) === undefined) continue
+    const merged = git(root, ['merge-base', head, trunk])
+    if (merged !== undefined && merged !== '') return merged
+  }
+
+  const rootCommits = git(root, ['rev-list', '--max-parents=0', head])
+  if (rootCommits === undefined || rootCommits === '') {
+    return {
+      kind: 'unreadable',
+      reason: `No base resolves against ${root}. Fetch origin or pass --base.`,
+    }
+  }
+
+  return rootCommits.split('\n')[0]
+}
+
+/**
+ * `execaSync` with git's repository-resolution variables stripped, so `-C`
+ * resolves against `root` and not against whatever repository a hook exported.
+ * `undefined` is the refusal, which every caller turns into its own reason.
+ */
+function git(root: string, args: readonly string[]): string | undefined {
+  const result = execaSync('git', ['-C', root, ...args], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+
+  return result.exitCode === 0 ? result.stdout.trimEnd() : undefined
+}
+
+/**
+ * The commit a ref names. `^{commit}` is what turns a tag or a tree into the
+ * commit behind it, so a caller never compares a ref against another type.
+ */
+function revParse(root: string, ref: string): string | undefined {
+  const resolved = git(root, [
+    'rev-parse',
+    '--verify',
+    '--quiet',
+    `${ref}^{commit}`,
+  ])
+
+  return resolved === undefined || resolved === '' ? undefined : resolved.trim()
+}

package/src/tasks/archive.ts

@@ -6,6 +6,7 @@ import { regenOne } from '@/indexes/regen'
 const TASKS_DIR = join('.claude', 'tasks')
 const ARCHIVE_DIR = join('.claude', 'task-archive')
 const PLANS_DIR = join('.claude', 'plans')
+const PLANS_ARCHIVE_DIR = join('.claude', 'plans-archive')
 
 /**
  * Siblings that sit on the board without being tasks: the generated index, the
@@ -192,13 +193,152 @@ function isUnder(path: string, dir: string): boolean {
  * both, which is how `claude-docs` reads the same line. It accepts `../plans/x.md`
  * and `.claude/plans/x.md` as one file, so a gate reading only the first form
  * would pass the second and strand the plan this exists to protect.
+ *
+ * The resolved path is returned rather than a boolean, because the citation
+ * count below compares two tasks by where their targets land and not by the
+ * strings they wrote. A target outside the live plans folder yields nothing,
+ * which is an archived plan or a pointer into somewhere else entirely.
  */
-function isLivePlan(target: string, dir: string, root: string): boolean {
+export function resolveLivePlan(
+  target: string,
+  dir: string,
+  root: string,
+): string | undefined {
   const plans = join(root, PLANS_DIR)
+  const fromBoard = resolve(dir, target)
+  const fromRoot = resolve(root, target)
+
+  if (isUnder(fromBoard, plans)) return fromBoard
+  if (isUnder(fromRoot, plans)) return fromRoot
+  return undefined
+}
+
+/**
+ * Names the other live tasks whose `Plan:` line lands on the same file. This is
+ * the rule `claude-docs` applies before it archives a plan, held here so one
+ * question has one implementation: a plan another live task still cites is a
+ * plan the sweep is correct to leave, and a guard that read the folder instead
+ * refused every task sharing one plan and deadlocked the board against the
+ * sweep that was behaving correctly.
+ *
+ * The closing task is excluded by name. It cites the plan itself, so counting
+ * it would never reach zero and the count would answer nothing.
+ */
+export async function otherTasksCitingPlan(
+  dir: string,
+  root: string,
+  plan: string,
+  closing: string,
+): Promise<string[]> {
+  const stems = (await listTaskStems(dir)).filter((stem) => stem !== closing)
+
+  const read = await Promise.all(
+    stems.map(async (stem) => {
+      const target = readPlanTarget(
+        await readFile(join(dir, `${stem}.md`), 'utf8'),
+      )
+      const resolved = target && resolveLivePlan(target, dir, root)
+      return resolved === plan ? stem : undefined
+    }),
+  )
+
+  return read.filter((stem): stem is string => stem !== undefined)
+}
+
+/**
+ * Where a task's `Plan:` target resolves, which is what decides whether the
+ * plan is the sweep's to move. `unstated` is a task carrying no line at all,
+ * and it is distinct from a line resolving somewhere unexpected.
+ */
+export const CITATION_LOCATIONS = [
+  'unstated',
+  'live',
+  'archived',
+  'outside',
+] as const
+
+export type CitationLocation = (typeof CITATION_LOCATIONS)[number]
+
+export interface PlanCitations {
+  readonly ok: true
+  readonly stem: string
+  readonly target: string | undefined
+  readonly location: CitationLocation
+  /** Other live tasks landing on the same file. Empty unless `location` is `live`. */
+  readonly citedBy: readonly string[]
+}
+
+export type CitationOutcome = PlanCitations | ArchiveRefused
+
+/**
+ * Answers where one task's plan sits and who else holds it, which is the whole
+ * of the last-live-citation rule. `claude-docs` reads this rather than scanning
+ * the board itself, so the sweep that moves a plan and the gate that refuses a
+ * task archive cannot drift into disagreeing about which plan is free.
+ *
+ * It reports and never writes. The move, the retarget, and the ordering the two
+ * happen in belong to the caller, and a verb that performed them would be
+ * deciding a question the sweep is there to decide.
+ */
+export async function planCitations(
+  root: string,
+  stem: string,
+): Promise<CitationOutcome> {
+  const dir = tasksDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-board', `No task board at ${relative(root, dir)}.`)
+  }
+
+  const stems = await listTaskStems(dir)
+  if (!stems.includes(stem)) {
+    return refuse('no-match', `No task named ${stem} on the board.`, stems)
+  }
+
+  const target = readPlanTarget(await readFile(join(dir, `${stem}.md`), 'utf8'))
+  if (!target) {
+    return {
+      ok: true,
+      stem,
+      target: undefined,
+      location: 'unstated',
+      citedBy: [],
+    }
+  }
+
+  const live = resolveLivePlan(target, dir, root)
+  if (!live) {
+    const location = resolvesUnder(target, dir, root, PLANS_ARCHIVE_DIR)
+      ? 'archived'
+      : 'outside'
+    return { ok: true, stem, target, location, citedBy: [] }
+  }
+
+  return {
+    ok: true,
+    stem,
+    target,
+    location: 'live',
+    citedBy: await otherTasksCitingPlan(dir, root, live, stem),
+  }
+}
+
+/**
+ * Runs the two-spelling resolution `resolveLivePlan` applies against a folder
+ * other than the live one, so an archived plan is read as archived whichever
+ * root the task wrote its path against.
+ */
+function resolvesUnder(
+  target: string,
+  dir: string,
+  root: string,
+  folder: string,
+): boolean {
+  const resolved = join(root, folder)
 
   return (
-    isUnder(resolve(dir, target), plans) ||
-    isUnder(resolve(root, target), plans)
+    isUnder(resolve(dir, target), resolved) ||
+    isUnder(resolve(root, target), resolved)
   )
 }
 
@@ -310,12 +450,21 @@ export async function archiveTask(
   }
 
   const planTarget = readPlanTarget(text)
-  if (planTarget && isLivePlan(planTarget, dir, root)) {
-    return refuse(
-      'plan-unswept',
-      `${stem} still points at a live plan. Run /claude-docs to sweep it first, then archive.`,
-      [planTarget],
-    )
+  const livePlan = planTarget && resolveLivePlan(planTarget, dir, root)
+
+  // A live plan is unswept only when nothing else on the board holds it. A plan
+  // several tasks share stays live by design, so refusing on the folder alone
+  // parked every one of those tasks behind a sweep that was right to decline.
+  if (livePlan) {
+    const shared = await otherTasksCitingPlan(dir, root, livePlan, stem)
+
+    if (shared.length === 0) {
+      return refuse(
+        'plan-unswept',
+        `${stem} is the last task pointing at a live plan. Run /claude-docs to sweep it first, then archive.`,
+        [planTarget],
+      )
+    }
   }
 
   const destination = archiveDir(root)

package/src/tasks/trunk.ts

@@ -0,0 +1,89 @@
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+
+const GIT_TIMEOUT_MS = 10_000
+
+/** Preferred first. A clone with no remote still answers off its local trunk. */
+const TRUNK_REFS = ['origin/main', 'main'] as const
+
+/**
+ * Reports whether a pull request's work reached the trunk. `undefined` means
+ * the trunk could not be read, which is a different answer from `false` and has
+ * to stay one: a check that degraded to "not landed" on an unreachable trunk
+ * would report a board silently rather than say what it failed to test.
+ */
+export type TrunkReader = (pullRequest: number) => Promise<boolean | undefined>
+
+/**
+ * Matches the two subjects a landed pull request leaves on the trunk: the
+ * `(#NNN)` suffix a squash merge writes, and the subject GitHub writes for a
+ * merge commit. Both carry the number in a form no other commit spells, so a
+ * pull request numbered 12 cannot match one numbered 123.
+ */
+function grepArgs(pullRequest: number): string[] {
+  return [
+    '--extended-regexp',
+    '--grep',
+    `\\(#${pullRequest}\\)`,
+    '--grep',
+    `Merge pull request #${pullRequest} from`,
+  ]
+}
+
+/**
+ * Reads the trunk as this clone already holds it and never fetches. A validate
+ * run happens several times a sweep and a fetch per run is a cost the check
+ * does not carry today, so a clone behind the remote reports the row untested
+ * or leaves it parked rather than claiming work landed.
+ */
+export function gitTrunkReader(root: string): TrunkReader {
+  const answered = new Map<number, boolean | undefined>()
+
+  return async (pullRequest) => {
+    if (answered.has(pullRequest)) return answered.get(pullRequest)
+
+    const landed = await readTrunk(root, pullRequest)
+    answered.set(pullRequest, landed)
+    return landed
+  }
+}
+
+async function readTrunk(
+  root: string,
+  pullRequest: number,
+): Promise<boolean | undefined> {
+  for (const ref of TRUNK_REFS) {
+    const result = await execa(
+      'git',
+      [
+        '-C',
+        root,
+        'log',
+        ref,
+        '-n',
+        '1',
+        '--format=%H',
+        ...grepArgs(pullRequest),
+        // The ref is a revision, and a repository tracking a path under the
+        // same name would otherwise fail the whole read as ambiguous.
+        '--',
+      ],
+      // `post-merge` drives the task verbs, and a hook exports the repository
+      // variables git reads ahead of `-C`, so the ambient environment would
+      // answer for whatever repository fired the hook.
+      {
+        reject: false,
+        timeout: GIT_TIMEOUT_MS,
+        env: gitEnv(),
+        extendEnv: false,
+      },
+    )
+
+    // A missing ref exits non-zero, which is the next ref's turn rather than an
+    // answer. An exit of zero with no commit is the ref saying the work is not
+    // on it, which is an answer and stops the walk.
+    if (result.exitCode === 0) return result.stdout.trim().length > 0
+  }
+
+  return undefined
+}