pipework 0.252.0 → 0.253.0

package/src/cli/commands/check.ts

@@ -0,0 +1,1418 @@
+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 { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+const execFileAsync = promisify(execFile)
+import { computeChecksum, checksumFromPackageJson } from '../../workspace/checksum.js'
+import { VITEST_CONFIG_CONTENT, ESLINT_CONFIG_CONTENT } from '../../workspace/generate.js'
+import { validateDoctrine, findSourceFiles } from '../../lint/doctrine.js'
+import { checkFlowAnnotations } from '../../trace/check/flow-check.js'
+import { checkCoverage } from '../../trace/check/coverage-check.js'
+import { checkCardinality } from '../../trace/cardinality/check.js'
+import { checkDependencies } from '../../workspace/check-deps.js'
+import { detectPipeworkInstall, distinctPipeworkVersions } from '../../workspace/detect-pipework-copies.js'
+import { info, success, error as logError, warn } from '../output.js'
+import { OWNER_DDL_LABELS } from '../../data/db/owner-labels.js'
+import type { ScopeMode } from '../../workspace/affected.js'
+import { resolveAffected } from '../../workspace/affected.js'
+import { findConfig } from '../../core/config/discover.js'
+import { expandGlob, resolveModules, type ResolvedModule } from '../../workspace/discover.js'
+import { filesMatchingGlobs, globRoot, lintIncludeGlobs } from '../../lint/include.js'
+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'
+
+// #322: discoverInstance evaluates pipework.config.ts — a dynamic import plus a
+// full module evaluation. A single `check` run needs it from four call sites;
+// memoizing collapses that to one load. The cache is reset at the start of
+// every `check` so a long-lived process still picks up later config edits.
+let instanceCache = new Map<string, Promise<Manifold>>()
+
+async function discoverInstanceCached(cwd: string): Promise<Manifold> {
+  let loading = instanceCache.get(cwd)
+  if (loading === undefined) {
+    loading = import('../../core/config/discover.js').then(m => m.discoverInstance(cwd))
+    instanceCache.set(cwd, loading)
+  }
+  return loading
+}
+
+export async function check(cwd: string, scope?: ScopeMode, shard?: Shard): 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 { paths: modulePaths, all: fullScope, configError, basis } = await resolveModulePaths(cwd, scope)
+
+  // #335: a pipework.config.ts that exists but cannot be loaded used to be
+  // swallowed — module scoping silently degraded to filesystem discovery, which
+  // in a package with no pnpm-workspace.yaml resolves to *no* modules, so lint,
+  // type check, doctrine and the flow checks never ran and `check` still exited
+  // 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) {
+    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`)
+    }
+    failed = true
+  }
+
+  if (modulePaths.length > 0) {
+    const sourceFiles = findSourceFiles(cwd, modulePaths)
+
+    const doctrineOk = runDoctrineValidation(cwd, sourceFiles)
+    if (!doctrineOk) {
+      failed = true
+    }
+
+    // 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
+    }
+
+    // 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)
+
+    const lintOk = await runLint(cwd, modulePaths, shard)
+    if (!lintOk) {
+      failed = true
+    }
+
+    const typeCheckOk = await runTypeCheck(cwd, modulePaths, shard)
+    if (!typeCheckOk) {
+      failed = true
+    }
+  } 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
+    }
+  }
+
+  const boundaryScript = join(cwd, 'scripts', 'check-boundaries.js')
+  if (existsSync(boundaryScript)) {
+    if (!runStep('Boundaries', 'node scripts/check-boundaries.js', cwd)) {
+      failed = true
+    }
+  }
+
+  const depCheckOk = runDependencyCheck(cwd)
+  if (!depCheckOk) {
+    failed = true
+  }
+
+  const copiesOk = runPipeworkCopiesCheck(cwd)
+  if (!copiesOk) {
+    failed = true
+  }
+
+  if (failed) process.exit(1)
+  success('All checks passed')
+}
+
+/** The startup checks that need no database — what `serve` would refuse before connecting. */
+export async function runStartupChecks(cwd: string): Promise<boolean> {
+  info('Startup checks')
+  let doors: readonly string[] = []
+  let roles: readonly string[] = []
+  try {
+    const instance = await discoverInstanceCached(cwd)
+    await instance.validate()
+    // Loaded here, not at the top: it pulls in the runtime, which `lintDirectory` callers must not load.
+    const { queueFrameworkDoors } = await import('../../async/jobs/queue-door.js')
+    doors = describeDoors({ ...instance.config.doors, ...instance.config.frameworkDoors, ...queueFrameworkDoors(instance.config) })
+    roles = describeRuntimeRoles(instance.config.databases())
+  } catch (err: unknown) {
+    if (err instanceof StartupValidationError) {
+      logError(`Startup checks — ${String(err.issues.length)} issue${err.issues.length === 1 ? '' : 's'}`)
+      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 false
+  }
+  success('Startup checks')
+  for (const line of roles) info(line)
+  if (doors.length > 0) {
+    success(`Doors (${String(doors.length)} declared)`)
+    for (const line of doors) info(`  ${line}`)
+  }
+  return true
+}
+
+/** One line per platform-mode database: the role a running manifold connects as, and the only callers that may open the owner. */
+export function describeRuntimeRoles(databases: ReadonlyMap<string, { readonly name: string; readonly rls?: { readonly platformRole?: string } }>): string[] {
+  const platform = [...databases.values()].filter(db => db.rls?.platformRole !== undefined)
+  return platform.map(db =>
+    `runtime role: ${db.rls!.platformRole!} (owner used only for: ${OWNER_DDL_LABELS.join(', ')})` +
+    (platform.length > 1 ? ` [${db.name}]` : ''))
+}
+
+/** One line per declared door: `name -> database.table: reason`. */
+export function describeDoors(doors: Readonly<Record<string, { database: string; table: string; reason: string; framework?: boolean }>>): string[] {
+  return Object.entries(doors).map(([name, door]) =>
+    `${name} -> ${door.database}.${door.table}: ${door.reason}${door.framework === true ? ' (pipework\'s own)' : ''}`)
+}
+
+export interface ModuleScope {
+  readonly paths: string[]
+  /**
+   * True when every module is in scope. A graph-wide derivation — the Q7
+   * `structuralMax` — only reflects the whole codebase when this holds; under a
+   * scoped run it sees a subset and the derived value is a lower bound.
+   */
+  readonly all: boolean
+  /**
+   * Set when a pipework.config.ts was found but could not be loaded (#335).
+   * The module set then comes from filesystem discovery and is not the declared
+   * one — `--module` is not applied and the set can be empty. `check` reports
+   * this as a failed step; it must never contribute to a green exit.
+   */
+  readonly configError?: Error
+  /** Population line from `resolveAffected` — what the module scope was computed from. */
+  readonly basis?: string
+}
+
+export async function resolveModulePaths(cwd: string, scope?: ScopeMode): Promise<ModuleScope> {
+  const configPath = findConfig(cwd)
+
+  if (configPath !== null) {
+    let instance: Manifold
+    try {
+      instance = await discoverInstanceCached(cwd)
+    } catch (err: unknown) {
+      // Only the *load* is tolerated (degraded, and reported by the caller).
+      // Everything below — an unknown `--module`, a malformed `modules` map —
+      // is a user error with an actionable message, and swallowing it was its
+      // own false green: `pipework check --module typo` silently checked
+      // something other than what was asked for.
+      return {
+        paths: discoverModulePaths(cwd),
+        all: true,
+        configError: err instanceof Error ? err : new Error(String(err)),
+      }
+    }
+
+    const blueprint = instance.config.raw
+    const configDir = dirname(configPath)
+    const resolved = resolveModules(blueprint.modules, configDir)
+
+    // No declared modules: this is a single-package repo whose one implicit
+    // module is the repo root, addressed as '.'. Synthesize it so check
+    // typechecks/lints/validates the root `src/` — `runTypeCheck`, `runLint`,
+    // and `findSourceFiles` all collapse a '.' module path back to the root.
+    // `resolveVitestModules` projects the same '.' module, keeping the two in
+    // sync. Without this, `discoverModulePaths` excludes '.' and check silently
+    // skips typecheck/lint/doctrine for the entire project.
+    const effectiveModules: ResolvedModule[] = resolved.length === 0
+      ? [{ key: '.', relativePath: '.', config: {} }]
+      : resolved
+
+    const effectiveScope = scope ?? { kind: 'all' } as ScopeMode
+    const result = resolveAffected(configDir, effectiveModules, blueprint.name ?? '', effectiveScope, blueprint.fastPath?.baseBranches)
+
+    // Population line: what this run's module scope was computed from. Printed
+    // unconditionally so scope-of-invocation is visible next to every verdict.
+    info(`Scope: ${result.basis}`)
+
+    if (result.failedOpen === true) {
+      warn('Affected set could not be computed — checking all modules (fast path failed open). Issue #325.')
+    }
+
+    if (result.modules.size === 0) {
+      return { paths: [], all: result.all, basis: result.basis }
+    }
+
+    const paths = effectiveModules.map(m => m.relativePath).filter(p => result.modules.has(p))
+
+    if (!result.all) {
+      info(`Scoped to ${String(paths.length)} of ${String(effectiveModules.length)} module(s): ${paths.join(', ')}`)
+    }
+
+    return { paths, all: result.all, basis: result.basis }
+  }
+
+  return { paths: discoverModulePaths(cwd), all: true }
+}
+
+function verifyChecksums(cwd: string): boolean {
+  const pkgPath = join(cwd, 'package.json')
+
+  if (!existsSync(pkgPath)) {
+    return true
+  }
+
+  let pkg: Record<string, unknown>
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as Record<string, unknown>
+  } catch {
+    return true
+  }
+
+  if (typeof pkg['_generated'] !== 'string') {
+    return true
+  }
+
+  info('Workspace checksums')
+
+  const storedChecksum = checksumFromPackageJson(readFileSync(pkgPath, 'utf-8'))
+  if (storedChecksum === undefined) {
+    warn('package.json has _generated marker but no _checksum')
+    return true
+  }
+
+  const withoutChecksum = { ...pkg }
+  delete withoutChecksum['_checksum']
+  const content = JSON.stringify(withoutChecksum, null, 2) + '\n'
+  const expected = computeChecksum(content)
+
+  if (storedChecksum !== expected) {
+    logError('Workspace checksums — package.json has been modified. Run `pipework install` to regenerate.')
+    return false
+  }
+
+  success('Workspace checksums')
+  return true
+}
+
+export async function verifyVitestConfig(cwd: string): Promise<boolean> {
+  const configPath = join(cwd, 'vitest.config.ts')
+  if (!existsSync(configPath)) {
+    return true
+  }
+
+  info('Vitest config')
+
+  let ok = true
+  const hasVitest = await blueprintHasVitest(cwd)
+
+  if (hasVitest === undefined) {
+    // pipework.config.ts is absent or could not be loaded — we cannot confirm
+    // whether pipework owns vitest.config.ts, so we must not fail on a file
+    // ownership we can't verify.
+    warn('vitest.config.ts present but pipework.config.ts could not be loaded — skipping vitest config check')
+  } else if (hasVitest) {
+    // The blueprint declares `vitest`, so pipework generates and owns
+    // vitest.config.ts — it must match the generated template byte-for-byte.
+    const content = readFileSync(configPath, 'utf-8')
+    if (content !== VITEST_CONFIG_CONTENT) {
+      logError('vitest.config.ts is stale. Run `pipework install` to regenerate.')
+      ok = false
+    }
+  } else {
+    // The blueprint does not declare `vitest`, so pipework did not generate
+    // this file. Test config is centralized — a hand-written vitest.config.ts
+    // is not a supported layout.
+    logError(
+      'vitest.config.ts is hand-written, but test config is centralized.\n' +
+      '  Move its settings into the `vitest` key of pipework.config.ts and delete this file,\n' +
+      '  then run `pipework install` to regenerate it.',
+    )
+    ok = false
+  }
+
+  const staleConfigs = findStaleVitestConfigs(cwd)
+  if (staleConfigs.length > 0) {
+    warn('Stale vitest configs (test config is centralized in pipework.config.ts):')
+    for (const file of staleConfigs) {
+      warn(`  ${file} — remove this file`)
+    }
+    ok = false
+  }
+
+  if (ok) {
+    success(`Vitest config${await describeWorkerIsolation(cwd)}`)
+  }
+  return ok
+}
+
+/**
+ * Name the worker pool and isolation the projects actually run with.
+ *
+ * Pipework's defaults (`forks`, `isolate: false`) differ from vitest's own, so a suite
+ * migrating off a hand-written config changes isolation. Nothing said so (#394); the
+ * green line now does, and names each project that overrides.
+ */
+async function describeWorkerIsolation(cwd: string): Promise<string> {
+  let vitest: VitestConfig | undefined
+  try {
+    vitest = (await discoverInstanceCached(cwd)).config.raw.vitest
+  } catch {
+    return ''
+  }
+  if (vitest === undefined) return ''
+
+  const overrides: string[] = []
+  for (const [path, mod] of Object.entries(vitest.modules ?? {})) {
+    if (mod.pool !== undefined || mod.isolate !== undefined) overrides.push(path)
+    for (const [name, profile] of Object.entries(mod.profiles ?? {})) {
+      if (profile.pool !== undefined || profile.isolate !== undefined) overrides.push(`${path}:${name}`)
+    }
+  }
+
+  const base = ` (pool ${vitest.pool ?? 'forks'}, isolate ${String(vitest.isolate ?? false)})`
+  return overrides.length === 0 ? base : `${base}; overridden by ${overrides.join(', ')}`
+}
+
+export function verifyEslintConfig(cwd: string): boolean {
+  const configPath = join(cwd, 'eslint.config.js')
+  if (!existsSync(configPath)) {
+    return true
+  }
+
+  info('Eslint config')
+
+  // eslint.config.js is unconditionally generated by `pipework install` —
+  // when present it must match the template byte-for-byte. Consumer extensions
+  // (plugins, rules, additional flat-config blocks) flow through `lint.extra`
+  // in pipework.config.ts; the generated file is a thin resolver shell.
+  const content = readFileSync(configPath, 'utf-8')
+  if (content !== ESLINT_CONFIG_CONTENT) {
+    logError(
+      'eslint.config.js is stale. Run `pipework install` to regenerate.\n' +
+      '  Consumer plugins, rules, and additional flat-config blocks belong under\n' +
+      '  `lint.extra` in pipework.config.ts — the generated file is a resolver shell.',
+    )
+    return false
+  }
+
+  success('Eslint config')
+  return true
+}
+
+/**
+ * Returns whether the project's blueprint declares centralized `vitest` config,
+ * or `undefined` when there is no loadable pipework.config.ts to consult.
+ */
+async function blueprintHasVitest(cwd: string): Promise<boolean | undefined> {
+  if (findConfig(cwd) === null) return undefined
+  try {
+    const instance = await discoverInstanceCached(cwd)
+    return instance.config.raw.vitest !== undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Returns the configured `trace.structuralMax`, or `undefined` when the
+ * blueprint either doesn't set it or can't be loaded. The cardinality check
+ * uses this to verify the runtime cap against the value the analyzer derives.
+ */
+async function loadConfiguredStructuralMax(cwd: string): Promise<number | undefined> {
+  if (findConfig(cwd) === null) return undefined
+  try {
+    const instance = await discoverInstanceCached(cwd)
+    return instance.config.trace.structuralMax
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Returns the configured `trace.io` registry (Q9), or an empty record when
+ * the blueprint either doesn't extend the registry or can't be loaded. The
+ * Tier-2 coverage check unions this with the stock pipework registry.
+ */
+async function loadConsumerIoPatterns(cwd: string): Promise<Readonly<Record<string, 'read' | 'write'>>> {
+  if (findConfig(cwd) === null) return {}
+  try {
+    const instance = await discoverInstanceCached(cwd)
+    return instance.config.trace.io
+  } catch {
+    return {}
+  }
+}
+
+function findStaleVitestConfigs(cwd: string): string[] {
+  const workspaceYamlPath = join(cwd, 'pnpm-workspace.yaml')
+  if (!existsSync(workspaceYamlPath)) return []
+
+  const yaml = readFileSync(workspaceYamlPath, 'utf-8')
+  const packages: string[] = []
+  for (const line of yaml.split('\n')) {
+    const match = line.match(/^\s*-\s*"(.+)"/)
+    if (match?.[1] !== undefined && match[1] !== '.') {
+      packages.push(match[1])
+    }
+  }
+
+  const stale: string[] = []
+  for (const pkg of packages) {
+    const pkgDir = join(cwd, pkg)
+    if (!existsSync(pkgDir)) continue
+
+    try {
+      const entries = readdirSync(pkgDir)
+      for (const entry of entries) {
+        if (/^vitest.*\.config\.(ts|js|mts|mjs)$/.test(entry)) {
+          stale.push(join(pkg, entry))
+        }
+      }
+    } catch {
+      continue
+    }
+  }
+
+  return stale.sort()
+}
+
+function runDoctrineValidation(cwd: string, sourceFiles: string[]): boolean {
+  info('Doctrine validation')
+
+  if (sourceFiles.length === 0) {
+    success('Doctrine validation (no source files)')
+    return true
+  }
+
+  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 false
+}
+
+export function runFlowCheck(cwd: string, sourceFiles: string[]): boolean {
+  info('Flow annotations')
+
+  if (sourceFiles.length === 0) {
+    success('Flow annotations (no source files)')
+    return true
+  }
+
+  const result = checkFlowAnnotations(cwd, sourceFiles)
+
+  if (result.violations.length === 0) {
+    success(`Flow annotations (${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 false
+}
+
+export function runCardinalityCheck(
+  cwd: string,
+  sourceFiles: string[],
+  configuredStructuralMax?: number,
+  fullScope = true,
+): boolean {
+  info('Flow cardinality')
+
+  if (sourceFiles.length === 0) {
+    success('Flow cardinality (no source files)')
+    return true
+  }
+
+  const result = checkCardinality(cwd, sourceFiles)
+
+  // Verify the configured cap against what the analyzer just derived (Q7).
+  // Unset config + flow_steps present → warn with the recommended value (the
+  // runtime cap stays open until the user sets it). Zero flow_steps → no cap to
+  // check.
+  //
+  // The analyzer derives structuralMax from the source files it was handed.
+  // Under a scoped run (`--staged`, a diff) it sees only the affected modules,
+  // and dropping modules only ever shortens the longest step-chain — so the
+  // derived value is a *lower bound* on the true global max. That makes the two
+  // mismatch directions asymmetric:
+  //   derived > configured → a subset already exceeds the cap, so the whole
+  //     graph does too. The cap is genuinely too low: good traces would be
+  //     truncated. Sound under any scope → hard error.
+  //   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
+  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
+  } 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
+}
+
+export function runCoverageCheckWarning(
+  cwd: string,
+  sourceFiles: string[],
+  extras: Readonly<Record<string, 'read' | 'write'>> = {},
+): void {
+  info('Flow coverage (Tier-2, warning)')
+
+  if (sourceFiles.length === 0) {
+    success('Flow coverage (no source files)')
+    return
+  }
+
+  const result = checkCoverage(cwd, sourceFiles, extras)
+
+  if (result.violations.length === 0) {
+    success(`Flow coverage (${String(result.scanned)} files scanned)`)
+    return
+  }
+
+  // Warning mode: emit diagnostics but never bump `failed`. The caller never
+  // sees a return value — this rule cannot fail the build until Phase 7a.
+  const grouped = groupByRule(result.violations)
+  warn(`Flow coverage (${String(result.violations.length)} warning${result.violations.length === 1 ? '' : 's'})`)
+  for (const [rule, items] of grouped) {
+    warn(`  ${rule} (${String(items.length)})`)
+    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`)
+    }
+  }
+}
+
+function groupByRule<T extends { readonly rule: string }>(items: readonly T[]): Map<string, T[]> {
+  const map = new Map<string, T[]>()
+  for (const item of items) {
+    let arr = map.get(item.rule)
+    if (arr === undefined) {
+      arr = []
+      map.set(item.rule, arr)
+    }
+    arr.push(item)
+  }
+  return map
+}
+
+function discoverModulePaths(cwd: string): string[] {
+  const workspaceYamlPath = join(cwd, 'pnpm-workspace.yaml')
+  if (!existsSync(workspaceYamlPath)) return []
+
+  const yaml = readFileSync(workspaceYamlPath, 'utf-8')
+  const paths: string[] = []
+  for (const line of yaml.split('\n')) {
+    const match = line.match(/^\s*-\s*["']?([^"'\s]+)["']?/)
+    if (match?.[1] !== undefined && match[1] !== '.') {
+      const pattern = match[1]
+      if (pattern.endsWith('/*')) {
+        const base = pattern.slice(0, -2)
+        const baseDir = join(cwd, base)
+        if (existsSync(baseDir)) {
+          try {
+            const entries = readdirSync(baseDir, { withFileTypes: true })
+            for (const entry of entries) {
+              if (entry.isDirectory()) {
+                paths.push(join(base, entry.name))
+              }
+            }
+          } catch {
+            // skip
+          }
+        }
+      } else {
+        paths.push(pattern)
+      }
+    }
+  }
+
+  return paths
+}
+
+function runStep(name: string, cmd: string, cwd: string): boolean {
+  info(name)
+  try {
+    execSync(cmd, { cwd, stdio: 'pipe' })
+    success(name)
+    return true
+  } catch (err: unknown) {
+    logError(`${name} failed`)
+    if (typeof err === 'object' && err !== null && 'stdout' in err) {
+      process.stderr.write(String((err as { stdout: Buffer }).stdout))
+    }
+    return false
+  }
+}
+
+// Type-check every module serially. Each `tsc` instance can consume 800 MB–1.5
+// GB; spawning them concurrently via `Promise.all` exceeded a 2 GB ceiling on
+// memory-constrained hosts (an OOM kill, not a slow run). Serializing 2–3
+// modules costs negligible wall-clock next to that, and peak memory drops from
+// N×(process size) to 1×. The `tsc` binary is still resolved once rather than
+// re-resolved through `npx` per module (#322).
+async function runTypeCheck(cwd: string, allModules: string[], shard?: Shard): Promise<boolean> {
+  const modulePaths = shardModules(allModules, shard)
+  if (shard !== undefined && allModules.length > 0) {
+    info(`Type check shard ${shardArg(shard)}: ${String(modulePaths.length)} of ${String(allModules.length)} module(s)`)
+    if (modulePaths.length === 0) return true
+  }
+  if (allModules.length === 0) {
+    if (shard !== undefined && shard.index !== 1) return true
+    if (existsSync(join(cwd, 'tsconfig.json'))) {
+      return runStep('Type check', 'npx tsc --noEmit', cwd)
+    }
+    success('Type check (no tsconfig.json found)')
+    return true
+  }
+
+  info('Type check')
+  const tscBin = resolveTscBin(cwd)
+
+  let ok = true
+  for (const mod of modulePaths) {
+    const modDir = join(cwd, mod)
+    // `tsconfig.check.json` resolves cross-package imports from `src/`, so a
+    // clean checkout type-checks without a prior build (#270). The synthesized
+    // root module '.' has no check config — it has no siblings to resolve — so
+    // fall back to its build `tsconfig.json`.
+    const checkTsconfig = join(modDir, 'tsconfig.check.json')
+    const tsconfig = existsSync(checkTsconfig) ? checkTsconfig : join(modDir, 'tsconfig.json')
+    if (!existsSync(tsconfig)) continue
+
+    try {
+      await execFileAsync(tscBin, ['--noEmit', '-p', tsconfig], { cwd })
+    } catch (err: unknown) {
+      logError(`Type check failed: ${mod}`)
+      if (typeof err === 'object' && err !== null && 'stdout' in err) {
+        process.stderr.write(String((err as { stdout: string | Buffer }).stdout))
+      }
+      ok = false
+    }
+  }
+
+  if (ok) {
+    success(`Type check (${String(modulePaths.length)} module${modulePaths.length === 1 ? '' : 's'})`)
+  }
+  return ok
+}
+
+// Resolve the `tsc` binary once, the same way `resolveEslintBin` resolves
+// eslint — module manifest first, PATH fallback — so each module's type check
+// spawns the binary directly instead of paying an `npx` resolution per module.
+export function resolveTscBin(cwd: string): string {
+  const thisDir = dirname(fileURLToPath(import.meta.url))
+  const require = createRequire(import.meta.url)
+  try {
+    const pkgJsonPath = require.resolve('typescript/package.json', { paths: [cwd, thisDir] })
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as { bin?: string | Record<string, string> }
+    const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.['tsc']
+    if (binRel !== undefined) return join(dirname(pkgJsonPath), binRel)
+  } catch {
+    // fall through to PATH lookup
+  }
+
+  try {
+    const found = execSync('which tsc', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
+    return isAbsolute(found) ? found : resolve(cwd, found)
+  } catch {
+    throw new Error('tsc not found — typescript should be installed as a dependency of pipework')
+  }
+}
+
+export function resolveEslintBin(cwd: string): string {
+  // The resolved path is later handed to execSync with `cwd` set to each
+  // per-module directory, so it MUST be absolute — a relative path resolves
+  // against the wrong directory and fails to spawn.
+  const thisDir = dirname(fileURLToPath(import.meta.url))
+
+  // Resolve eslint as a module from the project root (and pipework's own
+  // install as a fallback). `./package.json` is in eslint's `exports`, the
+  // `./bin/eslint.js` subpath is not — so resolve the manifest, then derive
+  // the bin from it. This finds eslint whether pnpm hoisted it to the
+  // workspace root or nested it under pipework.
+  const require = createRequire(import.meta.url)
+  try {
+    const pkgJsonPath = require.resolve('eslint/package.json', { paths: [cwd, thisDir] })
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as { bin?: string | Record<string, string> }
+    const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.['eslint']
+    if (binRel !== undefined) return join(dirname(pkgJsonPath), binRel)
+  } catch {
+    // fall through to PATH lookup
+  }
+
+  try {
+    const found = execSync('which eslint', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
+    // Under pnpm, `which` can return a cwd-relative path (./node_modules/.bin/eslint).
+    // Anchor it to cwd so it survives the cwd change in lintDirectory().
+    return isAbsolute(found) ? found : resolve(cwd, found)
+  } catch {
+    throw new Error('eslint not found — it should be installed as a dependency of pipework')
+  }
+}
+
+// ESLint's `--cache` key is (file content + local eslint.config + eslint version)
+// — it does NOT include the transitive pipework ruleset that the local config
+// imports. So a pipework bump that tightens rules leaves every unchanged file's
+// cached "pass" verdict in place, false-greening pre-existing violations until
+// the file itself changes. Stamping the cache path with pipework's own version
+// (read here from pipework's package.json) makes a bump point eslint at a fresh
+// cache file, busting the stale verdicts. #781-followup
+function pipeworkVersion(): string {
+  // dist/cli/commands/check.js → pipework root is three levels up; mirrors the
+  // builtin-preset path resolution used in lintDirectory.
+  const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'package.json')
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: string }
+  return pkg.version ?? '0.0.0'
+}
+
+// Absolute path of the stamped eslint cache for one module. Under the
+// workspace-root `node_modules/.cache` (always gitignored, so the cache is never
+// committed and never travels between clones) and keyed on the pipework version
+// (so a ruleset bump points eslint at a fresh file instead of reusing stale
+// "pass" verdicts) and on `fingerprint`, the resolved tsconfig chain (#409 — the
+// type-aware rules' verdicts depend on it and eslint's own cache key does not).
+// `label` is a module path, so `/` and `\` are flattened to `__` — one file per
+// module, no nested dirs, no traversal out of the cache root.
+export function eslintCacheLocation(cwd: string, version: string, label: string, fingerprint?: string): string {
+  const stamp = fingerprint === undefined ? version : `${version}-${fingerprint}`
+  return join(cwd, 'node_modules', '.cache', 'pipework', `eslint-${stamp}-${label.replace(/[/\\]/g, '__')}`)
+}
+
+/**
+ * A hash of the tsconfigs the typescript project service will resolve for `targets`.
+ *
+ * The type-aware rules produce their verdict from the program that tsconfig defines,
+ * and a parse error is a verdict about the tsconfig alone. eslint's `--cache` key is
+ * (content + eslint config + eslint version) — none of that moves when a tsconfig
+ * does, so a cached verdict survives the checkout that changed it (#409). Stamping
+ * the chain into the cache path makes any change point eslint at a fresh file.
+ *
+ * Covered: the nearest `tsconfig.json` above each target, up to `dir`, and every file
+ * its `extends` reaches. Not covered: `references`, and a tsconfig outside `dir`.
+ */
+export function tsconfigFingerprint(dir: string, targets: readonly string[]): string {
+  const seen = new Map<string, string>()
+  for (const target of targets) {
+    const start = nearestTsconfig(dir, globRoot(target))
+    if (start !== undefined) collectTsconfigChain(start, seen)
+  }
+  const hash = createHash('sha256')
+  for (const path of [...seen.keys()].sort()) hash.update(path).update('\0').update(seen.get(path) ?? '').update('\0')
+  return hash.digest('hex').slice(0, 16)
+}
+
+// The tsconfig the project service picks for a file: the nearest one at or above it,
+// stopping at `dir` — the lint root, past which the service is not looking either.
+function nearestTsconfig(dir: string, relativeRoot: string): string | undefined {
+  let current = relativeRoot === '' ? dir : join(dir, relativeRoot)
+  for (;;) {
+    const candidate = join(current, 'tsconfig.json')
+    if (existsSync(candidate)) return candidate
+    if (resolve(current) === resolve(dir)) return undefined
+    const parent = dirname(current)
+    if (parent === current) return undefined
+    current = parent
+  }
+}
+
+function collectTsconfigChain(path: string, seen: Map<string, string>): void {
+  const key = resolve(path)
+  if (seen.has(key)) return
+  let raw: string
+  try {
+    raw = readFileSync(key, 'utf-8')
+  } catch {
+    return
+  }
+  seen.set(key, raw)
+
+  let extendsField: unknown
+  try {
+    extendsField = (JSON.parse(stripJsonComments(raw)) as { extends?: unknown }).extends
+  } catch {
+    // An unparseable tsconfig is itself part of the fingerprint — its content is
+    // already recorded, and there is no chain to follow.
+    return
+  }
+  const parents = typeof extendsField === 'string' ? [extendsField] : Array.isArray(extendsField) ? extendsField : []
+  for (const parent of parents) {
+    // Only a relative extends resolves to a file in the checkout; a package
+    // specifier lives in node_modules, which the pipework version stamp covers.
+    if (typeof parent === 'string' && parent.startsWith('.')) {
+      collectTsconfigChain(join(dirname(key), parent.endsWith('.json') ? parent : `${parent}.json`), seen)
+    }
+  }
+}
+
+// tsconfig.json is JSONC. Enough to reach `extends`; a miss only costs a coarser
+// fingerprint, never a wrong one, because the raw content is hashed regardless.
+function stripJsonComments(raw: string): string {
+  return raw.replace(/"(?:[^"\\]|\\.)*"|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, m => (m.startsWith('"') ? m : ''))
+}
+
+/**
+ * True when eslint reported a fatal parse error — a file it could not read at all.
+ *
+ * Distinct from a rule failure: it says the program the tsconfig defines could not be
+ * built, so it is never a fact about the file's content alone, and must not outlive
+ * the state that produced it in a cache eslint will happily reuse (#409).
+ */
+export function hasFatalParseError(stdout: string): boolean {
+  let results: unknown
+  try {
+    results = JSON.parse(stdout)
+  } catch {
+    return false
+  }
+  if (!Array.isArray(results)) return false
+  return results.some(r => {
+    const messages = (r as { messages?: unknown }).messages
+    return Array.isArray(messages) && messages.some(m => (m as { fatal?: unknown }).fatal === true)
+  })
+}
+
+function hasEslintConfig(dir: string): boolean {
+  return existsSync(join(dir, 'eslint.config.js'))
+    || existsSync(join(dir, 'eslint.config.mjs'))
+    || existsSync(join(dir, 'eslint.config.ts'))
+    || existsSync(join(dir, 'eslint.config.mts'))
+}
+
+/**
+ * The globs eslint is pointed at for `dir`, relative to `dir`.
+ *
+ * `configured` is the module's `lint.include` (or the global one). Unset, the globs
+ * cover `src` plus the `src` of each workspace package under `dir` — a nested pnpm
+ * workspace keeps its sources one level further down, and `eslint src` never sees
+ * them (#393).
+ */
+export function lintTargets(dir: string, configured?: readonly string[]): string[] {
+  return lintIncludeGlobs(dir, configured).filter(glob => {
+    const root = globRoot(glob)
+    return root === '' || existsSync(join(dir, root))
+  })
+}
+
+interface EslintFileResult {
+  readonly filePath: string
+  readonly messages?: ReadonlyArray<{ readonly message?: string; readonly severity?: number; readonly ruleId?: string | null }>
+}
+
+/**
+ * The files eslint actually linted, and any it refused, from `--format json` output.
+ *
+ * A file eslint declines to lint still appears in the report, carrying a single
+ * message with no rule — "File ignored because no matching configuration was
+ * supplied", or because it sits outside the base path. That is a silent skip, not a
+ * pass, so `check` treats it as a failure rather than counting the file green.
+ */
+export function readEslintReport(stdout: string): { linted: string[]; ignored: Array<{ file: string; reason: string }> } {
+  let results: EslintFileResult[]
+  try {
+    results = JSON.parse(stdout) as EslintFileResult[]
+  } catch {
+    return { linted: [], ignored: [] }
+  }
+
+  const linted: string[] = []
+  const ignored: Array<{ file: string; reason: string }> = []
+  for (const result of results) {
+    // eslint reports a skip as its only message, with no rule and warning severity —
+    // narrow on all three so a rule whose text happens to say "ignored" is not mistaken
+    // for one.
+    const skip = result.messages?.length === 1
+      ? result.messages.find(m =>
+          (m.ruleId === null || m.ruleId === undefined)
+          && m.severity === 1
+          && m.message !== undefined
+          && /^File ignored\b/i.test(m.message))
+      : undefined
+    if (skip !== undefined) {
+      ignored.push({ file: result.filePath, reason: skip.message ?? 'ignored' })
+    } else {
+      linted.push(result.filePath)
+    }
+  }
+  return { linted, ignored }
+}
+
+/**
+ * `--config <preset>` for a directory with no eslint config of its own, else nothing.
+ * `check` and `pipework lint` both use it, so they run the same resolved config.
+ */
+export function builtinConfigArgs(dir: string): string[] {
+  if (hasEslintConfig(dir)) return []
+  return ['--config', join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'lint', 'preset.js')]
+}
+
+export async function lintDirectory(
+  eslintBin: string,
+  dir: string,
+  label: string,
+  cacheLocation: string | ((fingerprint: string) => string),
+  configured?: readonly string[],
+): Promise<boolean> {
+  const globs = lintIncludeGlobs(dir, configured)
+  const targets = lintTargets(dir, configured)
+  // #392: a module whose globs reach nothing on disk used to report Lint ✓. A check
+  // that ran over nothing is not a check that passed.
+  if (targets.length === 0) return refuseEmptyLint(label, globs, 'none of these paths exist')
+
+  // The cache file is chosen only once the targets are known, because the tsconfig
+  // chain they resolve is part of its key (#409).
+  const cacheFile = typeof cacheLocation === 'string'
+    ? cacheLocation
+    : cacheLocation(tsconfigFingerprint(dir, targets))
+
+  // `--cache` lets ESLint skip files unchanged since the last run — without it
+  // every `check` rebuilds the whole program from scratch. #322
+  // `--cache-location` is version-stamped and lives under node_modules/.cache
+  // (computed in runLint) so a pipework ruleset bump busts the cache and a stale
+  // cache never gets committed or travels between clones. See pipeworkVersion.
+  // `--format json` so the pass can name what it linted and refuse a file eslint
+  // reported as ignored — the run's own record of coverage, not an exit code alone.
+  // `--no-error-on-unmatched-pattern`: a glob that reaches nothing is refused here, by
+  // refuseEmptyLint, which can say what to change. eslint's own error for it names the
+  // pattern and stops — it cannot mention `lint.include`.
+  const args = [
+    ...targets,
+    '--max-warnings', '0',
+    '--format', 'json',
+    '--no-error-on-unmatched-pattern',
+    '--cache', '--cache-location', cacheFile,
+  ]
+  args.push(...builtinConfigArgs(dir))
+
+  let stdout: string
+  try {
+    stdout = (await execFileAsync(eslintBin, args, { cwd: dir })).stdout
+  } catch (err: unknown) {
+    logError(`Lint failed: ${label}`)
+    const failureStdout = typeof err === 'object' && err !== null && 'stdout' in err
+      ? String((err as { stdout: string | Buffer }).stdout)
+      : ''
+    if (failureStdout !== '') writeEslintFailures(failureStdout)
+    // A parse error is a verdict about the program the tsconfig defines, not about
+    // the file's content — so it must not be left in a cache eslint will reuse after
+    // a checkout fixes the tsconfig. The stamp above already separates the two
+    // states; dropping the file makes a stale red impossible rather than unlikely.
+    if (hasFatalParseError(failureStdout)) rmSync(cacheFile, { force: true })
+    // A spawn failure (eslint not found, bad path) reports on stderr, not
+    // stdout — surface it so the real error isn't hidden behind "Lint failed".
+    const stderr = typeof err === 'object' && err !== null && 'stderr' in err
+      ? String((err as { stderr: string | Buffer }).stderr)
+      : ''
+    process.stderr.write(stderr)
+    // eslint's own wording for "you pointed me at a directory I have no config for".
+    // Say which pipework-side cause produces it, since the fix is not in eslint's config.
+    if (/are ignored/.test(stderr)) {
+      process.stderr.write(
+        '    A lint target with no matching `files` glob. Run `pipework install` to regenerate\n' +
+        '    eslint.config.js — an older one carries a single `src` glob and cannot reach a\n' +
+        '    nested workspace package (#393).\n',
+      )
+    }
+    return false
+  }
+
+  return reportLintCoverage(eslintBin, dir, label, globs, targets, stdout)
+}
+
+/**
+ * Refuse when a source file in scope was not linted.
+ *
+ * `check` enumerates the same sources doctrine walks, so a file present on disk and
+ * absent from eslint's report is a file that matched no config block — the #393
+ * failure, which until now read as Lint ✓. eslint is asked for its own reason before
+ * the run is failed: a file left out by a deliberate `ignores` pattern is a choice and
+ * is reported, not refused; "no matching configuration" and an outside-base-path
+ * refusal are the bug and fail the run.
+ */
+async function reportLintCoverage(
+  eslintBin: string,
+  dir: string,
+  label: string,
+  globs: readonly string[],
+  targets: string[],
+  stdout: string,
+): Promise<boolean> {
+  const linted = new Set(readEslintReport(stdout).linted.map(f => resolve(dir, f)))
+  const inScope = filesMatchingGlobs(dir, globs)
+  const missed = inScope.filter(f => !linted.has(resolve(dir, f)))
+  const reportOutside = (): void => reportOutsideGlobs(dir, label, globs, inScope)
+
+  if (missed.length === 0) {
+    if (linted.size === 0) return refuseEmptyLint(label, globs, 'they matched no file')
+    reportOutside()
+    info(`  ${label}: ${String(linted.size)} file${linted.size === 1 ? '' : 's'} linted (${targets.join(', ')})`)
+    return true
+  }
+
+  const reasons = await explainUnlinted(eslintBin, dir, missed)
+  const deliberate = reasons.filter(r => /matching ignore pattern/i.test(r.reason))
+  const unconfigured = reasons.filter(r => !/matching ignore pattern/i.test(r.reason))
+
+  if (unconfigured.length === 0) {
+    if (linted.size === 0) return refuseEmptyLint(label, globs, 'every file they matched is ignored')
+    reportOutside()
+    info(`  ${label}: ${String(linted.size)} file${linted.size === 1 ? '' : 's'} linted, ${String(deliberate.length)} ignored by pattern (${targets.join(', ')})`)
+    return true
+  }
+
+  logError(`Lint incomplete: ${label} — ${String(unconfigured.length)} file(s) in scope were never linted`)
+  for (const { file, reason } of unconfigured) {
+    process.stderr.write(`    ${file}  ${reason}\n`)
+  }
+  process.stderr.write(
+    "    eslint resolves flat-config `files` globs against eslint.config.js's directory.\n" +
+    '    Run `pipework install` to regenerate eslint.config.js — an older one carries a single\n' +
+    '    `src` glob and cannot reach a nested workspace package. A green Lint over files that\n' +
+    '    were never read is the failure this refuses.\n',
+  )
+  return false
+}
+
+// Sources under the module's src/ that no lint glob reaches. A configured `include` is a
+// choice, so this is said, not failed (#348).
+function reportOutsideGlobs(dir: string, label: string, globs: readonly string[], inScope: readonly string[]): void {
+  const covered = new Set(inScope)
+  const outside = findSourceFiles(dir, ['.']).filter(f => !covered.has(f))
+  if (outside.length === 0) return
+  warn(`  ${label}: ${String(outside.length)} source file(s) under src/ are outside the lint globs (${globs.join(', ')})`)
+}
+
+// A module that linted nothing names the globs it tried and why they came up empty —
+// the alternative is a ✓ that means "there was nothing to look at" (#392).
+function refuseEmptyLint(label: string, globs: readonly string[], why: string): boolean {
+  logError(`Lint linted no files: ${label} — ${why}`)
+  for (const glob of globs) process.stderr.write(`    ${glob}\n`)
+  process.stderr.write(
+    '    Point `lint.include` (or `lint.modules["' + label + '"].include`) in pipework.config.ts\n' +
+    '    at this module\'s sources, or drop the module from `modules` if it has none. A lint\n' +
+    '    pass over zero files is reported as a failure, not a pass.\n',
+  )
+  return false
+}
+
+/**
+ * eslint's own reason for leaving each of `files` out, one explicit-path run.
+ *
+ * Passing a directory makes eslint skip an unmatched file in silence; passing the path
+ * makes it say why. Only reached when something was missing, so the extra run costs
+ * nothing on a healthy repo.
+ */
+async function explainUnlinted(
+  eslintBin: string,
+  dir: string,
+  files: string[],
+): Promise<Array<{ file: string; reason: string }>> {
+  const args = [...files, '--format', 'json', '--no-error-on-unmatched-pattern']
+  if (!hasEslintConfig(dir)) {
+    args.push('--config', join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'lint', 'preset.js'))
+  }
+
+  let stdout: string
+  try {
+    stdout = (await execFileAsync(eslintBin, args, { cwd: dir })).stdout
+  } catch (err: unknown) {
+    stdout = typeof err === 'object' && err !== null && 'stdout' in err
+      ? String((err as { stdout: string | Buffer }).stdout)
+      : ''
+  }
+
+  const { ignored } = readEslintReport(stdout)
+  const byFile = new Map(ignored.map(i => [resolve(dir, i.file), i.reason]))
+  return files.map(file => ({
+    file,
+    reason: byFile.get(resolve(dir, file)) ?? 'matched no configuration block',
+  }))
+}
+
+// eslint's stdout on a failing run is the JSON report; anything else (a crash before
+// it formats) is passed through verbatim rather than swallowed.
+function writeEslintFailures(stdout: string): void {
+  process.stderr.write(stdout.trimStart().startsWith('[') ? formatEslintJson(stdout) : stdout)
+}
+
+// `--format json` costs the human-readable report, so rebuild the essentials:
+// file, line:col, rule, message — enough to fix without a second run.
+function formatEslintJson(stdout: string): string {
+  let results: Array<{ filePath: string; messages?: Array<{ line?: number; column?: number; ruleId?: string | null; message?: string; severity?: number }> }>
+  try {
+    results = JSON.parse(stdout) as typeof results
+  } catch {
+    return stdout
+  }
+  let out = ''
+  for (const result of results) {
+    const messages = result.messages ?? []
+    if (messages.length === 0) continue
+    out += `\n${result.filePath}\n`
+    for (const m of messages) {
+      const where = `${String(m.line ?? 0)}:${String(m.column ?? 0)}`
+      const level = m.severity === 1 ? 'warning' : 'error'
+      out += `  ${where.padEnd(8)} ${level.padEnd(7)} ${m.message ?? ''}  ${m.ruleId ?? ''}\n`
+    }
+  }
+  return out + '\n'
+}
+
+function runDependencyCheck(cwd: string): boolean {
+  info('Dependency boundaries')
+
+  const result = checkDependencies(cwd)
+
+  if (result.packagesChecked === 0) {
+    success('Dependency boundaries (no workspace packages)')
+    return true
+  }
+
+  if (result.violations.length === 0) {
+    success(`Dependency boundaries (${String(result.packagesChecked)} package${result.packagesChecked === 1 ? '' : 's'})`)
+    return true
+  }
+
+  for (const v of result.violations) {
+    logError(`  ${v.package} → ${v.dependency} (${v.field})`)
+    warn(`    ${v.message}`)
+  }
+
+  logError(`Dependency boundaries: ${String(result.violations.length)} violation(s)`)
+  return false
+}
+
+// Lint every module serially. Each eslint run with type-aware rules can consume
+// 300–800 MB, and concurrent spawning compounds with `tsc` to exceed memory
+// 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> {
+  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)`)
+  }
+  if (allModules.length === 0 && shard !== undefined && shard.index !== 1) return true
+  info('Lint')
+
+  const eslintBin = resolveEslintBin(cwd)
+  const includes = await loadLintIncludes(cwd)
+
+  // Per-module eslint cache, version-stamped and under the workspace-root
+  // node_modules/.cache — always present, always gitignored. The version stamp
+  // busts the cache on a pipework ruleset bump; the node_modules location keeps
+  // it out of git so a stale cache never travels between clones. See lintDirectory.
+  const version = pipeworkVersion()
+  mkdirSync(join(cwd, 'node_modules', '.cache', 'pipework'), { recursive: true })
+  const cacheFor = (label: string) => (fingerprint: string): string =>
+    eslintCacheLocation(cwd, version, label, fingerprint)
+
+  if (allModules.length === 0) {
+    const ok = await lintDirectory(eslintBin, cwd, '.', cacheFor('root'), includes.for('.'))
+    if (ok) success('Lint')
+    return ok
+  }
+
+  let ok = true
+  for (const mod of modulePaths) {
+    if (!await lintDirectory(eslintBin, join(cwd, mod), mod, cacheFor(mod), includes.for(mod))) {
+      ok = false
+    }
+  }
+
+  // #402: the module loop never reaches a lintable file sitting at the workspace
+  // 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('.'))
+  if (rootOnly.length > 0) {
+    if (!await lintDirectory(eslintBin, cwd, 'root', cacheFor('__root'), rootOnly)) {
+      ok = false
+    }
+  }
+
+  if (ok) {
+    const modules = `${String(modulePaths.length)} module${modulePaths.length === 1 ? '' : 's'}`
+    const root = rootOnly.length > 0
+      ? ` + ${String(rootOnly.length)} root file${rootOnly.length === 1 ? '' : 's'}`
+      : ''
+    success(`Lint (${modules}${root})`)
+  }
+  return ok
+}
+
+/**
+ * Root-level lintable files that no module covers (#402).
+ *
+ * `lint.include` for `.` — else the default `src` globs — minus everything under a
+ * module path, which the module loop already linted. What remains is the population
+ * `check` used to count as if it did not exist.
+ */
+export function rootFilesOutsideModules(
+  cwd: string,
+  modulePaths: readonly string[],
+  configured?: readonly string[],
+): string[] {
+  const owners = modulePaths.map(normalizeModulePath)
+  // A module at the workspace root owns every root file. Its own pass already lints
+  // them, so a root pass here would lint and count each of them a second time (#408).
+  if (owners.includes('')) return []
+
+  const files = filesMatchingGlobs(cwd, lintIncludeGlobs(cwd, configured))
+  return files.filter(f => !owners.some(m => f === m || f.startsWith(m + '/')))
+}
+
+// `.`, `./` and `` all name the workspace root, and `./pkg` names the same module as
+// `pkg`. Compared as raw strings they did not, so a module at `.` excluded nothing.
+function normalizeModulePath(path: string): string {
+  return path.replace(/^\.\/+/, '').replace(/\/+$/, '').replace(/^\.$/, '')
+}
+
+/**
+ * `lint.include` from pipework.config.ts, global and per module (#392).
+ *
+ * A module entry replaces the global one; both replace the `src`-derived default. A
+ * config that cannot be loaded yields no includes — the load failure is already
+ * reported by `check` itself, and defaulting here would hide it behind a lint error.
+ */
+export async function loadLintIncludes(cwd: string): Promise<{ for: (mod: string) => readonly string[] | undefined }> {
+  let lint: LintConfig | undefined
+  try {
+    lint = (await discoverInstanceCached(cwd)).config.raw.lint
+  } catch {
+    lint = undefined
+  }
+
+  // Glob keys expand the same way resolveLintConfig expands them, so `check` and the
+  // eslint config agree on which module an entry belongs to.
+  const entries: Array<{ path: string; include?: readonly string[] }> = []
+  for (const [key, config] of Object.entries(lint?.modules ?? {})) {
+    const paths = key.includes('*') ? expandGlob(key, cwd) : [key]
+    for (const path of paths) entries.push({ path, ...(config.include !== undefined ? { include: config.include } : {}) })
+  }
+
+  return {
+    for: (mod: string): readonly string[] | undefined => {
+      // Deepest match wins; entries.sort is by key length, so walk it from the back.
+      const matching = entries
+        .filter(e => mod === e.path || mod.startsWith(e.path + '/'))
+        .sort((a, b) => a.path.length - b.path.length)
+      for (let i = matching.length - 1; i >= 0; i--) {
+        const include = matching[i]!.include
+        if (include !== undefined) return include
+      }
+      return lint?.include
+    },
+  }
+}
+
+function runPipeworkCopiesCheck(cwd: string): boolean {
+  info('pipework install integrity')
+  const { copies, orphans } = detectPipeworkInstall(cwd)
+  const versions = distinctPipeworkVersions(copies)
+  for (const o of orphans) {
+    warn(`Orphaned pipework ${o.version} at ${o.path}: a stale copy pnpm left in its virtual store; \`pnpm prune\` removes it.`)
+  }
+  if (versions.length <= 1) {
+    success(`pipework install integrity (${String(copies.length)} cop${copies.length === 1 ? 'y' : 'ies'}, ${versions.length === 1 ? 'one version' : 'none resolved'})`)
+    return true
+  }
+  logError(`Multiple pipework versions resolved in one install: ${versions.join(', ')}.`)
+  for (const c of copies) {
+    process.stderr.write(`    ${c.version}  ${c.path}\n`)
+  }
+  process.stderr.write(
+    '    A shared library that imports pipework must resolve the SAME version as its consuming\n' +
+    '    workspace; otherwise their AsyncLocalStorage and error classes fork (no active context;\n' +
+    '    403->500). Align every pipework copy to one version.\n',
+  )
+  return false
+}