@starci/hfs 4.12.0 → 4.13.0

package/cache/session.mjs

@@ -0,0 +1,197 @@
+// session.mts - the disk-backed CheckSession of `starci app check` and `starci app lint`. It decides per family whether a run is full or diff
+// (the rules of contexts/project/check-cache.md "When a run is full"), serves the trusted records of a folder, takes the records a family
+// replaces and writes them once on flush: one JSON Lines file per area, byte-stable, only the files whose bytes changed. In CI it writes
+// nothing and compares the committed cache with what it inherited or computed instead.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createContentIndex } from './content-index.mjs';
+import { computeFingerprint, fingerprintDifferences, parseFingerprint, serializeFingerprint } from './fingerprint.mjs';
+import { hashFile } from './hash.mjs';
+import { groupByArea, parseRecords, serializeRecords } from './jsonl.mjs';
+import { readCacheDir, resolveTrust, verifyCommitted } from './trust.mjs';
+import { CACHE_DIR } from './types.mjs';
+/** `STARCI_APP_CHECK_CACHE`: `full` ignores the cache (the release gate sets it), `verify` is read by the caller (runs diff, then full, compares). */
+export const CACHE_ENV = 'STARCI_APP_CHECK_CACHE';
+const FINGERPRINT_FILE = 'fingerprint.jsonl';
+const dirOf = (root, folder) => path.join(root, ...CACHE_DIR.split('/'), ...folder.split('/'));
+function removeEmptyDirs(dir, stop) {
+    for (let at = dir; at.startsWith(stop) && at !== stop; at = path.dirname(at)) {
+        try {
+            fs.rmdirSync(at);
+        }
+        catch {
+            return;
+        }
+    }
+}
+function writeIfChanged(file, text, written) {
+    let current;
+    try {
+        current = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        current = undefined;
+    }
+    if (current === text)
+        return;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, text);
+    written.push(file);
+}
+function filesUnder(dir) {
+    const out = [];
+    const walk = (at) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(at, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                walk(path.join(at, entry.name));
+            else
+                out.push(path.join(at, entry.name));
+        }
+    };
+    walk(dir);
+    return out;
+}
+export function createDiskSession(options) {
+    const { root, env, tracked } = options;
+    const index = createContentIndex(root, tracked);
+    const fingerprint = options.fingerprint ?? computeFingerprint({ root, tracked, cliVersion: options.cliVersion, hfsDir: options.hfsDir });
+    const trust = options.trust ?? resolveTrust({ root, env });
+    const forcedFull = env[CACHE_ENV] === 'full';
+    const reports = [];
+    const replaced = new Map();
+    const parsed = new Map();
+    const trustedCache = () => trust.files();
+    const trustedRecords = (folder) => {
+        const hit = parsed.get(folder);
+        if (hit !== undefined)
+            return hit;
+        const prefix = `${folder}/`;
+        const seen = new Set();
+        const records = [];
+        for (const [file, text] of [...trustedCache()].sort(([a], [b]) => (a < b ? -1 : 1))) {
+            if (!file.startsWith(prefix) || !file.endsWith('.jsonl'))
+                continue;
+            for (const record of parseRecords(text).records) {
+                const line = JSON.stringify(record);
+                if (seen.has(line))
+                    continue;
+                seen.add(line);
+                records.push(record);
+            }
+        }
+        parsed.set(folder, records);
+        return records;
+    };
+    const cachedFingerprint = parseFingerprint(trustedCache().get(FINGERPRINT_FILE) ?? '');
+    const differences = cachedFingerprint.length === 0 ? [] : fingerprintDifferences(cachedFingerprint, fingerprint.parts);
+    let verdictList = [];
+    const global = () => {
+        if (forcedFull)
+            return { mode: 'full', reason: `${CACHE_ENV}=full, the release gate never reads the cache` };
+        if (!fingerprint.portable)
+            return { mode: 'full', reason: `no portable fingerprint, nothing is written (${fingerprint.localReasons[0] ?? 'a local package'})` };
+        if (trust.kind === 'none')
+            return { mode: 'full', reason: `no trusted base (${trust.reason})` };
+        if (cachedFingerprint.length === 0)
+            return { mode: 'full', reason: trust.kind === 'base' ? 'no cache at the trusted base' : 'no cache in the tree' };
+        if (differences.length > 0)
+            return { mode: 'full', reason: `the fingerprint differs (${differences.slice(0, 3).join(', ')}${differences.length > 3 ? ', ...' : ''})` };
+        return undefined;
+    };
+    const writes = !forcedFull && fingerprint.portable && trust.kind === 'worktree';
+    const session = {
+        root,
+        index,
+        fingerprint,
+        trust,
+        writes,
+        progress: options.progress,
+        get reports() {
+            return reports;
+        },
+        decide(family) {
+            if (options.full?.has(family) === true)
+                return { mode: 'full', reason: '--full' };
+            return global() ?? { mode: 'diff', reason: `against ${trust.reason}` };
+        },
+        records(folder) {
+            return replaced.get(folder)?.records ?? trustedRecords(folder);
+        },
+        replace(folder, records, replaceOptions) {
+            replaced.set(folder, { records, depth: replaceOptions?.depth ?? 2 });
+        },
+        unchanged: (paths) => paths.every((file) => hashFile(path.join(root, file)) === index.hashOf(file)),
+        report: (report) => void reports.push(report),
+        verdicts: () => verdictList,
+        flush() {
+            const written = [];
+            const removed = [];
+            const warnings = [];
+            // A file edited while the run read it gets no record.
+            const settled = new Map();
+            for (const [folder, { records }] of replaced) {
+                settled.set(folder, records.filter((record) => index.hashOf(record.path) === undefined || hashFile(path.join(root, record.path)) === record.hash));
+            }
+            if (trust.kind === 'base') {
+                const committed = new Map();
+                for (const [file, text] of readCacheDir(root)) {
+                    if (!file.endsWith('.jsonl'))
+                        continue;
+                    for (const folderName of settled.keys()) {
+                        if (file.startsWith(`${folderName}/`))
+                            committed.set(folderName, [...(committed.get(folderName) ?? []), ...parseRecords(text).records]);
+                    }
+                }
+                const trusted = new Map([...settled.keys()].map((folder) => [folder, trustedRecords(folder)]));
+                const computed = new Map(settled);
+                verdictList = verifyCommitted({ trusted, computed, committed });
+                return { written, removed, warnings };
+            }
+            if (!writes)
+                return { written, removed, warnings };
+            try {
+                const base = path.join(root, ...CACHE_DIR.split('/'));
+                const stalePrint = cachedFingerprint.length === 0 || differences.length > 0;
+                if (stalePrint) {
+                    // A new fingerprint invalidates every folder this run did not rewrite: they were computed under the old one.
+                    for (const file of filesUnder(base)) {
+                        const rel = path.relative(base, file).split(path.sep).join('/');
+                        if (rel === FINGERPRINT_FILE || [...settled.keys()].some((folder) => rel.startsWith(`${folder}/`)))
+                            continue;
+                        fs.rmSync(file);
+                        removed.push(file);
+                        removeEmptyDirs(path.dirname(file), base);
+                    }
+                }
+                for (const [folder, records] of settled) {
+                    const depth = replaced.get(folder)?.depth ?? 2;
+                    const dir = dirOf(root, folder);
+                    const wanted = new Map([...groupByArea(records, depth)].map(([file, group]) => [path.join(dir, ...file.split('/')), serializeRecords(group)]));
+                    for (const [file, text] of wanted)
+                        writeIfChanged(file, text, written);
+                    for (const file of filesUnder(dir)) {
+                        if (wanted.has(file))
+                            continue;
+                        fs.rmSync(file);
+                        removed.push(file);
+                        removeEmptyDirs(path.dirname(file), base);
+                    }
+                }
+                if (replaced.size > 0 || stalePrint)
+                    writeIfChanged(path.join(base, FINGERPRINT_FILE), serializeFingerprint(fingerprint.parts), written);
+            }
+            catch (error) {
+                warnings.push(`the cache could not be written: ${String(error.message ?? error).split('\n')[0]}`);
+            }
+            return { written: written.map((file) => path.relative(root, file).split(path.sep).join('/')), removed: removed.map((file) => path.relative(root, file).split(path.sep).join('/')), warnings };
+        },
+    };
+    return session;
+}

package/cache/side-key.d.mts

@@ -0,0 +1,10 @@
+import type { ContentIndex } from './types.mjs';
+export interface SideKey {
+    readonly key: string;
+    /** Every path the key covers: tracked paths of the side and the untracked program inputs. */
+    readonly inputs: readonly string[];
+}
+/** The untracked files the side's TypeScript program includes (generated code), side-relative paths prefixed with `side/`. */
+export declare function untrackedProgramInputs(root: string, side: string, tracked: ReadonlySet<string>): string[];
+/** The key of `side` (`be` or `fe`) of the app at `root`. */
+export declare function sideKey(root: string, index: ContentIndex, side: string): SideKey;

package/cache/side-key.mjs

@@ -0,0 +1,47 @@
+// side-key.mts - the key of a side for the steps that read its whole program (the architecture machine, the contract emit, the boot proof,
+// the type-aware lint rules, tsc). It is the sha256 of the hash of each tracked path of the side (`absent` for one deleted in the work tree),
+// its staged entries (the machine reads the index), and the untracked files its TypeScript program reads: what its tsconfig includes that git
+// does not track, generated code included. One edit anywhere in the side changes the key, so a scoped step re-runs the whole side.
+import fs from 'node:fs';
+import path from 'node:path';
+import { combineHashes, hashFile, hashText } from './hash.mjs';
+import { git } from './git.mjs';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+/** The untracked files the side's TypeScript program includes (generated code), side-relative paths prefixed with `side/`. */
+export function untrackedProgramInputs(root, side, tracked) {
+    const ts = loadTypescript(root);
+    const tsconfig = path.join(root, side, 'tsconfig.json');
+    if (ts === null || !fs.existsSync(tsconfig))
+        return [];
+    try {
+        const read = ts.readConfigFile(tsconfig, ts.sys.readFile);
+        if (read.error !== undefined)
+            return [];
+        const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.join(root, side));
+        const found = [];
+        for (const name of parsed.fileNames) {
+            const rel = path.relative(root, name).split(path.sep).join('/');
+            if (rel.startsWith('..') || rel.includes('/node_modules/') || tracked.has(rel))
+                continue;
+            found.push(rel);
+        }
+        return found.sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** The key of `side` (`be` or `fe`) of the app at `root`. */
+export function sideKey(root, index, side) {
+    const prefix = `${side}/`;
+    const trackedPaths = index.paths.filter((file) => file.startsWith(prefix));
+    const parts = {};
+    for (const file of trackedPaths)
+        parts[`tracked:${file}`] = index.hashOf(file) ?? 'absent';
+    const staged = git(root, ['ls-files', '-s', '-z', '--', prefix]);
+    parts['staged'] = hashText(staged.stdout);
+    const untracked = untrackedProgramInputs(root, side, new Set(index.paths));
+    for (const file of untracked)
+        parts[`untracked:${file}`] = hashFile(path.join(root, file)) ?? 'absent';
+    return { key: combineHashes(parts), inputs: [...trackedPaths, ...untracked] };
+}

package/cache/test-family.d.mts

@@ -0,0 +1,130 @@
+import type { CacheRecord, CheckSession, FamilyReport, JsonValue } from './types.mjs';
+/** The folder of the session that holds the records of this family. */
+export declare const TEST_FOLDER = "test-coverage";
+/** The step of a unit spec's record. */
+export declare const SPEC_STEP = "unit-spec";
+/** The Jest projects a warm run never skips: they reach services, data and time a key cannot hold. */
+export declare const ALWAYS_FULL_PROJECTS: readonly ["integration", "e2e", "contract"];
+/** One source's items as the preset's reporter writes them: statements `[sl, sc, el, ec, flag]`, functions `[name, decl, loc, flag]`, branches `[type, loc, [[loc, flag]...]]`. */
+export interface SourceItems {
+    readonly s: JsonValue;
+    readonly f: JsonValue;
+    readonly b: JsonValue;
+}
+/** What the reporter of @starci/jest-preset wrote for one spec (`SpecCoverageFile`), with source paths relative to the Jest root. */
+export interface SpecCoverageOutput {
+    readonly spec: string;
+    readonly passed: boolean;
+    readonly sources: Readonly<Record<string, SourceItems>>;
+}
+/** What a Jest run of some specs came to. */
+export interface RunOutcome {
+    /** The process exit status (non-zero when any spec failed; the records, not the status, say which). */
+    readonly status: number;
+    /** Jest's own output, for the diagnosis of a failed spec. */
+    readonly output: string;
+}
+/** What the family needs of Jest: the specs, each spec's closure, the project's configuration, and a way to run specs. All paths are app-relative posix. */
+export interface JestEnvironment {
+    /** Every unit spec. */
+    readonly specs: readonly string[];
+    /** Every local module the spec loads, transitively, the setup files of the project included. Never a path under `node_modules`. */
+    closureOf(spec: string): readonly string[];
+    /** The digest of the unit project's configuration, free of host paths. */
+    readonly configHash: string;
+    /** Runs `specs` (all of them when `specs` is every spec) writing the per-spec coverage into `coverageDir`. */
+    run(specs: readonly string[], coverageDir: string): RunOutcome;
+    /** Reads what the reporter wrote into `coverageDir`. */
+    readCoverage(coverageDir: string): readonly SpecCoverageOutput[];
+}
+/** The union of the stored records, written as the lcov and coverage-final.json of the Jest root (`<root>/coverage`). */
+export type MergeSpecRecords = (records: ReadonlyArray<Readonly<Record<string, SourceItems>>>, args: {
+    outDir: string;
+    reportRoot: string;
+    recordRoot: string;
+}) => void;
+/** The per-file threshold (R273) judged on a report; `starci app check --coverage-from` is this judgement. */
+export type JudgeCoverage = (lcov: string) => {
+    readonly ok: boolean;
+    readonly findings: ReadonlyArray<{
+        readonly code?: string;
+        readonly path?: string;
+        readonly message?: string;
+    }>;
+};
+export interface TestFamilyOptions {
+    readonly session: CheckSession;
+    readonly jest: JestEnvironment;
+    /** The Jest root, app-relative posix (`be`). Source paths in the records are app-relative, so they carry it. */
+    readonly side: string;
+    readonly merge: MergeSpecRecords;
+    readonly judge: JudgeCoverage;
+    /** Where the temporary per-spec coverage goes; defaults to a fresh folder of the OS temp dir. */
+    readonly scratch?: string;
+}
+/** The outcome of the family. `ok` is false when a spec failed or the merged total is below the threshold. */
+export interface TestFamilyResult {
+    readonly ok: boolean;
+    readonly ran: readonly string[];
+    readonly reused: readonly string[];
+    /** Specs that failed or did not report: nothing of theirs is stored. */
+    readonly failed: readonly string[];
+    /** The merged lcov, or undefined when no spec has a record. */
+    readonly lcov: string | undefined;
+    readonly threshold: ReturnType<JudgeCoverage> | undefined;
+    readonly report: FamilyReport;
+    /** Jest's output of the specs that ran, kept for the diagnosis of failures. */
+    readonly output: string;
+}
+/** The snapshot file Jest keeps beside a spec. */
+export declare function snapshotOf(spec: string): string;
+/**
+ * The closure key of a spec: the spec, each module of its closure and its snapshot by content hash (`absent` for one the work tree lacks, so a deleted dependency
+ * changes the key), and the project configuration. The same files give the same key on every host.
+ */
+export declare function specKey({ spec, closure, configHash, hashOf }: {
+    spec: string;
+    closure: readonly string[];
+    configHash: string;
+    hashOf: (file: string) => string | undefined;
+}): string;
+/** The sources a stored record holds (app-relative paths), empty for a record that does not hold any. */
+export declare function sourcesOf(record: CacheRecord): Record<string, SourceItems>;
+/**
+ * Runs the unit specs against the cache. Diff mode runs the specs with no current record, full mode all of them; a passing spec's coverage is stored under its key,
+ * a failing one's is not, and the folder is replaced with exactly the current specs' records. The merged total is written to `<side>/coverage/lcov.info` and judged.
+ */
+export declare function runTestFamily(options: TestFamilyOptions): TestFamilyResult;
+/** The part of a Jest project config the closure needs. */
+interface ProjectConfigLike {
+    readonly rootDir: string;
+    readonly displayName?: {
+        readonly name?: string;
+    };
+    readonly setupFiles?: readonly string[];
+    readonly setupFilesAfterEnv?: readonly string[];
+    readonly [key: string]: unknown;
+}
+/** The digest of a project config with host paths turned into `<root>` and the keys that differ per host dropped. */
+export declare function projectConfigHash(config: ProjectConfigLike): string;
+/**
+ * The app's own Jest, resolved from `jestFrom` (a package.json or folder inside the app's install): its unit project's configuration, its haste map and resolver
+ * (so `moduleNameMapper`, `jest.mock` targets and setup files count as Jest sees them), and its binary to run specs. `side` is the Jest root, app-relative.
+ */
+export declare function createJestEnvironment({ appRoot, side, jestFrom, project }: {
+    appRoot: string;
+    side: string;
+    jestFrom?: string;
+    project?: string;
+}): Promise<JestEnvironment>;
+/** The installed preset's union merge (resolved like the shard merge of `app coverage`): the records in, the lcov and coverage-final.json out. */
+export declare function installedSpecMerge(appRoot: string, from?: string): MergeSpecRecords;
+/**
+ * The sharded full run of CI (`--test --full --shard i/n`): the shard's Jest run in the shape the shard merge reads, `coverage-final.json` of the files it loads,
+ * and nothing recorded. The merge job joins the shards (`starci app coverage merge`) and judges the merged report with `--coverage-from`.
+ */
+export declare function shardArgs(index: number, total: number): {
+    args: string[];
+    env: Record<string, string>;
+};
+export {};

package/cache/test-family.mjs

@@ -0,0 +1,258 @@
+// test-family.mts - the `--test` family of the app check cache (contexts/project/check-cache.md, "Unit coverage"). Each unit spec has a closure key: the sha256 of
+// the spec, every module Jest's own resolver reaches from it (with the project's moduleNameMapper, jest.mock targets and setup files), its snapshot file and its
+// project's configuration. A warm run runs only the specs whose key changed and keeps the records of the rest. The coverage of each spec is stored per source as
+// covered or not covered items (never hit counts), a failed spec stores nothing, and the per-file threshold is judged on the merged total of every record, never on
+// the partial run Jest itself saw. The lcov written is that merged total, the one Codecov and Sonar read. Integration, e2e and contract specs are not this family's:
+// they always run in full (ALWAYS_FULL_PROJECTS).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { combineHashes, hashFile } from './hash.mjs';
+import { canonicalJson } from './jsonl.mjs';
+/** The folder of the session that holds the records of this family. */
+export const TEST_FOLDER = 'test-coverage';
+/** The step of a unit spec's record. */
+export const SPEC_STEP = 'unit-spec';
+/** The Jest projects a warm run never skips: they reach services, data and time a key cannot hold. */
+export const ALWAYS_FULL_PROJECTS = ['integration', 'e2e', 'contract'];
+const posix = (file) => file.split(path.sep).join('/');
+/** The snapshot file Jest keeps beside a spec. */
+export function snapshotOf(spec) {
+    return `${path.posix.dirname(spec)}/__snapshots__/${path.posix.basename(spec)}.snap`;
+}
+/**
+ * The closure key of a spec: the spec, each module of its closure and its snapshot by content hash (`absent` for one the work tree lacks, so a deleted dependency
+ * changes the key), and the project configuration. The same files give the same key on every host.
+ */
+export function specKey({ spec, closure, configHash, hashOf }) {
+    const parts = { '#config': configHash };
+    for (const file of [spec, snapshotOf(spec), ...closure])
+        parts[file] = hashOf(file) ?? 'absent';
+    return combineHashes(parts);
+}
+function isSourceItems(value) {
+    return typeof value === 'object' && value !== null && 's' in value && 'f' in value && 'b' in value;
+}
+/** The sources a stored record holds (app-relative paths), empty for a record that does not hold any. */
+export function sourcesOf(record) {
+    const data = record.data;
+    const sources = typeof data === 'object' && data !== null && !Array.isArray(data) ? data['sources'] : undefined;
+    if (typeof sources !== 'object' || sources === null || Array.isArray(sources))
+        return {};
+    const out = {};
+    for (const [source, items] of Object.entries(sources))
+        if (isSourceItems(items))
+            out[source] = items;
+    return out;
+}
+function recordOf(spec, key, sources, side) {
+    const prefixed = {};
+    for (const [source, items] of Object.entries(sources))
+        prefixed[side === '' || side === '.' ? source : `${side}/${source}`] = items;
+    return { path: spec, step: SPEC_STEP, hash: key, findings: [], data: { sources: prefixed } };
+}
+/**
+ * Runs the unit specs against the cache. Diff mode runs the specs with no current record, full mode all of them; a passing spec's coverage is stored under its key,
+ * a failing one's is not, and the folder is replaced with exactly the current specs' records. The merged total is written to `<side>/coverage/lcov.info` and judged.
+ */
+export function runTestFamily(options) {
+    const { session, jest, side, merge, judge } = options;
+    const decision = session.decide('test');
+    const hashOf = (file) => session.index.hashOf(file) ?? hashFile(path.join(session.root, file));
+    const keys = new Map(jest.specs.map((spec) => [spec, specKey({ spec, closure: jest.closureOf(spec), configHash: jest.configHash, hashOf })]));
+    const stored = new Map(session.records(TEST_FOLDER).filter((record) => record.step === SPEC_STEP).map((record) => [record.path, record]));
+    const reusable = (spec) => {
+        const record = stored.get(spec);
+        return decision.mode === 'diff' && record !== undefined && record.hash === keys.get(spec) ? record : undefined;
+    };
+    const toRun = jest.specs.filter((spec) => reusable(spec) === undefined);
+    const kept = jest.specs.flatMap((spec) => reusable(spec) ?? []);
+    const progress = session.progress.step('test', 'unit specs', jest.specs.length);
+    progress.tick(kept.length, kept.length, 0);
+    const fresh = [];
+    const failed = [];
+    let output = '';
+    if (toRun.length > 0) {
+        const scratch = options.scratch ?? fs.mkdtempSync(path.join(os.tmpdir(), 'starci-spec-coverage-'));
+        try {
+            fs.rmSync(scratch, { recursive: true, force: true });
+            fs.mkdirSync(scratch, { recursive: true });
+            output = jest.run(toRun, scratch).output;
+            const reported = new Map(jest.readCoverage(scratch).map((file) => [file.spec, file]));
+            for (const spec of toRun) {
+                const file = reported.get(posix(path.relative(path.join(session.root, side), path.join(session.root, spec))));
+                const key = specKey({ spec, closure: jest.closureOf(spec), configHash: jest.configHash, hashOf });
+                // A spec that failed, did not report, or whose files changed while it ran stores nothing.
+                if (file?.passed === true && key === keys.get(spec))
+                    fresh.push(recordOf(spec, key, file.sources, side));
+                else
+                    failed.push(spec);
+            }
+        }
+        finally {
+            if (options.scratch === undefined)
+                fs.rmSync(scratch, { recursive: true, force: true });
+        }
+    }
+    progress.tick(jest.specs.length, kept.length, toRun.length);
+    progress.end();
+    const records = [...kept, ...fresh];
+    session.replace(TEST_FOLDER, records);
+    let lcov;
+    let threshold;
+    if (records.length > 0) {
+        const rootDir = path.join(session.root, side);
+        const outDir = path.join(rootDir, 'coverage');
+        merge(records.map(sourcesOf), { outDir, reportRoot: rootDir, recordRoot: session.root });
+        lcov = path.join(outDir, 'lcov.info');
+        // A failed spec leaves its sources short in the total, so the threshold is judged only when every spec reported.
+        if (failed.length === 0)
+            threshold = judge(lcov);
+    }
+    const thresholdFindings = threshold?.findings.length ?? 0;
+    const report = {
+        family: 'test',
+        mode: decision.mode,
+        reason: decision.reason,
+        checked: toRun.length,
+        reused: kept.length,
+        newFindings: failed.length + thresholdFindings,
+        knownFindings: 0,
+        fixedFindings: 0,
+    };
+    session.report(report);
+    return { ok: failed.length === 0 && (threshold?.ok ?? records.length === 0), ran: toRun, reused: kept.map((record) => record.path), failed, lcov, threshold, report, output };
+}
+/** The digest of a project config with host paths turned into `<root>` and the keys that differ per host dropped. */
+export function projectConfigHash(config) {
+    const root = config.rootDir;
+    const variants = [root, root.split(path.sep).join('/')].filter((value, index, all) => value !== '' && all.indexOf(value) === index);
+    const strip = (value) => {
+        if (typeof value === 'string')
+            return variants.reduce((text, variant) => text.split(variant).join('<root>'), value).split('\\').join('/');
+        if (Array.isArray(value))
+            return value.map(strip);
+        if (typeof value === 'object' && value !== null)
+            return Object.fromEntries(Object.entries(value).filter(([key]) => !['cacheDirectory', 'id', 'cwd'].includes(key)).map(([key, item]) => [key, strip(item)]));
+        return value;
+    };
+    return combineHashes({ config: canonicalJson(strip(config)) });
+}
+/**
+ * The app's own Jest, resolved from `jestFrom` (a package.json or folder inside the app's install): its unit project's configuration, its haste map and resolver
+ * (so `moduleNameMapper`, `jest.mock` targets and setup files count as Jest sees them), and its binary to run specs. `side` is the Jest root, app-relative.
+ */
+export async function createJestEnvironment({ appRoot, side, jestFrom, project = 'unit' }) {
+    const root = path.resolve(appRoot, side);
+    const fromApp = createRequire(jestFrom ?? path.join(root, 'package.json'));
+    const jestPackage = fromApp.resolve('jest/package.json');
+    const fromJest = createRequire(jestPackage);
+    const fromCore = createRequire(fromJest.resolve('@jest/core'));
+    const { readConfigs } = fromCore('jest-config');
+    const runtimeModule = fromCore('jest-runtime');
+    const Runtime = runtimeModule.default;
+    const { DependencyResolver } = fromCore('jest-resolve-dependencies');
+    const jestBin = path.join(path.dirname(jestPackage), 'bin', 'jest.js');
+    // The preset's config reads the working directory (the back end it describes), so it is read from the Jest root.
+    const previous = process.cwd();
+    let config;
+    let context;
+    try {
+        process.chdir(root);
+        const { configs } = await readConfigs({ $0: 'jest', _: [], selectProjects: [project] }, [root]);
+        config = configs.find((entry) => entry.displayName?.name === project);
+        if (config === undefined)
+            throw new Error(`the Jest config under ${side} has no project named ${project}`);
+        context = await Runtime.createContext(config, { maxWorkers: 1, watchman: false, console: { log: () => undefined, warn: () => undefined, error: () => undefined } });
+    }
+    finally {
+        process.chdir(previous);
+    }
+    const resolver = new DependencyResolver(context.resolver, context.hasteFS, undefined);
+    const tracked = (file) => !file.split(/[\\/]/u).includes('node_modules');
+    const closureFrom = (roots) => {
+        const seen = new Set();
+        const queue = roots.filter(tracked);
+        while (queue.length > 0) {
+            const file = queue.pop();
+            if (file === undefined || seen.has(file))
+                continue;
+            seen.add(file);
+            for (const next of resolver.resolve(file))
+                if (tracked(next) && !seen.has(next))
+                    queue.push(next);
+        }
+        return [...seen];
+    };
+    const relative = (file) => posix(path.relative(appRoot, file));
+    const setup = (name) => [...(config[name] ?? [])];
+    const setupClosure = closureFrom([...setup('setupFiles'), ...setup('setupFilesAfterEnv')]).map(relative);
+    const listed = spawnSync(process.execPath, [jestBin, '--selectProjects', project, '--listTests'], { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (listed.status !== 0)
+        throw new Error(`jest --listTests failed under ${side}: ${(listed.stderr || listed.stdout).split('\n')[0]}`);
+    const specs = listed.stdout.split(/\r?\n/u).map((line) => line.trim()).filter((line) => path.isAbsolute(line)).map((line) => relative(path.resolve(line))).sort();
+    const closures = new Map();
+    return {
+        specs,
+        configHash: projectConfigHash(config),
+        closureOf(spec) {
+            const cached = closures.get(spec);
+            if (cached !== undefined)
+                return cached;
+            const own = closureFrom([path.resolve(appRoot, spec)]).map(relative).filter((file) => file !== spec);
+            const closure = [...new Set([...own, ...setupClosure])].sort();
+            closures.set(spec, closure);
+            return closure;
+        },
+        run(toRun, coverageDir) {
+            const base = [jestBin, '--selectProjects', project, '--coverage', '--ci'];
+            const everything = toRun.length === specs.length;
+            const sideRelative = toRun.map((spec) => posix(path.relative(root, path.resolve(appRoot, spec))));
+            // One process for all of them; a command line that would not fit (Windows) goes in several.
+            const chunks = everything ? [[]] : [];
+            for (const spec of everything ? [] : sideRelative) {
+                const last = chunks[chunks.length - 1];
+                if (last !== undefined && last.join(' ').length + spec.length < 24000)
+                    last.push(spec);
+                else
+                    chunks.push([spec]);
+            }
+            let status = 0;
+            let output = '';
+            for (const chunk of chunks) {
+                const args = chunk.length > 0 ? [...base, '--runTestsByPath', ...chunk] : base;
+                const result = spawnSync(process.execPath, args, { cwd: root, encoding: 'utf8', env: { ...process.env, STARCI_SPEC_COVERAGE_DIR: coverageDir }, maxBuffer: 256 * 1024 * 1024 });
+                status = status || (result.status ?? 1);
+                output += `${result.stdout}${result.stderr}`;
+            }
+            return { status, output };
+        },
+        readCoverage(coverageDir) {
+            return fs.readdirSync(coverageDir).filter((name) => name.endsWith('.json')).map((name) => JSON.parse(fs.readFileSync(path.join(coverageDir, name), 'utf8')));
+        },
+    };
+}
+/** The installed preset's union merge (resolved like the shard merge of `app coverage`): the records in, the lcov and coverage-final.json out. */
+export function installedSpecMerge(appRoot, from) {
+    return (records, { outDir, reportRoot, recordRoot }) => {
+        let load;
+        try {
+            load = createRequire(from ?? path.join(appRoot, 'package.json'))('@starci/jest-preset/spec-coverage');
+        }
+        catch (error) {
+            throw new Error(`@starci/jest-preset/spec-coverage is not installed under ${appRoot} (${error.code ?? error.message}); install the canon @starci/jest-preset`);
+        }
+        load.mergeSpecCoverage({ records: [...records], outDir, projectRoot: reportRoot, recordRoot });
+    };
+}
+/**
+ * The sharded full run of CI (`--test --full --shard i/n`): the shard's Jest run in the shape the shard merge reads, `coverage-final.json` of the files it loads,
+ * and nothing recorded. The merge job joins the shards (`starci app coverage merge`) and judges the merged report with `--coverage-from`.
+ */
+export function shardArgs(index, total) {
+    if (!Number.isInteger(index) || !Number.isInteger(total) || index < 1 || total < index)
+        throw new Error(`--shard needs <i>/<n> with 1 <= i <= n, got ${index}/${total}`);
+    return { args: [`--shard=${index}/${total}`, '--coverage', '--ci', '--selectProjects', 'unit'], env: { STARCI_COVERAGE_SHARD: '1' } };
+}