pipework 0.268.0 → 0.270.0

package/src/cli/commands/check.ts

@@ -2,7 +2,7 @@ import { execSync, execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { createHash } from 'node:crypto'
-import { join, dirname, isAbsolute, resolve } from 'node:path'
+import { join, dirname, isAbsolute, relative, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { createRequire } from 'node:module'
 
@@ -26,6 +26,24 @@ import { StartupValidationError } from '../../core/validation/types.js'
 import type { Manifold } from '../../core/pipework.js'
 import type { LintConfig, VitestConfig } from '../../core/config/schema.js'
 import { shardArg, shardModules, type Shard } from './shard.js'
+import { record, emitJson, type StepName, type StepRecord, type StepSelection, type StepViolation } from './check-steps.js'
+
+function stepRecord(
+  step: StepName,
+  status: StepRecord['status'],
+  violations: readonly StepViolation[] = [],
+  scannedFiles?: readonly string[],
+): StepRecord {
+  return record(step, pipeworkVersion(), status, violations, scannedFiles)
+}
+
+export interface CheckOptions {
+  /** `json`: one record per step on stdout (or `outputFile`); human lines stay on stderr. */
+  readonly format?: 'human' | 'json'
+  readonly outputFile?: string | undefined
+  /** Which steps run; the rest are recorded as skipped. */
+  readonly select?: StepSelection
+}
 
 // #322: discoverInstance evaluates pipework.config.ts — a dynamic import plus a
 // full module evaluation. A single `check` run needs it from four call sites;
@@ -42,24 +60,36 @@ async function discoverInstanceCached(cwd: string): Promise<Manifold> {
   return loading
 }
 
-export async function check(cwd: string, scope?: ScopeMode, shard?: Shard): Promise<void> {
+export async function check(cwd: string, scope?: ScopeMode, shard?: Shard, options: CheckOptions = {}): Promise<void> {
   instanceCache = new Map()
   let failed = false
-
-  const checksumOk = verifyChecksums(cwd)
-  if (!checksumOk) {
-    failed = true
-  }
-
-  const vitestOk = await verifyVitestConfig(cwd)
-  if (!vitestOk) {
-    failed = true
-  }
-
-  const eslintOk = verifyEslintConfig(cwd)
-  if (!eslintOk) {
-    failed = true
-  }
+  const selected = options.select ?? (() => true)
+  const records: StepRecord[] = []
+
+  // A deselected step is named in the human output; a step whose precondition is
+  // absent is skipped as it always was, without a line.
+  const skip = (step: StepName, label: string, reason: string): void => {
+    if (!selected(step)) warn(`${label} — skipped (not selected)`)
+    records.push(record(step, pipeworkVersion(), 'skipped', [], undefined, selected(step) ? reason : 'not selected'))
+  }
+  // A step that prints its own lines and answers pass/fail.
+  const plain = async (step: StepName, label: string, fn: () => boolean | Promise<boolean>): Promise<void> => {
+    if (!selected(step)) return skip(step, label, '')
+    const ok = await fn()
+    records.push(stepRecord(step, ok ? 'passed' : 'failed'))
+    if (!ok) failed = true
+  }
+  // A step that prints its own lines and returns its record.
+  const rich = async (step: StepName, label: string, fn: () => StepRecord | Promise<StepRecord>): Promise<void> => {
+    if (!selected(step)) return skip(step, label, '')
+    const result = await fn()
+    records.push(result)
+    if (result.status === 'failed') failed = true
+  }
+
+  await plain('checksums', 'Workspace checksums', () => verifyChecksums(cwd))
+  await plain('vitest-config', 'Vitest config', () => verifyVitestConfig(cwd))
+  await plain('eslint-config', 'Eslint config', () => verifyEslintConfig(cwd))
 
   const { paths: modulePaths, all: fullScope, configError, basis } = await resolveModulePaths(cwd, scope)
 
@@ -70,93 +100,143 @@ export async function check(cwd: string, scope?: ScopeMode, shard?: Shard): Prom
   // 0 with "All checks passed". A step that cannot run is a failed step: the
   // load failure is reported here and fails the run. The remaining steps still
   // execute so one run surfaces everything it can, but none of them can green it.
-  if (configError !== undefined) {
+  if (!selected('config-load')) {
+    skip('config-load', 'Config load', '')
+  } else if (configError !== undefined) {
     info('Config load')
     logError('Config load — pipework.config.ts could not be loaded. Config-derived steps ran degraded or not at all.')
     for (const line of configError.message.split('\n')) {
       process.stderr.write(`  ${line}\n`)
     }
+    records.push(stepRecord('config-load', 'failed', [{ rule: 'config/load', file: CONFIG_FILE, line: 0, message: configError.message }]))
     failed = true
+  } else {
+    records.push(stepRecord('config-load', 'passed'))
   }
 
   if (modulePaths.length > 0) {
     const sourceFiles = findSourceFiles(cwd, modulePaths)
 
-    const doctrineOk = runDoctrineValidation(cwd, sourceFiles)
-    if (!doctrineOk) {
-      failed = true
-    }
+    await rich('doctrine', 'Doctrine validation', () => doctrineStep(cwd, sourceFiles))
 
     // Phase 4b: the flow and cardinality checks are hard errors. Consumers
     // upgrading from an earlier release run `pipework codemod` once to fill
     // missing `@downstream` cardinalities; anything the codemod cannot
     // resolve (indirection, non-trivial form, method flow steps, orphans)
     // must be fixed by hand before the build will pass.
-    if (!runFlowCheck(cwd, sourceFiles)) {
-      failed = true
-    }
-    const configuredStructuralMax = await loadConfiguredStructuralMax(cwd)
-    if (!runCardinalityCheck(cwd, sourceFiles, configuredStructuralMax, fullScope)) {
-      failed = true
-    }
+    await rich('flow', 'Flow annotations', () => flowStep(cwd, sourceFiles))
+    await rich('cardinality', 'Flow cardinality', async () =>
+      cardinalityStep(cwd, sourceFiles, await loadConfiguredStructuralMax(cwd), fullScope))
 
     // Phase 6f: Tier-2 coverage ships as warning. Surfaces structural gaps —
     // I/O outside any flow_step, more than one I/O in a single flow_step —
     // without failing the build. Phase 7a flips it to error once consumer
     // corpora have migrated to the new write surface. Consumers extend the
     // I/O call-target registry through `trace.io` in pipework.config.ts (Q9).
-    const consumerIoPatterns = await loadConsumerIoPatterns(cwd)
-    runCoverageCheckWarning(cwd, sourceFiles, consumerIoPatterns)
+    await rich('coverage', 'Flow coverage', async () =>
+      coverageStep(cwd, sourceFiles, await loadConsumerIoPatterns(cwd)))
 
-    const lintOk = await runLint(cwd, modulePaths, shard)
-    if (!lintOk) {
-      failed = true
+    await plain('lint', 'Lint', () => runLint(cwd, modulePaths, shard))
+    await plain('typecheck', 'Type check', () => runTypeCheck(cwd, modulePaths, shard))
+  } else {
+    for (const [step, label] of [
+      ['doctrine', 'Doctrine validation'], ['flow', 'Flow annotations'], ['cardinality', 'Flow cardinality'],
+      ['coverage', 'Flow coverage'], ['lint', 'Lint'], ['typecheck', 'Type check'],
+    ] as const) {
+      skip(step, label, 'no modules resolved')
     }
-
-    const typeCheckOk = await runTypeCheck(cwd, modulePaths, shard)
-    if (!typeCheckOk) {
-      failed = true
+    if (scope !== undefined && scope.kind === 'diff') {
+      // The basis says WHY the set is empty — a green here must state the scope
+      // it rested on, or an empty basis reads as "everything passed".
+      success(`No affected modules — per-module checks skipped (basis: ${basis ?? 'unknown'})`)
+    } else {
+      // Not a diff scope, so this is not "nothing changed" — no module could be
+      // resolved at all. Every per-module step was skipped; say so rather than
+      // letting their absence read as a clean pass (#335).
+      warn('No modules resolved — lint, type check, doctrine and flow checks did NOT run')
     }
-  } else if (scope !== undefined && scope.kind === 'diff') {
-    // The basis says WHY the set is empty — a green here must state the scope
-    // it rested on, or an empty basis reads as "everything passed".
-    success(`No affected modules — per-module checks skipped (basis: ${basis ?? 'unknown'})`)
-  } else {
-    // Not a diff scope, so this is not "nothing changed" — no module could be
-    // resolved at all. Every per-module step was skipped; say so rather than
-    // letting their absence read as a clean pass (#335).
-    warn('No modules resolved — lint, type check, doctrine and flow checks did NOT run')
   }
 
   if (configError === undefined && findConfig(cwd) !== null) {
-    if (!(await runStartupChecks(cwd))) {
-      failed = true
-    }
+    await plain('startup', 'Startup checks', () => runStartupChecks(cwd))
+  } else {
+    skip('startup', 'Startup checks', 'no loadable pipework.config.ts')
   }
 
   const boundaryScript = join(cwd, 'scripts', 'check-boundaries.js')
   if (existsSync(boundaryScript)) {
-    if (!runStep('Boundaries', 'node scripts/check-boundaries.js', cwd)) {
-      failed = true
-    }
+    await plain('boundaries', 'Boundaries', () => runStep('Boundaries', 'node scripts/check-boundaries.js', cwd))
+  } else {
+    skip('boundaries', 'Boundaries', 'no scripts/check-boundaries.js')
   }
 
-  const depCheckOk = runDependencyCheck(cwd)
-  if (!depCheckOk) {
-    failed = true
-  }
+  await plain('dependencies', 'Dependency boundaries', () => runDependencyCheck(cwd))
+  await plain('install', 'pipework install integrity', () => runPipeworkCopiesCheck(cwd))
 
-  const copiesOk = runPipeworkCopiesCheck(cwd)
-  if (!copiesOk) {
-    failed = true
-  }
+  if (options.format === 'json') emitJson(records, options.outputFile)
 
   if (failed) process.exit(1)
-  success('All checks passed')
+  const deselected = records.filter(r => r.reason === 'not selected').map(r => r.step)
+  success(deselected.length === 0 ? 'All checks passed' : `Selected checks passed (not run: ${deselected.join(', ')})`)
+}
+
+export interface StepCommandOptions {
+  readonly format?: 'human' | 'json'
+  readonly outputFile?: string | undefined
+  readonly scope?: ScopeMode
+  /** Explicit files (doctrine, flow, cardinality): only these are judged. */
+  readonly files?: readonly string[]
+}
+
+/** `pipework doctrine|flow|cardinality|startup`: one step alone. Returns the exit code. */
+export async function stepCommand(
+  cwd: string,
+  step: 'doctrine' | 'flow' | 'cardinality' | 'startup',
+  options: StepCommandOptions = {},
+): Promise<number> {
+  instanceCache = new Map()
+  const files = options.files ?? []
+  let result: StepRecord
+
+  if (step === 'startup') {
+    if (files.length > 0) throw new Error('startup takes no files.')
+    result = await startupStep(cwd)
+  } else {
+    let sourceFiles: string[]
+    let fullScope = false
+    let configError: Error | undefined
+    if (files.length > 0) {
+      sourceFiles = files.map(f => {
+        const rel = relative(cwd, resolve(cwd, f))
+        if (rel.startsWith('..') || isAbsolute(rel)) throw new Error(`${f} is outside ${cwd}.`)
+        if (!existsSync(join(cwd, rel))) throw new Error(`${f} does not exist.`)
+        return rel.split(sep).join('/')
+      })
+    } else {
+      const resolved = await resolveModulePaths(cwd, options.scope)
+      configError = resolved.configError
+      fullScope = resolved.all
+      sourceFiles = findSourceFiles(cwd, resolved.paths)
+    }
+    if (configError !== undefined) {
+      logError('Config load — pipework.config.ts could not be loaded.')
+      process.stderr.write(`  ${configError.message}\n`)
+      result = stepRecord(step, 'failed', [{ rule: 'config/load', file: CONFIG_FILE, line: 0, message: configError.message }])
+    } else if (step === 'doctrine') {
+      result = doctrineStep(cwd, sourceFiles)
+    } else if (step === 'flow') {
+      result = flowStep(cwd, sourceFiles)
+    } else {
+      result = cardinalityStep(cwd, sourceFiles, await loadConfiguredStructuralMax(cwd), fullScope)
+    }
+  }
+
+  if (options.format === 'json') emitJson(result, options.outputFile)
+  return result.status === 'failed' ? 1 : 0
 }
 
 /** The startup checks that need no database — what `serve` would refuse before connecting. */
-export async function runStartupChecks(cwd: string): Promise<boolean> {
+export async function startupStep(cwd: string): Promise<StepRecord> {
   info('Startup checks')
   let doors: readonly string[] = []
   let roles: readonly string[] = []
@@ -173,11 +253,14 @@ export async function runStartupChecks(cwd: string): Promise<boolean> {
       for (const issue of err.issues) {
         process.stderr.write(`  [${issue.phase}] ${issue.message}\n`)
       }
-    } else {
-      logError('Startup checks — could not run')
-      process.stderr.write(`  ${err instanceof Error ? err.message : String(err)}\n`)
+      return stepRecord('startup', 'failed', err.issues.map(issue => ({
+        rule: `startup/${issue.phase}`, file: CONFIG_FILE, line: 0, message: issue.message,
+      })))
     }
-    return false
+    logError('Startup checks — could not run')
+    const message = err instanceof Error ? err.message : String(err)
+    process.stderr.write(`  ${message}\n`)
+    return stepRecord('startup', 'failed', [{ rule: 'startup/could-not-run', file: CONFIG_FILE, line: 0, message }])
   }
   success('Startup checks')
   for (const line of roles) info(line)
@@ -185,7 +268,11 @@ export async function runStartupChecks(cwd: string): Promise<boolean> {
     success(`Doors (${String(doors.length)} declared)`)
     for (const line of doors) info(`  ${line}`)
   }
-  return true
+  return stepRecord('startup', 'passed')
+}
+
+export async function runStartupChecks(cwd: string): Promise<boolean> {
+  return (await startupStep(cwd)).status === 'passed'
 }
 
 /** One line per platform-mode database: the role a running manifold connects as, and the only callers that may open the owner. */
@@ -505,74 +592,74 @@ function findStaleVitestConfigs(cwd: string): string[] {
   return stale.sort()
 }
 
-function runDoctrineValidation(cwd: string, sourceFiles: string[]): boolean {
+function printGrouped(violations: readonly StepViolation[]): void {
+  const grouped = groupByRule(violations)
+  for (const [rule, items] of grouped) {
+    logError(`${rule} (${String(items.length)} violation${items.length === 1 ? '' : 's'})`)
+    for (const v of items.slice(0, 5)) {
+      warn(`  ${v.file}:${String(v.line)} — ${v.message}`)
+    }
+    if (items.length > 5) {
+      warn(`  ... and ${String(items.length - 5)} more`)
+    }
+  }
+}
+
+export function doctrineStep(cwd: string, sourceFiles: readonly string[]): StepRecord {
   info('Doctrine validation')
 
   if (sourceFiles.length === 0) {
     success('Doctrine validation (no source files)')
-    return true
+    return stepRecord('doctrine', 'passed', [], [])
   }
 
   const result = validateDoctrine(cwd, sourceFiles)
 
   if (result.violations.length === 0) {
     success(`Doctrine validation (${String(result.scanned)} files scanned)`)
-    return true
-  }
-
-  const grouped = groupByRule(result.violations)
-  for (const [rule, items] of grouped) {
-    logError(`${rule} (${String(items.length)} violation${items.length === 1 ? '' : 's'})`)
-    for (const v of items.slice(0, 5)) {
-      warn(`  ${v.file}:${String(v.line)} — ${v.message}`)
-    }
-    if (items.length > 5) {
-      warn(`  ... and ${String(items.length - 5)} more`)
-    }
+    return stepRecord('doctrine', 'passed', [], result.scannedFiles)
   }
 
-  return false
+  printGrouped(result.violations)
+  return stepRecord('doctrine', 'failed', result.violations, result.scannedFiles)
 }
 
-export function runFlowCheck(cwd: string, sourceFiles: string[]): boolean {
+export function flowStep(cwd: string, sourceFiles: readonly string[]): StepRecord {
   info('Flow annotations')
 
   if (sourceFiles.length === 0) {
     success('Flow annotations (no source files)')
-    return true
+    return stepRecord('flow', 'passed', [], [])
   }
 
   const result = checkFlowAnnotations(cwd, sourceFiles)
 
   if (result.violations.length === 0) {
     success(`Flow annotations (${String(result.scanned)} files scanned)`)
-    return true
+    return stepRecord('flow', 'passed', [], result.scannedFiles)
   }
 
-  const grouped = groupByRule(result.violations)
-  for (const [rule, items] of grouped) {
-    logError(`${rule} (${String(items.length)} violation${items.length === 1 ? '' : 's'})`)
-    for (const v of items.slice(0, 5)) {
-      warn(`  ${v.file}:${String(v.line)} — ${v.message}`)
-    }
-    if (items.length > 5) {
-      warn(`  ... and ${String(items.length - 5)} more`)
-    }
-  }
-  return false
+  printGrouped(result.violations)
+  return stepRecord('flow', 'failed', result.violations, result.scannedFiles)
 }
 
-export function runCardinalityCheck(
+export function runFlowCheck(cwd: string, sourceFiles: string[]): boolean {
+  return flowStep(cwd, sourceFiles).status === 'passed'
+}
+
+const CONFIG_FILE = 'pipework.config.ts'
+
+export function cardinalityStep(
   cwd: string,
-  sourceFiles: string[],
+  sourceFiles: readonly string[],
   configuredStructuralMax?: number,
   fullScope = true,
-): boolean {
+): StepRecord {
   info('Flow cardinality')
 
   if (sourceFiles.length === 0) {
     success('Flow cardinality (no source files)')
-    return true
+    return stepRecord('cardinality', 'passed', [], [])
   }
 
   const result = checkCardinality(cwd, sourceFiles)
@@ -593,69 +680,75 @@ export function runCardinalityCheck(
   //   derived < configured → only conclusive when the analyzer saw every module
   //     (`fullScope`). Under a scoped run an unscanned module may hold the
   //     deeper chain, so this is deferred to the full-scope check (pre-push).
-  let configFailed = false
+  const configViolations: StepViolation[] = []
   if (result.analyzed > 0 && configuredStructuralMax === undefined) {
     warn(
       `  trace.structuralMax is unset — runtime step cap is open (truncation never fires). ` +
       `Add this to pipework.config.ts: trace: { structuralMax: ${String(result.structuralMax)} }`,
     )
   } else if (result.analyzed > 0 && result.structuralMax > configuredStructuralMax!) {
-    logError(
-      `  trace.structuralMax is too low — config has ${String(configuredStructuralMax)}, ` +
-      `analyzer derived ${String(result.structuralMax)}. A trace this deep exceeds the cap and ` +
-      `would be truncated. Update pipework.config.ts: trace: { structuralMax: ${String(result.structuralMax)} }`,
-    )
-    configFailed = true
+    configViolations.push({
+      rule: 'cardinality/structural-max-too-low',
+      file: CONFIG_FILE,
+      line: 0,
+      message:
+        `trace.structuralMax is too low — config has ${String(configuredStructuralMax)}, ` +
+        `analyzer derived ${String(result.structuralMax)}. A trace this deep exceeds the cap and ` +
+        `would be truncated. Update pipework.config.ts: trace: { structuralMax: ${String(result.structuralMax)} }`,
+    })
   } else if (result.analyzed > 0 && result.structuralMax < configuredStructuralMax! && fullScope) {
-    logError(
-      `  trace.structuralMax is stale — config has ${String(configuredStructuralMax)}, ` +
-      `analyzer derived ${String(result.structuralMax)}. ` +
-      `Update pipework.config.ts: trace: { structuralMax: ${String(result.structuralMax)} }`,
-    )
-    configFailed = true
-  }
-
-  if (result.violations.length === 0) {
-    if (!configFailed) {
-      success(`Flow cardinality (${String(result.analyzed)} flow step${result.analyzed === 1 ? '' : 's'} analyzed)`)
-    }
-    return !configFailed
-  }
-
-  const grouped = groupByRule(result.violations)
-  for (const [rule, items] of grouped) {
-    logError(`${rule} (${String(items.length)} violation${items.length === 1 ? '' : 's'})`)
-    for (const v of items.slice(0, 5)) {
-      warn(`  ${v.file}:${String(v.line)} — ${v.message}`)
-    }
-    if (items.length > 5) {
-      warn(`  ... and ${String(items.length - 5)} more`)
-    }
-  }
-  return false
+    configViolations.push({
+      rule: 'cardinality/structural-max-stale',
+      file: CONFIG_FILE,
+      line: 0,
+      message:
+        `trace.structuralMax is stale — config has ${String(configuredStructuralMax)}, ` +
+        `analyzer derived ${String(result.structuralMax)}. ` +
+        `Update pipework.config.ts: trace: { structuralMax: ${String(result.structuralMax)} }`,
+    })
+  }
+  for (const v of configViolations) logError(`  ${v.message}`)
+
+  const violations = [...result.violations, ...configViolations]
+  if (violations.length === 0) {
+    success(`Flow cardinality (${String(result.analyzed)} flow step${result.analyzed === 1 ? '' : 's'} analyzed)`)
+    return stepRecord('cardinality', 'passed', [], result.scannedFiles)
+  }
+
+  printGrouped(result.violations)
+  return stepRecord('cardinality', 'failed', violations, result.scannedFiles)
 }
 
-export function runCoverageCheckWarning(
+export function runCardinalityCheck(
   cwd: string,
   sourceFiles: string[],
+  configuredStructuralMax?: number,
+  fullScope = true,
+): boolean {
+  return cardinalityStep(cwd, sourceFiles, configuredStructuralMax, fullScope).status === 'passed'
+}
+
+export function coverageStep(
+  cwd: string,
+  sourceFiles: readonly string[],
   extras: Readonly<Record<string, 'read' | 'write'>> = {},
-): void {
+): StepRecord {
   info('Flow coverage (Tier-2, warning)')
 
   if (sourceFiles.length === 0) {
     success('Flow coverage (no source files)')
-    return
+    return stepRecord('coverage', 'passed', [], [])
   }
 
   const result = checkCoverage(cwd, sourceFiles, extras)
 
   if (result.violations.length === 0) {
     success(`Flow coverage (${String(result.scanned)} files scanned)`)
-    return
+    return stepRecord('coverage', 'passed', [], result.scannedFiles)
   }
 
-  // Warning mode: emit diagnostics but never bump `failed`. The caller never
-  // sees a return value — this rule cannot fail the build until Phase 7a.
+  // Warning mode: emit diagnostics but never fail. This rule cannot fail the
+  // build until Phase 7a, so the record is passed with its warnings listed.
   const grouped = groupByRule(result.violations)
   warn(`Flow coverage (${String(result.violations.length)} warning${result.violations.length === 1 ? '' : 's'})`)
   for (const [rule, items] of grouped) {
@@ -667,6 +760,15 @@ export function runCoverageCheckWarning(
       warn(`    ... and ${String(items.length - 5)} more`)
     }
   }
+  return stepRecord('coverage', 'passed', result.violations, result.scannedFiles)
+}
+
+export function runCoverageCheckWarning(
+  cwd: string,
+  sourceFiles: string[],
+  extras: Readonly<Record<string, 'read' | 'write'>> = {},
+): void {
+  coverageStep(cwd, sourceFiles, extras)
 }
 
 function groupByRule<T extends { readonly rule: string }>(items: readonly T[]): Map<string, T[]> {
@@ -1273,7 +1375,7 @@ function runDependencyCheck(cwd: string): boolean {
 // limits on constrained hosts (#322 ran these via `Promise.all`; that is the
 // OOM this reverts). The wall-clock cost of a serial loop over 2–3 modules is
 // negligible next to an OOM kill.
-async function runLint(cwd: string, allModules: string[], shard?: Shard): Promise<boolean> {
+export async function runLint(cwd: string, allModules: string[], shard?: Shard): Promise<boolean> {
   const modulePaths = shardModules(allModules, shard)
   if (shard !== undefined && allModules.length > 0) {
     info(`Lint shard ${shardArg(shard)}: ${String(modulePaths.length)} of ${String(allModules.length)} module(s)`)
@@ -1283,6 +1385,7 @@ async function runLint(cwd: string, allModules: string[], shard?: Shard): Promis
 
   const eslintBin = resolveEslintBin(cwd)
   const includes = await loadLintIncludes(cwd)
+  const population = lintPopulation(cwd, allModules, includes, shard)
 
   // Per-module eslint cache, version-stamped and under the workspace-root
   // node_modules/.cache — always present, always gitignored. The version stamp
@@ -1300,8 +1403,8 @@ async function runLint(cwd: string, allModules: string[], shard?: Shard): Promis
   }
 
   let ok = true
-  for (const mod of modulePaths) {
-    if (!await lintDirectory(eslintBin, join(cwd, mod), mod, cacheFor(mod), includes.for(mod))) {
+  for (const mod of population.modules) {
+    if (!await lintDirectory(eslintBin, join(cwd, mod.path), mod.path, cacheFor(mod.path), mod.includes)) {
       ok = false
     }
   }
@@ -1310,9 +1413,7 @@ async function runLint(cwd: string, allModules: string[], shard?: Shard): Promis
   // root, outside every module. Those files were missing from the files-linted
   // count entirely — a coverage reading produced from a population that excluded
   // them. They get their own pass, counted and named like any module's.
-  const rootOnly = shard !== undefined && shard.index !== 1
-    ? []
-    : rootFilesOutsideModules(cwd, allModules, includes.for('.'))
+  const rootOnly = population.root
   if (rootOnly.length > 0) {
     if (!await lintDirectory(eslintBin, cwd, 'root', cacheFor('__root'), rootOnly)) {
       ok = false
@@ -1320,7 +1421,7 @@ async function runLint(cwd: string, allModules: string[], shard?: Shard): Promis
   }
 
   if (ok) {
-    const modules = `${String(modulePaths.length)} module${modulePaths.length === 1 ? '' : 's'}`
+    const modules = `${String(population.modules.length)} module${population.modules.length === 1 ? '' : 's'}`
     const root = rootOnly.length > 0
       ? ` + ${String(rootOnly.length)} root file${rootOnly.length === 1 ? '' : 's'}`
       : ''
@@ -1329,6 +1430,41 @@ async function runLint(cwd: string, allModules: string[], shard?: Shard): Promis
   return ok
 }
 
+export interface LintPopulation {
+  /** The sharded modules, each with the include globs `check` lints it with. */
+  readonly modules: ReadonlyArray<{ readonly path: string; readonly includes: readonly string[] | undefined }>
+  /** Root files outside every module; empty off shard 1. */
+  readonly root: string[]
+  /** Every file the run lints, repo-relative and sorted. */
+  readonly files: string[]
+}
+
+/**
+ * The files `check`'s lint pass covers: each sharded module's include globs plus the
+ * root-outside-modules pass (shard 1 only). `runLint` lints this population and
+ * `pipework lint --list-files` prints it, so the two cannot drift.
+ */
+export function lintPopulation(
+  cwd: string,
+  allModules: readonly string[],
+  includes: { for: (mod: string) => readonly string[] | undefined },
+  shard?: Shard,
+): LintPopulation {
+  const modules = shardModules([...allModules], shard).map(path => ({ path, includes: includes.for(path) }))
+  const root = shard !== undefined && shard.index !== 1
+    ? []
+    : rootFilesOutsideModules(cwd, [...allModules], includes.for('.'))
+  const files = new Set<string>(root)
+  for (const mod of modules) {
+    const dir = join(cwd, mod.path)
+    const prefix = normalizeModulePath(mod.path)
+    for (const f of filesMatchingGlobs(dir, lintIncludeGlobs(dir, mod.includes))) {
+      files.add(prefix === '' ? f : `${prefix}/${f}`)
+    }
+  }
+  return { modules, root, files: [...files].sort() }
+}
+
 /**
  * Root-level lintable files that no module covers (#402).
  *