@starci/hfs 4.12.2 → 4.13.2

package/coverage/cli.mjs

@@ -3,13 +3,18 @@
 // coverage proof, the Codecov upload and the Sonar import read. The merge is the app's installed @starci/jest-preset (`@starci/jest-preset/merge`):
 // istanbul-lib-coverage merges the shard maps by source location, and the preset's own lcov reporter writes the result exactly as an unsharded run
 // would. A path is a coverage-final.json or a directory searched for every one below it; no report found refuses (exit 2), never an empty report.
+// `--records <dir>` merges instead the committed per-spec records of the check cache (`.starcistacks/cache/test-coverage`): the union of what every spec covers,
+// which is the total of a full unit run, written as the same lcov.
 // `starci app coverage verify <lcov>`: the coverage proof alone (scripts/hfs/coverage-from.mjs, the judgement `starci app check --coverage-from`
 // adds to the whole check): every measured logic file is in the merged lcov at 100 per file. The managed CI's coverage job runs it after the merge,
 // so the job re-runs none of the rules the fast and lint jobs already judged. Exit 0 proved, 1 refused (the report lists every finding), 2 bad usage.
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import fs from 'node:fs';
 import { coverageFrom, formatCoverageReport } from '../runtime/scripts/hfs/coverage-from.mjs';
-export const USAGE = 'usage: starci app coverage merge --out <lcov> <coverage-final.json-or-dir>... [--cwd <dir>] | starci app coverage verify <lcov> [--cwd <dir>]';
+import { parseRecords } from '../cache/jsonl.mjs';
+import { SPEC_STEP, installedSpecMerge, sourcesOf } from '../cache/test-family.mjs';
+export const USAGE = 'usage: starci app coverage merge --out <lcov> (<coverage-final.json-or-dir>... | --records <test-coverage-dir>) [--cwd <dir>] | starci app coverage verify <lcov> [--cwd <dir>]';
 function parse(argv) {
     const [action, ...rest] = argv;
     if (action !== 'merge' && action !== 'verify')
@@ -17,7 +22,7 @@ function parse(argv) {
     const opts = { action, inputs: [] };
     for (let index = 0; index < rest.length; index += 1) {
         const arg = rest[index];
-        if (arg === '--out' || arg === '--cwd') {
+        if (arg === '--out' || arg === '--cwd' || arg === '--records') {
             const value = rest[index + 1];
             if (!value || value.startsWith('--'))
                 throw new Error(`${arg} needs a value; ${USAGE}`);
@@ -30,11 +35,11 @@ function parse(argv) {
             opts.inputs.push(arg);
     }
     if (action === 'verify') {
-        if (opts.out !== undefined || opts.inputs.length !== 1)
+        if (opts.out !== undefined || opts.records !== undefined || opts.inputs.length !== 1)
             throw new Error(USAGE);
         return opts;
     }
-    if (!opts.out || !opts.inputs.length)
+    if (!opts.out || (opts.records === undefined) === (opts.inputs.length === 0))
         throw new Error(USAGE);
     if (path.basename(opts.out) !== 'lcov.info')
         throw new Error(`--out names the lcov.info the coverage proof reads; ${USAGE}`);
@@ -49,6 +54,28 @@ function installedMerge(cwd) {
         throw new Error(`@starci/jest-preset/merge is not installed under ${cwd} (${error.code ?? error.message}); install the canon @starci/jest-preset`);
     }
 }
+/** Every `*.jsonl` file below `dir`, sorted: the area files of the check cache's `test-coverage` folder. */
+function recordFilesUnder(dir) {
+    return fs.readdirSync(dir, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.jsonl'))
+        .map((entry) => path.join(entry.parentPath, entry.name))
+        .sort();
+}
+/**
+ * The committed per-spec coverage records of `dir` (`.starcistacks/cache/test-coverage`) merged into the lcov at `out`: the union of what every spec covers, the total
+ * a full unit run reports. The lcov lists sources relative to the folder that holds `coverage/` (the side), the records carry them relative to the app.
+ */
+function mergeRecords(cwd, dir, out, merge) {
+    const absolute = path.resolve(cwd, dir);
+    if (!fs.existsSync(absolute) || !fs.statSync(absolute).isDirectory())
+        throw new Error(`no ${dir} folder: the check cache holds no unit coverage yet (run starci app check --test)`);
+    const records = recordFilesUnder(absolute).flatMap((file) => parseRecords(fs.readFileSync(file, 'utf8')).records).filter((record) => record.step === SPEC_STEP);
+    if (records.length === 0)
+        throw new Error(`no unit-spec record under ${dir}: the check cache holds no unit coverage yet (run starci app check --test)`);
+    const outDir = path.dirname(path.resolve(cwd, out));
+    merge(records.map(sourcesOf), { outDir, reportRoot: path.dirname(outDir), recordRoot: cwd });
+    return { specs: records.length };
+}
 /** The coverage proof of the app at `cwd` over the lcov `report`: exit 0 proved, 1 refused, 2 when the proof cannot run. */
 function verifyCoverage(cwd, report, { stdout, stderr, prove }) {
     try {
@@ -65,7 +92,7 @@ function verifyCoverage(cwd, report, { stdout, stderr, prove }) {
  * Exit 0 merged or proved, 1 a refused proof, 2 bad usage, no preset or no report found. `merge` replaces the installed preset merge and
  * `prove` the coverage proof in a spec.
  */
-export async function coverageMain(argv, { cwd: baseCwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), merge, prove = coverageFrom } = {}) {
+export async function coverageMain(argv, { cwd: baseCwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), merge, mergeSpecs, prove = coverageFrom } = {}) {
     let opts;
     try {
         opts = parse(argv);
@@ -77,6 +104,18 @@ export async function coverageMain(argv, { cwd: baseCwd = process.cwd(), stdout
     const cwd = path.resolve(baseCwd, opts.cwd ?? '.');
     if (opts.action === 'verify')
         return verifyCoverage(cwd, opts.inputs[0], { stdout, stderr, prove });
+    if (opts.records !== undefined) {
+        try {
+            const result = mergeRecords(cwd, opts.records, opts.out, mergeSpecs ?? installedSpecMerge(cwd));
+            stdout(`starci app coverage merge: ${result.specs} spec record(s) -> ${path.relative(cwd, path.resolve(cwd, opts.out)).replaceAll('\\', '/')}\n`);
+            return 0;
+        }
+        catch (error) {
+            stderr(`starci app coverage: ${error.message}
+`);
+            return 2;
+        }
+    }
     try {
         const run = merge ?? installedMerge(cwd);
         const outDir = path.dirname(path.resolve(cwd, opts.out));

package/db/migrate.d.mts

@@ -24,7 +24,15 @@ export interface DatabaseDecl {
     heldBack: string[];
     restamp: RestampPair[];
     postCutover: PostCutover | null;
+    /** Where the database runs: `stack` is a service of the environment's own stack (the deploy reaches it inside its container), `external` is outside it (the deploy keeps `--db-url-env`). */
+    target: DatabaseTarget;
+    /** The stack service of a `stack` database. */
+    service: string;
 }
+/** Where the database of an app runs (see DatabaseDecl.target). */
+export type DatabaseTarget = 'stack' | 'external';
+/** Which migrations a pass applies: all of them, the expand ones a deploy applies before the services update, or the contract ones it applies after accept. */
+export type MigrationPhase = 'all' | 'expand' | 'contract';
 /** An archived migration: its file name under the restamped version, and that version. */
 interface ArchiveRow {
     name: string;
@@ -70,6 +78,13 @@ interface MigrationPlan {
 export declare function loadDatabase(root: string): DatabaseDecl;
 /** Classifies the migration files of the app: baseline pair, held-back, forward, restamp pairs and archive. Refuses an inconsistent repository. */
 export declare function buildModel(root: string, decl: DatabaseDecl): MigrationModel;
+/** True for a contract migration, a file named `<stamp>_..contract_...sql` (BE-PERSISTENCE-19): destructive DDL that runs only after the release is accepted. */
+export declare const isContractMigration: (file: string) => boolean;
+/**
+ * The model one phase of a deploy works with. `expand` leaves the contract migrations out of the forward set (they are not pending yet, and a
+ * history that already holds them is still explained); `contract` keeps only them. The baseline stays in both: it was applied before.
+ */
+export declare function phaseModel(model: MigrationModel, phase: MigrationPhase): MigrationModel;
 /** The database of `--db-url-env` (default DATABASE_URL). */
 export declare const resolveTarget: (ctx: VerbContext, options?: {
     target?: DbTarget;
@@ -94,6 +109,7 @@ export declare function migrateDatabase(ctx: VerbContext, decl: DatabaseDecl, op
     execute?: boolean;
     urlEnv?: string | undefined;
     target?: DbTarget;
+    phase?: MigrationPhase;
 }): Promise<VerbResult>;
 /** The flags of `starci app db migrate`; the parser refuses every other. */
 export declare const SPEC: FlagSpec;

package/db/migrate.mjs

@@ -30,6 +30,7 @@ const matches = (pattern) => (value) => typeof value === 'string' && pattern.tes
 const listOf = (item) => (value) => Array.isArray(value) && value.every((entry) => item(entry));
 const dirOk = (value) => typeof value === 'string' && value.split('/').every((part) => SEGMENT.test(part) && part !== '..');
 const pairOk = (value) => plain(value) && Object.keys(value).length === 2 && matches(STAMP)(value.from) && matches(STAMP)(value.to);
+const SERVICE = /^[a-z][a-z0-9_-]*$/u;
 const POST_FIELDS = ['schema', 'functionPrefixes', 'functionNames', 'functions', 'minAgeHours'];
 const POST_CHECKS = {
     schema: matches(IDENT), functionPrefixes: listOf(matches(IDENT)), functionNames: listOf(matches(IDENT)),
@@ -44,8 +45,10 @@ const CHECKS = {
     heldBack: [listOf(matches(NAME)), 'must be a list of migration names'],
     restamp: [listOf(pairOk), 'must be a list of { from, to } fourteen-digit stamps'],
     postCutover: [postOk, `must use only ${POST_FIELDS.join(', ')} with valid values`],
+    target: [(value) => value === 'stack' || value === 'external', 'must be stack (a service of the environment stack) or external'],
+    service: [matches(SERVICE), `must match ${SERVICE} (the stack service that runs the database)`],
 };
-const DEFAULTS = Object.freeze({ migrationsDir: MIGRATIONS_DIR, archiveDir: null, baseline: null, standard: null, heldBack: [], restamp: [], postCutover: null });
+const DEFAULTS = Object.freeze({ migrationsDir: MIGRATIONS_DIR, archiveDir: null, baseline: null, standard: null, heldBack: [], restamp: [], postCutover: null, target: 'stack', service: 'db' });
 /** Judges the `database:` block. Returns { config } or { problems }; every field is optional (`standard` needs `baseline`). */
 function normalizeDatabase(block) {
     if (!plain(block))
@@ -136,6 +139,21 @@ export function buildModel(root, decl) {
     const base = baseline === null ? [] : [baseline];
     return { ...model, pushVersions: new Set([...base, ...model.pushPending]), allowed: new Set([...base, ...model.pushPending, ...model.heldVersions]) };
 }
+const fileOf = (model, version) => model.files.find((file) => file.startsWith(`${version}_`));
+/* ---- phases: expand before the services update, contract after accept */
+/** True for a contract migration, a file named `<stamp>_..contract_...sql` (BE-PERSISTENCE-19): destructive DDL that runs only after the release is accepted. */
+export const isContractMigration = (file) => /^\d{14}_(?:[A-Za-z0-9-]+_)?contract_[A-Za-z0-9_-]+\.sql$/u.test(file);
+/**
+ * The model one phase of a deploy works with. `expand` leaves the contract migrations out of the forward set (they are not pending yet, and a
+ * history that already holds them is still explained); `contract` keeps only them. The baseline stays in both: it was applied before.
+ */
+export function phaseModel(model, phase) {
+    if (phase === 'all')
+        return model;
+    const keep = (version) => isContractMigration(fileOf(model, version)) === (phase === 'contract');
+    const pushPending = model.pushPending.filter(keep);
+    return { ...model, pushPending, pushVersions: new Set([...(model.baseline === null ? [] : [model.baseline]), ...pushPending]) };
+}
 /* ---- the target */
 /** The database of `--db-url-env` (default DATABASE_URL). */
 export const resolveTarget = (ctx, options = {}) => options.target ?? dbTarget(ctx, options.urlEnv ?? DEFAULT_DB_URL_ENV);
@@ -176,7 +194,6 @@ export function planMigration(model, remote) {
     const bootstrap = remote.size === 0 && push.length > 0 && fs.existsSync(path.join(model.root, BOOTSTRAP_FILE));
     return { done, repairs, reverts, mark, push, bootstrap, missingFiles, unexpected: [...sim].filter((version) => !model.allowed.has(version)), final: sim.size };
 }
-const fileOf = (model, version) => model.files.find((file) => file.startsWith(`${version}_`));
 function planLines(model, session, remote, plan) {
     return [
         `target         ${session.target.how}`,
@@ -191,7 +208,7 @@ function planLines(model, session, remote, plan) {
 }
 const dataOf = (model, plan, remote, extra) => ({
     remoteCount: remote.size, repairs: plan.repairs.length, reverts: plan.reverts, baseline: model.baseline, markBaseline: plan.mark, push: plan.push,
-    heldBack: model.heldVersions, done: plan.done, ...extra,
+    heldBack: model.heldVersions, done: plan.done, pushFiles: plan.push.map((version) => fileOf(model, version)), ...extra,
 });
 /* ---- applying */
 /** Applies `versions` in order: each file and its history row in one transaction, so a failure leaves the history true. */
@@ -222,7 +239,7 @@ function applyPlan(session, plan) {
  * armed with STARCI_DB_ARMED=1 unless the database is on the loopback (the local db service of `npm run db:push`). Already baseline + forward: `nothing to do`, no mutating call, ok.
  */
 export async function migrateDatabase(ctx, decl, options = {}) {
-    const model = buildModel(ctx.cwd, decl);
+    const model = phaseModel(buildModel(ctx.cwd, decl), options.phase ?? 'all');
     const session = { ctx, model, target: resolveTarget(ctx, options) };
     const remote = listRemote(session);
     const plan = planMigration(model, remote);

package/db/postgres.d.mts

@@ -12,6 +12,8 @@ export interface DbTarget {
     env: Record<string, string>;
     secrets: string[];
     container?: string;
+    /** In-container only: the container holds its own credentials (its POSTGRES_PASSWORD_FILE), so no password travels from this machine. */
+    own?: boolean;
 }
 /** { url, password } of a postgres connection URL with the password removed, or null when `value` is not one. */
 export declare function parseConnection(value: string): {
@@ -32,6 +34,27 @@ export declare function dbTarget(ctx: VerbContext, name?: string): DbTarget & {
 export declare function inContainer(target: DbTarget, container: string): DbTarget & {
     container: string;
 };
+/** The shell an own-credentials client runs under: the password is read from the container's own secret file (the postgres image's POSTGRES_PASSWORD_FILE), so nothing about it crosses to the machine that runs docker. */
+export declare const OWN_PASSWORD_SHELL = "if [ -n \"${POSTGRES_PASSWORD_FILE:-}\" ] && [ -r \"$POSTGRES_PASSWORD_FILE\" ]; then PGPASSWORD=$(cat \"$POSTGRES_PASSWORD_FILE\"); export PGPASSWORD; fi; exec \"$@\"";
+/** The role and database names a container is allowed to answer with (they reach a connection URL and a remote script). */
+export declare const DB_IDENT: RegExp;
+/**
+ * The role and database of the running container `container`: the ones the image was started with (POSTGRES_USER, default postgres;
+ * POSTGRES_DB, default the role). Names only, never a secret.
+ */
+export declare function containerIdentity(ctx: VerbContext, container: string): {
+    role: string;
+    database: string;
+};
+/**
+ * The database of the running container `container` reached with the credentials that container holds: its own role and database on its own
+ * loopback, the password read inside the container from its POSTGRES_PASSWORD_FILE. A CI job that reaches the Docker daemon holds no database
+ * URL and no password: the deploy's migrate, emptiness proof and first start go through this target.
+ */
+export declare function ownContainerTarget(ctx: VerbContext, container: string): DbTarget & {
+    container: string;
+    own: true;
+};
 /** Runs a PostgreSQL client tool against `target`; a failure names the first stderr line with every secret scrubbed (or withholds it). */
 export declare function pgTool(ctx: VerbContext, target: DbTarget, command: string, args: readonly string[], { withhold, code }?: {
     withhold?: boolean;

package/db/postgres.mjs

@@ -52,7 +52,36 @@ export function inContainer(target, container) {
     url.hostname = '127.0.0.1';
     return { ...target, how: `${target.how}, inside container ${container.slice(0, 12)}`, url: url.toString(), container };
 }
-/** Runs `command` of an in-container target: copies each `-f` file in, then execs the tool through the stdin-password shell. */
+/** The shell an own-credentials client runs under: the password is read from the container's own secret file (the postgres image's POSTGRES_PASSWORD_FILE), so nothing about it crosses to the machine that runs docker. */
+export const OWN_PASSWORD_SHELL = 'if [ -n "${POSTGRES_PASSWORD_FILE:-}" ] && [ -r "$POSTGRES_PASSWORD_FILE" ]; then PGPASSWORD=$(cat "$POSTGRES_PASSWORD_FILE"); export PGPASSWORD; fi; exec "$@"';
+/** The role and database names a container is allowed to answer with (they reach a connection URL and a remote script). */
+export const DB_IDENT = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/u;
+/** What the container is asked: its role and database, one per line. */
+const IDENTITY_SCRIPT = 'printf "%s\\n%s\\n" "${POSTGRES_USER:-postgres}" "${POSTGRES_DB:-${POSTGRES_USER:-postgres}}"';
+/**
+ * The role and database of the running container `container`: the ones the image was started with (POSTGRES_USER, default postgres;
+ * POSTGRES_DB, default the role). Names only, never a secret.
+ */
+export function containerIdentity(ctx, container) {
+    const short = container.slice(0, 12);
+    const run = tool(ctx, 'docker', ['exec', container, 'sh', '-c', IDENTITY_SCRIPT]);
+    if (run.error || run.status !== 0)
+        throw failure('DB_CLI_FAILED', `cannot read the role and database of container ${short}: ${firstLine(run.stderr)}`);
+    const [role, database] = String(run.stdout ?? '').split(/\r?\n/u);
+    if (!role || !database || !DB_IDENT.test(role) || !DB_IDENT.test(database))
+        throw failure('DB_CLI_FAILED', `container ${short} names a role or database that is not a plain identifier`);
+    return { role, database };
+}
+/**
+ * The database of the running container `container` reached with the credentials that container holds: its own role and database on its own
+ * loopback, the password read inside the container from its POSTGRES_PASSWORD_FILE. A CI job that reaches the Docker daemon holds no database
+ * URL and no password: the deploy's migrate, emptiness proof and first start go through this target.
+ */
+export function ownContainerTarget(ctx, container) {
+    const { role, database } = containerIdentity(ctx, container);
+    return { kind: 'url', how: `the database credentials held inside container ${container.slice(0, 12)}`, url: `postgresql://${role}@127.0.0.1:5432/${database}`, env: {}, secrets: [], container, own: true };
+}
+/** Runs `command` of an in-container target: copies each `-f` file in, then execs the tool through the password shell. */
 function containerRun(ctx, target, command, args) {
     const short = target.container.slice(0, 12);
     const step = (what, run) => {
@@ -67,6 +96,8 @@ function containerRun(ctx, target, command, args) {
         step(`docker cp of ${path.basename(arg)}`, tool(ctx, 'docker', ['cp', arg, `${target.container}:${copied}`]));
         return copied;
     });
+    if (target.own)
+        return tool(ctx, 'docker', ['exec', target.container, 'sh', '-c', OWN_PASSWORD_SHELL, 'sh', command, ...inside]);
     return tool(ctx, 'docker', ['exec', '-i', target.container, 'sh', '-c', STDIN_PASSWORD, 'sh', command, ...inside], { input: `${target.env.PGPASSWORD ?? ''}\n` });
 }
 /** Runs a PostgreSQL client tool against `target`; a failure names the first stderr line with every secret scrubbed (or withholds it). */

package/lint/run.d.mts

@@ -1,3 +1,5 @@
+import { type CanonDeclarations, type LintSideStats } from '../cache/lint-family.mjs';
+import type { CheckSession } from '../cache/types.mjs';
 type Dynamic = any;
 /** The parsed arguments of the lint verb. */
 export interface LintOptions {
@@ -7,6 +9,11 @@ export interface LintOptions {
     out: string | undefined;
     workspace: string | undefined;
     side?: string;
+    full?: boolean;
+}
+/** The cache a lint run may use: the session of the check cache. The caller flushes it after the run. */
+export interface LintCache {
+    session: CheckSession;
 }
 /** What a linter run answers: its json results, or why it could not complete (both when the run was partial). */
 export interface LinterRun {
@@ -101,16 +108,55 @@ export declare function eslintRepository({ repoRoot, app, opts, changed, existin
         }>;
     };
 }>;
+/** What the cache reads of the canons a side lints with: the ESLint canon (which publishes the project-graph rules) and the grammar family of the fe side. */
+export declare function canonDeclarations({ repoRoot, cwd, side }: {
+    repoRoot: string;
+    cwd: string;
+    side: string;
+}): Promise<CanonDeclarations[]>;
+/**
+ * What the size-growth rules compare an over-budget file with: the merge-base of HEAD with the base branch (STARCI_BASE_REF, origin/main, then
+ * main), the same lookup the rules make. The cache keys the files those rules read history for on it, so a base that moved judges them again.
+ */
+export declare function gitBaseToken(repoRoot: string): string;
+/** What the cached linters answer: the ESLint answer in the shape of eslintRepository's, the stylelint results, and each side's counts. */
+export interface CachedLinters {
+    eslint: Awaited<ReturnType<typeof eslintRepository>>;
+    stylelint: {
+        results: Dynamic[];
+        errors: string[];
+        ran: boolean;
+    };
+    sides: {
+        side: string;
+        stats: LintSideStats;
+    }[];
+}
+/**
+ * ESLint and stylelint through the result cache: per side, the files the records cannot vouch for go to the very launcher, chunking and result
+ * validation of a full run (eslintRepository), the rest take their records. The answer has the shape of eslintRepository's, plus the stylelint
+ * results, so the lint report is built the same way from either.
+ */
+export declare function cachedLinters({ repoRoot, app, opts, workspace, onFe, run, cache }: {
+    repoRoot: string;
+    app: RepoDeclaration;
+    opts: LintOptions;
+    workspace: string | null;
+    onFe: string | null;
+    run?: LinterRunner | undefined;
+    cache: LintCache;
+}): Promise<CachedLinters>;
 /**
  * Run the whole lint of the app at `repoRoot`. `hfsCheck(repoRoot)` returns the `starci app check` result (`{ findings, tracked }`); the CLI
  * injects it. Returns `{ report, sonar, exit }`; `sonar` is the merged Generic Issue Import document.
  */
-export declare function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles, runLinter: linter }: {
+export declare function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles, runLinter: linter, cache }: {
     repoRoot: string;
     opts: LintOptions;
     hfsCheck: (repoRoot: string) => Dynamic;
     trackedFiles?: (repoRoot: string) => string[];
     runLinter?: LinterRunner | undefined;
+    cache?: LintCache | undefined;
 }): Promise<{
     report: Dynamic;
     sonar: Dynamic;

package/lint/run.mjs

@@ -8,7 +8,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 // starci app lint - the ONE lint entry and the ONE report of a StarCi app.
 //
-//   starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--json] [--out <file>]
+//   starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--full] [--json] [--out <file>]
 //
 // It runs at the app root (the folder of hfs.json), over the app (or over the app-relative files named by --changed):
 //   1. ESLint once per side, from the side folder, through the app's own install and that side's eslint.config.mjs (be/ the be canon,
@@ -23,6 +23,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // --workspace scopes the same lint to one npm workspace of the fe side (fe/apps/<app> or fe/packages/<pkg>, app-relative): ESLint and
 // stylelint over that folder only, and of the app findings only those inside it. It is the `lint` script of every fe workspace (the
 // turbo `lint` task); the root `npm run lint` stays the whole app. There is no second linter: a workspace lint is this lint, scoped.
+// The result cache (contexts/project/check-cache.md): when the caller hands lintRepository a cache session, ESLint and stylelint judge only what
+// the records of `.starcistacks/cache/lint/<side>/` cannot vouch for (cache/lint-family.mjs) - the same records and fingerprint `app check --lint`
+// uses, so the two verbs never hold two answers. `--side` reads and writes its side's records, `--workspace` reads and writes none, `--changed`
+// and `--fix` bypass the cache, and `--full` judges everything again and rewrites the records.
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
@@ -37,6 +41,8 @@ import { byCodeUnit } from '../report/order.mjs';
 import { braceVariants, globExpression } from '../runtime/scripts/lib/glob.mjs';
 import { grammarLintFor } from '../runtime/scripts/lib/grammar-lint.mjs';
 import { gateVerdict } from '../runtime/scripts/hfs/gate-threshold.mjs';
+import { mergeBase } from '../runtime/scripts/api/git/merge-base.mjs';
+import { lintFamilyReport, lintSide, loadAppTypeScript } from '../cache/lint-family.mjs';
 // --side judges only that side; root HFS findings belong to be, its Sonar report stays on that side.
 export const LINT_SCHEMA = 'starci/lint@1';
 /** The side whose stylesheets stylelint judges. */
@@ -82,6 +88,8 @@ export function parseLintArgs(argv) {
         }
         else if (arg === '--fix')
             opts.fix = true;
+        else if (arg === '--full')
+            opts.full = true;
         else if (arg === '--json')
             opts.format = 'json';
         else if (['--out', '--workspace', '--side'].includes(arg)) {
@@ -408,6 +416,140 @@ export async function eslintRepository({ repoRoot, app = readRepoDeclaration(loa
     });
     return { findings, errors, raw, engine };
 }
+// ------------------------------------------------------------------------------------------------ the cached lint
+/** A `crossFileInputs` export that has the shape the cache reads, or null (an installed canon without it, or with a broken one, is linted whole). */
+function declaredInputs(value) {
+    if (!Array.isArray(value))
+        return null;
+    const sound = value.every((entry) => entry && typeof entry.rule === 'string' && (entry.kind === 'content' || entry.kind === 'exists' || entry.kind === 'git') && (entry.relativeTo === 'file' || entry.relativeTo === 'side')
+        && Array.isArray(entry.globs) && entry.globs.every((glob) => typeof glob === 'string') && Array.isArray(entry.appliesTo) && entry.appliesTo.every((glob) => typeof glob === 'string'));
+    return sound ? value : null;
+}
+const declarationOf = (name, installed, graphRules) => ({
+    name, crossFileInputs: declaredInputs(installed?.crossFileInputs), graphRules, projectGraph: graphRules && typeof installed?.projectGraph === 'function' ? installed.projectGraph : null,
+});
+/** What the cache reads of the canons a side lints with: the ESLint canon (which publishes the project-graph rules) and the grammar family of the fe side. */
+export async function canonDeclarations({ repoRoot, cwd, side }) {
+    const name = `@starci/eslint-canon-${side}`;
+    const canon = await import(__rewriteRelativeImportExtension(pathToFileURL(ownCanonEntry({ repoRoot, cwd }, name)).href));
+    const declarations = [declarationOf(name, canon, true)];
+    if (side !== 'fe')
+        return declarations;
+    const family = grammarLintFor(canon.loadHfs(pathToFileURL(path.join(cwd, 'eslint.config.mjs')).href).grammar);
+    if (family.package !== null)
+        declarations.push(declarationOf(family.package, await import(__rewriteRelativeImportExtension(pathToFileURL(ownCanonEntry({ repoRoot, cwd }, family.package)).href)), false));
+    return declarations;
+}
+/** The stylelint canon's declaration; one that cannot be imported has none, so every stylesheet is judged. */
+async function styleDeclaration({ repoRoot, cwd }) {
+    const name = '@starci/stylelint-canon';
+    try {
+        return declarationOf(name, await import(__rewriteRelativeImportExtension(pathToFileURL(ownCanonEntry({ repoRoot, cwd }, name)).href)), false);
+    }
+    catch {
+        return declarationOf(name, null, false);
+    }
+}
+/** The stylesheets of the fe side (sync STYLE_GLOB), side-relative, from the disk. */
+function stylesheetsOf(cwd) {
+    const patterns = braceVariants(STYLE_GLOB).map(globExpression);
+    const found = [];
+    const visit = (folder) => {
+        let children;
+        try {
+            children = fs.readdirSync(path.join(cwd, folder), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const child of children) {
+            if (child.name === 'node_modules' || child.name.startsWith('.git'))
+                continue;
+            const file = posix(path.join(folder, child.name));
+            if (child.isDirectory())
+                visit(file);
+            else if (child.isFile() && patterns.some((pattern) => pattern.test(file)))
+                found.push(file);
+        }
+    };
+    for (const container of ['apps', 'packages'])
+        visit(container);
+    return found.sort(byCodeUnit);
+}
+/**
+ * What the size-growth rules compare an over-budget file with: the merge-base of HEAD with the base branch (STARCI_BASE_REF, origin/main, then
+ * main), the same lookup the rules make. The cache keys the files those rules read history for on it, so a base that moved judges them again.
+ */
+export function gitBaseToken(repoRoot) {
+    const named = process.env['STARCI_BASE_REF'];
+    for (const ref of named ? [named] : ['origin/main', 'main']) {
+        const sha = mergeBase(repoRoot, 'HEAD', ref);
+        if (sha)
+            return sha;
+    }
+    return 'no-base';
+}
+/**
+ * ESLint and stylelint through the result cache: per side, the files the records cannot vouch for go to the very launcher, chunking and result
+ * validation of a full run (eslintRepository), the rest take their records. The answer has the shape of eslintRepository's, plus the stylelint
+ * results, so the lint report is built the same way from either.
+ */
+export async function cachedLinters({ repoRoot, app, opts, workspace, onFe, run, cache }) {
+    const eslint = { findings: [], errors: [], raw: [], engine: { sides: {} } };
+    const style = { results: [], errors: [], ran: false };
+    const sides = [];
+    const decision = cache.session.decide('lint');
+    const full = opts.full === true ? '--full' : decision.mode === 'full' ? decision.reason : null;
+    const gitToken = gitBaseToken(repoRoot);
+    for (const side of SIDES.filter((candidate) => opts.side === undefined || opts.side === candidate)) {
+        if (workspace !== null && side !== STYLE_SIDE) {
+            eslint.engine.sides[side] = { files: 0, skipped: `outside --workspace ${workspace}` };
+            continue;
+        }
+        const cwd = path.join(repoRoot, side);
+        let scope, canons;
+        try {
+            scope = await sourceFiles({ repoRoot, cwd, side, scope: null });
+            canons = await canonDeclarations({ repoRoot, cwd, side });
+        }
+        catch (error) {
+            eslint.errors.push(`eslint source scope is unavailable in ${side}/: ${String(error?.message ?? error)}`);
+            eslint.engine.sides[side] = { files: 0 };
+            continue;
+        }
+        const styled = side === STYLE_SIDE;
+        const outcome = await lintSide({
+            session: cache.session, side, sideRoot: cwd, scope, stylesheets: styled ? stylesheetsOf(cwd) : [],
+            report: onFe === null ? null : (file) => file.startsWith(`${onFe}/`),
+            canons, styleCanon: styled ? await styleDeclaration({ repoRoot, cwd }) : null, typescript: () => loadAppTypeScript(cwd), extraKey: '', gitToken, full, write: workspace === null,
+            eslint: async (files) => {
+                const listed = files === null ? null : files.map((file) => `${side}/${file}`);
+                const sub = await eslintRepository({ repoRoot, app, opts: { side }, changed: listed, existing: listed ?? [], workspace: listed === null ? workspace : null, onFe: listed === null ? onFe : null, run });
+                return { results: sub.raw, errors: sub.errors };
+            },
+            stylelint: styled ? async (files) => {
+                const linted = await runLinter({ cwd, pkg: 'stylelint', bin: 'stylelint', args: [...(files ?? [onFe ? `${onFe}/src/**/*.css` : STYLE_GLOB]), '--formatter', 'json'] });
+                const appRelative = appRelativeMessages(STYLE_SIDE, cwd);
+                for (const result of linted.results ?? [])
+                    for (const warning of result.warnings ?? [])
+                        warning.text = appRelative(warning.text);
+                return { results: (linted.results ?? []), errors: linted.error ? [linted.error] : [] };
+            } : null,
+        });
+        sides.push({ side, stats: outcome.stats });
+        for (const message of outcome.errors)
+            (message.startsWith('stylelint ') ? style.errors : eslint.errors).push(message);
+        eslint.raw.push(...outcome.eslint);
+        eslint.findings.push(...eslintFindings(outcome.eslint, repoRoot));
+        eslint.engine.sides[side] = { files: outcome.eslint.length };
+        if (styled) {
+            style.results.push(...outcome.stylelint);
+            style.ran = true;
+        }
+    }
+    cache.session.report(lintFamilyReport(sides));
+    return { eslint, stylelint: style, sides };
+}
 /** Starts stylelint over the fe stylesheets (the running child), or returns null when no stylesheet is in scope. */
 function launchStylelint({ repoRoot, opts, changed, existing, onFe }) {
     if (opts.side === 'be')
@@ -421,7 +563,7 @@ function launchStylelint({ repoRoot, opts, changed, existing, onFe }) {
  * Run the whole lint of the app at `repoRoot`. `hfsCheck(repoRoot)` returns the `starci app check` result (`{ findings, tracked }`); the CLI
  * injects it. Returns `{ report, sonar, exit }`; `sonar` is the merged Generic Issue Import document.
  */
-export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles = () => [], runLinter: linter }) {
+export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles = () => [], runLinter: linter, cache }) {
     const changed = opts.changed === null ? null : new Set(opts.changed);
     const errors = [];
     let workspace = null;
@@ -467,8 +609,11 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
     /** The workspace folder relative to the fe side folder (apps/<app> or packages/<pkg>). */
     const onFe = workspace === null ? null : workspace.slice(STYLE_SIDE.length + 1);
     // The linters and the app check are independent: every child starts first, the app check runs while they work, and the results are read in a fixed order.
-    const eslintRun = app ? eslintRepository({ app, repoRoot, opts, changed: changed ? [...changed] : null, existing, workspace, onFe, run: linter }) : null;
-    const styleLaunch = app ? launchStylelint({ repoRoot, opts, changed, existing, onFe }) : null;
+    // The cache serves a whole-side lint only: --changed judges named files and --fix rewrites them, so neither reads nor writes a record.
+    const cached = cache !== undefined && changed === null && !opts.fix ? cache : null;
+    const cachedRun = app && cached ? cachedLinters({ app, repoRoot, opts, workspace, onFe, run: linter, cache: cached }) : null;
+    const eslintRun = app ? (cachedRun ? cachedRun.then((answer) => answer.eslint) : eslintRepository({ app, repoRoot, opts, changed: changed ? [...changed] : null, existing, workspace, onFe, run: linter })) : null;
+    const styleLaunch = app && !cachedRun ? launchStylelint({ repoRoot, opts, changed, existing, onFe }) : null;
     const checkRun = app ? Promise.resolve().then(() => hfsCheck(repoRoot)).then((value) => ({ value, error: undefined }), (error) => ({ value: undefined, error })) : null;
     // 1. ESLint, once per side, from the side folder with that side's config.
     const eslint = eslintRun ? await eslintRun : { engine: { sides: {} }, errors: [], raw: [], findings: [] };
@@ -478,7 +623,14 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
     findings.push(...eslint.findings);
     // 3. stylelint over the fe side's stylesheets.
     if (app) {
-        if (styleLaunch) {
+        if (cachedRun) {
+            const answer = (await cachedRun).stylelint;
+            errors.push(...answer.errors);
+            if (answer.ran)
+                raw.stylelint = answer.results;
+            findings.push(...stylelintFindings(answer.results, repoRoot));
+        }
+        else if (styleLaunch) {
             const linted = await styleLaunch;
             if (linted.error)
                 errors.push(linted.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.12.2",
+  "version": "4.13.2",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",
@@ -63,6 +63,7 @@
     "release/**",
     "db/**",
     "ci/**",
+    "cache/**",
     "coverage/**",
     "codemod/**",
     "lint/**",

package/release/gate.d.mts

@@ -64,6 +64,8 @@ export declare const RELEASE_CODE = "RELEASE_CONFIG_INVALID";
 /** The note a release that does not wait for CI carries in its L4 record and its push output (owner ruling release-require-ci-per-project). */
 export declare const CI_NOT_REQUIRED = "CI not required by release.requireCi=false (owner ruling release-require-ci-per-project): the local release gate, this L4 record and the annotated tag, is the release proof";
 export declare const VERSION: RegExp;
+/** A release judges in full and never reads the committed check cache (contexts/project/check-cache.md): every gate row, the urgent back-fill included, runs with this set. */
+export declare const RELEASE_CACHE_ENV: Readonly<Record<string, string>>;
 /** True for a branch or remote name git can take as one argument (no leading dash, only path-like characters). */
 export declare const refName: (value: unknown) => value is string;
 /** Judges the optional `release:` block. Absence is fine (defaults). Returns { config } or { problems }. */

package/release/gate.mjs

@@ -32,6 +32,8 @@ const THRESHOLD_MISS = /coverage threshold .* not met/gu;
 const WRAPPED = new Set(['npm', 'npx']);
 // Every row the managed CI runs, so a release that does not wait for its candidate CI (release.requireCi false) still ran them all locally:
 // fast (audit, format, typecheck), lint, test + coverage (the managed `test` script is the per-file 100 threshold), build, the lite database lint, and Sonar.
+/** A release judges in full and never reads the committed check cache (contexts/project/check-cache.md): every gate row, the urgent back-fill included, runs with this set. */
+export const RELEASE_CACHE_ENV = Object.freeze({ STARCI_APP_CHECK_CACHE: 'full' });
 const SCRIPT_GATES = ['format:check', 'typecheck', 'build:be', 'lint', 'db:lint', 'build:fe', 'test'];
 // A full app has a test world (integration, e2e and contract projects, always present: the managed `test:e2e` script marks it), so those layers are rows of its gate;
 // a lite app's integration project exists only where it has integration specs, so it has no world rows.
@@ -270,7 +272,7 @@ export async function runAvailableGate(ctx, gate, options) {
             return runGate(ctx, gate, options);
         // The scanner imports the app's declared external issues report: produce it first with the app's own lint, as the managed CI does.
         const started = ctx.now();
-        const lint = produceLintReports(ctx, { launch, platform: options.platform, env: withoutCredentials(ctx.env, options.credentialNames) });
+        const lint = produceLintReports(ctx, { launch, platform: options.platform, env: { ...withoutCredentials(ctx.env, options.credentialNames), ...RELEASE_CACHE_ENV } });
         if (lint.pass)
             return judgeQualityGate(ctx, gate, runGate(ctx, gate, { ...options, preface: lint.text }));
         fs.writeFileSync(log, lint.text);
@@ -303,7 +305,7 @@ export function runGate(ctx, gate, { dir, platform, credentialNames, preface = '
     const started = ctx.now();
     const [command, args] = launch(gate.command, platform);
     // The native scanner alone consumes Sonar credentials; ordinary gates cannot inherit or reintroduce them.
-    const env = { ...ctx.env, ...(gate.provider ? gate.env : withoutCredentials(gate.env, credentialNames)) };
+    const env = { ...ctx.env, ...(gate.provider ? gate.env : withoutCredentials(gate.env, credentialNames)), ...RELEASE_CACHE_ENV };
     const run = tool(ctx, command, args, { cwd: ctx.cwd, env });
     const output = `${run.stdout ?? ''}${run.stderr ?? ''}`;
     const text = gate.name === 'sonar' && gate.env.SONAR_TOKEN ? output.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]') : output;