@starci/hfs 4.12.2 → 4.13.2

package/cache/quality-baselines.mjs

@@ -0,0 +1,235 @@
+// quality-baselines.mts - the `--sonar` family of the app check cache (contexts/project/check-cache.md, "Sonar and Codecov"). `sonar-baseline/` and `codecov-baseline/` hold
+// REFERENCE data only: the base commit of the new code, the quality gate's conditions as read from their owner with that owner's digest, the analysis scope's digest, and the
+// patch and project targets of codecov.yml with its digest. They never hold a server's result. From them and the merged coverage a run predicts what the servers will say,
+// and every prediction is labelled as one: Sonar's new-code coverage and duplication on the lines changed since the base commit, Codecov's patch coverage and project
+// change (the base total computed from the base commit's committed coverage records). The servers stay the judges: a prediction never passes or fails a run.
+import { spawnSync } from 'node:child_process';
+import { hashText } from './hash.mjs';
+import { parseRecords } from './jsonl.mjs';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+export const SONAR_FOLDER = 'sonar-baseline';
+export const CODECOV_FOLDER = 'codecov-baseline';
+/** The step of every reference record. */
+export const REFERENCE_STEP = 'reference';
+/** The label every prediction carries and every printed line states. */
+export const PREDICTION = 'prediction';
+/** The unit-spec records of the test family, read by folder and step (kept in step with test-family.mts, which owns them). */
+const TEST_FOLDER = 'test-coverage';
+const SPEC_STEP = 'unit-spec';
+function numberAt(document, keys, what) {
+    let value = document;
+    for (const key of keys)
+        value = typeof value === 'object' && value !== null ? value[key] : undefined;
+    const parsed = typeof value === 'string' ? Number.parseFloat(value) : value;
+    if (typeof parsed !== 'number' || !Number.isFinite(parsed))
+        throw new Error(`${what} is not declared at ${keys.join('.')}`);
+    return parsed;
+}
+/** The gate conditions the predictions are compared with, read from the gate document (`newCode.coverage.minPercent`, `newCode.duplication.maxPercent`). */
+export function readSonarGate(gateYaml) {
+    const document = parseYaml(gateYaml);
+    return { coverageMinPercent: numberAt(document, ['newCode', 'coverage', 'minPercent'], 'the Sonar gate'), duplicationMaxPercent: numberAt(document, ['newCode', 'duplication', 'maxPercent'], 'the Sonar gate') };
+}
+/** The patch and project targets of codecov.yml (`coverage.status.{project,patch}.default.target`, `90%`). */
+export function readCodecovTargets(codecovYaml) {
+    const document = parseYaml(codecovYaml);
+    return {
+        project: numberAt(document, ['coverage', 'status', 'project', 'default', 'target'], 'codecov.yml'),
+        patch: numberAt(document, ['coverage', 'status', 'patch', 'default', 'target'], 'codecov.yml'),
+    };
+}
+const SCOPE_KEY = /^sonar\.(?:sources|tests|inclusions|exclusions|test\.inclusions|test\.exclusions|coverage\.exclusions|cpd\.exclusions|javascript\.lcov\.reportPaths|typescript\.tsconfigPaths)$/u;
+/** The digest of the analysis scope settings of sonar-project.properties: the settings that decide which lines Sonar sees, sorted, nothing else. */
+export function scopeDigest(propertiesText) {
+    const settings = propertiesText.split(/\r?\n/u).flatMap((line) => {
+        const match = /^\s*([A-Za-z0-9_.-]+)\s*[=:]\s*(.*?)\s*$/u.exec(line);
+        return match !== null && SCOPE_KEY.test(match[1] ?? '') ? [`${match[1]}=${match[2]}`] : [];
+    });
+    return hashText(settings.sort().join('\n'));
+}
+const reference = (key, hash, data) => ({ path: key, step: REFERENCE_STEP, hash, findings: [], data });
+/** The records of the two baseline folders: reference data and digests, never a result of a server. */
+export function baselineRecords(sources) {
+    const gate = readSonarGate(sources.sonarGateYaml);
+    const targets = readCodecovTargets(sources.codecovYaml);
+    return {
+        sonar: [
+            reference('new-code-base', sources.baseCommit, { baseCommit: sources.baseCommit }),
+            reference('quality-gate', hashText(sources.sonarGateYaml), { coverageMinPercent: gate.coverageMinPercent, duplicationMaxPercent: gate.duplicationMaxPercent, owner: 'runtime/knowledge/sonar-gate.yaml' }),
+            reference('analysis-scope', scopeDigest(sources.sonarProperties), { digestOf: 'sonar-project.properties' }),
+        ],
+        codecov: [
+            reference('base', sources.baseCommit, { baseCommit: sources.baseCommit }),
+            reference('targets', hashText(sources.codecovYaml), { project: targets.project, patch: targets.patch, owner: 'codecov.yml' }),
+        ],
+    };
+}
+/** 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 function baselineDrift(stored, current) {
+    const before = new Map(stored.map((record) => [record.path, record.hash]));
+    return current.filter((record) => before.has(record.path) && before.get(record.path) !== record.hash).map((record) => record.path).sort();
+}
+/** 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 function changedLinesFromDiff(diff) {
+    const out = {};
+    let file;
+    for (const line of diff.split(/\r?\n/u)) {
+        if (line.startsWith('+++ ')) {
+            const target = line.slice(4).trim();
+            file = target === '/dev/null' ? undefined : target.replace(/^b\//u, '');
+            if (file !== undefined)
+                out[file] = out[file] ?? [];
+            continue;
+        }
+        const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/u.exec(line);
+        if (hunk !== null && file !== undefined) {
+            const start = Number(hunk[1]);
+            const count = hunk[2] === undefined ? 1 : Number(hunk[2]);
+            for (let i = 0; i < count; i += 1)
+                out[file]?.push(start + i);
+        }
+    }
+    return out;
+}
+/**
+ * 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 function lineCoverageOf(records) {
+    const instrumented = new Map();
+    const covered = new Map();
+    for (const record of records) {
+        if (record.step !== SPEC_STEP)
+            continue;
+        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))
+            continue;
+        for (const [source, items] of Object.entries(sources)) {
+            const statements = typeof items === 'object' && items !== null && !Array.isArray(items) ? items['s'] : undefined;
+            if (!Array.isArray(statements))
+                continue;
+            const all = instrumented.get(source) ?? new Set();
+            const hit = covered.get(source) ?? new Set();
+            for (const statement of statements) {
+                if (!Array.isArray(statement) || typeof statement[0] !== 'number')
+                    continue;
+                all.add(statement[0]);
+                if (statement[4] === 1)
+                    hit.add(statement[0]);
+            }
+            instrumented.set(source, all);
+            covered.set(source, hit);
+        }
+    }
+    return Object.fromEntries([...instrumented].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([source, lines]) => [source, { instrumented: [...lines].sort((a, b) => a - b), covered: [...(covered.get(source) ?? [])].sort((a, b) => a - b) }]));
+}
+/** 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 function recordsAtCommit(baseCommit, git, folder = `.starcistacks/cache/${TEST_FOLDER}`) {
+    const listing = git(['ls-tree', '-r', '--name-only', baseCommit, '--', folder]);
+    if (listing === undefined)
+        return [];
+    return listing.split(/\r?\n/u).filter((name) => name.endsWith('.jsonl')).flatMap((name) => parseRecords(git(['show', `${baseCommit}:${name}`]) ?? '').records);
+}
+/** `git` run in `cwd`, undefined when it fails (an unreadable base commit is no base total, not a crash). */
+export function gitRunner(cwd) {
+    return (args) => {
+        const result = spawnSync('git', [...args], { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+        return result.status === 0 ? result.stdout : undefined;
+    };
+}
+const percent = (part, whole) => (whole === 0 ? undefined : Math.round((part / whole) * 10000) / 100);
+/** Covered and coverable lines among the changed lines of the measured sources. */
+function changedCoverage(inputs) {
+    let covered = 0;
+    let coverable = 0;
+    for (const [file, lines] of Object.entries(inputs.changed)) {
+        const coverage = inputs.coverage[file];
+        if (coverage === undefined || inputs.measured?.(file) === false)
+            continue;
+        const instrumented = new Set(coverage.instrumented);
+        const hit = new Set(coverage.covered);
+        for (const line of new Set(lines)) {
+            if (!instrumented.has(line))
+                continue;
+            coverable += 1;
+            if (hit.has(line))
+                covered += 1;
+        }
+    }
+    return { covered, coverable };
+}
+function total(coverage, measured) {
+    let covered = 0;
+    let coverable = 0;
+    for (const [file, lines] of Object.entries(coverage)) {
+        if (measured?.(file) === false)
+            continue;
+        coverable += lines.instrumented.length;
+        covered += lines.covered.length;
+    }
+    return { covered, coverable };
+}
+/** Sonar's new-code coverage and duplication and Codecov's patch coverage and project change, each labelled as a prediction. */
+export function predict(inputs) {
+    const patch = changedCoverage(inputs);
+    const out = [
+        { label: PREDICTION, provider: 'sonar', metric: 'new-code coverage', value: percent(patch.covered, patch.coverable), basis: `${patch.covered} of ${patch.coverable} coverable changed lines`, target: `>= ${inputs.gate.coverageMinPercent}%` },
+    ];
+    let newLines = 0;
+    let duplicated = 0;
+    for (const [file, lines] of Object.entries(inputs.changed)) {
+        if (inputs.analysed?.(file) === false)
+            continue;
+        const changed = new Set(lines);
+        newLines += changed.size;
+        const inClone = new Set();
+        for (const block of inputs.clones)
+            if (block.path === file)
+                for (let line = block.startLine; line <= block.endLine; line += 1)
+                    if (changed.has(line))
+                        inClone.add(line);
+        duplicated += inClone.size;
+    }
+    out.push({ label: PREDICTION, provider: 'sonar', metric: 'new-code duplication', value: percent(duplicated, newLines), basis: `${duplicated} of ${newLines} changed lines`, target: `<= ${inputs.gate.duplicationMaxPercent}%` });
+    out.push({ label: PREDICTION, provider: 'codecov', metric: 'patch coverage', value: percent(patch.covered, patch.coverable), basis: `${patch.covered} of ${patch.coverable} changed lines with coverage`, target: `>= ${inputs.targets.patch}%` });
+    const now = total(inputs.coverage, inputs.measured);
+    const nowPercent = percent(now.covered, now.coverable);
+    if (inputs.baseCoverage === undefined) {
+        out.push({ label: PREDICTION, provider: 'codecov', metric: 'project change', value: undefined, basis: 'the base commit holds no readable coverage records', target: `project >= ${inputs.targets.project}%` });
+    }
+    else {
+        const base = total(inputs.baseCoverage, inputs.measured);
+        const basePercent = percent(base.covered, base.coverable);
+        const change = nowPercent === undefined || basePercent === undefined ? undefined : Math.round((nowPercent - basePercent) * 100) / 100;
+        out.push({ label: PREDICTION, provider: 'codecov', metric: 'project change', value: change, basis: `${nowPercent ?? 'n/a'}% now against ${basePercent ?? 'n/a'}% at the base commit`, target: `project >= ${inputs.targets.project}%` });
+    }
+    return out;
+}
+/** The lines a run prints: each states that it is a local prediction and what the server holds the metric to. */
+export function formatPredictions(predictions) {
+    return predictions.map((entry) => `${entry.provider}: ${entry.metric} ${entry.value === undefined ? 'not measurable' : `${entry.value}%`} (${entry.basis}) [${entry.label} from the local run, not the server's result; the server holds it to ${entry.target}]`);
+}
+/**
+ * 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 function runQualityFamily({ session, sources, changed, clones, baseCoverage, measured, analysed }) {
+    const records = baselineRecords(sources);
+    const drift = [...new Set([...baselineDrift(session.records(SONAR_FOLDER), records.sonar), ...baselineDrift(session.records(CODECOV_FOLDER), records.codecov)])].sort();
+    session.replace(SONAR_FOLDER, records.sonar);
+    session.replace(CODECOV_FOLDER, records.codecov);
+    const predictions = predict({
+        changed,
+        coverage: lineCoverageOf(session.records(TEST_FOLDER)),
+        baseCoverage,
+        clones,
+        gate: readSonarGate(sources.sonarGateYaml),
+        targets: readCodecovTargets(sources.codecovYaml),
+        ...(measured === undefined ? {} : { measured }),
+        ...(analysed === undefined ? {} : { analysed }),
+    });
+    const report = { family: 'sonar', mode: 'full', reason: 'predictions always run', checked: predictions.length, reused: 0, newFindings: 0, knownFindings: 0, fixedFindings: 0 };
+    session.report(report);
+    return { predictions, lines: formatPredictions(predictions), drift, report };
+}

package/cache/records.d.mts

@@ -0,0 +1,33 @@
+import type { CacheRecord, CheckSession, ContentIndex, Finding, JsonValue } from './types.mjs';
+export declare class RecordSet {
+    private readonly records;
+    constructor(initial?: readonly CacheRecord[]);
+    /** The record of (path, step) whose hash is `hash`, else undefined: a record of other content is no answer. */
+    matching(path: string, step: string, hash: string): CacheRecord | undefined;
+    put(record: CacheRecord): void;
+    /** Drops every record of `step` whose path is not in `keep`: a deleted path drops every record it owns. */
+    retain(step: string, keep: ReadonlySet<string>): void;
+    /** Every finding the records of `step` hold. */
+    findings(step: string): Finding[];
+    toArray(): CacheRecord[];
+}
+/** The key of an input set: the sha256 of its members and their hashes, `absent` for a member the work tree no longer holds. */
+export declare function keyOfPaths(index: ContentIndex, paths: readonly string[], extra?: Readonly<Record<string, string>>): string;
+/**
+ * One scoped step: reuses the recorded `data` when the family runs diff and the record's key is `key`; else computes, and stores unless the
+ * step's inputs (`inputs`, tracked paths) were edited during the run or `store(value)` says the result must not be kept (a timeout is never
+ * stored). `compact` is the record's findings, for the new / known / fixed comparison.
+ */
+export declare function scopedStep<T extends JsonValue>(session: CheckSession, records: RecordSet, step: {
+    readonly path: string;
+    readonly step: string;
+    readonly key: string;
+    readonly reuse: boolean;
+    readonly inputs: readonly string[];
+    compute(): T | Promise<T>;
+    compact(value: T): Finding[];
+    store?(value: T): boolean;
+}): Promise<{
+    value: T;
+    reused: boolean;
+}>;

package/cache/records.mjs

@@ -0,0 +1,54 @@
+// records.mts - the working set of one folder during a run: the records the family inherited, replaced key by key as its steps judge, then
+// handed back to the session in one `replace`. A step that throws puts nothing, so it keeps (or loses) no record of that step.
+import { compare } from './order.mjs';
+import { combineHashes } from './hash.mjs';
+const keyOf = (path, step) => `${path}\0${step}`;
+export class RecordSet {
+    records = new Map();
+    constructor(initial = []) {
+        for (const record of initial)
+            this.records.set(keyOf(record.path, record.step), record);
+    }
+    /** The record of (path, step) whose hash is `hash`, else undefined: a record of other content is no answer. */
+    matching(path, step, hash) {
+        const record = this.records.get(keyOf(path, step));
+        return record?.hash === hash ? record : undefined;
+    }
+    put(record) {
+        this.records.set(keyOf(record.path, record.step), record);
+    }
+    /** Drops every record of `step` whose path is not in `keep`: a deleted path drops every record it owns. */
+    retain(step, keep) {
+        for (const [key, record] of this.records)
+            if (record.step === step && !keep.has(record.path))
+                this.records.delete(key);
+    }
+    /** Every finding the records of `step` hold. */
+    findings(step) {
+        return [...this.records.values()].filter((record) => record.step === step).flatMap((record) => record.findings);
+    }
+    toArray() {
+        return [...this.records.values()].sort((a, b) => compare(a.path, b.path) || compare(a.step, b.step));
+    }
+}
+/** The key of an input set: the sha256 of its members and their hashes, `absent` for a member the work tree no longer holds. */
+export function keyOfPaths(index, paths, extra = {}) {
+    const parts = { ...extra };
+    for (const file of paths)
+        parts[`path:${file}`] = index.hashOf(file) ?? 'absent';
+    return combineHashes(parts);
+}
+/**
+ * One scoped step: reuses the recorded `data` when the family runs diff and the record's key is `key`; else computes, and stores unless the
+ * step's inputs (`inputs`, tracked paths) were edited during the run or `store(value)` says the result must not be kept (a timeout is never
+ * stored). `compact` is the record's findings, for the new / known / fixed comparison.
+ */
+export async function scopedStep(session, records, step) {
+    const held = step.reuse ? records.matching(step.path, step.step, step.key) : undefined;
+    if (held?.data !== undefined)
+        return { value: held.data, reused: true };
+    const value = await step.compute();
+    if ((step.store?.(value) ?? true) && session.unchanged(step.inputs))
+        records.put({ path: step.path, step: step.step, hash: step.key, findings: step.compact(value), data: value });
+    return { value, reused: false };
+}

package/cache/report.d.mts

@@ -0,0 +1,19 @@
+import { type Finding, type FamilyReport, type FamilyId, type RunMode } from './types.mjs';
+/** `hfs: diff (against the cache at 1a2b3c4d5e6f), checked 12, reused 3400; findings 1 new, 4 known, 0 fixed` */
+export declare function familyLine(report: FamilyReport): string;
+/** The findings this run produced against the ones the records held: new, known (held already) and fixed (held, no longer produced). */
+export declare function compareFindings(previous: readonly Finding[], current: readonly Finding[]): {
+    newFindings: number;
+    knownFindings: number;
+    fixedFindings: number;
+};
+/** A family report from a decision, the work it did and the findings before and after. */
+export declare function makeReport(input: {
+    family: FamilyId;
+    mode: RunMode;
+    reason: string;
+    checked: number;
+    reused: number;
+    previous: readonly Finding[];
+    current: readonly Finding[];
+}): FamilyReport;

package/cache/report.mjs

@@ -0,0 +1,32 @@
+// report.mts - what a family says about itself: one diagnosis line, and the comparison of its findings with the ones its records held.
+import {} from './types.mjs';
+/** `hfs: diff (against the cache at 1a2b3c4d5e6f), checked 12, reused 3400; findings 1 new, 4 known, 0 fixed` */
+export function familyLine(report) {
+    return `${report.family}: ${report.mode} (${report.reason}), checked ${report.checked}, reused ${report.reused}; findings ${report.newFindings} new, ${report.knownFindings} known, ${report.fixedFindings} fixed`;
+}
+const keyOf = (finding) => `${finding.path}\0${finding.rule}\0${finding.message}`;
+/** The findings this run produced against the ones the records held: new, known (held already) and fixed (held, no longer produced). */
+export function compareFindings(previous, current) {
+    const before = new Map();
+    for (const finding of previous)
+        before.set(keyOf(finding), (before.get(keyOf(finding)) ?? 0) + 1);
+    let known = 0;
+    let fresh = 0;
+    for (const finding of current) {
+        const held = before.get(keyOf(finding)) ?? 0;
+        if (held > 0) {
+            known += 1;
+            before.set(keyOf(finding), held - 1);
+        }
+        else
+            fresh += 1;
+    }
+    let fixed = 0;
+    for (const left of before.values())
+        fixed += left;
+    return { newFindings: fresh, knownFindings: known, fixedFindings: fixed };
+}
+/** A family report from a decision, the work it did and the findings before and after. */
+export function makeReport(input) {
+    return { family: input.family, mode: input.mode, reason: input.reason, checked: input.checked, reused: input.reused, ...compareFindings(input.previous, input.current) };
+}

package/cache/run-log.d.mts

@@ -0,0 +1,17 @@
+import type { FamilyReport } from './types.mjs';
+export declare const RUN_LOG_LIMIT = 100;
+/** One step or family of a run: how long it took. */
+export interface TimedFamily extends FamilyReport {
+    readonly seconds: number;
+}
+/** One run. */
+export interface RunEntry {
+    readonly command: string;
+    readonly seconds: number;
+    readonly exit: number;
+    readonly families: readonly TimedFamily[];
+}
+/** The folder of the untracked tool cache for the app at `root`. */
+export declare function toolCacheDir(root: string, env?: NodeJS.ProcessEnv): string;
+/** Writes `last-run.json` and appends to `runs.jsonl`, keeping the last 100 runs. A disk error is no failure of the run. */
+export declare function writeRunLog(root: string, entry: RunEntry, env?: NodeJS.ProcessEnv): void;

package/cache/run-log.mjs

@@ -0,0 +1,37 @@
+// run-log.mts - the timings of a run. They change every run, so they are host state and stay out of git: `last-run.json` and `runs.jsonl`
+// (the last 100 runs) in the untracked tool cache of slot app.tool-cache,
+// `${STARCI_CACHE_HOME:-%LOCALAPPDATA%/StarCi/cache}/<repo>/app-check/`, where <repo> is the app folder's name and the first 12 hex digits of
+// the sha256 of its real path.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export const RUN_LOG_LIMIT = 100;
+/** The folder of the untracked tool cache for the app at `root`. */
+export function toolCacheDir(root, env = process.env) {
+    const home = env['STARCI_CACHE_HOME'] ?? (process.platform === 'win32' ? path.join(env['LOCALAPPDATA'] ?? path.join(os.homedir(), 'AppData', 'Local'), 'StarCi', 'cache') : path.join(env['XDG_CACHE_HOME'] ?? path.join(os.homedir(), '.cache'), 'starci'));
+    let real = path.resolve(root);
+    try {
+        real = fs.realpathSync(real);
+    }
+    catch { /* the given path names the app */ }
+    const id = `${path.basename(real)}-${createHash('sha256').update(real).digest('hex').slice(0, 12)}`;
+    return path.join(home, id, 'app-check');
+}
+/** Writes `last-run.json` and appends to `runs.jsonl`, keeping the last 100 runs. A disk error is no failure of the run. */
+export function writeRunLog(root, entry, env = process.env) {
+    try {
+        const dir = toolCacheDir(root, env);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'last-run.json'), `${JSON.stringify(entry, null, 2)}\n`);
+        const file = path.join(dir, 'runs.jsonl');
+        let lines = [];
+        try {
+            lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+        }
+        catch { /* the first run */ }
+        lines.push(JSON.stringify(entry));
+        fs.writeFileSync(file, `${lines.slice(-RUN_LOG_LIMIT).join('\n')}\n`);
+    }
+    catch { /* host state only */ }
+}

package/cache/run.d.mts

@@ -0,0 +1,33 @@
+import { type CheckFinding, type RepositoryResult } from '../runtime/scripts/hfs/check.mjs';
+import type { Presets } from '../sync/index.mjs';
+import type { Prettier } from '../sync/format.mjs';
+import { type CheckSession, type FamilyId, type FamilyReport } from './types.mjs';
+/** The families of a run with no selector, in the order they run. Families a work package adds register in `extraFamilies`. */
+export declare const DEFAULT_FAMILIES: readonly FamilyId[];
+export interface AppRunInput {
+    readonly repoRoot: string;
+    readonly tracked: readonly string[];
+    readonly session: CheckSession;
+    readonly selected: ReadonlySet<FamilyId>;
+    readonly harness?: {
+        version?: string;
+    } | undefined;
+    readonly presets?: Presets | undefined;
+    readonly prettier?: Prettier | undefined;
+    readonly edition?: string | undefined;
+    /** Limits the formatter to these app-relative files (`app lint --changed`). */
+    readonly only?: readonly string[] | undefined;
+    /** The ref the baseline database rules compare with, when the caller names one. */
+    readonly base?: string | undefined;
+}
+export interface AppRunResult extends RepositoryResult {
+    readonly families: readonly FamilyReport[];
+    /** The wiring proof, when the wiring family ran. */
+    wiring?: {
+        status: string;
+        apps: string[];
+        findings: CheckFinding[];
+    };
+}
+/** Runs the selected families against `session` and merges their findings. The caller flushes the session. */
+export declare function runAppFamilies(input: AppRunInput): Promise<AppRunResult>;

package/cache/run.mjs

@@ -0,0 +1,65 @@
+// run.mts - one `starci app check` / `starci app lint` pass over the selected families, against one session. It owns the order of the families,
+// the judging of their findings (edition and the Vietnamese why of every code) and the merge into the one result the verb prints and the gate
+// judges, so the two verbs never hold two answers for one tree.
+import { skillRoot } from '../runtime/engine/runtime-root.mjs';
+import { readWhy } from '../runtime/scripts/hfs/check.mjs';
+import { judgedFindings, summarize, withWhy } from '../runtime/scripts/hfs/check-results.mjs';
+import { loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
+import { runDbFamily } from './db-family.mjs';
+import { runFormatFamily } from './format-family.mjs';
+import { runStructurePass } from './hfs-family.mjs';
+import { runWiringFamily } from './wiring-family.mjs';
+import { FAMILIES } from './types.mjs';
+/** The families of a run with no selector, in the order they run. Families a work package adds register in `extraFamilies`. */
+export const DEFAULT_FAMILIES = FAMILIES.filter((family) => ['hfs', 'format', 'db', 'secrets', 'wiring', 'types', 'lint', 'test', 'sonar'].includes(family));
+const emptyResult = (repoRoot, tracked) => ({
+    ok: true, repoRoot, manifest: '', profile: null, apps: [], tracked, findings: [], counts: summarize([]),
+    machine: { status: 'skipped', reason: 'the structure family was not selected' },
+});
+/** Runs the selected families against `session` and merges their findings. The caller flushes the session. */
+export async function runAppFamilies(input) {
+    const { repoRoot, session, selected } = input;
+    const reports = [];
+    const track = (report) => void (report && reports.push(report));
+    const structure = selected.has('hfs') || selected.has('secrets');
+    const pass = structure
+        ? await runStructurePass(session, { repoRoot, harness: input.harness, presets: input.presets, tracked: input.tracked, hfs: selected.has('hfs'), secrets: selected.has('secrets') })
+        : null;
+    if (pass) {
+        track(pass.report);
+        track(pass.secretsReport);
+    }
+    const base = pass?.result ?? emptyResult(repoRoot, input.tracked.length);
+    const extra = [];
+    if (selected.has('format')) {
+        const formatted = await runFormatFamily(session, { files: input.only ?? input.tracked, prettier: input.prettier });
+        track(formatted.report);
+        extra.push(...formatted.findings);
+    }
+    if (selected.has('db')) {
+        const database = await runDbFamily(session, { repoRoot, tracked: input.tracked, base: input.base });
+        track(database.report);
+        extra.push(...database.findings);
+    }
+    let wiring;
+    if (selected.has('wiring')) {
+        const proved = await runWiringFamily(session, { repoRoot, edition: input.edition, files: input.tracked });
+        track(proved.report);
+        wiring = { status: proved.wiring.status, apps: proved.wiring.apps, findings: proved.wiring.findings };
+        extra.push(...proved.wiring.findings);
+    }
+    const edition = input.edition ?? declaredEdition(repoRoot);
+    const judged = extra.length === 0 ? [] : withWhy(judgedFindings(extra, edition, skillRoot), readWhy(skillRoot, [...new Set(extra.map((finding) => finding.code))]));
+    // A family's findings reach the result once: the pass already holds the ones the always-run rules produced.
+    const findings = [...base.findings, ...judged];
+    const counts = summarize(findings);
+    return { ...base, findings, counts, ok: counts.error === 0, families: reports, ...(wiring ? { wiring } : {}) };
+}
+function declaredEdition(repoRoot) {
+    try {
+        return readRepoDeclaration(loadSlotManifest(), repoRoot).edition ?? 'full';
+    }
+    catch {
+        return 'full';
+    }
+}

package/cache/session.d.mts

@@ -0,0 +1,29 @@
+import { type Fingerprint } from './fingerprint.mjs';
+import { type CacheVerdict, type TrustSource } from './trust.mjs';
+import { type CheckSession, type FamilyId, type FamilyReport, type ProgressSink } 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 declare const CACHE_ENV = "STARCI_APP_CHECK_CACHE";
+export interface DiskSessionOptions {
+    readonly root: string;
+    readonly tracked: readonly string[];
+    readonly env: NodeJS.ProcessEnv;
+    readonly progress: ProgressSink;
+    readonly cliVersion?: string | undefined;
+    /** The families `--full` selects. */
+    readonly full?: ReadonlySet<FamilyId> | undefined;
+    /** Seams for specs. */
+    readonly trust?: TrustSource | undefined;
+    readonly fingerprint?: Fingerprint | undefined;
+    readonly hfsDir?: string | undefined;
+}
+/** What the disk session adds to the contract: the fingerprint and trust it works under, and the CI verdicts. */
+export interface DiskSession extends CheckSession {
+    readonly fingerprint: Fingerprint;
+    readonly trust: TrustSource;
+    readonly reports: readonly FamilyReport[];
+    /** Whether this run may write the cache folder (a host run with a portable fingerprint that is not a forced-full release run). */
+    readonly writes: boolean;
+    /** In CI after `flush`: the committed cache compared with what the run inherited or computed. */
+    verdicts(): readonly CacheVerdict[];
+}
+export declare function createDiskSession(options: DiskSessionOptions): DiskSession;