@starci/eslint-canon-be 3.11.19 → 3.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.12.0
4
+
5
+ - Added: `starci-be/explicit-export-surface` (R368, `HFS_EXPLICIT_EXPORT_SURFACE`) at error: an exported function's return type, an exported variable's type and a parameter's type are written, not inferred from a body or from other files. It reports each export the isolated declaration emit cannot write, at the offending span, and says what to annotate. It reads the classifier the lint result cache reads.
6
+ - Added: `projectGraphSnapshot`, the findings of the project graph the process has already built, which the ESLint child hands to the cache; `projectGraph` stays the fresh build.
7
+ - Changed: carry the bundled runtime of @starci/hfs 5.1.0 (the classifier, the rule factory, the rule catalog with R368, the canon pins).
8
+
3
9
  ## 3.11.19
4
10
 
5
11
  - Changed: Carry the bundled runtime of @starci/hfs 5.0.8 (the rule texts name `app check`, the read-set helper of the rule memo) and its canon pins; the comments name `app check` for the removed lint verb.
package/README.md CHANGED
@@ -155,6 +155,16 @@ in `src/lib/hfs-view.ts`, which is emitted, so the published declarations of `lo
155
155
  untyped runtime file. `fixtures/` is spec data and stays JavaScript with
156
156
  `.d.mts` contracts, because the front-end canon and the Grammar lint families import its helpers by path.
157
157
 
158
+ The [explicit exported surface](../../contexts/code/shared/typing.md) (R368, SHARED-TYPING-5) is `explicit-export-surface`
159
+ (`HFS_EXPLICIT_EXPORT_SURFACE`): an exported function's return type, an exported variable's type and a parameter's type are
160
+ written where they are exported, never inferred from a body or from other files; a component that returns only JSX, `null` or
161
+ `undefined` is explicit. It reports each export TypeScript's isolated declaration emit cannot write, at the offending span, and says
162
+ which annotation to add. It reads the classifier the lint result cache reads (`declarationSurface`, the bundled
163
+ `runtime/scripts/lib/declaration-surface.mjs`), so it reports exactly the files the cache counts as open.
164
+
165
+ `projectGraph` and `projectGraphSnapshot` are the cache's two readers of the project graph the graph rules share: the first builds it
166
+ afresh, the second answers from the graph the process has already built, which is how the ESLint child hands its graph to the cache.
167
+
158
168
  ## HFS rules and their why codes
159
169
 
160
170
  Every rule of this plugin is an enforcer of one HFS rule. The relation (rule id -> HFS rule -> catalogued Vietnamese why code)
@@ -0,0 +1,7 @@
1
+ import type { Recommended, RuleModule } from "./lib/rule.js";
2
+ /** The rules this law contributes to the plugin. */
3
+ export declare const rules: {
4
+ "explicit-export-surface": RuleModule;
5
+ };
6
+ /** Every exported type is written out, at error. */
7
+ export declare const recommended: Recommended;
@@ -0,0 +1,19 @@
1
+ /**
2
+ * The explicit exported surface (HFS R368, `HFS_EXPLICIT_EXPORT_SURFACE`): an exported declaration states its type, in the file that exports it.
3
+ *
4
+ * A return type, variable type or parameter type left to inference is a surface importers read from the body and from the files the body uses, so
5
+ * the result cache of `starci app check --gate lint` lints every importer again whenever the file changes (check-cache.md, ESLint). The rule
6
+ * reports each export the isolated declaration emit (`ts.transpileDeclaration`) cannot write without inference, where it is written, and says
7
+ * what to annotate. A component that returns only JSX has the type the JSX namespace gives it and is not reported. It is the very classifier the
8
+ * cache reads (`declarationSurface` of the bundled runtime), so the rule reports exactly the files the cache counts as open.
9
+ */
10
+ import ts from "typescript";
11
+ import { explicitSurfaceRule } from "../runtime/scripts/hfs/explicit-surface-rule.mjs";
12
+ /** The rules this law contributes to the plugin. */
13
+ export const rules = {
14
+ "explicit-export-surface": explicitSurfaceRule({ ts }),
15
+ };
16
+ /** Every exported type is written out, at error. */
17
+ export const recommended = {
18
+ "starci-be/explicit-export-surface": "error",
19
+ };
package/dist/index.d.ts CHANGED
@@ -54,5 +54,5 @@ export { linterOptions } from "./lib/config.js";
54
54
  export { loadHfs } from "./lib/hfs.js";
55
55
  export { crossFileInputs } from "./lib/cross-file-inputs.js";
56
56
  export type { CrossFileInput } from "./lib/cross-file-inputs.js";
57
- export { projectGraph } from "./project-graph.js";
57
+ export { projectGraph, projectGraphSnapshot } from "./project-graph.js";
58
58
  export type { ProjectGraphFinding, ProjectGraphSnapshot } from "./project-graph.js";
package/dist/index.js CHANGED
@@ -61,6 +61,7 @@ import { recommended as serviceIsolationRecommended, rules as serviceIsolationRu
61
61
  import { recommended as sizeBudgetRecommended, rules as sizeBudgetRules } from "./size-budget.js";
62
62
  import { recommended as specNoSkipRecommended, rules as specNoSkipRules } from "./spec-no-skip.js";
63
63
  import { recommended as specQualityRecommended, rules as specQualityRules } from "./spec-quality.js";
64
+ import { recommended as explicitSurfaceRecommended, rules as explicitSurfaceRules } from "./explicit-surface.js";
64
65
  import { recommended as suppressionRecommended, rules as suppressionRules } from "./suppression.js";
65
66
  import { recommended as temporalRecommended, rules as temporalRules } from "./temporal.js";
66
67
  import { recommended as testingRecommended, rules as testingRules } from "./testing.js";
@@ -121,6 +122,7 @@ const CONTRIBUTIONS = [
121
122
  { law: "size-budget", rules: sizeBudgetRules, recommended: sizeBudgetRecommended },
122
123
  { law: "spec-no-skip", rules: specNoSkipRules, recommended: specNoSkipRecommended },
123
124
  { law: "spec-quality", rules: specQualityRules, recommended: specQualityRecommended },
125
+ { law: "explicit-surface", rules: explicitSurfaceRules, recommended: explicitSurfaceRecommended },
124
126
  { law: "suppression", rules: suppressionRules, recommended: suppressionRecommended },
125
127
  { law: "temporal", rules: temporalRules, recommended: temporalRecommended },
126
128
  { law: "testing", rules: testingRules, recommended: testingRecommended },
@@ -220,4 +222,4 @@ for (const entry of [
220
222
  }
221
223
  // The result cache of `starci app check --gate lint` (contexts/project/check-cache.md) reads these two declarations of the installed canon.
222
224
  export { crossFileInputs } from "./lib/cross-file-inputs.js";
223
- export { projectGraph } from "./project-graph.js";
225
+ export { projectGraph, projectGraphSnapshot } from "./project-graph.js";
@@ -34,3 +34,17 @@ export declare const projectGraph: ({ repoRoot, injectedTypeScript }: {
34
34
  repoRoot: string;
35
35
  injectedTypeScript?: object;
36
36
  }) => ProjectGraphSnapshot;
37
+ /**
38
+ * The same findings from the graph this process has already built, so a process that linted the side hands them out without building the graph again.
39
+ *
40
+ * The rules read one graph per process and per side, built when the first file is linted. The ESLint child of `starci app check --gate lint` calls
41
+ * this after its run and writes the result beside its report; the result cache keeps the graph findings from it instead of building the graph a
42
+ * second time in the CLI. A process that has not built the graph yet builds it here, once, exactly as `projectGraph` does, and the value is the
43
+ * same: `projectGraph` is a fresh build, this is the build the rules used.
44
+ *
45
+ * @param input - The side folder (`repoRoot`, the folder of the side's `eslint.config.mjs`).
46
+ * @returns The findings of the rules of `recommended`, keyed by path relative to the side folder.
47
+ */
48
+ export declare const projectGraphSnapshot: ({ repoRoot }: {
49
+ repoRoot: string;
50
+ }) => ProjectGraphSnapshot;
@@ -32,7 +32,22 @@ export const recommended = Object.fromEntries(mine.map((e) => [`starci-be/${e.id
32
32
  */
33
33
  export const projectGraph = ({ repoRoot, injectedTypeScript }) => {
34
34
  resetProjectGraphs();
35
- const graph = buildProjectGraph({ repoRoot, ...(injectedTypeScript === undefined ? {} : { injectedTypeScript }), runtimeRoot: RUNTIME_ROOT });
35
+ return snapshotOf(buildProjectGraph({ repoRoot, ...(injectedTypeScript === undefined ? {} : { injectedTypeScript }), runtimeRoot: RUNTIME_ROOT }));
36
+ };
37
+ /**
38
+ * The same findings from the graph this process has already built, so a process that linted the side hands them out without building the graph again.
39
+ *
40
+ * The rules read one graph per process and per side, built when the first file is linted. The ESLint child of `starci app check --gate lint` calls
41
+ * this after its run and writes the result beside its report; the result cache keeps the graph findings from it instead of building the graph a
42
+ * second time in the CLI. A process that has not built the graph yet builds it here, once, exactly as `projectGraph` does, and the value is the
43
+ * same: `projectGraph` is a fresh build, this is the build the rules used.
44
+ *
45
+ * @param input - The side folder (`repoRoot`, the folder of the side's `eslint.config.mjs`).
46
+ * @returns The findings of the rules of `recommended`, keyed by path relative to the side folder.
47
+ */
48
+ export const projectGraphSnapshot = ({ repoRoot }) => snapshotOf(buildProjectGraph({ repoRoot, runtimeRoot: RUNTIME_ROOT }));
49
+ /** The findings of the rules of this canon in a built graph, by side-relative path, each list sorted by line, column, code and message. */
50
+ const snapshotOf = (graph) => {
36
51
  const byFile = {};
37
52
  for (const [file, findings] of graph.byFile) {
38
53
  for (const finding of findings) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/eslint-canon-be",
3
- "version": "3.11.19",
3
+ "version": "3.12.0",
4
4
  "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -126,6 +126,7 @@
126
126
  "scripts/hfs/declaration-shape.mjs",
127
127
  "scripts/hfs/declaration-slots.mjs",
128
128
  "scripts/hfs/edition-slots.mjs",
129
+ "scripts/hfs/explicit-surface-rule.mjs",
129
130
  "scripts/hfs/linear-text.mjs",
130
131
  "scripts/hfs/param-names.mjs",
131
132
  "scripts/hfs/path-findings.mjs",
@@ -151,6 +152,7 @@
151
152
  "scripts/hfs/trailing-slashes.mjs",
152
153
  "scripts/hfs/typescript-programs.mjs",
153
154
  "scripts/hfs/view.mjs",
155
+ "scripts/lib/declaration-surface.mjs",
154
156
  "scripts/lib/dockerfile.mjs",
155
157
  "scripts/lib/env.mjs",
156
158
  "scripts/lib/event-contract.mjs",
@@ -31,35 +31,35 @@ pins:
31
31
  source: packages/event-stream/package.json
32
32
  why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
33
33
  '@starci/grammar':
34
- version: 0.21.12
34
+ version: 0.21.13
35
35
  group: starci
36
36
  install: registry
37
37
  side: fe
38
38
  source: packages/grammar/package.json
39
39
  why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
40
40
  '@starci/eslint-canon-be':
41
- version: 3.11.19
41
+ version: 3.12.0
42
42
  group: starci
43
43
  install: registry
44
44
  side: be
45
45
  source: packages/eslint-canon-be/package.json
46
46
  why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
47
47
  '@starci/eslint-canon-fe':
48
- version: 9.9.12
48
+ version: 9.10.0
49
49
  group: starci
50
50
  install: registry
51
51
  side: fe
52
52
  source: packages/eslint-canon-fe/package.json
53
53
  why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
54
54
  '@starci/eslint-grammar-core':
55
- version: 0.21.12
55
+ version: 0.21.13
56
56
  group: starci
57
57
  install: registry
58
58
  side: fe
59
59
  source: packages/eslint-grammar-core/package.json
60
60
  why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
61
61
  '@starci/eslint-grammar-offset-pop':
62
- version: 0.21.12
62
+ version: 0.21.13
63
63
  group: starci
64
64
  install: registry
65
65
  side: fe
@@ -92,7 +92,7 @@ pins:
92
92
  source: packages/jest-preset/package.json
93
93
  why: 'the Jest preset of a back end: the world runner runs up to min(--maxWorkers, slots) world files at once, each in its own process bound to one data slot of the test world (STARCI_TEST_WORLD_SLOT), and reads test-world state protocol 2 only: it pairs exactly with @starci/test-world, and any other state file is JEST_PRESET_WORLD_PAIR_MISMATCH. The unit run writes the lcov Sonar and Codecov import (services only); the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; it ships the unit kit (mockEntityManager, fakeTransaction, fakeQueryBuilder, queueQueryBuilders, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
94
94
  '@starci/test-world':
95
- version: 1.3.3
95
+ version: 1.3.4
96
96
  group: starci
97
97
  install: registry
98
98
  side: be
@@ -106,7 +106,7 @@ pins:
106
106
  source: packages/ai-router/package.json
107
107
  why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
108
108
  '@starci/hfs':
109
- version: 5.0.8
109
+ version: 5.1.0
110
110
  group: starci
111
111
  install: registry
112
112
  side: both
@@ -924,7 +924,7 @@ rules:
924
924
  code: "BE_TEST_TOPOLOGY"
925
925
  editions: [lite, full]
926
926
  docs: [docs/quality-bar.md#r47-test-topology]
927
- law: "One jest config, projects `unit`, `integration`, `e2e` and `contract`, live by folder, `diagnostics: false`; unit specs are `<name>.<role>.spec.ts` beside the file they test: required for the roles of `ruleParams.be.unitRoles` (`<name>.service.spec.ts` beside a `<name>.service.ts`, `<name>.cli.spec.ts` beside a cli command `<name>.cli.ts` of `src/features/cli`), optional for any other logic role (`ruleParams.be.logicRoles`) inside a slot whose `coverage` is required and beside a logic file such a slot declares (`logic`: `passport.tokens.spec.ts` beside `passport.tokens.ts`), except that the commit adding a measured logic file stages its `<name>.<role>.spec.ts` beside it (owner 2026-10-20, judged by `starci app check --staged` in the pre-commit hook), and nowhere else but beside a webhook or realtime door that has no service of its own (`<provider>.webhook.spec.ts`, `<channel>.gateway.spec.ts`, `<x>.subscription.spec.ts`) (every unit-tested subject has exactly one; any other `*.spec.ts` outside `be/src/tests/{world,integration,e2e,contract}` is a finding, including specs in apps), and the unit project collects coverage from the logic roles of the measured roots and the logic files their slots declare only (the scope derived from the slot manifest, R204) with a per-file threshold of 100 on lines, branches, functions and statements (`test` runs `--coverage`; `importHelpers` and `tslib`); `be/src/tests/world/` is the ONLY test infrastructure: `global-setup.ts` starts the app's own stack (`.starcistacks/<env>`, named by `stack` in `test-world.config.ts`, the declaration of the test-world library in its one named form `export const { useTestWorld, useSandbox } = defineTestWorld({...})` (a default export is not read): every service it declares runs REAL, behind toxiproxy, images and versions read from the stack at run time, never spelled in test source) or attaches to a warm one that answers, and runs the migrations once over the cli app's connections (the runner of the cli migrate command); `global-teardown.ts` stops only what its setup started; `use-test-world.ts` exports `useTestWorld({ apps } | { modules })` (`world.apps.<name>.api`, `world.db.<connection>`, `world.infra.<service>` with `latency(ms)`, `cut()` and `restore()` on the real service, `world.fake.<provider>`, `world.waitFor`) and `fakes/<provider>/` holds the network-edge fakes (`failNext`, `replayWebhook`, `delay`, payload fixtures) of external SaaS the team does not operate ONLY: a fake of a service the stack declares is refused, except stateless compute that needs special hardware or an external model (GPU inference, a self-hosted embedding model), whose `stacks` entry in `test-world.config.ts` declares `{ fakedBy: <fake>, reason }` with a non-empty `reason` (a stateful service, or one with a persistent volume, is never accepted); it alone owns containers, DataSource, migrations and `process.env`; nothing under `be/src/tests` overrides a provider or DI token; `be/src/tests/integration/<capability>/*.integration-spec.ts` (`{ modules }`, with the real peer apps its client calls beside them as `apps`; real infrastructure, no HTTP door of ours), `be/src/tests/e2e/<area>/*.e2e-spec.ts` (`{ apps }`) and `be/src/tests/contract/<provider>/*.contract-spec.ts` (provider sandboxes, skipped without sandbox config, run only by `test:contract`, never by `test` or `test:e2e`) agree folder with suffix; an integration or e2e spec passes `useTestWorld` one object literal with plain keys (no variable, spread or computed key) and calls it; the contract layer has no skip either: a contract spec writes `sandbox.describe(...)` from the test-world library's `useSandbox(...)`, and when the sandbox config is absent that describe registers one failing test naming the missing keys (the body never runs), and every `fakes/<provider>/` that serves payload fixtures (`payloads/*.json`) has a `contract/<provider>/*.contract-spec.ts` that references those fixtures and asserts `shapeOf(real)` equals `shapeOf(fixture)` (the helper `shapeOf` is named by `ruleParams.be.contractShape` of the slot manifest; fakes the test-world library provides are guarded by the library); no `.test.ts`, `int-spec` or `harness-spec`, no `live/` and no `be/src/tests/e2e/world`."
927
+ law: "One jest config, projects `unit`, `integration`, `e2e` and `contract`, live by folder, `diagnostics: false`; unit specs are `<name>.<role>.spec.ts` beside the file they test: required for the roles of `ruleParams.be.unitRoles` (`<name>.service.spec.ts` beside a `<name>.service.ts`, `<name>.cli.spec.ts` beside a cli command `<name>.cli.ts` of `src/features/cli`), optional for any other logic role (`ruleParams.be.logicRoles`) inside a slot whose `coverage` is required and beside a logic file such a slot declares (`logic`: `passport.tokens.spec.ts` beside `passport.tokens.ts`), except that the commit adding a measured logic file stages its `<name>.<role>.spec.ts` beside it (owner 2026-10-20, judged by `starci app check --staged` in the pre-commit hook), and nowhere else but beside a webhook or realtime door that has no service of its own (`<provider>.webhook.spec.ts`, `<channel>.gateway.spec.ts`, `<x>.subscription.spec.ts`) (every unit-tested subject has exactly one; any other `*.spec.ts` outside `be/src/tests/{world,integration,e2e,contract}` is a finding, including specs in apps), and the unit project collects coverage from the logic roles of the measured roots and the logic files their slots declare only (the scope derived from the slot manifest, R204) with a per-file threshold of 100 on lines, branches, functions and statements (`test` runs `--coverage`; `importHelpers` and `tslib`); `be/src/tests/world/` is the ONLY test infrastructure: `global-setup.ts` starts the app's own stack (`.starcistacks/<env>`, named by `stack` in `test-world.config.ts`, the declaration of the test-world library in a named form: `export const { useTestWorld, useSandbox } = defineTestWorld({...})`, or `const world: TestWorldApi = defineTestWorld({...})` with `useTestWorld` and `useSandbox` exported typed from it (a default export is not read): every service it declares runs REAL, behind toxiproxy, images and versions read from the stack at run time, never spelled in test source) or attaches to a warm one that answers, and runs the migrations once over the cli app's connections (the runner of the cli migrate command); `global-teardown.ts` stops only what its setup started; `use-test-world.ts` exports `useTestWorld({ apps } | { modules })` (`world.apps.<name>.api`, `world.db.<connection>`, `world.infra.<service>` with `latency(ms)`, `cut()` and `restore()` on the real service, `world.fake.<provider>`, `world.waitFor`) and `fakes/<provider>/` holds the network-edge fakes (`failNext`, `replayWebhook`, `delay`, payload fixtures) of external SaaS the team does not operate ONLY: a fake of a service the stack declares is refused, except stateless compute that needs special hardware or an external model (GPU inference, a self-hosted embedding model), whose `stacks` entry in `test-world.config.ts` declares `{ fakedBy: <fake>, reason }` with a non-empty `reason` (a stateful service, or one with a persistent volume, is never accepted); it alone owns containers, DataSource, migrations and `process.env`; nothing under `be/src/tests` overrides a provider or DI token; `be/src/tests/integration/<capability>/*.integration-spec.ts` (`{ modules }`, with the real peer apps its client calls beside them as `apps`; real infrastructure, no HTTP door of ours), `be/src/tests/e2e/<area>/*.e2e-spec.ts` (`{ apps }`) and `be/src/tests/contract/<provider>/*.contract-spec.ts` (provider sandboxes, skipped without sandbox config, run only by `test:contract`, never by `test` or `test:e2e`) agree folder with suffix; an integration or e2e spec passes `useTestWorld` one object literal with plain keys (no variable, spread or computed key) and calls it; the contract layer has no skip either: a contract spec writes `sandbox.describe(...)` from the test-world library's `useSandbox(...)`, and when the sandbox config is absent that describe registers one failing test naming the missing keys (the body never runs), and every `fakes/<provider>/` that serves payload fixtures (`payloads/*.json`) has a `contract/<provider>/*.contract-spec.ts` that references those fixtures and asserts `shapeOf(real)` equals `shapeOf(fixture)` (the helper `shapeOf` is named by `ruleParams.be.contractShape` of the slot manifest; fakes the test-world library provides are guarded by the library); no `.test.ts`, `int-spec` or `harness-spec`, no `live/` and no `be/src/tests/e2e/world`."
928
928
  kinds: [check, codemod, lint]
929
929
  gates: [land, ci]
930
930
  failureCodes: ["BE_TEST_TOPOLOGY", "BE_CONTRACT_UNGUARDED", "BE_UNIT_SPEC_NOT_STAGED"]
@@ -6525,3 +6525,54 @@ rules:
6525
6525
  source: owner
6526
6526
  quote: "The skeleton is the ready structure with its data missing; it is drawn from isLoading alone and from the reads the region shows."
6527
6527
  ruling: "Several reads feed one frame: loading is any read loading with no data; a key change reloads only the region keyed by it; a refresh keeps the content."
6528
+ - id: R368
6529
+ code: "HFS_EXPLICIT_EXPORT_SURFACE"
6530
+ law: "An exported declaration states its type where it is exported: the return type of an exported function, the type of an exported variable and the type of its parameters are written, not inferred from a body or from other files, because the isolated declaration emit must be able to write the file's surface alone. A component that returns only JSX is explicit. Each export that cannot be written is reported at its place with what to annotate, in a front-end and a back-end file alike."
6531
+ kinds: [lint]
6532
+ gates: [pre-commit, settle, land, ci]
6533
+ failureCodes: ["HFS_EXPLICIT_EXPORT_SURFACE"]
6534
+ enforcers:
6535
+ - {kind: eslint-fe, id: explicit-export-surface}
6536
+ - {kind: eslint-be, id: explicit-export-surface}
6537
+ editions: [lite, full]
6538
+ docs: [contexts/code/shared/typing.md]
6539
+ templateNa: "A template exports nothing the lint result cache keys on."
6540
+ proves:
6541
+ - {path: packages/eslint-canon-fe/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
6542
+ - {path: packages/eslint-canon-be/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
6543
+ - {path: packages/hfs/src/explicit-surface.spec.mts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
6544
+ exemplifiedBy:
6545
+ - {path: packages/eslint-canon-fe/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
6546
+ witness:
6547
+ - {path: packages/eslint-canon-fe/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
6548
+ - {path: packages/eslint-canon-be/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
6549
+ - {path: packages/hfs/src/explicit-surface.spec.mts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
6550
+ cases:
6551
+ - id: case-1
6552
+ date: "2026-11-03"
6553
+ source: owner
6554
+ quote: "enforce it by lint"
6555
+ ruling: "A file whose exported surface is inferred is open in the lint result cache: one body edit lints every importer again. The exported surface is written out, and the rule reports exactly what the cache counts as open."
6556
+ - id: R369
6557
+ code: "FE_DIRECTIVE_FIRST"
6558
+ law: "A `use client` or `use server` directive is the first statement of its module, above every import: below another statement it is an expression that does nothing (Prettier writes it as a parenthesised string) and next build refuses the file."
6559
+ kinds: [lint]
6560
+ gates: [pre-commit, settle, land, ci]
6561
+ failureCodes: ["FE_DIRECTIVE_FIRST"]
6562
+ enforcers:
6563
+ - {kind: eslint-fe, id: directive-first}
6564
+ editions: [lite, full]
6565
+ docs: [contexts/code/fe/boundaries.md]
6566
+ templateNa: "A template places its directives first."
6567
+ proves:
6568
+ - {path: packages/eslint-canon-fe/src/directive-first.spec.ts, editions: [lite, full], codes: [FE_DIRECTIVE_FIRST]}
6569
+ exemplifiedBy:
6570
+ - {path: packages/eslint-canon-fe/src/directive-first.spec.ts, editions: [lite, full], codes: [FE_DIRECTIVE_FIRST]}
6571
+ witness:
6572
+ - {path: packages/eslint-canon-fe/src/directive-first.spec.ts, editions: [lite, full], codes: [FE_DIRECTIVE_FIRST]}
6573
+ cases:
6574
+ - id: case-1
6575
+ date: "2026-11-03"
6576
+ source: owner
6577
+ quote: "no lint caught it"
6578
+ ruling: "A directive below an import broke Nivo's CI build on 2026-11-02; the directive is the first statement of its module and a lint reports it elsewhere."
@@ -15,9 +15,10 @@ import { byCodeUnit } from '../../lib/list.mjs';
15
15
  * its own slot, be.tests.world.kit) plus files at its root whose role suffix is in ruleParams.be.suffixes
16
16
  * (`stripe.client.ts`, `checkout.contracts.ts`, `test-world.config.ts`, ...). Every tracked file below the world root is
17
17
  * matched by the slot's own entries through `allowsFile`.
18
- * 2. The declaration. `test-world.config.ts` declares the world in ONE form, the named export R89 allows:
19
- * `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })` (an exported `const` initialized by a
20
- * `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
18
+ * 2. The declaration. `test-world.config.ts` declares the world in a named form R89 allows: the destructured export
19
+ * `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })`, or the typed form
20
+ * `const world: TestWorldApi = defineTestWorld({ ... })` whose `useTestWorld` and `useSandbox` are exported consts typed from
21
+ * `TestWorldApi` (a `const` initialized by a `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
21
22
  * read) is refused: the world it declares could not be judged.
22
23
  * 3. Fakes against the stack (owner refinement 2026-09-30). Every service the stack declares runs real in the world; a fake
23
24
  * (a `fakes/<provider>/` folder, or a `fakes` entry of the declaration such as `smtp: smtpFake()`) is a network-edge fake
@@ -38,6 +39,7 @@ const FAKES_DIRECTORY = 'fakes/';
38
39
  const CONFIG_FILE = 'test-world.config.ts';
39
40
  const DEFINE = 'defineTestWorld';
40
41
  const NAMED_FORM = `export const { useTestWorld, useSandbox } = ${DEFINE}({ ... })`;
42
+ const TYPED_FORM = `const world: TestWorldApi = ${DEFINE}({ ... })` + ' with export const useTestWorld / useSandbox typed from it';
41
43
  const defaultEnvironment = DEFAULT_ENVIRONMENT;
42
44
  const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
43
45
  const unwrap = (ts, node) => unwrapEach(ts, node, [ts.isParenthesizedExpression, ts.isAsExpression, ts.isSatisfiesExpression]);
@@ -52,21 +54,38 @@ function defineLiteral(ts, expression) {
52
54
  const literal = first ? unwrap(ts, first) : null;
53
55
  return literal && ts.isObjectLiteralExpression(literal) ? literal : null;
54
56
  }
55
- /** The declaration of the world: the object literal of an exported `const` initialized by `defineTestWorld({ ... })`, or null. */
57
+ /**
58
+ * The declaration of the world: the object literal of a top-level `const` initialized by `defineTestWorld({ ... })`, or null. The config
59
+ * exports `useTestWorld` and `useSandbox` either by destructuring that call (the original form) or, typed, from the world the call
60
+ * built: `const world: TestWorldApi = defineTestWorld({ ... })` with `export const useTestWorld: TestWorldApi["useTestWorld"] = world.useTestWorld`.
61
+ * Both are read; a world no exported name reaches is refused by the caller.
62
+ */
56
63
  function configLiteral(ts, sourceFile) {
57
64
  for (const statement of sourceFile.statements) {
58
- if (!ts.isVariableStatement(statement) || !isExported(ts, statement))
65
+ if (!ts.isVariableStatement(statement))
59
66
  continue;
60
67
  if (!hasAnyFlag(statement.declarationList.flags, ts.NodeFlags.Const))
61
68
  continue;
62
69
  for (const declaration of statement.declarationList.declarations) {
63
70
  const literal = declaration.initializer ? defineLiteral(ts, declaration.initializer) : null;
64
- if (literal)
71
+ if (literal && (isExported(ts, statement) || exportsWorld(ts, sourceFile)))
65
72
  return literal;
66
73
  }
67
74
  }
68
75
  return null;
69
76
  }
77
+ /** Whether the file exports both `useTestWorld` and `useSandbox` as consts (the typed form re-exports them from the built world). */
78
+ function exportsWorld(ts, sourceFile) {
79
+ const exported = new Set();
80
+ for (const statement of sourceFile.statements) {
81
+ if (!ts.isVariableStatement(statement) || !isExported(ts, statement))
82
+ continue;
83
+ for (const declaration of statement.declarationList.declarations)
84
+ if (ts.isIdentifier(declaration.name))
85
+ exported.add(declaration.name.text);
86
+ }
87
+ return exported.has('useTestWorld') && exported.has('useSandbox');
88
+ }
70
89
  /** `stack` as the environment it names: the last segment of `".starcistacks/<env>"`; null when absent or not a literal. */
71
90
  function environmentOf(ts, literal) {
72
91
  const node = literal ? propertyOf(ts, literal, 'stack') : null;
@@ -152,7 +171,7 @@ function worldDeclaration(graph, ts, worldRoot, violations) {
152
171
  if (configFile && !literal) {
153
172
  violations.push({
154
173
  ruleId: RULE, path: configPath, line: 1, column: 1, slot: WORLD_SLOT,
155
- message: `${configPath} declares no world the machine can read. Declare it in the one named form \`${NAMED_FORM}\` (an exported const of a ${DEFINE} call with an object literal, imported from @starci/test-world); a default export is refused by R89 and is not read.`,
174
+ message: `${configPath} declares no world the machine can read. Declare it in the named form \`${NAMED_FORM}\` or the typed form \`${TYPED_FORM}\` (a const of a ${DEFINE} call with an object literal, imported from @starci/test-world); a default export is refused by R89 and is not read.`,
156
175
  });
157
176
  }
158
177
  return { configPath, configFile, literal };
@@ -0,0 +1,59 @@
1
+ import { declarationSurface, isEmittableSource } from '../lib/declaration-surface.mjs';
2
+ /** What to write, by what the classifier says to annotate. */
3
+ const HINTS = {
4
+ 'return type': 'Write the return type after the parameter list: `(): Result =>` or `function name(): Result`.',
5
+ 'variable type': 'Give the variable a type: `export const name: Result = ...`.',
6
+ 'parameter type': 'Give the parameter a type: `(value: Input)`.',
7
+ 'property type': 'Give the property a type: `name: Result = ...`.',
8
+ 'accessor type': 'Give the accessor a type: `get name(): Result` (a setter takes it from its parameter).',
9
+ 'destructured export': 'A destructuring pattern cannot carry a type per name: export each name as its own variable with a type, `export const name: Type = source.name`.',
10
+ 'exported value': 'Declare the type (an interface or a type alias) and annotate the export with it: `export const name: Shape = ...`.',
11
+ };
12
+ /** The `--isolatedDeclarations` flag name TypeScript ends its reasons with says nothing to the reader. */
13
+ const plain = (reason) => reason.replace(/ with --isolatedDeclarations\.?/, '').replace(/\.$/, '');
14
+ /**
15
+ * The rule. `ts` is the canon's own TypeScript (its peer dependency); the side's `module` option comes from the typed program when the file is linted with one.
16
+ *
17
+ * @param input - `ts` is the compiler.
18
+ * @returns An ESLint rule reporting each export of a TypeScript source whose type is inferred.
19
+ */
20
+ export const explicitSurfaceRule = ({ ts }) => ({
21
+ meta: {
22
+ type: 'problem',
23
+ docs: { description: 'An exported declaration states its type: the return type, variable type or parameter type is written, not inferred from a body or from other files.' },
24
+ schema: [],
25
+ messages: {
26
+ inferred: 'HFS_EXPLICIT_EXPORT_SURFACE: `{{name}}` is exported with an inferred type ({{reason}}), so importers cannot read it from this file and every one of them is linted again whenever the file changes. Annotate the {{annotate}}. {{hint}}',
27
+ },
28
+ },
29
+ create(context) {
30
+ return {
31
+ Program() {
32
+ const file = context.filename;
33
+ if (!isEmittableSource(file))
34
+ return;
35
+ const { sourceCode } = context;
36
+ const module = sourceCode.parserServices?.program?.getCompilerOptions().module;
37
+ const whole = { start: { line: 1, column: 0 }, end: { line: 1, column: 0 } };
38
+ let surface;
39
+ try {
40
+ surface = declarationSurface(ts, file, sourceCode.text, module);
41
+ }
42
+ catch {
43
+ surface = null;
44
+ }
45
+ if (surface === null) {
46
+ context.report({ loc: whole, messageId: 'inferred', data: { name: 'this file', reason: 'the declaration emit could not read it', annotate: 'exported value', hint: HINTS['exported value'] } });
47
+ return;
48
+ }
49
+ for (const problem of surface.problems) {
50
+ context.report({
51
+ loc: { start: sourceCode.getLocFromIndex(problem.start), end: sourceCode.getLocFromIndex(problem.start + problem.length) },
52
+ messageId: 'inferred',
53
+ data: { name: problem.name, reason: plain(problem.reason), annotate: problem.annotate, hint: HINTS[problem.annotate] },
54
+ });
55
+ }
56
+ },
57
+ };
58
+ },
59
+ });
@@ -0,0 +1,112 @@
1
+ /** A script file (`.js`, `.mjs`, `.cjs`, `.jsx`): it has no declaration emit and stands for its content. */
2
+ export const SCRIPT = /\.(?:[cm]?jsx?)$/;
3
+ /** A declaration file: it is its own surface. */
4
+ export const DECLARATION = /\.d\.[cm]?ts$/;
5
+ /** A TypeScript source file whose surface the declaration emit writes. */
6
+ export const TYPESCRIPT = /\.(?:[cm]?tsx?)$/;
7
+ /** Whether `file` is a TypeScript source (not a declaration file) the declaration emit reads. */
8
+ export const isEmittableSource = (file) => TYPESCRIPT.test(file) && !DECLARATION.test(file);
9
+ /** Whether `expression` is a JSX element, fragment, `null` or `undefined`, or a conditional of those: its type does not depend on any other file. */
10
+ function isJsxValue(ts, expression) {
11
+ if (expression === undefined)
12
+ return false;
13
+ let node = expression;
14
+ while (ts.isParenthesizedExpression(node))
15
+ node = node.expression;
16
+ if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node) || node.kind === ts.SyntaxKind.NullKeyword)
17
+ return true;
18
+ if (ts.isIdentifier(node))
19
+ return node.text === 'undefined';
20
+ return ts.isConditionalExpression(node) && isJsxValue(ts, node.whenTrue) && isJsxValue(ts, node.whenFalse);
21
+ }
22
+ /**
23
+ * Whether the function (or method) the declaration diagnostic at `start` points at has the type `JSX.Element | null | undefined` whatever its body
24
+ * 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
25
+ * 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.
26
+ */
27
+ function returnsOnlyJsx(ts, source, start) {
28
+ let found;
29
+ const find = (node) => {
30
+ if (found !== undefined || start < node.getFullStart() || start >= node.end)
31
+ return;
32
+ const named = (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name !== undefined && node.name.getStart(source) === start;
33
+ if (named || ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.getStart(source) === start)) {
34
+ found = node;
35
+ return;
36
+ }
37
+ ts.forEachChild(node, find);
38
+ };
39
+ find(source);
40
+ const fn = found;
41
+ if (fn === undefined || fn.type !== undefined || fn.body === undefined)
42
+ return false;
43
+ if (fn.asteriskToken !== undefined || (ts.getCombinedModifierFlags(fn) & ts.ModifierFlags.Async) !== 0)
44
+ return false;
45
+ if (!ts.isBlock(fn.body))
46
+ return isJsxValue(ts, fn.body);
47
+ let only = true;
48
+ const visit = (node) => {
49
+ if (!only || ts.isFunctionLike(node) || ts.isClassLike(node))
50
+ return;
51
+ if (ts.isReturnStatement(node) && node.expression !== undefined && !isJsxValue(ts, node.expression))
52
+ only = false;
53
+ ts.forEachChild(node, visit);
54
+ };
55
+ ts.forEachChild(fn.body, visit);
56
+ return only;
57
+ }
58
+ /** What to annotate for each isolated-declaration diagnostic code; any other code asks for the exported value's type. */
59
+ const ANNOTATE = new Map([
60
+ [9007, 'return type'], [9008, 'return type'], [9009, 'accessor type'], [9010, 'variable type'], [9011, 'parameter type'], [9012, 'property type'],
61
+ [9019, 'destructured export'], [9025, 'parameter type'],
62
+ ]);
63
+ /** The declaration kinds whose name labels the export a diagnostic sits in, innermost first. */
64
+ function nameOf(ts, source, start) {
65
+ let innermost = source;
66
+ const descend = (node) => {
67
+ if (start < node.getFullStart() || start >= node.end)
68
+ return;
69
+ innermost = node;
70
+ ts.forEachChild(node, descend);
71
+ };
72
+ ts.forEachChild(source, descend);
73
+ for (let node = innermost; node !== undefined && node !== source; node = node.parent) {
74
+ if (ts.isExportAssignment(node))
75
+ return 'default export';
76
+ if (ts.isBindingElement(node) && ts.isIdentifier(node.name))
77
+ return node.name.text;
78
+ if ((ts.isVariableDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isMethodDeclaration(node) || ts.isPropertyDeclaration(node) || ts.isPropertyAssignment(node) || ts.isGetAccessorDeclaration(node)) && node.name !== undefined && ts.isIdentifier(node.name))
79
+ return node.name.text;
80
+ if (ts.isFunctionDeclaration(node) && (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Default) !== 0)
81
+ return 'default export';
82
+ }
83
+ return 'default export';
84
+ }
85
+ /**
86
+ * The declaration emit of one TypeScript source and the exports it could not write explicitly (a type inferred from bodies and other files), or null
87
+ * when the compiler has no `transpileDeclaration` (before TypeScript 5.5). A declaration whose only diagnostics are components returning JSX has the
88
+ * surface its emit shows. `module` is the side's `module` compiler option, which the emit reads. A throw from the compiler propagates: the caller
89
+ * decides what an unreadable file means.
90
+ */
91
+ export function declarationSurface(ts, file, text, module) {
92
+ const emit = ts.transpileDeclaration;
93
+ if (emit === undefined)
94
+ return null;
95
+ const declared = emit.call(ts, text, { compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest, ...(module === undefined ? {} : { module }) }, fileName: file, reportDiagnostics: true });
96
+ const diagnostics = (declared.diagnostics ?? []);
97
+ if (diagnostics.length === 0)
98
+ return { outputText: declared.outputText, problems: [] };
99
+ const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
100
+ const problems = [];
101
+ for (const diagnostic of diagnostics) {
102
+ const exempt = (diagnostic.code === 9007 || diagnostic.code === 9008) && diagnostic.start !== undefined && returnsOnlyJsx(ts, source, diagnostic.start);
103
+ if (exempt)
104
+ continue;
105
+ const start = diagnostic.start ?? 0;
106
+ problems.push({
107
+ code: diagnostic.code, start, length: diagnostic.length ?? 0, name: nameOf(ts, source, start), annotate: ANNOTATE.get(diagnostic.code) ?? 'exported value',
108
+ reason: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').split('\n')[0] ?? '',
109
+ });
110
+ }
111
+ return { outputText: declared.outputText, problems };
112
+ }