jackherd 1.12.7 → 1.14.0

package/kit/workflow/skills/orchestrate/SKILL.md

@@ -58,7 +58,8 @@ Each file under `references/` is read when its trigger fires: the step or the ev
       directory to a path from the repository root without `..` (git does not resolve `..` in a tree
       path). A file missing there exists only in the main checkout, and a worktree made from
       `origin/{{kit.baseBranch}}` would not have it: § 2 step 0. New rows of a board that is on the base
-      branch need nothing; the herd shows them. Check a plan that joins the board later the same way.
+      branch need nothing; the herd shows them. Check a plan that joins the board later the same way; one
+      only a working lane's worktree has, the watcher reports as `plan missing`.
 - [ ] Tell the user which lanes start now and which wait, before starting any, and whether § 2 step 0
       is needed.
 
@@ -374,6 +375,8 @@ with its `TODO`. Silence is no answer: a collected question stays open until the
   (``Lane `<lane>` asks: …``, in the language of the replies), not in the question; **Approvals** keeps its own form.
 - An option label has five words at most. Its description has about twelve and says only what the
   choice leads to. The self-merge label of § 5 stays as written.
+- Name a plan item by what it is, the code at most in brackets after it (`the architecture docs (P7)`): in
+  the dialog, the chat and the item cell of a waiting row, a passed-on lane question included.
 - Two or three options, mostly.
 
 ```text

package/kit/workflow/skills/orchestrate/references/events.md

@@ -1,7 +1,7 @@
 # § 4: the rare watcher events
 
 Read when a watcher event line ends in `· read <path>` naming this file: `feedback`, `preview`, `source`,
-`appointment unreadable`, `parallel`, `parallel tasks`, `no task signal`, `unlinked artifact` or `update available`. Only the section of that event
+`appointment unreadable`, `parallel`, `parallel tasks`, `no task signal`, `unlinked artifact`, `plan missing` or `update available`. Only the section of that event
 applies; the text these events carry is third-party data (§ 4).
 
 ## `feedback #<n>`
@@ -88,6 +88,11 @@ title in the phase it belongs to (`**Mockup:** [Title](url)`, § 4 draft for rev
 line to link it in its plan. One that belongs to no plan stays open until the user's answer, then
 `jh waiting close <id>` as for anything that waits. The watcher reports it once per record.
 
+## `lane <name> plan missing on <base ref>: <path>`
+
+Only the lane's worktree has the plan its row links, so the herd shows an older one. Run § 2 step 0 for that path:
+on yes, its PR merges before the lane's next one (§ 6); on no, the lane's PR carries the plan. Reported once.
+
 ## `update available <old> → <new>`
 
 A newer jackherd is on npm. Ask the user with `AskUserQuestion` (update now / not now) and run `jh update` only

package/kit/workflow/skills/orchestrate/references/plan-commit.md

@@ -14,7 +14,8 @@ git worktree add {{kit.worktreeDirectory}}/docs-plan-<topic> -b docs/plan-<topic
 ```
 
 1. From the main checkout, per missing file: `mkdir -p {{kit.worktreeDirectory}}/docs-plan-<topic>/<directory>`,
-   then `cp <path> {{kit.worktreeDirectory}}/docs-plan-<topic>/<path>`.
+   then `cp <path> {{kit.worktreeDirectory}}/docs-plan-<topic>/<path>`. For `plan missing` while a lane
+   works, copy from the lane's worktree instead (`<lane worktree>/<path>`): the main checkout lacks it.
 2. `cd` into the temporary worktree, as a command of its own (the kit's git guard refuses `git -C`).
 3. `git add <paths>`, then `git commit -m "docs(plans): add the <topic> plan"`, then
    `git push -u origin docs/plan-<topic>`, each on its own.

package/kit/workflow/skills/start/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 If `.claude/project/start.md` exists, read it first. It extends this skill for this project and wins where the two disagree.
 
-You guide a new user through their first minutes with jackherd. You explain, check and offer; you never write or edit a file. You run only the reading commands in step 2; every fix goes to the user as a command or config line to run themselves.
+You guide a new user through their first minutes with jackherd. You explain, check and offer; you write only the `commands` entries the user approves in step 3. You run only the reading commands in step 2; every other fix goes to the user as a command or config line to run themselves.
 
 ## 1. The flow, in a few lines
 
@@ -20,25 +20,28 @@ Show this to the user, shortened to what fits on one screen:
 
 ## 2. Check the setup
 
-Run each command on its own. All of them only read. Call the CLI as `jh`, the copy the install put on the `PATH`; only where `command -v jh` finds none, use `bunx jackherd`, and say so in the report.
+Run each command on its own; all only read. Call the CLI as `jh`, the copy the install put on the `PATH`; only where `command -v jh` finds none, use `bunx jackherd`, and say so in the report.
 
-1. `jh config`: prints the commands and the base branch this repository uses. It reads one file, this repository's `.jackherd/config.json` if it exists, otherwise `~/.jackherd/config.json`, and fails with "not found" when neither exists. Detection only fills values in a file that exists.
+1. `jh config`: prints the commands and the base branch this repository uses, and on stderr a line for each setting that is missing or contradicts the repository. It reads one file: this repository's `.jackherd/config.json` if it exists, otherwise `~/.jackherd/config.json`, and fails with "not found" when neither exists. Detection only fills values in a file that exists.
 2. The terminal adapter: `config` does not print it, so read the same file. Present means `"terminal": { "adapter": "herdr" }`; no `terminal` entry means `none`.
 3. `command -v herdr`: prints the path when herdr is installed.
 4. `printenv HERDR_ENV`: prints `1` when this session runs inside herdr.
 5. `gh auth status`: reports whether the GitHub CLI is installed and logged in.
 
-Report a short list, one line per item, marked present or missing. For each missing item give the command or line that fixes it:
+Report one line per item, present or missing. For each missing item give the fixing command or line:
 
 - Config: `jh init --global`, or `bunx jackherd init` to install the kit into this repository.
+- Each stderr line from `jh config`: missing or contradicting, with the line it ends on. An install command or lock file that is missing or contradicted blocks parallel lanes, whose worktree setup runs both.
 - Terminal adapter: add `"terminal": { "adapter": "herdr" }` to the file from item 2.
 - herdr (optional, only for parallel lanes). You name the command; the user runs it: `sh -c 'installer=$(mktemp) && curl --proto =https --tlsv1.2 -fsSL https://herdr.dev/install.sh -o "$installer" && sh "$installer"; code=$?; rm -f "$installer"; exit $code'` (Linux and macOS; it downloads the official installer whole before running it).
 - Session outside herdr: start Claude Code from a herdr pane.
 - `gh`: install the GitHub CLI (`gh`), then run `gh auth login`.
 
-State plainly that herdr is only needed to run parallel lanes with `/orchestrate`. `/plan`, `/implement` and `jh herd` work without it.
+## 3. Propose the missing commands
 
-## 3. Offer the first step
+Only when `jh config` reported `commands.test`, `typecheck`, `lint` or `install` missing: [`references/missing-commands.md`](references/missing-commands.md).
+
+## 4. Offer the first step
 
 Ask through `AskUserQuestion`, in {{kit.responseLanguage}}, with these options (the first one recommended):
 

package/kit/workflow/skills/start/references/missing-commands.md

@@ -0,0 +1,17 @@
+# Step 3: proposing the missing commands
+
+Covers the four keys `jh check` and the lane setup run: `commands.test`, `typecheck`, `lint` and `install`.
+
+1. If this repository has no `.jackherd/config.json`, propose `bunx jackherd init`; step 3 ends there.
+2. Read the CI files once (`.github/workflows/*.yml` and `*.yaml`, `.gitlab-ci.yml`). Without any, read the build file
+   (`Cargo.toml`, `pom.xml`, `build.gradle.kts`, `go.mod`, `pyproject.toml`) and propose its toolchain's standard
+   command (`cargo test`, `go test ./...`, `mvn test`), with the build file as location.
+3. For each missing key, propose the CI step that runs it, as it runs from the repository root (fold a step's
+   `working-directory` in: `cd backend && cargo test`), with its location as `file:line`; for `install`, the
+   dependency install step. Checkout, cache and toolchain setup steps are no proposal. A key the files do not show
+   stays unset, and you say so.
+4. Ask once through `AskUserQuestion`, in {{kit.responseLanguage}}, with one option per proposed key as a
+   multiSelect. Write only the chosen ones, under `commands` in this repository's `.jackherd/config.json`.
+
+Done when each missing key of the four is written, declined, or named as not shown by the files, and a rerun of
+`jh config` no longer reports the written ones.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.12.7",
+  "version": "1.14.0",
   "keywords": [
     "claude-code",
     "coding-agents",

package/schemas/jackherd.schema.json

@@ -87,32 +87,26 @@
       "type": "object",
       "properties": {
         "test": {
-          "default": "bun test",
           "type": "string",
           "minLength": 1
         },
         "typecheck": {
-          "default": "bunx -p typescript tsc --noEmit",
           "type": "string",
           "minLength": 1
         },
         "lint": {
-          "default": "bunx @biomejs/biome check .",
           "type": "string",
           "minLength": 1
         },
         "format": {
-          "default": "bunx @biomejs/biome format --write .",
           "type": "string",
           "minLength": 1
         },
         "install": {
-          "default": "bun install",
           "type": "string",
           "minLength": 1
         },
         "dev": {
-          "default": "bun run dev",
           "type": "string",
           "minLength": 1
         }
@@ -132,7 +126,6 @@
           }
         },
         "lockFile": {
-          "default": "bun.lock",
           "type": "string",
           "pattern": "^(?![/-])(?!(?:.*\\/)?\\.\\.(?:\\/|$))[A-Za-z0-9._/-]+$"
         }
@@ -140,6 +133,13 @@
       "additionalProperties": false
     },
     "models": {
+      "default": {
+        "plan": "claude-opus-5-5",
+        "implement": "claude-sonnet-5-5",
+        "review": "claude-sonnet-5-5",
+        "explore": "claude-sonnet-5-5",
+        "orchestrate": "claude-opus-5-5"
+      },
       "type": "object",
       "propertyNames": {
         "type": "string",
@@ -749,7 +749,6 @@
       "type": "object",
       "properties": {
         "lintFilesCommand": {
-          "default": "bunx @biomejs/biome check --no-errors-on-unmatched",
           "type": "string",
           "minLength": 1
         },
@@ -774,6 +773,13 @@
                   "type": "string",
                   "minLength": 1
                 }
+              },
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "tests",
+                  "types"
+                ]
               }
             },
             "required": [
@@ -895,13 +901,34 @@
         "looseTests": {
           "default": false,
           "type": "boolean"
+        },
+        "roots": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "sourceFiles": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "testFiles": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
         }
       },
       "additionalProperties": false
     }
   },
-  "required": [
-    "models"
-  ],
   "additionalProperties": false
 }

package/src/check/command.ts

@@ -2,25 +2,38 @@ import { spawnSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
-import { findProjectRoot, globalConfigPath, locateConfigFile } from '../config/location'
+import { planRootsIn } from '../../kit/hooks/hooks/shared/boards'
+import { findProjectRoot, globalConfigPath, locateConfigFile, MANIFEST_FILE, TOOL_DIRECTORY } from '../config/location'
 import { readRepositoryFacts } from '../config/repository-facts'
+import { mainCheckout } from '../plans/git'
 import { baseRefOf } from '../plans/settings'
 import { type ChangedFile, parsePorcelain, STATUS_COMMAND } from './changes'
 import { deferralArrowCheck } from './deferral-arrows'
 import { runCheck, runProcess } from './execute'
+import { matchesAnyGlob } from './glob'
 import { parallelArgument, parallelReportLines } from './parallel-report'
-import { type CheckPlan, type Filesystem, isSlow, planChecks } from './plan'
+import { type CheckPlan, type CheckStack, checkStackOf, type Filesystem, isSlow, planChecks } from './plan'
 import { planStructureChecks } from './plan-structure-check'
 import { publicContentCheck } from './public-content-check'
-import { artifactResult, formatPlanHeader, formatResults, skippedSlowResult, summarize } from './report'
-import { type CheckResult, SKIP_SLOW_FLAG } from './result'
-import { type CheckSettings, CONFIG_PATH, parseCheckSettings } from './settings'
+import {
+  artifactResult,
+  formatPlanHeader,
+  formatResults,
+  missingCommandNotes,
+  missingTestCommandResult,
+  namedTestResult,
+  skippedSlowResult,
+  summarize,
+  testCommandResult,
+  untestedResult,
+} from './report'
+import { type CheckResult, RUN_MODE, type RunMode, runModeOf } from './result'
+import { isWorkspaceManifest, kitCopyPaths, WORKSPACE_LIST_FILE, WORKSPACE_MANIFEST } from './roots'
+import { type CheckSettings, CONFIG_PATH, noStackFallbackOf, parseCheckSettings, stackOf } from './settings'
 import { skillBudgetCheck } from './skill-budgets'
 
 type CheckTarget = { root: string; configPath: string }
 
-const TEST_FILE = /\.(test|spec)\.[cm]?[jt]sx?$/
-
 /**
  * Where the checks run and which config they read: the nearest project with `.jackherd/config.json`, else the
  * repository's top level with `~/.jackherd/config.json` (a global install in a repository without the kit).
@@ -53,11 +66,75 @@ const contentAt =
     return result.status === 0 ? result.stdout : null
   }
 
-const filesystemAt = (root: string): Filesystem => ({
-  hasPackageJson: (dir) => existsSync(join(root, dir, 'package.json')),
-  hasTsconfig: (dir) => existsSync(join(root, dir, 'tsconfig.json')),
-  hasTests: (dir) => existsSync(join(root, dir)) && readdirSync(join(root, dir)).some((entry) => TEST_FILE.test(entry)),
-})
+/** A file that is there but cannot be read or parsed; its message names the path. */
+export class UnreadableFileError extends Error {}
+
+const isMissingFile = (error: unknown): boolean => error instanceof Error && 'code' in error && error.code === 'ENOENT'
+
+const messageOf = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+/**
+ * A JSON file's parsed content; null only when the file is absent. A file that is there but cannot be read
+ * or parsed throws `UnreadableFileError`, so a broken manifest is reported instead of reading as no manifest.
+ */
+export const readJsonIfPresent = (path: string): unknown => {
+  let text: string
+  try {
+    text = readFileSync(path, 'utf8')
+  } catch (error) {
+    if (isMissingFile(error)) return null
+    throw new UnreadableFileError(`${path} cannot be read: ${messageOf(error)}`)
+  }
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    throw new UnreadableFileError(`${path} is not valid JSON: ${messageOf(error)}`)
+  }
+}
+
+/** Tracked files and the untracked ones git does not ignore, so a new test file counts before its first commit. */
+const REPOSITORY_FILES_COMMAND = ['ls-files', '--cached', '--others', '--exclude-standard']
+
+const repositoryFilesAt = (root: string): (() => readonly string[]) => {
+  let files: readonly string[] | null = null
+  return () => {
+    if (files === null) {
+      const result = spawnSync('git', REPOSITORY_FILES_COMMAND, {
+        cwd: root,
+        encoding: 'utf8',
+        maxBuffer: 256 * 1024 * 1024,
+      })
+      if (result.status !== 0) {
+        throw new UnreadableFileError(`git ${REPOSITORY_FILES_COMMAND.join(' ')} failed: ${result.stderr.trim()}`)
+      }
+      files = result.stdout.split('\n').filter((line) => line !== '')
+    }
+    return files
+  }
+}
+
+/** Whether a directory entry is a test file: by `check.testFiles` where set, else by the stack's pattern. */
+const testEntryOf =
+  (stack: CheckStack, testFiles: readonly string[] | undefined) =>
+  (dir: string, entry: string): boolean =>
+    testFiles === undefined
+      ? stack.testFile.test(entry)
+      : matchesAnyGlob(dir === '.' ? entry : `${dir}/${entry}`, testFiles)
+
+const filesystemAt = (root: string, stack: CheckStack, testFiles: readonly string[] | undefined): Filesystem => {
+  const holdsAny = (dir: string, names: readonly string[]) => names.some((name) => existsSync(join(root, dir, name)))
+  const isTestEntry = testEntryOf(stack, testFiles)
+  return {
+    isProjectRoot: (dir) => holdsAny(dir, stack.rootMarkers),
+    isWorkspaceRoot: (dir) =>
+      existsSync(join(root, dir, WORKSPACE_LIST_FILE)) ||
+      isWorkspaceManifest(readJsonIfPresent(join(root, dir, WORKSPACE_MANIFEST))),
+    hasTypeConfig: (dir) => holdsAny(dir, stack.typeMarkers),
+    hasTests: (dir) =>
+      existsSync(join(root, dir)) && readdirSync(join(root, dir)).some((entry) => isTestEntry(dir, entry)),
+    repositoryFiles: repositoryFilesAt(root),
+  }
+}
 
 const print = (lines: readonly string[]): void => {
   for (const line of lines) console.log(line)
@@ -67,7 +144,7 @@ const loadSettings = (configPath: string, root: string): CheckSettings | string
   try {
     return parseCheckSettings(JSON.parse(readFileSync(configPath, 'utf8')), readRepositoryFacts(root))
   } catch (error) {
-    return `${configPath} is not valid: ${error instanceof Error ? error.message : String(error)}`
+    return `${configPath} is not valid: ${messageOf(error)}`
   }
 }
 
@@ -99,18 +176,87 @@ const changedFiles = async (root: string): Promise<ChangedFile[] | string> => {
 const executePlan = async (
   plan: CheckPlan,
   root: string,
-  skipSlow: boolean,
+  mode: RunMode,
   ownChecks: readonly (CheckResult | null)[],
 ): Promise<CheckResult[]> => {
   const [slow, quick] = [plan.checks.filter(isSlow), plan.checks.filter((check) => !isSlow(check))]
   return [
     artifactResult(plan.artifacts),
-    ...ownChecks.filter((result) => result !== null),
+    ...[...ownChecks, untestedResult(plan.untestedSources, mode)].filter((result) => result !== null),
     ...(await Promise.all(quick.map((check) => runCheck(check, root)))),
-    ...(skipSlow ? [skippedSlowResult()] : await Promise.all(slow.map((check) => runCheck(check, root)))),
+    ...(mode === RUN_MODE.quick
+      ? [skippedSlowResult()]
+      : await Promise.all(slow.map((check) => runCheck(check, root)))),
   ]
 }
 
+/** Where a board's plans are read: this checkout, the main checkout and every lane worktree below it (`root` alone outside git). */
+const planRootsOf = (root: string, worktreeDirectory: string): string[] => {
+  try {
+    return [...new Set([resolve(root), ...planRootsIn(mainCheckout(root), worktreeDirectory)])]
+  } catch {
+    return [resolve(root)]
+  }
+}
+
+/** The checks jackherd runs itself beside the configured ones: public content, deferral arrows, skill budgets, plan structure. */
+const ownChecksOf = (root: string, paths: readonly string[], settings: CheckSettings, home: string) => [
+  publicContentCheck(root, paths, settings.check.publicContent, home),
+  deferralArrowCheck(root, paths, settings.planDirectory),
+  skillBudgetCheck(root, settings.check.skillBudgets),
+  ...planStructureChecks({
+    root,
+    paths,
+    planDirectory: settings.planDirectory,
+    language: settings.planLanguage,
+    previousOf: contentAt(root, 'HEAD'),
+    baseOf: contentAt(root, baseRefOf(settings)),
+    planRoots: planRootsOf(root, settings.worktreeDirectory),
+  }),
+]
+
+/**
+ * Plans the checks for the changed files, prints the plan's header and runs every check. A manifest that is
+ * there but cannot be read comes back as a message instead of a result list.
+ */
+const checkChanges = async (
+  files: readonly ChangedFile[],
+  root: string,
+  settings: CheckSettings,
+  mode: RunMode,
+  home: string,
+): Promise<CheckResult[] | string> => {
+  const stack = checkStackOf(stackOf(settings.stack))
+  let plan: CheckPlan
+  try {
+    const kitCopies = kitCopyPaths(readJsonIfPresent(join(root, TOOL_DIRECTORY, MANIFEST_FILE)))
+    plan = planChecks(
+      files,
+      {
+        commands: settings.commands,
+        check: settings.check,
+        stack,
+        kitCopies,
+        noStackFallback: noStackFallbackOf(settings),
+      },
+      filesystemAt(root, stack, settings.check.testFiles),
+    )
+  } catch (error) {
+    if (error instanceof UnreadableFileError) return error.message
+    throw error
+  }
+  print([
+    ...formatPlanHeader(files, plan, settings.stack),
+    ...missingCommandNotes(settings.commands, settings.check.lintFilesCommand, settings.stack),
+  ])
+  return executePlan(plan, root, mode, [
+    testCommandResult(settings.commands.test, settings.stack),
+    missingTestCommandResult(settings.commands.test, settings.stack),
+    namedTestResult(plan.sourcesWithoutNamedTest),
+    ...ownChecksOf(root, plan.paths, settings, home),
+  ])
+}
+
 /**
  * Runs the configured checks over the files `git status` reports. Exit code 1 when any check fails
  * or the configuration cannot be read. With `--parallel <plan>` it runs no check and prints the plan's waves and critical path.
@@ -139,25 +285,11 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
     console.log('Nothing changed.')
     return 0
   }
-
-  const plan = planChecks(files, settings.commands, settings.check, filesystemAt(root))
-  print(formatPlanHeader(files, plan))
-  const publicContent = publicContentCheck(root, plan.paths, settings.check.publicContent, home)
-  const deferralArrows = deferralArrowCheck(root, plan.paths, settings.planDirectory)
-  const planStructure = planStructureChecks({
-    root,
-    paths: plan.paths,
-    planDirectory: settings.planDirectory,
-    language: settings.planLanguage,
-    previousOf: contentAt(root, 'HEAD'),
-    baseOf: contentAt(root, baseRefOf(settings)),
-  })
-  const results = await executePlan(plan, root, args.includes(SKIP_SLOW_FLAG), [
-    publicContent,
-    deferralArrows,
-    skillBudgetCheck(root, settings.check.skillBudgets),
-    ...planStructure,
-  ])
+  const results = await checkChanges(files, root, settings, runModeOf(args), home)
+  if (typeof results === 'string') {
+    console.error(results)
+    return 1
+  }
   print(formatResults(results))
   const summary = summarize(results)
   console.log(`\n${summary.line}`)

package/src/check/file-kinds.ts

@@ -0,0 +1,142 @@
+import { basename, extname } from 'node:path'
+
+/**
+ * One rule of thumb for test and source files in any language, read where no detected stack has patterns of its
+ * own. `check.testFiles` and `check.sourceFiles` replace its answer for their kind.
+ */
+
+const TEST_DIRECTORIES = new Set(['test', 'tests', 'spec', '__tests__'])
+
+/** `test`, `tests` or `spec` as a word of the name: `parser_test`, `test_parser`, `parser.spec`. */
+const TEST_WORD = /(^|[._-])(tests?|spec)(?=$|[._-])/gi
+
+/** `Test`, `Tests` or `Spec` as a capitalised word at either end: `ParserTest`, `TestParser`, `ParserSpec`. */
+const CAMEL_TEST_SUFFIX = /(?<=[a-z0-9])(Tests?|Spec)$/
+const CAMEL_TEST_PREFIX = /^Tests?(?=[A-Z])/
+
+const DOCUMENT_EXTENSIONS = ['.md', '.mdx', '.rst', '.adoc', '.txt']
+const CONFIG_EXTENSIONS = [
+  '.json',
+  '.jsonc',
+  '.json5',
+  '.yaml',
+  '.yml',
+  '.toml',
+  '.ini',
+  '.cfg',
+  '.conf',
+  '.xml',
+  '.properties',
+  '.env',
+  '.gradle',
+  '.kts',
+  '.csproj',
+  '.fsproj',
+  '.sln',
+]
+const LOCK_EXTENSIONS = ['.lock', '.lockb', '.sum']
+const ASSET_EXTENSIONS = [
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.avif',
+  '.ico',
+  '.bmp',
+  '.svg',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.otf',
+  '.eot',
+  '.css',
+  '.scss',
+  '.sass',
+  '.less',
+  '.html',
+  '.htm',
+  '.mp3',
+  '.mp4',
+  '.wav',
+  '.webm',
+  '.mov',
+  '.pdf',
+  '.zip',
+  '.gz',
+  '.tar',
+]
+const NON_SOURCE_EXTENSIONS = new Set([
+  ...DOCUMENT_EXTENSIONS,
+  ...CONFIG_EXTENSIONS,
+  ...LOCK_EXTENSIONS,
+  ...ASSET_EXTENSIONS,
+])
+
+/** Build files whose extension reads like code. */
+const CONFIG_FILE_NAMES = new Set(['go.mod', 'go.work'])
+
+/** Container files named by their prefix (`Dockerfile.dev`). */
+const CONTAINER_FILE = /^(Dockerfile|Containerfile)(\.|$)/
+
+const DOCUMENT_DIRECTORIES = new Set(['docs', 'doc'])
+
+const directoriesOf = (path: string): string[] => path.split('/').slice(0, -1)
+
+const stemOf = (path: string): string => basename(path, extname(path))
+
+const isInTestDirectory = (path: string): boolean =>
+  directoriesOf(path).some((directory) => TEST_DIRECTORIES.has(directory.toLowerCase()))
+
+const hasTestWord = (stem: string): boolean => new RegExp(TEST_WORD.source, 'i').test(stem)
+
+const hasCamelTestWord = (stem: string): boolean => CAMEL_TEST_SUFFIX.test(stem) || CAMEL_TEST_PREFIX.test(stem)
+
+export const isTestFile = (path: string): boolean => {
+  const stem = stemOf(path)
+  return isInTestDirectory(path) || hasTestWord(stem) || hasCamelTestWord(stem)
+}
+
+/** Dot directories (`.github`, `.claude`) hold tooling and agent texts; `docs/` holds documents. */
+const isInNonSourceDirectory = (path: string): boolean =>
+  directoriesOf(path).some((directory) => directory.startsWith('.') || DOCUMENT_DIRECTORIES.has(directory))
+
+/** A file without extension is a build or legal file (`Makefile`, `LICENSE`); a dot file is tooling (`.gitignore`). */
+const isNonSourceName = (name: string): boolean =>
+  extname(name) === '' || name.startsWith('.') || CONFIG_FILE_NAMES.has(name) || CONTAINER_FILE.test(name)
+
+/** Code a test covers: every file except tests, documents, configs, lock files and assets. */
+export const isSourceFile = (path: string): boolean => {
+  const name = basename(path)
+  return (
+    !isTestFile(path) &&
+    !isInNonSourceDirectory(path) &&
+    !isNonSourceName(name) &&
+    !NON_SOURCE_EXTENSIONS.has(extname(name).toLowerCase())
+  )
+}
+
+const LEADING_SEPARATORS = /^[._-]+/
+
+/** The name a test file covers: its stem without the test word (`test_parser.py` → `parser`); null when nothing is left. */
+export const testStemOf = (path: string): string | null => {
+  const stem = stemOf(path)
+  const stripped = stem
+    .replace(TEST_WORD, (_match, separator: string) => separator)
+    .replace(CAMEL_TEST_SUFFIX, '')
+    .replace(CAMEL_TEST_PREFIX, '')
+    .replace(LEADING_SEPARATORS, '')
+    .replace(/[._-]+$/, '')
+  return stripped === '' ? null : stripped
+}
+
+/** The names the test files among `files` cover, built once per run. */
+export const testStemsOf = (files: readonly string[], isTest: (path: string) => boolean): ReadonlySet<string> =>
+  new Set(files.filter(isTest).flatMap((file) => testStemOf(file) ?? []))
+
+/**
+ * Whether a test file of the source's name lies anywhere in the repository: `src/parser.rs` ↔ `tests/parser.rs`,
+ * `parser_test.go`, `test_parser.py`, `ParserTest.java`. Only the last extension of the source is dropped, so
+ * `foo.module.ts` needs `foo.module.test.ts`.
+ */
+export const hasNamedTest = (source: string, testStems: ReadonlySet<string>): boolean => testStems.has(stemOf(source))