pipework 0.269.0 → 0.271.0

package/dist/cli/commands/check.js

@@ -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';
 const execFileAsync = promisify(execFile);
@@ -22,6 +22,10 @@ import { expandGlob, resolveModules } from '../../workspace/discover.js';
 import { filesMatchingGlobs, globRoot, lintIncludeGlobs } from '../../lint/include.js';
 import { StartupValidationError } from '../../core/validation/types.js';
 import { shardArg, shardModules } from './shard.js';
+import { record, emitJson } from './check-steps.js';
+function stepRecord(step, status, violations = [], scannedFiles) {
+    return record(step, pipeworkVersion(), status, violations, scannedFiles);
+}
 // #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
@@ -35,21 +39,39 @@ async function discoverInstanceCached(cwd) {
     }
     return loading;
 }
-export async function check(cwd, scope, shard) {
+export async function check(cwd, scope, shard, options = {}) {
     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 = [];
+    // 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, label, reason) => {
+        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, label, fn) => {
+        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, label, fn) => {
+        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);
     // #335: a pipework.config.ts that exists but cannot be loaded used to be
     // swallowed — module scoping silently degraded to filesystem discovery, which
@@ -58,84 +80,132 @@ export async function check(cwd, scope, shard) {
     // 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);
-        const lintOk = await runLint(cwd, modulePaths, shard);
-        if (!lintOk) {
-            failed = true;
+        await rich('coverage', 'Flow coverage', async () => coverageStep(cwd, sourceFiles, await loadConsumerIoPatterns(cwd)));
+        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'],
+        ]) {
+            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'})`);
+    if (configError === undefined && findConfig(cwd) !== null) {
+        await plain('startup', 'Startup checks', () => runStartupChecks(cwd));
     }
     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;
-        }
+        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;
-        }
-    }
-    const depCheckOk = runDependencyCheck(cwd);
-    if (!depCheckOk) {
-        failed = true;
+        await plain('boundaries', 'Boundaries', () => runStep('Boundaries', 'node scripts/check-boundaries.js', cwd));
     }
-    const copiesOk = runPipeworkCopiesCheck(cwd);
-    if (!copiesOk) {
-        failed = true;
+    else {
+        skip('boundaries', 'Boundaries', 'no scripts/check-boundaries.js');
     }
+    await plain('dependencies', 'Dependency boundaries', () => runDependencyCheck(cwd));
+    await plain('install', 'pipework install integrity', () => runPipeworkCopiesCheck(cwd));
+    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(', ')})`);
+}
+/** `pipework doctrine|flow|cardinality|startup`: one step alone. Returns the exit code. */
+export async function stepCommand(cwd, step, options = {}) {
+    instanceCache = new Map();
+    const files = options.files ?? [];
+    let result;
+    if (step === 'startup') {
+        if (files.length > 0)
+            throw new Error('startup takes no files.');
+        result = await startupStep(cwd);
+    }
+    else {
+        let sourceFiles;
+        let fullScope = false;
+        let configError;
+        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) {
+export async function startupStep(cwd) {
     info('Startup checks');
     let doors = [];
     let roles = [];
@@ -153,12 +223,14 @@ export async function runStartupChecks(cwd) {
             for (const issue of err.issues) {
                 process.stderr.write(`  [${issue.phase}] ${issue.message}\n`);
             }
+            return stepRecord('startup', 'failed', err.issues.map(issue => ({
+                rule: `startup/${issue.phase}`, file: CONFIG_FILE, line: 0, message: issue.message,
+            })));
         }
-        else {
-            logError('Startup checks — could not run');
-            process.stderr.write(`  ${err instanceof Error ? err.message : String(err)}\n`);
-        }
-        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)
@@ -168,7 +240,10 @@ export async function runStartupChecks(cwd) {
         for (const line of doors)
             info(`  ${line}`);
     }
-    return true;
+    return stepRecord('startup', 'passed');
+}
+export async function runStartupChecks(cwd) {
+    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. */
 export function describeRuntimeRoles(databases) {
@@ -435,18 +510,8 @@ function findStaleVitestConfigs(cwd) {
     }
     return stale.sort();
 }
-function runDoctrineValidation(cwd, sourceFiles) {
-    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);
+function printGrouped(violations) {
+    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)) {
@@ -456,36 +521,44 @@ function runDoctrineValidation(cwd, sourceFiles) {
             warn(`  ... and ${String(items.length - 5)} more`);
         }
     }
-    return false;
 }
-export function runFlowCheck(cwd, sourceFiles) {
+export function doctrineStep(cwd, sourceFiles) {
+    info('Doctrine validation');
+    if (sourceFiles.length === 0) {
+        success('Doctrine validation (no source files)');
+        return stepRecord('doctrine', 'passed', [], []);
+    }
+    const result = validateDoctrine(cwd, sourceFiles);
+    if (result.violations.length === 0) {
+        success(`Doctrine validation (${String(result.scanned)} files scanned)`);
+        return stepRecord('doctrine', 'passed', [], result.scannedFiles);
+    }
+    printGrouped(result.violations);
+    return stepRecord('doctrine', 'failed', result.violations, result.scannedFiles);
+}
+export function flowStep(cwd, sourceFiles) {
     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;
-    }
-    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('flow', 'passed', [], result.scannedFiles);
     }
-    return false;
+    printGrouped(result.violations);
+    return stepRecord('flow', 'failed', result.violations, result.scannedFiles);
 }
-export function runCardinalityCheck(cwd, sourceFiles, configuredStructuralMax, fullScope = true) {
+export function runFlowCheck(cwd, sourceFiles) {
+    return flowStep(cwd, sourceFiles).status === 'passed';
+}
+const CONFIG_FILE = 'pipework.config.ts';
+export function cardinalityStep(cwd, sourceFiles, configuredStructuralMax, fullScope = true) {
     info('Flow cardinality');
     if (sourceFiles.length === 0) {
         success('Flow cardinality (no source files)');
-        return true;
+        return stepRecord('cardinality', 'passed', [], []);
     }
     const result = checkCardinality(cwd, sourceFiles);
     // Verify the configured cap against what the analyzer just derived (Q7).
@@ -504,54 +577,57 @@ export function runCardinalityCheck(cwd, sourceFiles, configuredStructuralMax, f
     //   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 = [];
     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(cwd, sourceFiles, extras = {}) {
+export function runCardinalityCheck(cwd, sourceFiles, configuredStructuralMax, fullScope = true) {
+    return cardinalityStep(cwd, sourceFiles, configuredStructuralMax, fullScope).status === 'passed';
+}
+export function coverageStep(cwd, sourceFiles, extras = {}) {
     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) {
@@ -563,6 +639,10 @@ export function runCoverageCheckWarning(cwd, sourceFiles, extras = {}) {
             warn(`    ... and ${String(items.length - 5)} more`);
         }
     }
+    return stepRecord('coverage', 'passed', result.violations, result.scannedFiles);
+}
+export function runCoverageCheckWarning(cwd, sourceFiles, extras = {}) {
+    coverageStep(cwd, sourceFiles, extras);
 }
 function groupByRule(items) {
     const map = new Map();
@@ -1126,7 +1206,7 @@ function runDependencyCheck(cwd) {
 // 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, allModules, shard) {
+export async function runLint(cwd, allModules, shard) {
     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)`);
@@ -1136,6 +1216,7 @@ async function runLint(cwd, allModules, shard) {
     info('Lint');
     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
     // busts the cache on a pipework ruleset bump; the node_modules location keeps
@@ -1150,8 +1231,8 @@ async function runLint(cwd, allModules, shard) {
         return ok;
     }
     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;
         }
     }
@@ -1159,16 +1240,14 @@ async function runLint(cwd, allModules, shard) {
     // 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;
         }
     }
     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'}`
             : '';
@@ -1176,6 +1255,26 @@ async function runLint(cwd, allModules, shard) {
     }
     return ok;
 }
+/**
+ * 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, allModules, includes, shard) {
+    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(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).
  *