@starci/hfs 4.12.0 → 4.13.0

package/cache/format-family.mjs

@@ -0,0 +1,49 @@
+// format-family.mts - `app check --format`: Prettier (HFS_FORMAT) over every tracked file, reused per file. A path whose content hash is
+// unchanged keeps its recorded verdict; changed and added paths are formatted again, in batches (sync/format.mts). The records are
+// `check/format/`, sparse: a clean file is a record with its hash and no finding.
+import { formatFindings, formattable, FORMAT } from '../sync/format.mjs';
+import { reconcile } from './jsonl.mjs';
+import { makeReport } from './report.mjs';
+export const FORMAT_FOLDER = 'check/format';
+const STEP = 'prettier';
+/** Area files of the format records: app-relative paths, so `fe/apps/web` is the third folder. */
+const FORMAT_DEPTH = 3;
+const asFinding = (found) => ({ path: found.path, line: 0, column: 0, rule: found.code, message: found.message });
+const fromFinding = (found) => ({ code: found.rule, level: 'error', path: found.path, message: found.message });
+/** Runs the format family against `session`: decides, formats what must be formatted, replaces the records, reports. */
+export async function runFormatFamily(session, { files, prettier }) {
+    const decision = session.decide('format');
+    const candidates = formattable(files).filter((file) => session.index.hashOf(file) !== undefined);
+    const previous = session.records(FORMAT_FOLDER);
+    const reusable = decision.mode === 'diff'
+        ? new Map(reconcile(previous.filter((record) => record.step === STEP), (file) => session.index.hashOf(file)).map((record) => [record.path, record]))
+        : new Map();
+    const todo = candidates.filter((file) => !reusable.has(file));
+    const step = session.progress.step('format', STEP, candidates.length);
+    step.tick(candidates.length - todo.length, candidates.length - todo.length, 0);
+    const judged = await formatFindings({
+        repoRoot: session.root, files: todo, prettier,
+        onProgress: (done) => step.tick(candidates.length - todo.length + done, candidates.length - todo.length, done),
+    });
+    step.end();
+    const byPath = new Map();
+    for (const found of judged)
+        byPath.set(found.path, [...(byPath.get(found.path) ?? []), found]);
+    const records = [];
+    for (const file of candidates) {
+        const kept = reusable.get(file);
+        if (kept !== undefined)
+            records.push(kept);
+        else
+            records.push({ path: file, step: STEP, hash: session.index.hashOf(file) ?? '', findings: (byPath.get(file) ?? []).map(asFinding) });
+    }
+    const findings = records.flatMap((record) => record.findings.map(fromFinding));
+    session.replace(FORMAT_FOLDER, records, { depth: FORMAT_DEPTH });
+    const report = makeReport({
+        family: 'format', mode: decision.mode, reason: decision.reason, checked: todo.length, reused: candidates.length - todo.length,
+        previous: previous.flatMap((record) => record.findings), current: records.flatMap((record) => record.findings),
+    });
+    session.report(report);
+    return { findings, report };
+}
+export { FORMAT };

package/cache/git.d.mts

@@ -0,0 +1,11 @@
+export interface GitAnswer {
+    readonly ok: boolean;
+    readonly stdout: string;
+}
+/** `git args` in `root`: ok only on a clean exit; stdout is text. */
+export declare function git(root: string, args: readonly string[], input?: string): GitAnswer;
+/** `git args` in `root` as raw bytes. */
+export declare function gitBytes(root: string, args: readonly string[], input?: string): {
+    ok: boolean;
+    stdout: Buffer;
+};

package/cache/git.mjs

@@ -0,0 +1,13 @@
+// git.mts - the few git questions the cache asks, through the runtime's one git owner (runtime/scripts/api/git/lib.mts).
+import { runGit } from '../runtime/scripts/api/git/lib.mjs';
+/** `git args` in `root`: ok only on a clean exit; stdout is text. */
+export function git(root, args, input) {
+    const run = runGit(args, { dir: root, maxBuffer: 256 * 1024 * 1024, ...(input === undefined ? {} : { input }) });
+    return { ok: !run.error && run.status === 0, stdout: run.stdout ?? '' };
+}
+/** `git args` in `root` as raw bytes. */
+export function gitBytes(root, args, input) {
+    const run = runGit(args, { dir: root, maxBuffer: 1024 * 1024 * 1024, encoding: 'buffer', ...(input === undefined ? {} : { input }) });
+    const out = run.stdout;
+    return { ok: !run.error && run.status === 0, stdout: Buffer.isBuffer(out) ? out : Buffer.from(String(out ?? '')) };
+}

package/cache/hash.d.mts

@@ -0,0 +1,15 @@
+/** Whether `bytes` is text by git's test: no NUL in the first 8000 bytes. */
+export declare function isText(bytes: Uint8Array): boolean;
+/** `bytes` with every CRLF turned into LF; a lone CR is kept. */
+export declare function normaliseNewlines(bytes: Uint8Array): Uint8Array;
+/** The sha256 (hex) of `bytes`, newline-normalised when they are text. */
+export declare function hashBytes(bytes: Uint8Array): string;
+/** The sha256 (hex) of a text, newline-normalised. */
+export declare function hashText(text: string): string;
+/** The hash of the file at `absolute`, or undefined when it cannot be read (absent, a directory, a race). */
+export declare function hashFile(absolute: string): string | undefined;
+/**
+ * One digest over named parts, order-independent and unambiguous: the parts are sorted by name and each contributes
+ * `name NUL hash NUL`, so no two different part sets share a digest by concatenation.
+ */
+export declare function combineHashes(parts: Readonly<Record<string, string>>): string;

package/cache/hash.mjs

@@ -0,0 +1,58 @@
+// hash.mts - content hashes of the cache. A hash is the sha256 of the bytes with CRLF turned into LF for text files, so a
+// Windows checkout and a Linux CI runner hash one commit alike. Text is git's own test: no NUL in the first 8000 bytes.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+const BINARY_PROBE = 8000;
+/** Whether `bytes` is text by git's test: no NUL in the first 8000 bytes. */
+export function isText(bytes) {
+    const end = Math.min(bytes.length, BINARY_PROBE);
+    for (let i = 0; i < end; i += 1)
+        if (bytes[i] === 0)
+            return false;
+    return true;
+}
+/** `bytes` with every CRLF turned into LF; a lone CR is kept. */
+export function normaliseNewlines(bytes) {
+    let crlf = 0;
+    for (let i = 0; i + 1 < bytes.length; i += 1)
+        if (bytes[i] === 0x0d && bytes[i + 1] === 0x0a)
+            crlf += 1;
+    if (crlf === 0)
+        return bytes;
+    const out = new Uint8Array(bytes.length - crlf);
+    let at = 0;
+    for (let i = 0; i < bytes.length; i += 1) {
+        if (bytes[i] === 0x0d && bytes[i + 1] === 0x0a)
+            continue;
+        out[at] = bytes[i] ?? 0;
+        at += 1;
+    }
+    return out;
+}
+/** The sha256 (hex) of `bytes`, newline-normalised when they are text. */
+export function hashBytes(bytes) {
+    return createHash('sha256').update(isText(bytes) ? normaliseNewlines(bytes) : bytes).digest('hex');
+}
+/** The sha256 (hex) of a text, newline-normalised. */
+export function hashText(text) {
+    return hashBytes(Buffer.from(text, 'utf8'));
+}
+/** The hash of the file at `absolute`, or undefined when it cannot be read (absent, a directory, a race). */
+export function hashFile(absolute) {
+    try {
+        return hashBytes(fs.readFileSync(absolute));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * One digest over named parts, order-independent and unambiguous: the parts are sorted by name and each contributes
+ * `name NUL hash NUL`, so no two different part sets share a digest by concatenation.
+ */
+export function combineHashes(parts) {
+    const h = createHash('sha256');
+    for (const name of Object.keys(parts).sort())
+        h.update(`${name}\0${parts[name] ?? ''}\0`);
+    return h.digest('hex');
+}

package/cache/hfs-family.d.mts

@@ -0,0 +1,35 @@
+import { type MachineFn, type RepositoryResult } from '../runtime/scripts/hfs/check.mjs';
+import type { Presets } from '../sync/index.mjs';
+import type { CheckSession, FamilyReport } from './types.mjs';
+export declare const HFS_FOLDER = "check/hfs";
+export declare const SECRETS_FOLDER = "check/secrets";
+/** The finding codes of the secrets family: plaintext secrets, sealed custody, untracked secret files. */
+export declare const SECRET_CODES: ReadonlySet<string>;
+/** What the structure pass answers. */
+export interface PassResult {
+    /** The whole-app check result of the pass (the shape `printCheck` reads), or the slot result when only secrets were asked for. */
+    readonly result: RepositoryResult;
+    readonly contracts: {
+        status: string;
+        reason?: string;
+        apps?: unknown[];
+    } | null;
+    readonly machineReused: Record<string, boolean>;
+    readonly report: FamilyReport | null;
+    readonly secretsReport: FamilyReport | null;
+}
+export interface PassInput {
+    readonly repoRoot: string;
+    readonly harness?: {
+        version?: string;
+    } | undefined;
+    readonly presets?: Presets | undefined;
+    readonly tracked?: readonly string[] | undefined;
+    /** Which families the run selected: the pass runs whole for hfs, light (slots and rules, no machine) for secrets alone. */
+    readonly hfs: boolean;
+    readonly secrets: boolean;
+    /** A seam for specs. */
+    readonly machine?: MachineFn | undefined;
+}
+/** The structure pass of `starci app check`, with the architecture machine and the contract emit reused by side key. */
+export declare function runStructurePass(session: CheckSession, input: PassInput): Promise<PassResult>;

package/cache/hfs-family.mjs

@@ -0,0 +1,164 @@
+// hfs-family.mts - the families that read the structure of the app: `--hfs` (slots, tree, pins, managed files against their templates, the content
+// rules of the app pass, the architecture machine's check surface, the contract emit) and `--secrets` (plaintext secrets, sealed custody, untracked
+// secret files, which the same pass finds). The cheap rules always run: they read untracked entries and git state the index does not hold. The
+// costly whole-program parts are scoped steps keyed on the side: the architecture machine per side, the contract emit on the back-end side.
+import path from 'node:path';
+import { checkRepo, checkRepository, trackedFiles } from '../runtime/scripts/hfs/check.mjs';
+import { checkArchitecture } from '../runtime/scripts/hfs/architecture/index.mjs';
+import { withoutBootProof } from '../runtime/scripts/hfs/rules/boot-proof.mjs';
+import { withUnusedSymbolMemo } from '../runtime/scripts/hfs/rules/unused-symbol.mjs';
+import { contractEmitFindings } from '../runtime/scripts/hfs/rules/contract.mjs';
+import { loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
+import { emitContracts } from '../emit/contracts.mjs';
+import { summarize } from '../runtime/scripts/hfs/check-results.mjs';
+import { managedFindings } from '../sync/managed.mjs';
+import { RecordSet, scopedStep } from './records.mjs';
+import { makeReport } from './report.mjs';
+import { sideKey } from './side-key.mjs';
+export const HFS_FOLDER = 'check/hfs';
+export const SECRETS_FOLDER = 'check/secrets';
+/** The finding codes of the secrets family: plaintext secrets, sealed custody, untracked secret files. */
+export const SECRET_CODES = new Set([
+    'HFS_PLAINTEXT_SECRET', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_LITE_SECRET_CUSTODY', 'HFS_IDENTITY_CUSTODY',
+    'HFS_AGE_KEY_CUSTODY', 'RT_SECRET_TRACKED', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'SEALED_CUSTODY_LOCATION',
+    'APP_SECRET_IN_CI', 'CI_SECRET_SEALED', 'BE_LOG_SECRET', 'BE_SECRET_DEFAULT', 'HFS_DOCKER_SECRETS',
+]);
+const compact = (finding) => ({
+    path: finding.path ?? '.', line: finding.line ?? 0, column: finding.column ?? 0, rule: finding.code, message: String(finding.message ?? ''),
+});
+/** The findings of a pass as records grouped by path, one per path, sparse. */
+function findingRecords(findings, hashOf, step) {
+    const byPath = new Map();
+    for (const finding of findings)
+        byPath.set(finding.path ?? '.', [...(byPath.get(finding.path ?? '.') ?? []), compact(finding)]);
+    return [...byPath].map(([file, list]) => ({ path: file, step, hash: hashOf(file) ?? 'absent', findings: list }));
+}
+const beDeclaration = (repoRoot) => {
+    try {
+        return readRepoDeclaration(loadSlotManifest(), repoRoot).sides?.be ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+/** The structure pass of `starci app check`, with the architecture machine and the contract emit reused by side key. */
+export async function runStructurePass(session, input) {
+    const { repoRoot, harness, presets } = input;
+    const tracked = [...(input.tracked ?? trackedFiles(repoRoot))];
+    const decision = session.decide('hfs');
+    const records = new RecordSet(session.records(HFS_FOLDER));
+    const previous = records.toArray();
+    const reuse = decision.mode === 'diff';
+    const sideOf = (side) => sideKey(repoRoot, session.index, side);
+    const keys = new Map(['be', 'fe'].map((side) => [side, sideOf(side)]));
+    const extra = [...await managedFindings({ repoRoot, tracked, presets })];
+    let checked = 0;
+    let reused = 0;
+    let contracts = null;
+    const be = beDeclaration(repoRoot);
+    if (input.hfs && be !== null) {
+        const bePrefix = 'be/';
+        const key = keys.get('be');
+        const emit = await scopedStep(session, records, {
+            path: 'be', step: 'contract-emit', key: key?.key ?? 'none', reuse, inputs: key?.inputs ?? [],
+            compute: () => {
+                const files = tracked.filter((file) => file.startsWith(bePrefix)).map((file) => file.slice(bePrefix.length));
+                const emitted = contractEmitFindings({ repoRoot: path.join(repoRoot, 'be'), files, repo: be, emit: emitContracts });
+                return JSON.parse(JSON.stringify({ findings: emitted.findings, apps: emitted.apps }));
+            },
+            compact: (value) => (value.findings).map(compact),
+        });
+        if (emit.reused)
+            reused += 1;
+        else
+            checked += 1;
+        const value = emit.value;
+        extra.push(...value.findings.map((finding) => ({ ...finding, side: 'be', path: `be/${finding.path}` })));
+        contracts = { status: 'checked', apps: value.apps };
+    }
+    const reasons = {};
+    const baseMachine = input.machine ?? checkArchitecture;
+    const cachedMachine = (call) => {
+        const side = path.basename(call.repositoryRoot);
+        const key = keys.get(side);
+        if (key === undefined || call.fast === true || call.paths !== undefined)
+            return baseMachine(call);
+        const held = reuse ? records.matching(side, 'machine', key.key) : undefined;
+        if (held?.data !== undefined) {
+            reasons[side] = true;
+            reused += 1;
+            return held.data;
+        }
+        const report = baseMachine(call);
+        checked += 1;
+        if (session.unchanged(key.inputs)) {
+            records.put({ path: side, step: 'machine', hash: key.key, findings: [...report.violations, ...report.errors].map((item) => ({ path: item.path ?? side, line: item.line ?? 0, column: item.column ?? 0, rule: item.ruleId, message: item.message })), data: JSON.parse(JSON.stringify(report)) });
+        }
+        return report;
+    };
+    // The whole-program unused-symbol analysis is the costliest rule of the pass (92 of 141 seconds on a 13.7k-file app): a scoped step keyed on the side.
+    const unusedMemo = {
+        run: (root, compute) => {
+            const side = path.basename(root);
+            const key = keys.get(side);
+            if (key === undefined)
+                return compute();
+            const held = reuse ? records.matching(side, 'unused-symbol', key.key) : undefined;
+            if (held?.data !== undefined) {
+                reused += 1;
+                return held.data;
+            }
+            const found = compute();
+            checked += 1;
+            if (session.unchanged(key.inputs)) {
+                const list = found;
+                records.put({ path: side, step: 'unused-symbol', hash: key.key, findings: list.map(compact), data: JSON.parse(JSON.stringify(found)) });
+            }
+            return found;
+        },
+    };
+    const step = session.progress.step('hfs', 'structure', tracked.length);
+    const result = input.hfs
+        ? withUnusedSymbolMemo(unusedMemo, () => withoutBootProof(() => checkRepository({ repoRoot, harness, extraFindings: extra, machine: cachedMachine })))
+        : (() => {
+            const slot = withUnusedSymbolMemo(unusedMemo, () => withoutBootProof(() => checkRepo({ repoRoot, harness, extraFindings: [], surface: 'check' })));
+            return { ...slot, machine: { status: 'skipped', reason: '--secrets alone runs the rules, not the machine' } };
+        })();
+    step.tick(tracked.length, reused, checked);
+    step.end();
+    if (contracts)
+        result.contracts = contracts;
+    if (!input.hfs) {
+        result.findings = result.findings.filter((finding) => SECRET_CODES.has(finding.code));
+        result.counts = summarize(result.findings);
+        result.ok = result.counts.error === 0;
+    }
+    if (input.hfs) {
+        const live = new Set(['be', 'fe']);
+        records.retain('machine', live);
+        records.retain('unused-symbol', live);
+        records.retain('contract-emit', new Set(['be']));
+        // The always-run rules still record their findings, so the next run can say what is new and what is known.
+        for (const record of findingRecords(result.findings.filter((finding) => !SECRET_CODES.has(finding.code)), session.index.hashOf.bind(session.index), 'hfs'))
+            records.put(record);
+        const seen = new Set(result.findings.map((finding) => finding.path ?? '.'));
+        records.retain('hfs', seen);
+        session.replace(HFS_FOLDER, records.toArray());
+    }
+    const hfsFindings = result.findings.filter((finding) => !SECRET_CODES.has(finding.code));
+    const report = input.hfs
+        ? makeReport({ family: 'hfs', mode: decision.mode, reason: decision.reason, checked, reused, previous: previous.flatMap((record) => record.step === 'hfs' ? record.findings : []), current: hfsFindings.map(compact) })
+        : null;
+    if (report)
+        session.report(report);
+    let secretsReport = null;
+    if (input.secrets) {
+        const secretDecision = session.decide('secrets');
+        const prior = session.records(SECRETS_FOLDER);
+        const secretFindings = result.findings.filter((finding) => SECRET_CODES.has(finding.code));
+        session.replace(SECRETS_FOLDER, findingRecords(secretFindings, session.index.hashOf.bind(session.index), 'secrets'));
+        secretsReport = makeReport({ family: 'secrets', mode: secretDecision.mode, reason: secretDecision.reason, checked: tracked.length, reused: 0, previous: prior.flatMap((record) => record.findings), current: secretFindings.map(compact) });
+        session.report(secretsReport);
+    }
+    return { result, contracts, machineReused: reasons, report, secretsReport };
+}

package/cache/import-graph.d.mts

@@ -0,0 +1,75 @@
+import type TypeScript from 'typescript';
+type Ts = typeof TypeScript;
+/** One file of the graph: its content hash, the side-relative posix paths of the local files it imports, and whether it declares globals. */
+export interface ImportNode {
+    hash: string;
+    imports: string[];
+    declaresGlobals: boolean;
+}
+/** The graph of a side: side-relative posix path to node. Leaves (a JSON file, a declaration file out of the lint scope) are nodes with no imports. */
+export type ImportGraph = ReadonlyMap<string, ImportNode>;
+/** What the graph builder reads of the world: the compiler of the app, file text and existence, and the content hash of a path. */
+export interface GraphHost {
+    ts: Ts;
+    /** The absolute folder of the side. */
+    sideRoot: string;
+    /** The text of an absolute file, or null when it cannot be read. */
+    readText: (file: string) => string | null;
+    fileExists: (file: string) => boolean;
+    directoryExists?: (directory: string) => boolean;
+    /** The content hash of a side-relative path the graph reaches (the scope's files and any resolved leaf), or null when it is not a file. */
+    hashOf: (relative: string) => string | null;
+}
+export declare const posix: (file: string) => string;
+/** The compiler options of the side's own tsconfig (the file the typed ESLint run reads), or the permissive defaults when the side holds none. */
+export declare function compilerOptionsOf(ts: Ts, sideRoot: string, readText: (file: string) => string | null, fileExists: (file: string) => boolean): TypeScript.CompilerOptions;
+/**
+ * Whether a source file declares globals: a script (a file with no import or export that has statements), a `declare global` block, or a module
+ * augmentation (`declare module 'x'` inside a module). A change to such a file can alter the types of any file of the side.
+ */
+export declare function declaresGlobals(ts: Ts, fileName: string, text: string): boolean;
+/**
+ * The module specifiers and path references a file's text names: static, type-only and dynamic imports, re-exports, `require`, import types and
+ * triple-slash paths. TypeScript's preprocessor finds most of them without a full parse; the syntax tree adds the forms it misses (a dynamic
+ * import of a plain template literal, an `import('x').T` type), so the graph holds every edge the compiler's program would.
+ */
+export declare function referencesOf(ts: Ts, text: string): {
+    specifiers: string[];
+    paths: string[];
+};
+/** The local files `file` (side-relative) imports, resolved with the side's compiler options. Unresolved and installed-package imports are not edges. */
+export declare function resolveImports(host: GraphHost, options: TypeScript.CompilerOptions, file: string, text: string): string[];
+/** What a build reports of its work. */
+export interface GraphBuild {
+    graph: Map<string, ImportNode>;
+    reused: number;
+    scanned: number;
+    resolvedAgain: boolean;
+}
+/**
+ * The import graph of `files` (the side's lint scope, side-relative posix) and the leaves they reach.
+ *
+ * A file whose recorded hash equals its hash now reuses its recorded imports, unless a path of the side was added or removed since the record:
+ * a new file can change where an unchanged import resolves, so every file is then resolved again. `pathsChanged` lets the caller report a change in
+ * the side's paths the scope does not list (a JSON file, a generated declaration).
+ */
+export declare function buildImportGraph(host: GraphHost, files: readonly string[], recorded: ImportGraph | null, options?: {
+    pathsChanged?: boolean;
+}): GraphBuild;
+/** Every path whose node differs between two graphs: added, removed, or with another hash. */
+export declare function changedPaths(previous: ImportGraph | null, next: ImportGraph): Set<string>;
+/** The files that reach any of `seeds` through imports in `graph` (the seeds themselves are not added unless a cycle reaches them). */
+export declare function dependentsOf(graph: ImportGraph, seeds: Iterable<string>): Set<string>;
+/** The dirty set of a side: what must be linted again, or the whole side with the reason. */
+export interface DirtySet {
+    dirty: Set<string>;
+    wholeSide: string | null;
+    changed: Set<string>;
+}
+/**
+ * The files to lint again after a change from `previous` (the recorded graph, null when none) to `next`: every changed path, and every file that
+ * reaches one through imports in either graph (a file that stopped importing a changed file still holds a result from the old types), and every
+ * file whose imports resolve to other files than recorded. A changed file that declares globals, now or before, dirties the whole side.
+ */
+export declare function dirtySetOf(previous: ImportGraph | null, next: ImportGraph): DirtySet;
+export {};

package/cache/import-graph.mjs

@@ -0,0 +1,204 @@
+// import-graph.mts - the resolved local import graph of one lint side, and the dirty set a change in it implies (check-cache.md, ESLint, kind 1).
+//
+// A type-aware rule's result on a file depends on the files whose types it reads, so ESLint's own per-file cache cannot be trusted. The cache records
+// for every file of a side its content hash and the local files it imports (TypeScript `preProcessFile` and `resolveModuleName` under the side's
+// tsconfig: static, type-only and dynamic imports, re-exports, `require`, triple-slash references, JSON). The dirty set of a change is every changed,
+// added or removed file and every file that reaches one through imports, in the new graph and in the recorded one. Everything here is pure over
+// its inputs (the compiler, a file reader, the hashes), so a spec drives it with fixtures and the cache itself stays in lint-family.mts.
+import path from 'node:path';
+export const posix = (file) => file.replace(/\\/g, '/').replace(/^\.\//, '');
+/** The compiler options of the side's own tsconfig (the file the typed ESLint run reads), or the permissive defaults when the side holds none. */
+export function compilerOptionsOf(ts, sideRoot, readText, fileExists) {
+    const configPath = path.join(sideRoot, 'tsconfig.json');
+    if (!fileExists(configPath))
+        return { allowJs: true, resolveJsonModule: true };
+    const read = ts.readConfigFile(configPath, (file) => readText(file) ?? undefined);
+    if (read.error || read.config === undefined)
+        return { allowJs: true, resolveJsonModule: true };
+    const host = {
+        useCaseSensitiveFileNames: true,
+        readDirectory: () => [],
+        fileExists,
+        readFile: (file) => readText(file) ?? undefined,
+    };
+    return { ...ts.parseJsonConfigFileContent(read.config, host, sideRoot).options, resolveJsonModule: true };
+}
+/**
+ * Whether a source file declares globals: a script (a file with no import or export that has statements), a `declare global` block, or a module
+ * augmentation (`declare module 'x'` inside a module). A change to such a file can alter the types of any file of the side.
+ */
+export function declaresGlobals(ts, fileName, text) {
+    const source = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, false);
+    let isModule = false;
+    let declaring = false;
+    for (const statement of source.statements) {
+        if (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement) || ts.isExportAssignment(statement))
+            isModule = true;
+        else if (ts.isImportEqualsDeclaration(statement) && ts.isExternalModuleReference(statement.moduleReference))
+            isModule = true;
+        else if (ts.canHaveModifiers(statement) && ts.getModifiers(statement)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword))
+            isModule = true;
+        else if (ts.isModuleDeclaration(statement) && (statement.flags & ts.NodeFlags.GlobalAugmentation) !== 0)
+            declaring = true;
+        else if (ts.isModuleDeclaration(statement) && ts.isStringLiteral(statement.name))
+            declaring = true;
+    }
+    if (isModule) {
+        // inside a module a `declare module 'x'` or `declare global` augments; a plain exported declaration does not
+        return source.statements.some((statement) => ts.isModuleDeclaration(statement) && ((statement.flags & ts.NodeFlags.GlobalAugmentation) !== 0 || ts.isStringLiteral(statement.name)));
+    }
+    return declaring || source.statements.length > 0;
+}
+/**
+ * The module specifiers and path references a file's text names: static, type-only and dynamic imports, re-exports, `require`, import types and
+ * triple-slash paths. TypeScript's preprocessor finds most of them without a full parse; the syntax tree adds the forms it misses (a dynamic
+ * import of a plain template literal, an `import('x').T` type), so the graph holds every edge the compiler's program would.
+ */
+export function referencesOf(ts, text) {
+    const info = ts.preProcessFile(text, true, true);
+    const found = new Set([...info.importedFiles.map((imported) => imported.fileName), ...info.typeReferenceDirectives.map((directive) => directive.fileName)]);
+    const source = ts.createSourceFile('references.ts', text, ts.ScriptTarget.Latest, false);
+    const literal = (node) => (node !== undefined && ts.isStringLiteralLike(node) ? node.text : null);
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(node.expression) && node.expression.text === 'require'))) {
+            const name = literal(node.arguments[0]);
+            if (name !== null)
+                found.add(name);
+        }
+        else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) {
+            const name = literal(node.argument.literal);
+            if (name !== null)
+                found.add(name);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return { specifiers: [...found], paths: info.referencedFiles.map((reference) => reference.fileName) };
+}
+/** The side-relative posix path of an absolute file below the side, or null when it lies outside it or in an installed package. */
+function localPath(sideRoot, absolute) {
+    const relative = posix(path.relative(sideRoot, absolute));
+    if (relative === '' || relative === '..' || relative.startsWith('../') || path.isAbsolute(relative))
+        return null;
+    return relative.split('/').includes('node_modules') ? null : relative;
+}
+/** The local files `file` (side-relative) imports, resolved with the side's compiler options. Unresolved and installed-package imports are not edges. */
+export function resolveImports(host, options, file, text) {
+    const { ts, sideRoot } = host;
+    const absolute = path.join(sideRoot, file);
+    const { specifiers, paths } = referencesOf(ts, text);
+    const moduleHost = {
+        fileExists: host.fileExists,
+        readFile: (name) => host.readText(name) ?? undefined,
+        directoryExists: host.directoryExists ?? (() => true),
+        getCurrentDirectory: () => sideRoot,
+    };
+    const found = new Set();
+    for (const specifier of specifiers) {
+        const resolved = ts.resolveModuleName(specifier, absolute, options, moduleHost).resolvedModule;
+        if (!resolved || resolved.isExternalLibraryImport)
+            continue;
+        const local = localPath(sideRoot, resolved.resolvedFileName);
+        if (local !== null && local !== file)
+            found.add(local);
+    }
+    for (const reference of paths) {
+        const local = localPath(sideRoot, path.resolve(path.dirname(absolute), reference));
+        if (local !== null && host.fileExists(path.join(sideRoot, local)))
+            found.add(local);
+    }
+    return [...found].sort();
+}
+/**
+ * The import graph of `files` (the side's lint scope, side-relative posix) and the leaves they reach.
+ *
+ * A file whose recorded hash equals its hash now reuses its recorded imports, unless a path of the side was added or removed since the record:
+ * a new file can change where an unchanged import resolves, so every file is then resolved again. `pathsChanged` lets the caller report a change in
+ * the side's paths the scope does not list (a JSON file, a generated declaration).
+ */
+export function buildImportGraph(host, files, recorded, options = {}) {
+    const compiler = compilerOptionsOf(host.ts, host.sideRoot, host.readText, host.fileExists);
+    const known = new Set(files);
+    const pathsChanged = options.pathsChanged === true || recorded === null || recorded.size === 0
+        || files.some((file) => !recorded.has(file))
+        || [...recorded.keys()].some((file) => !known.has(file) && host.hashOf(file) === null);
+    const graph = new Map();
+    let reused = 0, scanned = 0;
+    const visit = (file) => {
+        if (graph.has(file))
+            return;
+        const hash = host.hashOf(file);
+        if (hash === null)
+            return;
+        const before = recorded?.get(file);
+        if (!pathsChanged && before !== undefined && before.hash === hash) {
+            graph.set(file, before);
+            reused += 1;
+        }
+        else if (/\.(?:[cm]?[jt]sx?)$/.test(file)) {
+            const text = host.readText(path.join(host.sideRoot, file));
+            scanned += 1;
+            graph.set(file, text === null
+                ? { hash, imports: [], declaresGlobals: false }
+                : { hash, imports: resolveImports(host, compiler, file, text), declaresGlobals: declaresGlobals(host.ts, file, text) });
+        }
+        else
+            graph.set(file, { hash, imports: [], declaresGlobals: false });
+        for (const next of graph.get(file)?.imports ?? [])
+            visit(next);
+    };
+    for (const file of files)
+        visit(file);
+    return { graph, reused, scanned, resolvedAgain: pathsChanged };
+}
+/** Every path whose node differs between two graphs: added, removed, or with another hash. */
+export function changedPaths(previous, next) {
+    const changed = new Set();
+    for (const [file, node] of next)
+        if (previous?.get(file)?.hash !== node.hash)
+            changed.add(file);
+    for (const file of previous?.keys() ?? [])
+        if (!next.has(file))
+            changed.add(file);
+    return changed;
+}
+/** The files that reach any of `seeds` through imports in `graph` (the seeds themselves are not added unless a cycle reaches them). */
+export function dependentsOf(graph, seeds) {
+    const importers = new Map();
+    for (const [file, node] of graph)
+        for (const target of node.imports)
+            importers.set(target, [...(importers.get(target) ?? []), file]);
+    const reached = new Set();
+    const queue = [...seeds];
+    while (queue.length) {
+        for (const importer of importers.get(queue.pop()) ?? []) {
+            if (reached.has(importer))
+                continue;
+            reached.add(importer);
+            queue.push(importer);
+        }
+    }
+    return reached;
+}
+/**
+ * The files to lint again after a change from `previous` (the recorded graph, null when none) to `next`: every changed path, and every file that
+ * reaches one through imports in either graph (a file that stopped importing a changed file still holds a result from the old types), and every
+ * file whose imports resolve to other files than recorded. A changed file that declares globals, now or before, dirties the whole side.
+ */
+export function dirtySetOf(previous, next) {
+    const changed = changedPaths(previous, next);
+    if (previous === null)
+        return { dirty: new Set(next.keys()), wholeSide: 'no recorded import graph', changed };
+    for (const file of changed) {
+        if (next.get(file)?.declaresGlobals === true || previous.get(file)?.declaresGlobals === true) {
+            return { dirty: new Set(next.keys()), wholeSide: `${file} declares globals`, changed };
+        }
+    }
+    // a file whose imports resolve elsewhere now (a new file shadows a module, a missing one appeared) reads other types than before
+    const rewired = [...next].filter(([file, node]) => {
+        const before = previous.get(file);
+        return before !== undefined && before.hash === node.hash && JSON.stringify(before.imports) !== JSON.stringify(node.imports);
+    }).map(([file]) => file);
+    const dirty = new Set([...changed, ...rewired, ...dependentsOf(next, [...changed, ...rewired]), ...dependentsOf(previous, changed)]);
+    return { dirty, wholeSide: null, changed };
+}