@starci/hfs 5.0.7 → 5.1.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 5.1.0
+
+- Added: `starci app codemod explicit-surface` writes the inferred type of every export the classifier counts as open (R368): return types, variable, parameter and property types, from the app's own TypeScript program. It prefers a named type the program exports, writes `ReactElement` for components and Next's `Metadata` for `generateMetadata`, adds merged type-only imports after a directive prologue, compiles the result beside the original and writes a file only when it gains no diagnostic, and reports (with a suggested fix) destructured exports and anonymous, computed, too long, `any`, unnameable and predicate types. Prettier of the app formats what is written.
+- Added: `starci app codemod directive-first` moves a `"use client"` or `"use server"` below another statement, or in the form `("use client")`, to the first statement of its module (R369).
+- Changed: the test-world declaration (R47, R89) is read in its typed form, `const world: TestWorldApi = defineTestWorld({ ... })` with `useTestWorld` and `useSandbox` exported typed from it, as well as in the destructured form; the template writes the typed form, and a config with neither is still refused.
+- Added: `template-surface.spec.mts` holds every TypeScript template to R368 and R369 (the front-end units are judged through their generators).
+- Changed: the scaffold templates write the type of every export (R368): Nest module definitions export each `ConfigurableModuleHost` member with its type, hooks name their result interface, async pages and layouts return `Promise<ReactElement>`, redux, zustand, next-intl and Apollo exports are typed, SQL texts are `SqlText`, entity and migration lists are `DatabaseConnectionOptions` members. A new app scaffolds clean under `explicit-export-surface`.
+- Added: `runtime/scripts/lib/declaration-surface.mjs`, the one classifier of a TypeScript file's exported type surface (the isolated declaration emit and the exports it cannot write without inference, with the JSX-only component exemption), and `runtime/scripts/hfs/explicit-surface-rule.mjs`, the factory of the `explicit-export-surface` rule both lint canons build (R368). The app-check ESLint cache reads the same classifier for `open`, so the rule reports exactly the files the cache counts as open.
+- Changed: the ESLint child of the cached lint hands its project-graph snapshot out. The list runner (`lint/eslint-list.cjs`, now also the runner of a whole-side run, as the list `.`) asks each installed canon for `projectGraphSnapshot` after the lint and writes the findings beside its results; `lintSide` writes the `graph` records from them and builds the graph itself only for a canon the child did not answer for. A whole-side lint no longer builds the project graph a second time in the CLI process.
+
+## 5.0.8
+
+- Removed: the `starci app lint` verb. `starci app check` is the one verb for app quality and carries what the lint verb carried: `--side be|fe` limits the lint gate to one side (reading and writing that side's cache records), `--out <file>` writes the merged Sonar Generic Issue Import document of the run (the findings of the selected gates under `starci-hfs`, then ESLint and stylelint), and `--fix` runs ESLint and stylelint with `--fix` before the check (with `--gate lint`). There is no `--changed` and no `--workspace`: the cache makes a whole-app check of an unchanged tree take seconds. The rendered `lint` and `lint:fix` scripts, the managed CI lint step and the release gate's Sonar row call `app check --gate lint`, and rule R13 requires that form.
+- Changed: usage is printed only for a usage error (`UsageError`), not for a failed check.
+- Fixed: the `small-renames` codemod keeps `size="control"` on a bar control instead of rewriting it to `lg`.
+- Changed: the structure pass keeps its work in the committed cache. A side key carries the hash it took of each input, so a stable untracked input (generated code) no longer discards the record of a scoped step, and `CheckSession.unchanged(paths, captured?)` compares an input with that hash. The per-file content rules (plaintext secrets, bypass markers, soft file size) are kept by the file's hash, the cross-file finders by the read set they recorded, and `--gate secrets` reuses the same per-file records, so a warm run judges nothing and a run after an edit judges that file. The whole-program records of a side with untracked program inputs are kept.
+- Changed: The app-check ESLint cache dirties a file only when the type surface it reads can have changed. Each file records the digest of its isolated declaration emit and whether that surface is open (inferred from other files); a body-only edit lints that file alone, a changed signature its direct importers, an inferred type one more level at a time. A file that only names the types of others (a re-export, an imported type in a signature) and a component that returns only JSX carry a change of those types, never an edit of their bodies. Records without a surface are read as changed.
+- Fixed: A file edited while the ESLint of a side ran loses only its own cache records instead of the records of the whole side.
+- Changed: The files of a diff lint go to ONE ESLint child through a job file read by a small runner (`lint/eslint-list.cjs`) on the ESLint API of the side's install, instead of several chunked command lines that each built the TypeScript program again. The heavy-node request carries the number of files it judges (`files`).
+- Changed: The import graph of the app-check lint cache remembers the files and folders it probes while resolving imports, and the launcher takes the side's scope from the cache instead of enumerating it again; the graph of a large side builds in a sixth of the time.
+
 ## 5.0.7
 
 - Changed: Refresh aligned canonical package pins.

package/README.md

@@ -16,9 +16,8 @@ starci app add overlay <name> --kind modal|drawer [--form] [--app <fe app>] [--c
 starci app add service <dir> <name> [--inject <binding>...] [--cwd <dir>]
 starci app add spec <file>.service.ts [--cwd <dir>]
 starci app add image [--cwd <dir>]
-starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--fix] [--json] [--out <sonar file>]
 starci app sync [--execute] [--cwd <dir>]
-starci app check [--cwd <dir>] [--gate <hfs|format|db|secrets|wiring|types|lint|test|sonar|codecov> ...] [--no-cache] [--json] [--coverage-from <lcov>] [--quiet]
+starci app check [--cwd <dir>] [--gate <hfs|format|db|secrets|wiring|types|lint|test|sonar|codecov> ...] [--side be|fe] [--fix] [--out <sonar file>] [--no-cache] [--json] [--coverage-from <lcov>] [--quiet]
 starci app check --staged [--cwd <dir>]
 starci app upgrade [--execute]
 starci app world <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--cwd <dir>]
@@ -166,7 +165,7 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 | `HFS_UNTRACKED_ROOT_ENTRY` | error | an entry git neither tracks nor ignores (`git ls-files -o --exclude-standard`), outside an `ignored` slot |
 | `HFS_PLAINTEXT_SECRET` | error | a tracked plaintext secret: an env, key or credentials file, a value the push scan refuses (never printed), or an `.enc` that is no sops envelope (R06) |
 | `HFS_STACKS_SHAPE` | error | a `.starcistacks` path outside the standard shape (a sealed file outside `<env>/secrets/`, `runtime/files/`, root `DESIGN.md` or `k8s/`), a local Sonar not owned by the host, a service still rooted at `.stacks` (R10) |
-| `HFS_CI_MISSING_CANON` | error | `ci.yml` without a `run:` step of `starci app lint` (`npm run lint`, or `npx --no-install starci app lint`, the app's pinned copy) (R13) |
+| `HFS_CI_MISSING_CANON` | error | `ci.yml` without a `run:` step of `starci app check --gate lint` (`npm run lint`, or `npx --no-install starci app check --gate lint`, the app's pinned copy) (R13) |
 | `HFS_DEP_VERSION_SKEW` | error | a dependency at two specs across the root and workspace `package.json` files, a dependency declared at another version than the root `overrides` pin, or a nested copy of a declared dependency in `package-lock.json` (R14) |
 | `HFS_CONTRACT_SNAPSHOT_DRIFT` | error | a back-end api app serving GraphQL without `be/contracts/<app>/schema.graphql` (R23); the front end reads that snapshot in place, so there is no copy to drift |
 | `BE_TEST_TOPOLOGY` | error | a `*.test.*` file, a `testing/` folder, a second jest configuration or a `jest` key in `package.json` (R47; `int-spec`, `harness-spec`, the retired test folders and a per-lane test config are the machine's, under the same code) |
@@ -182,7 +181,7 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 | `BE_ASYNC_SPEC_MISSING` | error | a consumed event no e2e spec through `useTestWorld` names, or a saga step whose spec does not also name the compensated event (R167) |
 | `BE_INTEGRATION_SPEC_MISSING` | error | an integration (`src/modules/integrations/<provider>/` with `<provider>.config.ts`) without a `src/tests/integration/<provider>/*.integration-spec.ts` that registers its module through `useTestWorld({ modules })`, references its ErrorCode enum and drives an outage through the world (R112) |
 | `HFS_MONO_WORKSPACES` | error | the app root `package.json` without `workspaces` exactly `["fe/apps/*", "fe/packages/*"]`, `packageManager` `npm@<version>` or a `turbo` devDependency (R143) |
-| `HFS_MONO_FE_WORKSPACE` | error | an fe app `package.json` not named `@<project>/<app>`, not private, or without exactly the workspace scripts; an fe package without `build`, `typecheck` and the workspace `lint` (R144) |
+| `HFS_MONO_FE_WORKSPACE` | error | an fe app `package.json` not named `@<project>/<app>`, not private, or without exactly the workspace scripts; an fe package without `build` and `typecheck`; a workspace with a `lint` script (R144) |
 | `HFS_MONO_NEST_PROJECTS` | error | `be/nest-cli.json` not `monorepo: true`, its default project not an api app, or its `projects` not exactly the declared be apps (R145) |
 | `HFS_MONO_WORKSPACE_DEP` | error | an fe workspace imports a package its own `package.json` does not declare, or the root `package.json` declares a workspace package (R146) |
 | `BE_CLI_REQUIRED` | error | a back end with a connection or a command under `src/features/cli/` and no cli app `be/apps/cli`, a cli app of another name, or no `be/apps/cli/Dockerfile` (R147) |
@@ -200,7 +199,7 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 The managed files are judged by `sync/managed.mjs` and `sync/ts-strict.mjs` (the package renders the templates; the runtime copy does not). The list of managed
 files is the `managedBy` slots of `slots.yaml`; `starci app sync --execute` renders them and `starci app check` compares them, so a hand edit and a forgotten `sync` are the same finding.
 Each finding is reported once: the managed ESLint and stylelint factory configs under R17, `tsconfig.json` under R22 when it names a flag, a workflow or hook that lost a canon step under R13 (or R19 for the format step), everything else under R05.
-The root and both sides are rendered by the one mechanism. The root: the `scripts` block of `app.package-manifest` (`dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `lint`, `lint:fix`, `test`, `test:integration`, `test:e2e`, `test:contract`, `test:world`, `codegen`, `contract:emit`, `migrate`, `typecheck`, ...; a be script runs from `be/`, where its tsconfig and jest configuration are), `app.format-config`, `app.hooks`, the CI slots (`app.ci`, `app.ci-e2e`, `app.ci-images`), `app.quality-config` and the managed block of `app.git-meta`. A side: its `be.tool-config` or `fe.tool-config` slot — the side's tsconfig (resolving `@starci/tsconfig` from the root `node_modules`) and its managed ESLint factory config, the back end's build tsconfig, tests tsconfig and jest configuration, the front end's stylelint configuration. `lint` is the one lint gate, `starci app lint`: ESLint over each side with its canon, the app check and stylelint over fe; `lint:fix` is the same with `--fix`. The front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool or test script under `fe/`. `turbo.json` stays the app's own
+The root and both sides are rendered by the one mechanism. The root: the `scripts` block of `app.package-manifest` (`dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `lint`, `lint:fix`, `test`, `test:integration`, `test:e2e`, `test:contract`, `test:world`, `codegen`, `contract:emit`, `migrate`, `typecheck`, ...; a be script runs from `be/`, where its tsconfig and jest configuration are), `app.format-config`, `app.hooks`, the CI slots (`app.ci`, `app.ci-e2e`, `app.ci-images`), `app.quality-config` and the managed block of `app.git-meta`. A side: its `be.tool-config` or `fe.tool-config` slot — the side's tsconfig (resolving `@starci/tsconfig` from the root `node_modules`) and its managed ESLint factory config, the back end's build tsconfig, tests tsconfig and jest configuration, the front end's stylelint configuration. `lint` is `starci app check --gate lint`: ESLint over each side with its canon and stylelint over fe; `lint:fix` is the same with `--fix`. The front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool or test script under `fe/`. `turbo.json` stays the app's own
 (slot `app.task-graph`): it carries the task graph, which no preset can render.
 
 The architecture machine (`scripts/hfs/architecture.mjs` of the runtime, the same code bundled here): tiers and import
@@ -218,7 +217,7 @@ Predictions remain diagnostics; actual Sonar CI/release checks and Codecov CI up
 findings n new, n known, n fixed`. Progress goes to stderr (`--quiet` silences it). `STARCI_APP_CHECK_CACHE=verify` runs diff then full and exits 2 on any difference;
 `STARCI_APP_CHECK_CACHE=full` never reads the cache (the release gate).
 
-Exit codes: 0 clean, 1 an error finding, 2 a tool could not run or a refusal (not a Git work tree, bad flag). `starci app check` and `starci app lint` write only `.starcistacks/cache/` (and `starci app lint --fix` lets ESLint and stylelint fix in place).
+Exit codes: 0 clean, 1 an error finding, 2 a tool could not run or a refusal (not a Git work tree, bad flag). `starci app check` writes only `.starcistacks/cache/` (and `--out`'s file; `--fix` lets ESLint and stylelint fix in place).
 
 ## Secrets
 
@@ -267,7 +266,7 @@ Analysis never creates a project, replaces its history or rotates a token. OIDC
 One mechanism for both sides: every finding of the canon is imported into Sonar, and the quality gate
 fails while any is open. Nothing is configured per app; the pieces are managed files (`starci app sync`) and this package.
 
-One entry, one report, one file: `npm run lint` is `starci app lint`; `npm run lint -- --out reports/lint.sonar.json` writes the ONE Sonar file, read through `sonar.externalIssuesReportPaths`. It carries three engines: `starci-hfs` (the repository findings, rule id = the finding code), `eslint` (the BE canon, universal FE canon and selected Grammar-family plugin, rule id = the ESLint rule) and `stylelint` over fe (rule id = the stylelint rule). App lint shares app check's ESLint runner and calls its HFS checks in process, so each side's ESLint config runs once. `starci app lint --format json` prints the same findings as the one report `starci/lint@1` (`{ schema, ok, changed, counts.error, engines, errors[], findings[{ engine, rule, code, severity, path, line, column, message }] }`); `--changed <files...>` restricts ESLint and stylelint to those files and keeps of the repository findings the ones on a listed file or on no file. The exit code is 0 clean, 1 findings, 2 a tool could not run (a missing ESLint install is never a pass).
+One entry, one report, one file: `npm run lint` is `starci app check --gate lint`; `starci app check --gate lint --out reports/lint.sonar.json` writes the ONE Sonar file, read through `sonar.externalIssuesReportPaths`. It carries three engines: `starci-hfs` (the repository findings, rule id = the finding code), `eslint` (the BE canon, universal FE canon and selected Grammar-family plugin, rule id = the ESLint rule) and `stylelint` over fe (rule id = the stylelint rule). The lint gate runs each side's ESLint config once, through the cache; `--side be|fe` limits it to one side, `--fix` runs ESLint and stylelint with `--fix` first (refused without `--gate lint`), and the findings the other gates selected join the same document. The exit code is 0 clean, 1 findings, 2 a tool could not run (a missing ESLint install is never a pass).
 
 `--out` writes the findings as a Generic Issue Import document (SonarQube 10.3+ format: `{ rules, issues }`) before the verdict, so a
 failing lint still leaves its report. A rule's name and description are the catalog's English title and Vietnamese title, meaning and next step;
@@ -278,7 +277,7 @@ Sonar's own ESLint import (`sonar.eslint.reportPaths`) is not used: it drops tho
 
 The managed `sonar-project.properties` carries `sonar.externalIssuesReportPaths` (`reports/lint.sonar.json` only) and no `sonar.host.url` (the host is
 `SONAR_HOST_URL`); the managed CI workflow produces the report and runs the scan and the gate action with `!cancelled()`, so a failed lint step still
-reaches Sonar while the job stays failed. There is no `continue-on-error`. CI runs `npm run lint -- --out reports/lint.sonar.json` once at the app root, before the scan. The duplicate-block threshold (`ruleParams.<side>.duplicateBlock`) has no Sonar property for TypeScript (SonarJS detects
+reaches Sonar while the job stays failed. There is no `continue-on-error`. CI runs `starci app check --gate lint --side <side> --out reports/lint.<side>.sonar.json` per side and merges the reports into `reports/lint.sonar.json`, before the scan. The duplicate-block threshold (`ruleParams.<side>.duplicateBlock`) has no Sonar property for TypeScript (SonarJS detects
 clones with its own token rule), so the machine enforces it (R21) and its findings are imported like every other.
 
 The gate is `knowledge/sonar-gate.yaml`, the one declaration: the new-code conditions (coverage 100, duplication, issues of every severity, hotspots) and an `overall` part (coverage 100, 0 open issues on the whole code,

package/cache/fake-session.mjs

@@ -44,7 +44,7 @@ export function createFakeSession(options = {}) {
         decide: () => decision,
         records: (folder) => replaced.get(folder) ?? stored.get(folder) ?? [],
         replace: (folder, records) => void replaced.set(folder, records),
-        unchanged: (paths) => paths.every((file) => index.hashOf(file) === initial.get(file)),
+        unchanged: (paths, captured) => paths.every((file) => (captured?.[file] === undefined ? index.hashOf(file) === initial.get(file) : (index.hashOf(file) ?? 'absent') === captured[file])),
         report: (report) => void reports.push(report),
         progress,
         setFile: (path, text) => index.set(path, text),

package/cache/hfs-family.mjs

@@ -12,7 +12,9 @@ import { loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/hfs/sl
 import { emitContractsAsync } from '../emit/contracts.mjs';
 import { summarize } from '../runtime/scripts/hfs/check-results.mjs';
 import { managedFindings } from '../sync/managed.mjs';
+import { withRuleMemo } from '../runtime/scripts/hfs/rule-memo.mjs';
 import { RecordSet, scopedStep } from './records.mjs';
+import { FILE_RULES_STEP, RULE_STEP_PREFIX, UNIT_STEP_PREFIX, createStructureMemo } from './structure-memo.mjs';
 import { makeReport } from './report.mjs';
 import { sideKey } from './side-key.mjs';
 export const HFS_FOLDER = 'check/hfs';
@@ -45,10 +47,12 @@ const beDeclaration = (repoRoot) => {
 export async function runStructurePass(session, input) {
     const { repoRoot, harness, presets } = input;
     const tracked = [...(input.tracked ?? trackedFiles(repoRoot))];
-    const decision = session.decide('hfs');
+    const decision = session.decide(input.hfs ? 'hfs' : 'secrets');
     const records = new RecordSet(session.records(HFS_FOLDER));
     const previous = records.toArray();
     const reuse = decision.mode === 'diff';
+    // The per-file and cross-file content rules are shared by both families: a record is read only when every selected family runs diff.
+    const structure = createStructureMemo({ session, records, reuse: reuse && (!input.hfs || !input.secrets || session.decide('secrets').mode === 'diff'), root: repoRoot, tracked });
     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 })];
@@ -60,7 +64,7 @@ export async function runStructurePass(session, input) {
         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 ?? [],
+            path: 'be', step: 'contract-emit', key: key?.key ?? 'none', reuse, inputs: key?.inputs ?? [], captured: key?.hashes ?? {},
             compute: async () => {
                 const files = tracked.filter((file) => file.startsWith(bePrefix)).map((file) => file.slice(bePrefix.length));
                 const emitted = await contractEmitFindingsAsync({ repoRoot: path.join(repoRoot, 'be'), files, repo: be, emit: (request) => emitContractsAsync({ ...request, execute: input.execute }) });
@@ -91,7 +95,7 @@ export async function runStructurePass(session, input) {
         }
         const report = baseMachine(call);
         checked += 1;
-        if (session.unchanged(key.inputs)) {
+        if (session.unchanged(key.inputs, key.hashes)) {
             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;
@@ -110,7 +114,7 @@ export async function runStructurePass(session, input) {
             }
             const found = compute();
             checked += 1;
-            if (session.unchanged(key.inputs)) {
+            if (session.unchanged(key.inputs, key.hashes)) {
                 const list = found;
                 records.put({ path: side, step: 'unused-symbol', hash: key.key, findings: list.map(compact), data: JSON.parse(JSON.stringify(found)) });
             }
@@ -118,13 +122,15 @@ export async function runStructurePass(session, input) {
         },
     };
     const step = session.progress.step('hfs', 'structure', tracked.length);
-    const result = input.hfs
+    const result = withRuleMemo(structure.memo, () => (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);
+        })()));
+    const filesChecked = structure.counts.filesChecked, filesReused = structure.counts.filesReused;
+    const keyedChecked = structure.counts.keyedChecked + structure.counts.unitsChecked, keyedReused = structure.counts.keyedReused + structure.counts.unitsReused;
+    step.tick(tracked.length, reused + filesReused + keyedReused, checked + filesChecked + keyedChecked);
     step.end();
     if (contracts)
         result.contracts = contracts;
@@ -133,6 +139,13 @@ export async function runStructurePass(session, input) {
         result.counts = summarize(result.findings);
         result.ok = result.counts.error === 0;
     }
+    records.retain(FILE_RULES_STEP, structure.files);
+    records.retainPrefix(RULE_STEP_PREFIX, new Set(['.', 'be', 'fe']));
+    for (const [step, paths] of structure.units)
+        records.retain(step, paths);
+    records.dropPrefixExcept(UNIT_STEP_PREFIX, new Set(structure.units.keys()));
+    if (!input.hfs)
+        session.replace(HFS_FOLDER, records.toArray());
     if (input.hfs) {
         const live = new Set(['be', 'fe']);
         records.retain('machine', live);
@@ -147,7 +160,7 @@ export async function runStructurePass(session, input) {
     }
     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) })
+        ? makeReport({ family: 'hfs', mode: decision.mode, reason: decision.reason, checked: checked + filesChecked + keyedChecked, reused: reused + filesReused + keyedReused, previous: previous.flatMap((record) => record.step === 'hfs' ? record.findings : []), current: hfsFindings.map(compact) })
         : null;
     if (report)
         session.report(report);
@@ -157,7 +170,7 @@ export async function runStructurePass(session, input) {
         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) });
+        secretsReport = makeReport({ family: 'secrets', mode: secretDecision.mode, reason: secretDecision.reason, checked: filesChecked, reused: filesReused, 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

@@ -1,10 +1,21 @@
 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. */
+/**
+ * One file of the graph: its content hash, the side-relative posix paths of the local files it imports, and whether it declares globals.
+ *
+ * `api` is the digest of the file's type surface, the text of TypeScript's isolated declaration emit (a source that is not TypeScript, or a
+ * declaration file, stands for itself: its content hash). `open` says the surface is inferred: the emit reported a diagnostic (a type the compiler
+ * has to infer from the bodies and the files they use), so it can change while the emit text does not. `refs` is the local files the emit names (a
+ * type imported from them, a re-export): an explicit surface is its emit text plus the surfaces of those files, nothing else. An absent `api`,
+ * `open` or `refs` (a record from before they existed) is read as "changed", "inferred" and "unknown".
+ */
 export interface ImportNode {
     hash: string;
     imports: string[];
     declaresGlobals: boolean;
+    api?: string | undefined;
+    open?: boolean | undefined;
+    refs?: string[] | undefined;
 }
 /** 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>;
@@ -39,6 +50,17 @@ export declare function referencesOf(ts: Ts, text: 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[];
+/**
+ * The type surface of one source file: the digest of its isolated declaration emit (`ts.transpileDeclaration`, TypeScript 5.5 and later, which reads the
+ * file alone) and whether it is open. A body-only edit leaves the emit, and so the digest, as it was; a changed signature, export list or doc comment
+ * (`@deprecated` is read by lint rules) changes it. A compiler without `transpileDeclaration` gives no digest, which every reader takes as changed.
+ * `open` is true when the emit reported a diagnostic (the compiler must infer a type); `refs` is the local files the emit names.
+ */
+export declare function surfaceOf(host: GraphHost, options: TypeScript.CompilerOptions, file: string, text: string): {
+    api: string | undefined;
+    open: boolean;
+    refs: string[] | undefined;
+};
 /** What a build reports of its work. */
 export interface GraphBuild {
     graph: Map<string, ImportNode>;
@@ -67,9 +89,15 @@ export interface DirtySet {
     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.
+ * The files to lint again after a change from `previous` (the recorded graph, null when none) to `next`.
+ *
+ * A file is dirty when it changed, was added or removed, resolves its imports to other files than recorded, or imports a file whose type surface
+ * changed, in the new graph or the recorded one (a file that stopped importing such a file still holds a result from the old types). A dirty file's
+ * surface changed when it was added or removed, gained an import, its surface digest differs from the record (or either is unknown), its surface
+ * is inferred (`open`: whatever dirtied it can have changed the inferred type), or its explicit surface names a file (`refs`) whose surface changed.
+ * An explicit surface is its emit text and the surfaces of the files it names, so a body-only edit of such a file dirties that file alone, a
+ * changed signature its direct importers, and a type it re-exports or names carries on through the files that name it. 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

@@ -6,6 +6,8 @@
 // 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';
+import { DECLARATION, SCRIPT, TYPESCRIPT, declarationSurface } from '../runtime/scripts/lib/declaration-surface.mjs';
+import { hashText } from './hash.mjs';
 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) {
@@ -82,6 +84,16 @@ function localPath(sideRoot, absolute) {
         return null;
     return relative.split('/').includes('node_modules') ? null : relative;
 }
+/** The resolution cache of one compiler-options object: a side's thousands of files share the directory lookups of their (mostly package) imports. */
+const resolutionCaches = new WeakMap();
+const resolutionCacheOf = (ts, sideRoot, options) => {
+    let cache = resolutionCaches.get(options);
+    if (cache === undefined) {
+        cache = ts.createModuleResolutionCache(sideRoot, (name) => name, options);
+        resolutionCaches.set(options, cache);
+    }
+    return cache;
+};
 /** 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;
@@ -95,7 +107,7 @@ export function resolveImports(host, options, file, text) {
     };
     const found = new Set();
     for (const specifier of specifiers) {
-        const resolved = ts.resolveModuleName(specifier, absolute, options, moduleHost).resolvedModule;
+        const resolved = ts.resolveModuleName(specifier, absolute, options, moduleHost, resolutionCacheOf(ts, sideRoot, options)).resolvedModule;
         if (!resolved || resolved.isExternalLibraryImport)
             continue;
         const local = localPath(sideRoot, resolved.resolvedFileName);
@@ -109,6 +121,29 @@ export function resolveImports(host, options, file, text) {
     }
     return [...found].sort();
 }
+/**
+ * The type surface of one source file: the digest of its isolated declaration emit (`ts.transpileDeclaration`, TypeScript 5.5 and later, which reads the
+ * file alone) and whether it is open. A body-only edit leaves the emit, and so the digest, as it was; a changed signature, export list or doc comment
+ * (`@deprecated` is read by lint rules) changes it. A compiler without `transpileDeclaration` gives no digest, which every reader takes as changed.
+ * `open` is true when the emit reported a diagnostic (the compiler must infer a type); `refs` is the local files the emit names.
+ */
+export function surfaceOf(host, options, file, text) {
+    const { ts } = host;
+    if (DECLARATION.test(file) || SCRIPT.test(file))
+        return { api: hashText(text), open: true, refs: undefined };
+    if (!TYPESCRIPT.test(file))
+        return { api: hashText(text), open: false, refs: [] };
+    try {
+        const surface = declarationSurface(ts, file, text, options.module);
+        if (surface === null)
+            return { api: undefined, open: true, refs: undefined };
+        // the classifier is the one the explicit-export-surface rule of the canons reports with: a file is open exactly when it has a problem
+        return { api: hashText(surface.outputText), open: surface.problems.length > 0, refs: resolveImports(host, options, file, surface.outputText) };
+    }
+    catch {
+        return { api: undefined, open: true, refs: undefined };
+    }
+}
 /**
  * The import graph of `files` (the side's lint scope, side-relative posix) and the leaves they reach.
  *
@@ -131,7 +166,8 @@ export function buildImportGraph(host, files, recorded, options = {}) {
         if (hash === null)
             return;
         const before = recorded?.get(file);
-        if (!pathsChanged && before !== undefined && before.hash === hash) {
+        // a record from before the type surface was kept has none: the file is read once more to give it one
+        if (!pathsChanged && before !== undefined && before.hash === hash && (before.api !== undefined || !/\.(?:[cm]?[jt]sx?)$/.test(file))) {
             graph.set(file, before);
             reused += 1;
         }
@@ -139,11 +175,11 @@ export function buildImportGraph(host, files, recorded, options = {}) {
             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) });
+                ? { hash, imports: [], declaresGlobals: false, api: undefined, open: true, refs: undefined }
+                : { hash, imports: resolveImports(host, compiler, file, text), declaresGlobals: declaresGlobals(host.ts, file, text), ...surfaceOf(host, compiler, file, text) });
         }
         else
-            graph.set(file, { hash, imports: [], declaresGlobals: false });
+            graph.set(file, { hash, imports: [], declaresGlobals: false, api: hash, open: false, refs: [] });
         for (const next of graph.get(file)?.imports ?? [])
             visit(next);
     };
@@ -181,9 +217,15 @@ export function dependentsOf(graph, seeds) {
     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.
+ * The files to lint again after a change from `previous` (the recorded graph, null when none) to `next`.
+ *
+ * A file is dirty when it changed, was added or removed, resolves its imports to other files than recorded, or imports a file whose type surface
+ * changed, in the new graph or the recorded one (a file that stopped importing such a file still holds a result from the old types). A dirty file's
+ * surface changed when it was added or removed, gained an import, its surface digest differs from the record (or either is unknown), its surface
+ * is inferred (`open`: whatever dirtied it can have changed the inferred type), or its explicit surface names a file (`refs`) whose surface changed.
+ * An explicit surface is its emit text and the surfaces of the files it names, so a body-only edit of such a file dirties that file alone, a
+ * changed signature its direct importers, and a type it re-exports or names carries on through the files that name it. A changed file that
+ * declares globals, now or before, dirties the whole side.
  */
 export function dirtySetOf(previous, next) {
     const changed = changedPaths(previous, next);
@@ -195,10 +237,45 @@ export function dirtySetOf(previous, next) {
         }
     }
     // 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 rewired = new Set([...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)]);
+    }).map(([file]) => file));
+    const importers = new Map();
+    for (const graph of [next, previous])
+        for (const [file, node] of graph)
+            for (const target of node.imports) {
+                const known = importers.get(target) ?? new Set();
+                known.add(file);
+                importers.set(target, known);
+            }
+    const dirty = new Set([...changed, ...rewired]);
+    const surface = new Set();
+    const surfaceChanged = (file) => {
+        const after = next.get(file), before = previous.get(file);
+        if (after === undefined || before === undefined)
+            return true;
+        // a new edge can resolve a name the emit already used to a file that was not there, so what the importers read of this file may differ
+        if (rewired.has(file) && after.imports.some((target) => !before.imports.includes(target)))
+            return true;
+        if (after.hash !== before.hash && (after.api === undefined || before.api === undefined || after.api !== before.api))
+            return true;
+        if (after.open !== false || before.open !== false || after.refs === undefined || before.refs === undefined)
+            return true;
+        return [...after.refs, ...before.refs].some((target) => surface.has(target));
+    };
+    const queue = [...dirty];
+    while (queue.length > 0) {
+        const file = queue.pop();
+        if (surface.has(file) || !surfaceChanged(file))
+            continue;
+        surface.add(file);
+        for (const importer of importers.get(file) ?? []) {
+            // a file already judged to keep its surface is looked at again: the file that just changed may be one its surface names
+            if (!dirty.has(importer))
+                dirty.add(importer);
+            queue.push(importer);
+        }
+    }
     return { dirty, wholeSide: null, changed };
 }

package/cache/lint-family.d.mts

@@ -78,10 +78,14 @@ export interface StylelintResult {
     warnings: StylelintWarning[];
     [key: string]: unknown;
 }
-/** The answer of a linter seam: validated results of the files it was asked about, or why it could not complete. */
+/**
+ * The answer of a linter seam: validated results of the files it was asked about, or why it could not complete. `graph` is, for ESLint, the project-graph
+ * snapshot each canon's graph rules built in the child, by canon name: the records of the `graph` step are written from it instead of building the graph again.
+ */
 export interface LinterOutcome<R> {
     results: R[];
     errors: string[];
+    graph?: Readonly<Record<string, GraphSnapshot>> | undefined;
 }
 /** Everything one side's cached lint needs. */
 export interface LintSideInput {
@@ -93,8 +97,6 @@ export interface LintSideInput {
     scope: readonly string[];
     /** The stylesheets stylelint judges (fe only): side-relative posix; empty otherwise. */
     stylesheets: readonly string[];
-    /** The files this run reports when it reports part of a side (a workspace lint); null reports the whole side. A partial run never writes. */
-    report: ((file: string) => boolean) | null;
     /** The ESLint canon, its grammar family, in config order. */
     canons: readonly CanonDeclarations[];
     /** The stylelint canon; null when the side has no stylesheet judge. */
@@ -149,6 +151,11 @@ export declare function crossDigestFactory(options: {
 }): (file: string) => string | undefined;
 /** The TypeScript the app installed, resolved from the side folder like the linters are (not this package's own copy). */
 export declare function loadAppTypeScript(sideRoot: string): Ts;
+/**
+ * The graph findings of every canon that publishes graph rules, merged by file and sorted. A canon whose snapshot the ESLint child handed out (`handed`, by
+ * canon name) is not asked to build its graph again; any other canon builds it through its `projectGraph`.
+ */
+export declare function mergedSnapshot(sideRoot: string, canons: readonly CanonDeclarations[], handed?: Readonly<Record<string, GraphSnapshot>>): Record<string, GraphFinding[]> | null;
 /**
  * Judges one side: ESLint (and, for fe, stylelint) over what the records cannot vouch for, the records of the rest, and the new records.
  * Never throws for a tool failure: those come back in `errors`, and a side with an error stores nothing.