@starci/hfs 4.12.2 → 4.13.0

package/cache/lint-family.mjs

@@ -0,0 +1,433 @@
+// lint-family.mts - the `lint` family of the app check cache (contexts/project/check-cache.md, ESLint and stylelint): the per-file results of ESLint
+// and stylelint, judged again only for what a change can have altered, on the records of `.starcistacks/cache/lint/<side>/`.
+//
+// ESLint's own `--cache` is not used. A file's result is reused when the side key is unchanged, or when the file is outside the dirty set:
+//   1. the files that changed (hash differs from the record, added, removed) and every file that reaches one through imports, in the new import
+//      graph and the recorded one (import-graph.mts); a changed file that declares globals dirties the whole side;
+//   2. every file whose project-graph findings (duplicate code, unused exports, tier direction, ...) differ from the recorded ones, taken from the
+//      installed canon's own `projectGraph` run once over the side; ESLint itself lints that file again, so ESLint stays the only emitter of a message;
+//   3. every file whose declared cross-file inputs (`crossFileInputs` of the canons: siblings, listings, manifests, stylesheets) differ from the
+//      digest recorded with its result. A canon without the declaration makes the side a whole-side lint.
+// The dirty set is linted by the same launcher, chunking and result validation as a full run (the `eslint` and `stylelint` seams); the rest of the
+// scope takes its record. Everything the family needs of the world is a seam, so a spec drives it with a fake session and a fake linter.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { braceVariants, globExpression } from '../runtime/scripts/lib/glob.mjs';
+import { combineHashes, hashFile, hashText } from './hash.mjs';
+import { buildImportGraph, dirtySetOf, posix } from './import-graph.mjs';
+import { canonicalJson, reconcile, sortFindings } from './jsonl.mjs';
+/** Record steps of the `lint/<side>` folder. */
+export const LINT_STEPS = Object.freeze({ eslint: 'eslint', stylelint: 'stylelint', imports: 'imports', graph: 'graph', meta: 'meta' });
+/** The record path of the side's own record (no file of the tree holds it). */
+export const SIDE_RECORD = '.side';
+// ---------------------------------------------------------------------------------------------------- findings <-> records
+const byLocation = (a, b) => a.line - b.line || a.column - b.column || (a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0) || (a.message < b.message ? -1 : a.message > b.message ? 1 : 0) || a.end - b.end;
+/** The findings of a record in the order they are stored, with their end lines. */
+function fromEslint(side, file, result) {
+    const located = result.messages.map((message) => ({
+        line: message.line ?? 0, column: message.column ?? 0, rule: message.ruleId ?? 'eslint-error', message: message.message, end: message.endLine ?? 0,
+    }));
+    located.sort(byLocation);
+    return { findings: located.map((entry) => ({ path: `${side}/${file}`, line: entry.line, column: entry.column, rule: entry.rule, message: entry.message })), ends: located.map((entry) => entry.end) };
+}
+function fromStylelint(side, file, result) {
+    const located = result.warnings.map((warning) => ({
+        line: warning.line ?? 0, column: warning.column ?? 0, rule: warning.rule || 'stylelint-error', message: warning.text, end: warning.endLine ?? 0,
+    }));
+    located.sort(byLocation);
+    return { findings: located.map((entry) => ({ path: `${side}/${file}`, line: entry.line, column: entry.column, rule: entry.rule, message: entry.message })), ends: located.map((entry) => entry.end) };
+}
+const endsOf = (record) => {
+    const data = record.data;
+    const ends = data !== null && typeof data === 'object' && !Array.isArray(data) ? data['ends'] : undefined;
+    return Array.isArray(ends) ? ends.map((value) => (typeof value === 'number' ? value : 0)) : [];
+};
+const crossOf = (record) => {
+    const data = record?.data;
+    const cross = data !== null && typeof data === 'object' && !Array.isArray(data) ? data['cross'] : undefined;
+    return typeof cross === 'string' ? cross : undefined;
+};
+/** The ESLint result a record stands for. */
+function toEslint(sideRoot, file, record) {
+    const ends = endsOf(record);
+    return {
+        filePath: path.join(sideRoot, file),
+        messages: record.findings.map((finding, at) => ({
+            ruleId: finding.rule === 'eslint-error' ? null : finding.rule, message: finding.message, line: finding.line, column: finding.column,
+            ...((ends[at] ?? 0) > 0 ? { endLine: ends[at] } : {}), severity: 2,
+        })),
+    };
+}
+function toStylelint(sideRoot, file, record) {
+    const ends = endsOf(record);
+    return {
+        source: path.join(sideRoot, file),
+        warnings: record.findings.map((finding, at) => ({
+            rule: finding.rule === 'stylelint-error' ? '' : finding.rule, text: finding.message, line: finding.line, column: finding.column,
+            ...((ends[at] ?? 0) > 0 ? { endLine: ends[at] } : {}), severity: 'error',
+        })),
+    };
+}
+const keyOf = (finding) => `${finding.path}\0${finding.line}\0${finding.column}\0${finding.rule}\0${finding.message}`;
+// ---------------------------------------------------------------------------------------------------- cross-file inputs
+/** The anchored expressions of a glob (braces expanded). */
+const expressions = (glob) => braceVariants(glob).map((variant) => globExpression(variant));
+const matchesAny = (patterns, file) => patterns.some((pattern) => pattern.test(file));
+/**
+ * The digest of what the declared cross-file inputs of `file` hold now: for each declaration that applies, the matching paths of the app with
+ * their hashes (`content`) or alone (`exists`). Undefined when no declaration applies. `paths` are app-relative; side-relative globs are
+ * resolved below `<side>/`, so a glob may step out of the side with `../` to the app root.
+ */
+export function crossDigestFactory(options) {
+    const { side, declarations, paths, hashOf } = options;
+    const compiled = declarations.map((declaration) => ({ declaration, applies: declaration.appliesTo.flatMap(expressions) }));
+    const cache = new Map();
+    const matched = (index, directory) => {
+        const declaration = declarations[index];
+        const key = `${index}\0${declaration.relativeTo === 'file' ? directory : ''}`;
+        const known = cache.get(key);
+        if (known !== undefined)
+            return known;
+        const base = declaration.relativeTo === 'file' ? path.posix.join(side, directory) : side;
+        const resolved = declaration.globs.map((glob) => path.posix.normalize(path.posix.join(base, glob)));
+        const patterns = resolved.flatMap(expressions);
+        // a glob can only match below the folder in front of its first wildcard; testing the other paths would cost a regular expression each
+        const roots = resolved.flatMap((glob) => braceVariants(glob)).map((glob) => (glob.search(/[*?]/) < 0 ? glob : glob.slice(0, glob.search(/[*?]/))).replace(/[^/]*$/, ''));
+        const lines = paths.filter((candidate) => roots.some((root) => candidate.startsWith(root)) && matchesAny(patterns, candidate)).sort()
+            .map((candidate) => (declaration.kind === 'content' ? `${candidate}\0${hashOf(candidate) ?? 'absent'}` : candidate));
+        const digest = hashText(lines.join('\n'));
+        cache.set(key, digest);
+        return digest;
+    };
+    return (file) => {
+        const parts = {};
+        compiled.forEach((entry, index) => {
+            if (!matchesAny(entry.applies, file))
+                return;
+            if (entry.declaration.kind === 'git') {
+                const long = (options.lineCountOf?.(file) ?? Number.POSITIVE_INFINITY) > (entry.declaration.minLines ?? 0);
+                parts[`${index}:${entry.declaration.rule}:git`] = long ? `git:${options.gitToken ?? ''}` : 'short';
+                return;
+            }
+            parts[`${index}:${entry.declaration.rule}:${entry.declaration.kind}`] = matched(index, path.posix.dirname(file) === '.' ? '' : path.posix.dirname(file));
+        });
+        return Object.keys(parts).length === 0 ? undefined : combineHashes(parts);
+    };
+}
+// ---------------------------------------------------------------------------------------------------- the app's TypeScript
+/** The TypeScript the app installed, resolved from the side folder like the linters are (not this package's own copy). */
+export function loadAppTypeScript(sideRoot) {
+    const require = createRequire(path.join(sideRoot, 'package.json'));
+    return require('typescript');
+}
+// ---------------------------------------------------------------------------------------------------- one side
+const readText = (file) => {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+const isFile = (file) => {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** A record's `data` object, or an empty one. */
+const dataOf = (record) => (record.data !== null && typeof record.data === 'object' && !Array.isArray(record.data) ? record.data : {});
+/** The graph findings of every canon that publishes graph rules, merged by file and sorted. */
+function mergedSnapshot(sideRoot, canons) {
+    const merged = {};
+    for (const canon of canons) {
+        if (!canon.graphRules)
+            continue;
+        if (canon.projectGraph === null)
+            return null;
+        for (const [file, findings] of Object.entries(canon.projectGraph({ repoRoot: sideRoot }).byFile))
+            merged[posix(file)] = [...(merged[posix(file)] ?? []), ...findings];
+    }
+    for (const list of Object.values(merged))
+        list.sort((a, b) => a.line - b.line || a.column - b.column || (a.code < b.code ? -1 : a.code > b.code ? 1 : 0) || (a.message < b.message ? -1 : a.message > b.message ? 1 : 0));
+    return merged;
+}
+const graphRecordFindings = (side, file, findings) => sortFindings(findings.map((finding) => ({ path: `${side}/${file}`, line: finding.line, column: finding.column, rule: finding.code, message: finding.message })));
+/**
+ * Judges one side: ESLint (and, for fe, stylelint) over what the records cannot vouch for, the records of the rest, and the new records.
+ * Never throws for a tool failure: those come back in `errors`, and a side with an error stores nothing.
+ */
+export async function lintSide(input) {
+    const { session, side, sideRoot, scope, stylesheets } = input;
+    const inReport = input.report ?? (() => true);
+    const scopeSet = new Set(scope);
+    const styleSet = new Set(stylesheets);
+    const folder = `lint/${side}`;
+    const prefix = `${side}/`;
+    const errors = [];
+    const abs = (file) => path.join(sideRoot, file);
+    // what the tree holds now
+    const memo = new Map();
+    const hashOf = (file) => {
+        if (!memo.has(file))
+            memo.set(file, session.index.hashOf(`${prefix}${file}`) ?? hashFile(abs(file)));
+        return memo.get(file);
+    };
+    const trackedHere = session.index.paths.filter((entry) => entry.startsWith(prefix)).map((entry) => entry.slice(prefix.length));
+    const sidePaths = [...new Set([...trackedHere, ...scope, ...stylesheets])].sort();
+    const sideKey = combineHashes(Object.fromEntries(sidePaths.map((file) => [file, hashOf(file) ?? 'absent'])));
+    const pathsDigest = hashText(sidePaths.join('\n'));
+    const appHash = (appRelative) => session.index.hashOf(appRelative) ?? (appRelative.startsWith(prefix) ? hashOf(appRelative.slice(prefix.length)) : hashFile(path.join(session.root, appRelative)));
+    const appPaths = [...new Set([...session.index.paths, ...scope.map((file) => `${prefix}${file}`), ...stylesheets.map((file) => `${prefix}${file}`)])];
+    // what the cache holds
+    const stored = session.records(folder);
+    const ofStep = (step) => stored.filter((record) => record.step === step);
+    const validEslint = new Map(reconcile(ofStep(LINT_STEPS.eslint), hashOf).map((record) => [record.path, record]));
+    const validStyle = new Map(reconcile(ofStep(LINT_STEPS.stylelint), hashOf).map((record) => [record.path, record]));
+    const meta = ofStep(LINT_STEPS.meta).find((record) => record.path === SIDE_RECORD);
+    const metaData = meta === undefined ? {} : dataOf(meta);
+    const previousFindings = new Set([...ofStep(LINT_STEPS.eslint), ...ofStep(LINT_STEPS.stylelint)].filter((record) => inReport(record.path)).flatMap((record) => record.findings.map(keyOf)));
+    const progress = session.progress.step('lint', `lint ${side}`, scope.length + stylesheets.length);
+    // ------------------------------------------------------------------ the plan
+    let whole = input.full;
+    let dirtyEslint = new Set();
+    let dirtyStyle = new Set();
+    let build = null;
+    let snapshot = null;
+    const crossEslint = new Map();
+    const crossStyle = new Map();
+    const sideUnchanged = whole === null && meta !== undefined && meta.hash === sideKey && metaData['extra'] === input.extraKey
+        && scope.every((file) => validEslint.has(file)) && stylesheets.every((file) => validStyle.has(file))
+        && ofStep(LINT_STEPS.eslint).every((record) => scopeSet.has(record.path)) && ofStep(LINT_STEPS.stylelint).every((record) => styleSet.has(record.path))
+        // a file the program reads that is no lint source (a JSON module, untracked generated code) is part of the side too
+        && ofStep(LINT_STEPS.imports).filter((record) => !scopeSet.has(record.path)).every((record) => hashOf(record.path) === record.hash);
+    const lineCountOf = (file) => {
+        const text = readText(abs(file));
+        if (text === null)
+            return 0;
+        const lines = text.split(/\r?\n/);
+        return lines.at(-1) === '' ? lines.length - 1 : lines.length;
+    };
+    const crossFor = (canons) => crossDigestFactory({ side, declarations: canons.flatMap((canon) => canon.crossFileInputs ?? []), paths: appPaths, hashOf: appHash, gitToken: input.gitToken ?? '', lineCountOf });
+    const eslintCross = crossFor(input.canons);
+    const styleCross = crossFor(input.styleCanon === null ? [] : [input.styleCanon]);
+    if (!sideUnchanged) {
+        for (const file of scope)
+            crossEslint.set(file, eslintCross(file));
+        for (const file of stylesheets)
+            crossStyle.set(file, styleCross(file));
+    }
+    let reason = whole === null ? '' : `${whole}`;
+    if (whole === null && !sideUnchanged) {
+        // a plan only a changed side needs
+        const undeclared = input.canons.find((canon) => canon.crossFileInputs === null);
+        const styleUndeclared = input.styleCanon !== null && input.styleCanon.crossFileInputs === null;
+        if (meta === undefined)
+            whole = 'no recorded lint of this side';
+        else if (metaData['extra'] !== input.extraKey)
+            whole = 'the untracked program inputs of the side changed';
+        else if (undeclared !== undefined)
+            whole = `${undeclared.name} declares no crossFileInputs`;
+        else if (input.canons.some((canon) => canon.graphRules && canon.projectGraph === null))
+            whole = `${input.canons.find((canon) => canon.graphRules)?.name ?? 'the canon'} exports no projectGraph`;
+        if (whole === null) {
+            try {
+                const ts = input.typescript();
+                const previous = new Map();
+                for (const record of ofStep(LINT_STEPS.imports)) {
+                    const data = dataOf(record);
+                    const imports = Array.isArray(data['imports']) ? data['imports'].filter((value) => typeof value === 'string') : [];
+                    const kept = previous.get(record.path);
+                    if (kept === undefined || record.hash === hashOf(record.path))
+                        previous.set(record.path, { hash: record.hash, imports, declaresGlobals: data['globals'] === true });
+                }
+                const recordedGraph = previous.size === 0 ? null : previous;
+                build = buildImportGraph({ ts, sideRoot, readText, fileExists: isFile, hashOf: (file) => hashOf(file) ?? null }, scope, recordedGraph, { pathsChanged: metaData['paths'] !== pathsDigest });
+                const dirty = dirtySetOf(recordedGraph, build.graph);
+                if (dirty.wholeSide !== null)
+                    whole = dirty.wholeSide;
+                else
+                    dirtyEslint = new Set([...dirty.dirty].filter((file) => scopeSet.has(file)));
+            }
+            catch (error) {
+                whole = `the import graph of the side cannot be built: ${String(error?.message ?? error).split('\n')[0]}`;
+            }
+        }
+        if (whole === null) {
+            for (const file of scope) {
+                const valid = validEslint.get(file);
+                if (valid === undefined)
+                    dirtyEslint.add(file);
+                else if (crossOf(valid) !== crossEslint.get(file))
+                    dirtyEslint.add(file);
+            }
+            try {
+                snapshot = mergedSnapshot(sideRoot, input.canons);
+                if (snapshot === null)
+                    whole = 'a canon exports no projectGraph';
+                else {
+                    const recorded = new Map(ofStep(LINT_STEPS.graph).filter((record) => record.hash === hashOf(record.path)).map((record) => [record.path, canonicalJson(record.findings)]));
+                    const files = new Set([...scope.filter((file) => validEslint.has(file)), ...recorded.keys()]);
+                    for (const file of files) {
+                        if (!scopeSet.has(file))
+                            continue;
+                        const now = canonicalJson(graphRecordFindings(side, file, snapshot[file] ?? []));
+                        if ((recorded.get(file) ?? '[]') !== now)
+                            dirtyEslint.add(file);
+                    }
+                }
+            }
+            catch (error) {
+                whole = `the project graph of the side cannot be built: ${String(error?.message ?? error).split('\n')[0]}`;
+            }
+        }
+        // stylelint
+        const recordedStyles = new Set(ofStep(LINT_STEPS.stylelint).map((record) => record.path));
+        const styleChanged = [...recordedStyles].some((file) => !styleSet.has(file)) || stylesheets.some((file) => !recordedStyles.has(file));
+        if (styleUndeclared)
+            dirtyStyle = new Set(stylesheets);
+        else if (styleChanged)
+            dirtyStyle = new Set(stylesheets);
+        else
+            for (const file of stylesheets) {
+                const valid = validStyle.get(file);
+                if (valid === undefined || crossOf(valid) !== crossStyle.get(file))
+                    dirtyStyle.add(file);
+            }
+        reason = whole ?? `${dirtyEslint.size} of ${scope.length} source files and ${dirtyStyle.size} of ${stylesheets.length} stylesheets differ from the cache`;
+    }
+    else if (whole === null)
+        reason = 'the side key is unchanged';
+    if (whole !== null) {
+        dirtyEslint = new Set(scope);
+        dirtyStyle = new Set(stylesheets);
+    }
+    // ------------------------------------------------------------------ the run
+    const eslintList = [...dirtyEslint].filter(inReport).sort();
+    const styleList = [...dirtyStyle].filter(inReport).sort();
+    const freshEslint = new Map();
+    const freshStyle = new Map();
+    const rootOf = (file) => path.relative(sideRoot, file).replace(/\\/g, '/');
+    if (eslintList.length > 0) {
+        const run = await input.eslint(whole !== null ? null : eslintList);
+        errors.push(...run.errors);
+        for (const result of run.results)
+            freshEslint.set(posix(rootOf(result.filePath)), result);
+    }
+    if (input.stylelint !== null && styleList.length > 0) {
+        const run = await input.stylelint(whole !== null ? null : styleList);
+        errors.push(...run.errors);
+        for (const result of run.results)
+            freshStyle.set(posix(rootOf(result.source)), result);
+    }
+    // ------------------------------------------------------------------ the answer
+    const eslintResults = [];
+    const styleResults = [];
+    const current = [];
+    const eslintRecords = [];
+    const styleRecords = [];
+    const planHash = (file) => hashOf(file) ?? 'absent';
+    for (const file of scope) {
+        if (!inReport(file))
+            continue;
+        const fresh = freshEslint.get(file);
+        const reuse = fresh === undefined ? validEslint.get(file) : undefined;
+        if (fresh !== undefined) {
+            eslintResults.push(fresh);
+            const converted = fromEslint(side, file, fresh);
+            current.push(...converted.findings);
+            const cross = crossEslint.get(file);
+            eslintRecords.push({ path: file, step: LINT_STEPS.eslint, hash: planHash(file), findings: converted.findings, data: { ends: converted.ends, ...(cross === undefined ? {} : { cross }) } });
+        }
+        else if (reuse !== undefined) {
+            eslintResults.push(toEslint(sideRoot, file, reuse));
+            current.push(...reuse.findings);
+            eslintRecords.push(reuse);
+        }
+    }
+    for (const file of stylesheets) {
+        if (!inReport(file))
+            continue;
+        const fresh = freshStyle.get(file);
+        const reuse = fresh === undefined ? validStyle.get(file) : undefined;
+        if (fresh !== undefined) {
+            styleResults.push(fresh);
+            const converted = fromStylelint(side, file, fresh);
+            current.push(...converted.findings);
+            const cross = crossStyle.get(file);
+            styleRecords.push({ path: file, step: LINT_STEPS.stylelint, hash: planHash(file), findings: converted.findings, data: { ends: converted.ends, ...(cross === undefined ? {} : { cross }) } });
+        }
+        else if (reuse !== undefined) {
+            styleResults.push(toStylelint(sideRoot, file, reuse));
+            current.push(...reuse.findings);
+            styleRecords.push(reuse);
+        }
+    }
+    const checked = freshEslint.size + freshStyle.size;
+    const units = [...scope, ...stylesheets].filter(inReport).length;
+    const reused = Math.max(0, units - checked);
+    progress.tick(units, reused, checked);
+    progress.end();
+    // ------------------------------------------------------------------ the records
+    let written = false;
+    const complete = errors.length === 0 && input.write && input.report === null && !sideUnchanged;
+    if (complete) {
+        const stable = [...freshEslint.keys(), ...freshStyle.keys()].every((file) => hashFile(abs(file)) === hashOf(file));
+        if (stable) {
+            const records = [...eslintRecords, ...styleRecords];
+            // without an import graph or a project graph the next run lints the side whole; the results themselves are still stored
+            try {
+                if (build === null) {
+                    const ts = input.typescript();
+                    build = buildImportGraph({ ts, sideRoot, readText, fileExists: isFile, hashOf: (file) => hashOf(file) ?? null }, scope, null);
+                }
+                for (const [file, node] of build.graph)
+                    records.push({ path: file, step: LINT_STEPS.imports, hash: node.hash, findings: [], data: { globals: node.declaresGlobals, imports: node.imports } });
+                snapshot ??= mergedSnapshot(sideRoot, input.canons);
+                for (const [file, findings] of Object.entries(snapshot ?? {})) {
+                    if (scopeSet.has(file) && findings.length > 0)
+                        records.push({ path: file, step: LINT_STEPS.graph, hash: planHash(file), findings: graphRecordFindings(side, file, findings) });
+                }
+            }
+            catch {
+                records.splice(0, records.length, ...records.filter((record) => record.step === LINT_STEPS.eslint || record.step === LINT_STEPS.stylelint));
+            }
+            records.push({ path: SIDE_RECORD, step: LINT_STEPS.meta, hash: sideKey, findings: [], data: { extra: input.extraKey, files: scope.length, paths: pathsDigest, stylesheets: stylesheets.length } });
+            session.replace(folder, records);
+            written = true;
+        }
+    }
+    const currentKeys = new Set(current.map(keyOf));
+    let knownFindings = 0;
+    for (const key of currentKeys)
+        if (previousFindings.has(key))
+            knownFindings += 1;
+    const stats = {
+        mode: whole !== null || input.full !== null ? 'full' : 'diff',
+        reason,
+        checked,
+        reused,
+        newFindings: currentKeys.size - knownFindings,
+        knownFindings,
+        fixedFindings: [...previousFindings].filter((key) => !currentKeys.has(key)).length,
+        written,
+    };
+    return { eslint: eslintResults, stylelint: styleResults, errors, stats };
+}
+/** The family line of a run over several sides: one report for the family, the sides' counts added and their reasons joined. */
+export function lintFamilyReport(sides) {
+    const sum = (pick) => sides.reduce((total, entry) => total + pick(entry.stats), 0);
+    return {
+        family: 'lint',
+        mode: sides.length > 0 && sides.every((entry) => entry.stats.mode === 'full') ? 'full' : 'diff',
+        reason: sides.map((entry) => `${entry.side}: ${entry.stats.reason}`).join('; '),
+        checked: sum((stats) => stats.checked),
+        reused: sum((stats) => stats.reused),
+        newFindings: sum((stats) => stats.newFindings),
+        knownFindings: sum((stats) => stats.knownFindings),
+        fixedFindings: sum((stats) => stats.fixedFindings),
+    };
+}

package/cache/order.d.mts

@@ -0,0 +1 @@
+export declare const compare: (a: string, b: string) => number;

package/cache/order.mjs

@@ -0,0 +1,2 @@
+// order.mts - the one string order of the cache: by UTF-16 code unit, so every host sorts one record set alike.
+export const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);

package/cache/progress.d.mts

@@ -0,0 +1,19 @@
+import type { ProgressSink } from './types.mjs';
+export interface ProgressOptions {
+    /** Where lines go (stderr). */
+    write: (text: string) => unknown;
+    /** True when `write` reaches a terminal: running lines then rewrite in place. */
+    tty?: boolean;
+    /** Milliseconds since the epoch; a seam for specs. */
+    now?: () => number;
+    /** Files the whole run is expected to touch, for the overall percentage; else the steps seen so far. */
+    planned?: number;
+    /** Seconds of work between running lines. */
+    everySeconds?: number;
+}
+/** `3m07s`, `42s`, `1h02m` for a duration in milliseconds. */
+export declare function elapsedText(ms: number): string;
+/** The sink that prints nothing (`--quiet`, and the library default). */
+export declare const silentProgress: ProgressSink;
+/** The stderr progress sink. */
+export declare function createProgress(options: ProgressOptions): ProgressSink;

package/cache/progress.mjs

@@ -0,0 +1,68 @@
+const pad = (n) => String(n).padStart(2, '0');
+/** `3m07s`, `42s`, `1h02m` for a duration in milliseconds. */
+export function elapsedText(ms) {
+    const total = Math.max(0, Math.floor(ms / 1000));
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const seconds = total % 60;
+    if (hours > 0)
+        return `${hours}h${pad(minutes)}m`;
+    return minutes > 0 ? `${minutes}m${pad(seconds)}s` : `${seconds}s`;
+}
+const clock = (at) => {
+    const d = new Date(at);
+    return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+};
+const percent = (done, total) => (total <= 0 ? 100 : Math.min(100, Math.floor((done / total) * 100)));
+/** The sink that prints nothing (`--quiet`, and the library default). */
+export const silentProgress = {
+    step: () => ({ tick: () => { }, end: () => { } }),
+};
+/** The stderr progress sink. */
+export function createProgress(options) {
+    const now = options.now ?? Date.now;
+    const started = now();
+    const every = (options.everySeconds ?? 10) * 1000;
+    let registered = 0;
+    let finished = 0;
+    let open = false;
+    const prefix = (done) => {
+        const total = Math.max(options.planned ?? 0, registered);
+        return `[${clock(now())} +${elapsedText(now() - started)} ${percent(finished + done, total)}%]`;
+    };
+    const emit = (text, running) => {
+        if (options.tty === true && running) {
+            options.write(`\r${text}`);
+            open = true;
+            return;
+        }
+        options.write(`${open ? '\r' : ''}${text}\n`);
+        open = false;
+    };
+    return {
+        step(family, name, total) {
+            registered += total;
+            let done = 0;
+            const stepStart = now();
+            let lastAt = stepStart;
+            let lastTenth = 0;
+            const body = (reused, checked) => `${family} ${name} ${done}/${total} (${percent(done, total)}%) reused ${reused} checked ${checked}`;
+            emit(`${prefix(0)} ${family} ${name} start, ${total} files`, false);
+            return {
+                tick(newDone, reused, checked) {
+                    done = newDone;
+                    const tenth = Math.floor(percent(done, total) / 10);
+                    if (now() - lastAt < every && tenth <= lastTenth)
+                        return;
+                    lastAt = now();
+                    lastTenth = tenth;
+                    emit(`${prefix(done)} ${body(reused, checked)}`, true);
+                },
+                end() {
+                    finished += total;
+                    emit(`${prefix(0)} ${family} ${name} done, ${total} files in ${elapsedText(now() - stepStart)}`, false);
+                },
+            };
+        },
+    };
+}

package/cache/quality-baselines.d.mts

@@ -0,0 +1,109 @@
+import type { CacheRecord, CheckSession, FamilyReport } from './types.mjs';
+export declare const SONAR_FOLDER = "sonar-baseline";
+export declare const CODECOV_FOLDER = "codecov-baseline";
+/** The step of every reference record. */
+export declare const REFERENCE_STEP = "reference";
+/** The label every prediction carries and every printed line states. */
+export declare const PREDICTION = "prediction";
+/** The new-code conditions of the Sonar quality gate, as its owner (`runtime/knowledge/sonar-gate.yaml`) states them. */
+export interface SonarGate {
+    readonly coverageMinPercent: number;
+    readonly duplicationMaxPercent: number;
+}
+/** The targets of codecov.yml, in percent. */
+export interface CodecovTargets {
+    readonly project: number;
+    readonly patch: number;
+}
+/** The gate conditions the predictions are compared with, read from the gate document (`newCode.coverage.minPercent`, `newCode.duplication.maxPercent`). */
+export declare function readSonarGate(gateYaml: string): SonarGate;
+/** The patch and project targets of codecov.yml (`coverage.status.{project,patch}.default.target`, `90%`). */
+export declare function readCodecovTargets(codecovYaml: string): CodecovTargets;
+/** The digest of the analysis scope settings of sonar-project.properties: the settings that decide which lines Sonar sees, sorted, nothing else. */
+export declare function scopeDigest(propertiesText: string): string;
+/** What the reference records are built from. Texts are the owners' files as they stand; the base commit is the merge-base the new code is measured against. */
+export interface BaselineSources {
+    readonly baseCommit: string;
+    readonly sonarGateYaml: string;
+    readonly sonarProperties: string;
+    readonly codecovYaml: string;
+}
+/** The records of the two baseline folders: reference data and digests, never a result of a server. */
+export declare function baselineRecords(sources: BaselineSources): {
+    readonly sonar: readonly CacheRecord[];
+    readonly codecov: readonly CacheRecord[];
+};
+/** The reference parts already stored whose digest differs from the current one (a first adoption has none): the gate, the scope or the targets moved since the baseline was written. */
+export declare function baselineDrift(stored: readonly CacheRecord[], current: readonly CacheRecord[]): string[];
+/** Per file, the lines added or changed since the base commit (new-code lines). */
+export type ChangedLines = Readonly<Record<string, readonly number[]>>;
+/** The lines a `git diff -U0 <base>` adds or changes, per file (`+++ b/path`, hunk headers `@@ -a,b +c,d @@`); a deleted file has none. */
+export declare function changedLinesFromDiff(diff: string): ChangedLines;
+/** Per source, its instrumented lines and the lines the whole suite covers. */
+export type LineCoverage = Readonly<Record<string, {
+    readonly instrumented: readonly number[];
+    readonly covered: readonly number[];
+}>>;
+/**
+ * The line coverage the unit-spec records stand for: a line is instrumented when a statement starts on it and covered when any spec covers one that does. Equal for a
+ * base commit's committed records and the work tree's, so the project change is computed on the same footing.
+ */
+export declare function lineCoverageOf(records: readonly CacheRecord[]): LineCoverage;
+/** The base commit's coverage records, read from the commit itself (`git show <base>:<path>`), so the base total is computed and not stored. */
+export declare function recordsAtCommit(baseCommit: string, git: (args: readonly string[]) => string | undefined, folder?: string): CacheRecord[];
+/** `git` run in `cwd`, undefined when it fails (an unreadable base commit is no base total, not a crash). */
+export declare function gitRunner(cwd: string): (args: readonly string[]) => string | undefined;
+/** A duplicated block of a source: where the clones step found it. */
+export interface CloneBlock {
+    readonly path: string;
+    readonly startLine: number;
+    readonly endLine: number;
+}
+export interface QualityInputs {
+    readonly changed: ChangedLines;
+    readonly coverage: LineCoverage;
+    /** The base commit's coverage, or undefined when it cannot be read (then no project change is predicted). */
+    readonly baseCoverage: LineCoverage | undefined;
+    readonly clones: readonly CloneBlock[];
+    readonly gate: SonarGate;
+    readonly targets: CodecovTargets;
+    /** The files Sonar and Codecov measure (the coverage scope), or every covered file when absent. */
+    readonly measured?: (path: string) => boolean;
+    /** The files Sonar counts new code in (its sources minus its exclusions), or every changed file when absent. */
+    readonly analysed?: (path: string) => boolean;
+}
+/** One prediction. `value` is undefined when nothing in the change could be measured; it is never a verdict. */
+export interface Prediction {
+    readonly label: typeof PREDICTION;
+    readonly provider: 'sonar' | 'codecov';
+    readonly metric: string;
+    readonly value: number | undefined;
+    /** The numbers the percentage comes from, as text (`28 of 30 changed lines`). */
+    readonly basis: string;
+    /** What the server holds the metric to, from the baseline. */
+    readonly target: string;
+}
+/** Sonar's new-code coverage and duplication and Codecov's patch coverage and project change, each labelled as a prediction. */
+export declare function predict(inputs: QualityInputs): Prediction[];
+/** The lines a run prints: each states that it is a local prediction and what the server holds the metric to. */
+export declare function formatPredictions(predictions: readonly Prediction[]): string[];
+export interface QualityFamilyResult {
+    readonly predictions: readonly Prediction[];
+    readonly lines: readonly string[];
+    /** The reference parts whose owner changed since the baseline was written. */
+    readonly drift: readonly string[];
+    readonly report: FamilyReport;
+}
+/**
+ * The `--sonar` family: writes the two baseline folders from the owners' files and predicts from the merged coverage. It always runs (the predictions read the changed
+ * lines, which no key holds) and it never fails a run: `ok` does not exist here, the servers judge.
+ */
+export declare function runQualityFamily({ session, sources, changed, clones, baseCoverage, measured, analysed }: {
+    session: CheckSession;
+    sources: BaselineSources;
+    changed: ChangedLines;
+    clones: readonly CloneBlock[];
+    baseCoverage: LineCoverage | undefined;
+    measured?: (path: string) => boolean;
+    analysed?: (path: string) => boolean;
+}): QualityFamilyResult;