@starci/hfs 5.0.7 → 5.0.8

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 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,7 @@
 // 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 { 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 +83,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 +106,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 +120,85 @@ export function resolveImports(host, options, file, text) {
     }
     return [...found].sort();
 }
+/** Whether `expression` is a JSX element, fragment, `null` or `undefined`, or a conditional of those: its type does not depend on any other file. */
+function isJsxValue(ts, expression) {
+    if (expression === undefined)
+        return false;
+    let node = expression;
+    while (ts.isParenthesizedExpression(node))
+        node = node.expression;
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node) || node.kind === ts.SyntaxKind.NullKeyword)
+        return true;
+    if (ts.isIdentifier(node))
+        return node.text === 'undefined';
+    return ts.isConditionalExpression(node) && isJsxValue(ts, node.whenTrue) && isJsxValue(ts, node.whenFalse);
+}
+/**
+ * Whether the function (or method) the declaration diagnostic at `start` points at has the type `JSX.Element | null | undefined` whatever its body
+ * reads: not async, not a generator, and every `return` of its own (and its concise body) a JSX value. A React component written without a return
+ * type is the common case; its inferred type is one the JSX namespace of the installed packages gives, which a lockfile change dirties as a whole.
+ */
+function returnsOnlyJsx(ts, source, start) {
+    let found;
+    const find = (node) => {
+        if (found !== undefined || start < node.getFullStart() || start >= node.end)
+            return;
+        const named = (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name !== undefined && node.name.getStart(source) === start;
+        if (named || ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.getStart(source) === start)) {
+            found = node;
+            return;
+        }
+        ts.forEachChild(node, find);
+    };
+    find(source);
+    const fn = found;
+    if (fn === undefined || fn.type !== undefined || fn.body === undefined)
+        return false;
+    if (fn.asteriskToken !== undefined || (ts.getCombinedModifierFlags(fn) & ts.ModifierFlags.Async) !== 0)
+        return false;
+    if (!ts.isBlock(fn.body))
+        return isJsxValue(ts, fn.body);
+    let only = true;
+    const visit = (node) => {
+        if (!only || ts.isFunctionLike(node) || ts.isClassLike(node))
+            return;
+        if (ts.isReturnStatement(node) && node.expression !== undefined && !isJsxValue(ts, node.expression))
+            only = false;
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(fn.body, visit);
+    return only;
+}
+const SCRIPT = /\.(?:[cm]?jsx?)$/;
+const DECLARATION = /\.d\.[cm]?ts$/;
+const TYPESCRIPT = /\.(?:[cm]?tsx?)$/;
+/**
+ * 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: [] };
+    const emit = ts.transpileDeclaration;
+    if (emit === undefined)
+        return { api: undefined, open: true, refs: undefined };
+    try {
+        const declared = emit.call(ts, text, { compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest, ...(options.module === undefined ? {} : { module: options.module }) }, fileName: file, reportDiagnostics: true });
+        const diagnostics = (declared.diagnostics ?? []);
+        // a declaration whose only diagnostics are components returning JSX has the surface its emit shows
+        const source = diagnostics.length === 0 ? undefined : ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+        const inferred = source !== undefined && !diagnostics.every((diagnostic) => (diagnostic.code === 9007 || diagnostic.code === 9008) && diagnostic.start !== undefined && returnsOnlyJsx(ts, source, diagnostic.start));
+        return { api: hashText(declared.outputText), open: inferred, refs: resolveImports(host, options, file, declared.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 +221,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 +230,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 +272,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 +292,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

@@ -93,8 +93,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. */