@starci/eslint-canon-fe 9.9.11 → 9.10.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 9.10.0
+
+- Added: `starci-fe/directive-first` (R369, `FE_DIRECTIVE_FIRST`) at error: a `"use client"` or `"use server"` directive is the first statement of its module; below an import it does nothing and `next build` refuses the file.
+- Added: `starci-fe/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; a component that returns only JSX, `null` or `undefined` is explicit. 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.
+- 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.
+- Changed: carry the bundled runtime of @starci/hfs 5.1.0 (the classifier, the rule factory, the rule catalog with R368, the canon pins).
+- Fixed: `no-swr-default-array` (R367) judges a `?? []` inside a `useMemo` callback or a `slotOfReads` projector by the hook that holds it, so a slot carrying the read's status is no longer reported.
+
+## 9.9.12
+
+- 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.
+
 ## 9.9.11
 
 - Changed: Recognize declared module hook roles through real hook-call provenance.

package/README.md

@@ -48,7 +48,7 @@ columns inside a joined card, where `PaneGrid` owns both (`FE_HAND_BUILT_PANES`)
 The spacing law (R350) leaves every distance to Grammar: `no-spacing-utility` refuses a padding, margin, gap
 or space utility (`p-*`, `px-*`, `m*-*`, `gap-*`, `space-*`, arbitrary values and variants included) in an app class
 string, where a role prop names the relation instead (`Stack`/`Cluster` `gap`, `Grid` `kind`, `PaneSection`, `Page`;
-`FE_SPACING_UTILITY`). It runs in the counting cohort (`COUNTING` of `src/lib/config.ts`): `starci app lint` reports
+`FE_SPACING_UTILITY`). It runs in the counting cohort (`COUNTING` of `src/lib/config.ts`): `starci app check --gate lint` reports
 and counts every finding at warn and fails on none, while `starci app codemod spacing-roles` migrates the app.
 
 The [button intent law](docs/button-intent.md) (CTA-6) requires every app Button and IconButton to
@@ -62,6 +62,16 @@ canonical page renderer. Only those exact input members may take `children`; ord
 renderers and shape records containing rendered trees remain refused. The selected canonical Grammar catalog owns
 semantic renderer bindings; universal code carries no concrete renderer spelling.
 
+The [explicit exported surface](../../contexts/code/shared/typing.md) (R368, SHARED-TYPING-5) is `explicit-export-surface`
+(`HFS_EXPLICIT_EXPORT_SURFACE`): an exported function's return type, an exported variable's type and a parameter's type are
+written where they are exported, never inferred from a body or from other files; a component that returns only JSX, `null` or
+`undefined` is explicit. It reports each export TypeScript's isolated declaration emit cannot write, at the offending span, and says
+which annotation to add. It reads the classifier the lint result cache reads (`declarationSurface`, the bundled
+`runtime/scripts/lib/declaration-surface.mjs`), so it reports exactly the files the cache counts as open.
+
+`projectGraph` and `projectGraphSnapshot` are the cache's two readers of the project graph the graph rules share: the first builds it
+afresh, the second answers from the graph the process has already built, which is how the ESLint child hands its graph to the cache.
+
 Regression specs belong to this package. Application front ends and Grammar libraries have no specs.
 
 ## The runtime copy

package/dist/directive-first.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A module directive is the first statement of its module (HFS R369, `FE_DIRECTIVE_FIRST`).
+ *
+ * `"use client"` and `"use server"` are directives only in the prologue, before any import or other statement. Below an import the string is an
+ * expression statement that does nothing, Prettier wraps it as `("use client")`, and `next build` stops with "The 'use client' directive must be placed
+ * before other expressions". ESLint's parser marks a real directive with `directive`, so a string statement of that text without one is misplaced.
+ */
+import { type Recommended } from "./lib/rule.js";
+/** A module directive stays in the prologue. */
+export declare const directiveFirst: import("./lib/rule.js").Rule<"misplaced", []>;
+/** The rules this law contributes to the plugin. */
+export declare const rules: {
+    "directive-first": import("./lib/rule.js").Rule<"misplaced", []>;
+};
+/** Every misplaced directive is a build error. */
+export declare const recommended: Recommended;

package/dist/directive-first.js

@@ -0,0 +1,37 @@
+/**
+ * A module directive is the first statement of its module (HFS R369, `FE_DIRECTIVE_FIRST`).
+ *
+ * `"use client"` and `"use server"` are directives only in the prologue, before any import or other statement. Below an import the string is an
+ * expression statement that does nothing, Prettier wraps it as `("use client")`, and `next build` stops with "The 'use client' directive must be placed
+ * before other expressions". ESLint's parser marks a real directive with `directive`, so a string statement of that text without one is misplaced.
+ */
+import { defineRule } from "./lib/rule.js";
+/** The directives Next.js reads from the prologue of a module. */
+const DIRECTIVES = new Set(["use client", "use server"]);
+/** A module directive stays in the prologue. */
+export const directiveFirst = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "R369: a 'use client' or 'use server' directive is the first statement of its module." },
+        schema: [],
+        messages: {
+            misplaced: 'FE_DIRECTIVE_FIRST: "{{directive}}" is not at the top of the module, so it is an expression that does nothing and `next build` refuses the file. Move it above every import and other statement.',
+        },
+    },
+    create(context) {
+        return {
+            ExpressionStatement(node) {
+                if (node.parent.type !== "Program" || "directive" in node && typeof node.directive === "string")
+                    return;
+                const expression = node.expression;
+                if (expression.type !== "Literal" || typeof expression.value !== "string" || !DIRECTIVES.has(expression.value))
+                    return;
+                context.report({ node, messageId: "misplaced", data: { directive: expression.value } });
+            },
+        };
+    },
+});
+/** The rules this law contributes to the plugin. */
+export const rules = { "directive-first": directiveFirst };
+/** Every misplaced directive is a build error. */
+export const recommended = { "starci-fe/directive-first": "error" };

package/dist/explicit-surface.d.ts

@@ -0,0 +1,7 @@
+import type { Recommended } from "./lib/rule.js";
+/** The rules this law contributes to the plugin. */
+export declare const rules: {
+    "explicit-export-surface": import("@typescript-eslint/utils/ts-eslint").RuleModule<"inferred", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener>;
+};
+/** Every exported type is written out, at error. */
+export declare const recommended: Recommended;

package/dist/explicit-surface.js

@@ -0,0 +1,19 @@
+/**
+ * The explicit exported surface (HFS R368, `HFS_EXPLICIT_EXPORT_SURFACE`): an exported declaration states its type, in the file that exports it.
+ *
+ * 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
+ * the result cache of `starci app check --gate lint` lints every importer again whenever the file changes (check-cache.md, ESLint). The rule
+ * reports each export the isolated declaration emit (`ts.transpileDeclaration`) cannot write without inference, where it is written, and says
+ * 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
+ * cache reads (`declarationSurface` of the bundled runtime), so the rule reports exactly the files the cache counts as open.
+ */
+import ts from "typescript";
+import { explicitSurfaceRule } from "#runtime/scripts/hfs/explicit-surface-rule.mjs";
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "explicit-export-surface": explicitSurfaceRule({ ts }),
+};
+/** Every exported type is written out, at error. */
+export const recommended = {
+    "starci-fe/explicit-export-surface": "error",
+};

package/dist/index.d.ts

@@ -106,5 +106,5 @@ export declare const starciTypedSourceConfig: ({ root }?: {
 }) => Linter.Config[];
 export { crossFileInputs } from "./lib/cross-file-inputs.js";
 export type { CrossFileInput } from "./lib/cross-file-inputs.js";
-export { projectGraph } from "./project-graph.js";
+export { projectGraph, projectGraphSnapshot } from "./project-graph.js";
 export type { ProjectGraphFinding, ProjectGraphSnapshot } from "./project-graph.js";

package/dist/index.js

@@ -27,6 +27,8 @@ import { recommended as hygieneRecommended, rules as hygieneRules } from "./hygi
 import { recommended as landmarkRecommended, rules as landmarkRules } from "./landmark.js";
 import { recommended as listsRecommended, rules as listsRules } from "./lists.js";
 import { recommended as loadingRecommended, rules as loadingRules } from "./loading.js";
+import { recommended as directiveFirstRecommended, rules as directiveFirstRules } from "./directive-first.js";
+import { recommended as explicitSurfaceRecommended, rules as explicitSurfaceRules } from "./explicit-surface.js";
 import { recommended as skeletonStatesRecommended, rules as skeletonStatesRules } from "./skeleton-states.js";
 import { recommended as lintEscapeRecommended, rules as lintEscapeRules } from "./lint-escape-hatch.js";
 import { recommended as namingRecommended, rules as namingRules } from "./naming.js";
@@ -74,6 +76,8 @@ const CONTRIBUTIONS = [
     { law: "landmark", rules: landmarkRules, recommended: landmarkRecommended },
     { law: "lists", rules: listsRules, recommended: listsRecommended },
     { law: "loading", rules: loadingRules, recommended: loadingRecommended },
+    { law: "directive-first", rules: directiveFirstRules, recommended: directiveFirstRecommended },
+    { law: "explicit-surface", rules: explicitSurfaceRules, recommended: explicitSurfaceRecommended },
     { law: "skeleton-states", rules: skeletonStatesRules, recommended: skeletonStatesRecommended },
     { law: "lint-escape-hatch", rules: lintEscapeRules, recommended: lintEscapeRecommended },
     { law: "naming", rules: namingRules, recommended: namingRecommended },
@@ -311,6 +315,6 @@ for (const addition of A14_CONTRIBUTIONS) {
     Object.assign(rules, addition.rules);
     Object.assign(recommended, addition.recommended);
 }
-// The result cache of `starci app lint` (contexts/project/check-cache.md) reads these two declarations of the installed canon.
+// The result cache of `starci app check --gate lint` (contexts/project/check-cache.md) reads these two declarations of the installed canon.
 export { crossFileInputs } from "./lib/cross-file-inputs.js";
-export { projectGraph } from "./project-graph.js";
+export { projectGraph, projectGraphSnapshot } from "./project-graph.js";

package/dist/lib/config.d.ts

@@ -29,7 +29,7 @@ export declare const IGNORED: readonly string[];
 export declare const BORROWED: Readonly<Record<string, "error">>;
 /**
  * The counting cohort: a rule the owner ruled to ship at `warn` for one release while a codemod moves apps onto the API
- * it asks for, each with the HFS rule id it enforces. `starci app lint` reports and counts its findings and never fails
+ * it asks for, each with the HFS rule id it enforces. `starci app check --gate lint` reports and counts its findings and never fails
  * on them; the next cohort moves the rule to error and deletes its entry. No other rule may be below error.
  */
 export declare const COUNTING: Readonly<Record<string, {

package/dist/lib/config.js

@@ -42,7 +42,7 @@ export const BORROWED = Object.freeze({
 const levelOf = (setting) => (Array.isArray(setting) ? setting[0] : setting);
 /**
  * The counting cohort: a rule the owner ruled to ship at `warn` for one release while a codemod moves apps onto the API
- * it asks for, each with the HFS rule id it enforces. `starci app lint` reports and counts its findings and never fails
+ * it asks for, each with the HFS rule id it enforces. `starci app check --gate lint` reports and counts its findings and never fails
  * on them; the next cohort moves the rule to error and deletes its entry. No other rule may be below error.
  */
 export const COUNTING = Object.freeze({
@@ -105,7 +105,7 @@ export const SLOT_FREE_RULES = Object.freeze([
     "outcome-kinds-exhaustive", "no-await-in-loop", "prefer-code-point", "prefer-string-raw", "no-nested-conditional", "no-void-operator", "no-unused-import",
     "prefer-export-from", "no-unused-prop-types", "media-has-caption", "max-params",
     "no-list-panel-padding", "no-hand-built-panes", "no-table-in-card", "no-heading-above-card", "no-selectable-tag-group", "no-fill-command-in-header", "no-app-surface-paint", "divider-full-bleed", "control-height", "selection-fill-no-check", "no-grammar-shim",
-    "no-swr-default-array", "no-foreign-slot-status", "no-validating-as-loading", "no-placeholder-object", "no-hand-skeleton",
+    "no-swr-default-array", "no-foreign-slot-status", "no-validating-as-loading", "no-placeholder-object", "no-hand-skeleton", "explicit-export-surface", "directive-first",
     "button-intent-required", "destructive-confirm-in-dialog", "single-commit-per-render", "no-commit-in-collection-item",
 ]);
 /** The source of a plain front-end tree: its `src/`. */

package/dist/lib/cross-file-inputs.d.ts

@@ -1,7 +1,7 @@
 /**
  * The files a rule of this canon reads that ESLint's own import graph does not carry.
  *
- * The result cache of `starci app lint` (contexts/project/check-cache.md, ESLint) re-lints a file when it or a file it reaches through imports
+ * The result cache of `starci app check --gate lint` (contexts/project/check-cache.md, ESLint) re-lints a file when it or a file it reaches through imports
  * changed. A rule that reads another file by path, with `fs` (a sibling, a directory listing, a manifest, a module file it follows by hand),
  * has an input the import graph cannot see, so the rule declares it here and the cache dirties the files that depend on it:
  *

package/dist/lib/cross-file-inputs.js

@@ -1,7 +1,7 @@
 /**
  * The files a rule of this canon reads that ESLint's own import graph does not carry.
  *
- * The result cache of `starci app lint` (contexts/project/check-cache.md, ESLint) re-lints a file when it or a file it reaches through imports
+ * The result cache of `starci app check --gate lint` (contexts/project/check-cache.md, ESLint) re-lints a file when it or a file it reaches through imports
  * changed. A rule that reads another file by path, with `fs` (a sibling, a directory listing, a manifest, a module file it follows by hand),
  * has an input the import graph cannot see, so the rule declares it here and the cache dirties the files that depend on it:
  *

package/dist/lib/why.d.ts

@@ -102,6 +102,16 @@ export declare const why: {
         en: string;
         fix: string;
     };
+    "directive-first": {
+        code: string;
+        en: string;
+        fix: string;
+    };
+    "explicit-export-surface": {
+        code: string;
+        en: string;
+        fix: string;
+    };
     "destructive-confirm-in-dialog": {
         code: string;
         en: string;

package/dist/lib/why.js

@@ -102,6 +102,16 @@ export const why = {
         en: "`<file>` draws a skeleton by hand.",
         fix: "Pass isLoading to the Grammar component and let it draw its loading structure; the block hands it the same-shape placeholder (FE-ERROR-1).",
     },
+    "directive-first": {
+        code: "FE_DIRECTIVE_FIRST",
+        en: "`<file>` has a `<what>` directive below another statement.",
+        fix: "Put the directive on the first line of the module, above every import; Next.js reads it only there.",
+    },
+    "explicit-export-surface": {
+        code: "HFS_EXPLICIT_EXPORT_SURFACE",
+        en: "`<file>` exports `<what>` with a type left to inference.",
+        fix: "Write the type where it is exported: the return type after the parameter list, the type of the exported variable, or the type of the parameter.",
+    },
     "destructive-confirm-in-dialog": {
         code: "FE_DESTRUCTIVE_CONFIRM_IN_DIALOG",
         en: "`<file>` renders a final destructive press outside its confirmation dialog.",

package/dist/project-graph.d.ts

@@ -19,7 +19,7 @@ export interface ProjectGraphSnapshot {
 /**
  * The findings every project-graph rule of this canon reports, per file, from one fresh build of the side's graph.
  *
- * The result cache of `starci app lint` calls this once for a side whose files changed and compares each file's findings with the recorded
+ * The result cache of `starci app check --gate lint` calls this once for a side whose files changed and compares each file's findings with the recorded
  * ones: a file whose graph findings differ is linted again by ESLint itself, so ESLint stays the only emitter of each message. It is the very
  * graph the rules read (same machine, same manifest, same filter), never a second judge.
  *
@@ -30,3 +30,17 @@ export declare const projectGraph: ({ repoRoot, injectedTypeScript }: {
     repoRoot: string;
     injectedTypeScript?: object;
 }) => ProjectGraphSnapshot;
+/**
+ * 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.
+ *
+ * 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
+ * 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
+ * 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
+ * same: `projectGraph` is a fresh build, this is the build the rules used.
+ *
+ * @param input - The side folder (`repoRoot`, the folder of the side's `eslint.config.mjs`).
+ * @returns The findings of the rules of `recommended`, keyed by path relative to the side folder.
+ */
+export declare const projectGraphSnapshot: ({ repoRoot }: {
+    repoRoot: string;
+}) => ProjectGraphSnapshot;

package/dist/project-graph.js

@@ -21,7 +21,7 @@ export const recommended = Object.fromEntries(mine.map((e) => [`starci-fe/${e.id
 /**
  * The findings every project-graph rule of this canon reports, per file, from one fresh build of the side's graph.
  *
- * The result cache of `starci app lint` calls this once for a side whose files changed and compares each file's findings with the recorded
+ * The result cache of `starci app check --gate lint` calls this once for a side whose files changed and compares each file's findings with the recorded
  * ones: a file whose graph findings differ is linted again by ESLint itself, so ESLint stays the only emitter of each message. It is the very
  * graph the rules read (same machine, same manifest, same filter), never a second judge.
  *
@@ -30,7 +30,22 @@ export const recommended = Object.fromEntries(mine.map((e) => [`starci-fe/${e.id
  */
 export const projectGraph = ({ repoRoot, injectedTypeScript }) => {
     resetProjectGraphs();
-    const graph = buildProjectGraph({ repoRoot, ...(injectedTypeScript === undefined ? {} : { injectedTypeScript }), runtimeRoot: RUNTIME });
+    return snapshotOf(buildProjectGraph({ repoRoot, ...(injectedTypeScript === undefined ? {} : { injectedTypeScript }), runtimeRoot: RUNTIME }));
+};
+/**
+ * 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.
+ *
+ * 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
+ * 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
+ * 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
+ * same: `projectGraph` is a fresh build, this is the build the rules used.
+ *
+ * @param input - The side folder (`repoRoot`, the folder of the side's `eslint.config.mjs`).
+ * @returns The findings of the rules of `recommended`, keyed by path relative to the side folder.
+ */
+export const projectGraphSnapshot = ({ repoRoot }) => snapshotOf(buildProjectGraph({ repoRoot, runtimeRoot: RUNTIME }));
+/** 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. */
+const snapshotOf = (graph) => {
     const byFile = {};
     for (const [file, findings] of graph.byFile) {
         for (const finding of findings) {

package/dist/skeleton-states.js

@@ -29,12 +29,17 @@ const rootOf = (input) => {
     }
     return null;
 };
-const enclosingFunction = (node) => {
+/**
+ * The outermost function around a node: the hook itself. A fold inside a `useMemo` callback or a `slotOfReads` projector is judged by what the
+ * hook returns of the read's status and by the slot it builds, not by the callback alone, which holds neither.
+ */
+const hookFunction = (node) => {
+    let found = null;
     for (let current = node.parent; current; current = current.parent) {
         if (current.type === "ArrowFunctionExpression" || current.type === "FunctionDeclaration" || current.type === "FunctionExpression")
-            return current;
+            found = current;
     }
-    return null;
+    return found;
 };
 const nameOfKey = (key) => (key.type === "Identifier" ? key.name : key.type === "Literal" && typeof key.value === "string" ? key.value : null);
 // -- no-swr-default-array -----------------------------------------------------------------------------------
@@ -79,7 +84,7 @@ const noSwrDefaultArray = defineRule({
                 const root = rootOf(node.left);
                 if (!root || !isHookResult(context, node, root))
                     return;
-                const fn = enclosingFunction(node);
+                const fn = hookFunction(node);
                 if (!fn)
                     return;
                 const text = source.getText(fn);

package/docs/surface-rules.md

@@ -4,7 +4,7 @@ Law module: `surface-rules.mjs`. HFS rule: R318. Canon: ANATOMY-2 and PADDING-0.
 
 ## `starci-fe/no-app-surface-paint`
 
-Finding code: `FE_GRAMMAR_LAYOUT_ONLY`. App classes carry layout. A raw `bg-surface` utility paints a surface and is refused, including conditional classes, class builders, responsive variants, important modifiers and opacity suffixes. Compose a painted Grammar surface such as `SurfaceCard`. Static props spreads keep the same obligations. Typed app lint follows imported colocated class declarations as well as local constants.
+Finding code: `FE_GRAMMAR_LAYOUT_ONLY`. App classes carry layout. A raw `bg-surface` utility paints a surface and is refused, including conditional classes, class builders, responsive variants, important modifiers and opacity suffixes. Compose a painted Grammar surface such as `SurfaceCard`. Static props spreads keep the same obligations. The typed lint of an app follows imported colocated class declarations as well as local constants.
 
 ## `starci-fe/no-list-panel-padding`
 
@@ -26,7 +26,7 @@ const Panel = () => <div className="px-4"><SurfaceCard><ListBox inset="panel" la
 
 ## `starci-fe/no-hand-built-panes`
 
-Finding code: `FE_HAND_BUILT_PANES`. A multi-pane frame is a `PaneGrid` of `Pane`s, which draws the dividers between panes, sizes the columns and collapses a side pane below medium. A vertical `Divider` used as a column seam is a pane frame drawn by hand: a vertical `Divider` (or the plain wrapper element that holds only it) standing among plain column elements (`div`, `aside`, `Region`) of a flex row, or a vertical `Divider` anywhere inside a `SurfaceCard composition="joined"`; and a joined card that holds a plain flex row of two or more columns as one of its own children. `joined` stacks bands divided by horizontal separators. A short vertical separator between controls of a toolbar, a `flex-col` stack, and a row whose classes cannot be read in the file are not judged. Typed app lint follows imported colocated class declarations.
+Finding code: `FE_HAND_BUILT_PANES`. A multi-pane frame is a `PaneGrid` of `Pane`s, which draws the dividers between panes, sizes the columns and collapses a side pane below medium. A vertical `Divider` used as a column seam is a pane frame drawn by hand: a vertical `Divider` (or the plain wrapper element that holds only it) standing among plain column elements (`div`, `aside`, `Region`) of a flex row, or a vertical `Divider` anywhere inside a `SurfaceCard composition="joined"`; and a joined card that holds a plain flex row of two or more columns as one of its own children. `joined` stacks bands divided by horizontal separators. A short vertical separator between controls of a toolbar, a `flex-col` stack, and a row whose classes cannot be read in the file are not judged. The typed lint of an app follows imported colocated class declarations.
 
 Invalid:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "9.9.11",
+  "version": "9.10.0",
   "description": "Universal front-end lint laws for TypeScript and Next.js, independent of the selected Grammar family.",
   "type": "module",
   "license": "MIT",

package/runtime/bundle.json

@@ -125,6 +125,7 @@
     "scripts/hfs/declaration-shape.mjs",
     "scripts/hfs/declaration-slots.mjs",
     "scripts/hfs/edition-slots.mjs",
+    "scripts/hfs/explicit-surface-rule.mjs",
     "scripts/hfs/linear-text.mjs",
     "scripts/hfs/param-names.mjs",
     "scripts/hfs/path-findings.mjs",
@@ -150,6 +151,7 @@
     "scripts/hfs/trailing-slashes.mjs",
     "scripts/hfs/typescript-programs.mjs",
     "scripts/hfs/view.mjs",
+    "scripts/lib/declaration-surface.mjs",
     "scripts/lib/dockerfile.mjs",
     "scripts/lib/env.mjs",
     "scripts/lib/event-contract.mjs",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,42 +31,42 @@ pins:
     source: packages/event-stream/package.json
     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.'
   '@starci/grammar':
-    version: 0.21.11
+    version: 0.21.13
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     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.'
   '@starci/eslint-canon-be':
-    version: 3.11.18
+    version: 3.12.0
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     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.'
   '@starci/eslint-canon-fe':
-    version: 9.9.11
+    version: 9.10.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     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.'
   '@starci/eslint-grammar-core':
-    version: 0.21.11
+    version: 0.21.13
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.21.11
+    version: 0.21.13
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-offset-pop/package.json
     why: 'the Offset Pop Grammar component API lint, versioned with @starci/grammar; its shared component contract comes from the StarCi family lint without copying rules.'
   '@starci/stylelint-canon':
-    version: 2.5.0
+    version: 2.5.1
     group: starci
     install: registry
     side: fe
@@ -92,7 +92,7 @@ pins:
     source: packages/jest-preset/package.json
     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.'
   '@starci/test-world':
-    version: 1.3.3
+    version: 1.3.4
     group: starci
     install: registry
     side: be
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     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.'
   '@starci/hfs':
-    version: 5.0.7
+    version: 5.1.0
     group: starci
     install: registry
     side: both

package/runtime/knowledge/sonar-gate.yaml

@@ -40,11 +40,11 @@ newCode:
     metric: new_security_hotspots_reviewed
     minReviewedPercent: 100
     unreviewedMax: 0
-# The whole code, not only the new code. Every finding of the HFS canon reaches Sonar through ONE entry, `starci app lint`
+# The whole code, not only the new code. Every finding of the HFS canon reaches Sonar through ONE entry, `starci app check --gate lint --out`
 # (packages/hfs, contract changes hfs-sonar-import and hfs-lint-entry). CI runs it per side with --side and --out,
 # then merges rules by id and joins issues into ONE file, reports/lint.sonar.json, named by sonar.externalIssuesReportPaths; the gate holds the open-issue count of
 # the whole project at zero. The file carries three engines:
-#   starci-hfs   the repository findings of `starci app check` (managed files, tree, pins, CI, contracts; the rule id is the finding code)
+#   starci-hfs   the repository findings of the gates a run selects (managed files, tree, pins, CI, contracts; the rule id is the finding code)
 #   eslint       ESLint's json over the repository (the BE and FE canon plugins alike, per-file and project-graph rules)
 #   stylelint    stylelint's json over the style glob (front ends)
 # The engines share ONE placement rule (a finding on a file Sonar does not index is filed on the first source file); Sonar's own

package/runtime/scripts/hfs/architecture/test-world-files.mjs

@@ -15,9 +15,10 @@ import { byCodeUnit } from '../../lib/list.mjs';
  *    its own slot, be.tests.world.kit) plus files at its root whose role suffix is in ruleParams.be.suffixes
  *    (`stripe.client.ts`, `checkout.contracts.ts`, `test-world.config.ts`, ...). Every tracked file below the world root is
  *    matched by the slot's own entries through `allowsFile`.
- * 2. The declaration. `test-world.config.ts` declares the world in ONE form, the named export R89 allows:
- *    `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })` (an exported `const` initialized by a
- *    `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
+ * 2. The declaration. `test-world.config.ts` declares the world in a named form R89 allows: the destructured export
+ *    `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })`, or the typed form
+ *    `const world: TestWorldApi = defineTestWorld({ ... })` whose `useTestWorld` and `useSandbox` are exported consts typed from
+ *    `TestWorldApi` (a `const` initialized by a `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
  *    read) is refused: the world it declares could not be judged.
  * 3. Fakes against the stack (owner refinement 2026-09-30). Every service the stack declares runs real in the world; a fake
  *    (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/';
 const CONFIG_FILE = 'test-world.config.ts';
 const DEFINE = 'defineTestWorld';
 const NAMED_FORM = `export const { useTestWorld, useSandbox } = ${DEFINE}({ ... })`;
+const TYPED_FORM = `const world: TestWorldApi = ${DEFINE}({ ... })` + ' with export const useTestWorld / useSandbox typed from it';
 const defaultEnvironment = DEFAULT_ENVIRONMENT;
 const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const unwrap = (ts, node) => unwrapEach(ts, node, [ts.isParenthesizedExpression, ts.isAsExpression, ts.isSatisfiesExpression]);
@@ -52,21 +54,38 @@ function defineLiteral(ts, expression) {
     const literal = first ? unwrap(ts, first) : null;
     return literal && ts.isObjectLiteralExpression(literal) ? literal : null;
 }
-/** The declaration of the world: the object literal of an exported `const` initialized by `defineTestWorld({ ... })`, or null. */
+/**
+ * The declaration of the world: the object literal of a top-level `const` initialized by `defineTestWorld({ ... })`, or null. The config
+ * exports `useTestWorld` and `useSandbox` either by destructuring that call (the original form) or, typed, from the world the call
+ * built: `const world: TestWorldApi = defineTestWorld({ ... })` with `export const useTestWorld: TestWorldApi["useTestWorld"] = world.useTestWorld`.
+ * Both are read; a world no exported name reaches is refused by the caller.
+ */
 function configLiteral(ts, sourceFile) {
     for (const statement of sourceFile.statements) {
-        if (!ts.isVariableStatement(statement) || !isExported(ts, statement))
+        if (!ts.isVariableStatement(statement))
             continue;
         if (!hasAnyFlag(statement.declarationList.flags, ts.NodeFlags.Const))
             continue;
         for (const declaration of statement.declarationList.declarations) {
             const literal = declaration.initializer ? defineLiteral(ts, declaration.initializer) : null;
-            if (literal)
+            if (literal && (isExported(ts, statement) || exportsWorld(ts, sourceFile)))
                 return literal;
         }
     }
     return null;
 }
+/** Whether the file exports both `useTestWorld` and `useSandbox` as consts (the typed form re-exports them from the built world). */
+function exportsWorld(ts, sourceFile) {
+    const exported = new Set();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement) || !isExported(ts, statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations)
+            if (ts.isIdentifier(declaration.name))
+                exported.add(declaration.name.text);
+    }
+    return exported.has('useTestWorld') && exported.has('useSandbox');
+}
 /** `stack` as the environment it names: the last segment of `".starcistacks/<env>"`; null when absent or not a literal. */
 function environmentOf(ts, literal) {
     const node = literal ? propertyOf(ts, literal, 'stack') : null;
@@ -152,7 +171,7 @@ function worldDeclaration(graph, ts, worldRoot, violations) {
     if (configFile && !literal) {
         violations.push({
             ruleId: RULE, path: configPath, line: 1, column: 1, slot: WORLD_SLOT,
-            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.`,
+            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.`,
         });
     }
     return { configPath, configFile, literal };

package/runtime/scripts/hfs/explicit-surface-rule.mjs

@@ -0,0 +1,59 @@
+import { declarationSurface, isEmittableSource } from '../lib/declaration-surface.mjs';
+/** What to write, by what the classifier says to annotate. */
+const HINTS = {
+    'return type': 'Write the return type after the parameter list: `(): Result =>` or `function name(): Result`.',
+    'variable type': 'Give the variable a type: `export const name: Result = ...`.',
+    'parameter type': 'Give the parameter a type: `(value: Input)`.',
+    'property type': 'Give the property a type: `name: Result = ...`.',
+    'accessor type': 'Give the accessor a type: `get name(): Result` (a setter takes it from its parameter).',
+    '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`.',
+    'exported value': 'Declare the type (an interface or a type alias) and annotate the export with it: `export const name: Shape = ...`.',
+};
+/** The `--isolatedDeclarations` flag name TypeScript ends its reasons with says nothing to the reader. */
+const plain = (reason) => reason.replace(/ with --isolatedDeclarations\.?/, '').replace(/\.$/, '');
+/**
+ * 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.
+ *
+ * @param input - `ts` is the compiler.
+ * @returns An ESLint rule reporting each export of a TypeScript source whose type is inferred.
+ */
+export const explicitSurfaceRule = ({ ts }) => ({
+    meta: {
+        type: 'problem',
+        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.' },
+        schema: [],
+        messages: {
+            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}}',
+        },
+    },
+    create(context) {
+        return {
+            Program() {
+                const file = context.filename;
+                if (!isEmittableSource(file))
+                    return;
+                const { sourceCode } = context;
+                const module = sourceCode.parserServices?.program?.getCompilerOptions().module;
+                const whole = { start: { line: 1, column: 0 }, end: { line: 1, column: 0 } };
+                let surface;
+                try {
+                    surface = declarationSurface(ts, file, sourceCode.text, module);
+                }
+                catch {
+                    surface = null;
+                }
+                if (surface === null) {
+                    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'] } });
+                    return;
+                }
+                for (const problem of surface.problems) {
+                    context.report({
+                        loc: { start: sourceCode.getLocFromIndex(problem.start), end: sourceCode.getLocFromIndex(problem.start + problem.length) },
+                        messageId: 'inferred',
+                        data: { name: problem.name, reason: plain(problem.reason), annotate: problem.annotate, hint: HINTS[problem.annotate] },
+                    });
+                }
+            },
+        };
+    },
+});

package/runtime/scripts/hfs/rules/read.mjs

@@ -3,8 +3,21 @@ import fs from 'node:fs';
 import path from 'node:path';
 /** Files above this size are not read by a tree check (a tracked binary or a generated dump is no source of these laws). */
 const MAX_READ_BYTES = 1024 * 1024;
+let sink = null;
+/** Runs `run` with every `readText` / `readJson` it makes reported to `onRead` (before the read), and returns its value. */
+export function recordReads(onRead, run) {
+    const before = sink;
+    sink = onRead;
+    try {
+        return run();
+    }
+    finally {
+        sink = before;
+    }
+}
 /** The text of `rel` under `repoRoot`, or null when it is absent, unreadable, over MAX_READ_BYTES or binary. */
 export function readText(repoRoot, rel) {
+    sink?.(repoRoot, rel);
     try {
         const target = path.join(repoRoot, rel);
         if (fs.statSync(target).size > MAX_READ_BYTES)

package/runtime/scripts/lib/declaration-surface.mjs

@@ -0,0 +1,112 @@
+/** A script file (`.js`, `.mjs`, `.cjs`, `.jsx`): it has no declaration emit and stands for its content. */
+export const SCRIPT = /\.(?:[cm]?jsx?)$/;
+/** A declaration file: it is its own surface. */
+export const DECLARATION = /\.d\.[cm]?ts$/;
+/** A TypeScript source file whose surface the declaration emit writes. */
+export const TYPESCRIPT = /\.(?:[cm]?tsx?)$/;
+/** Whether `file` is a TypeScript source (not a declaration file) the declaration emit reads. */
+export const isEmittableSource = (file) => TYPESCRIPT.test(file) && !DECLARATION.test(file);
+/** 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;
+}
+/** What to annotate for each isolated-declaration diagnostic code; any other code asks for the exported value's type. */
+const ANNOTATE = new Map([
+    [9007, 'return type'], [9008, 'return type'], [9009, 'accessor type'], [9010, 'variable type'], [9011, 'parameter type'], [9012, 'property type'],
+    [9019, 'destructured export'], [9025, 'parameter type'],
+]);
+/** The declaration kinds whose name labels the export a diagnostic sits in, innermost first. */
+function nameOf(ts, source, start) {
+    let innermost = source;
+    const descend = (node) => {
+        if (start < node.getFullStart() || start >= node.end)
+            return;
+        innermost = node;
+        ts.forEachChild(node, descend);
+    };
+    ts.forEachChild(source, descend);
+    for (let node = innermost; node !== undefined && node !== source; node = node.parent) {
+        if (ts.isExportAssignment(node))
+            return 'default export';
+        if (ts.isBindingElement(node) && ts.isIdentifier(node.name))
+            return node.name.text;
+        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))
+            return node.name.text;
+        if (ts.isFunctionDeclaration(node) && (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Default) !== 0)
+            return 'default export';
+    }
+    return 'default export';
+}
+/**
+ * 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
+ * when the compiler has no `transpileDeclaration` (before TypeScript 5.5). A declaration whose only diagnostics are components returning JSX has the
+ * surface its emit shows. `module` is the side's `module` compiler option, which the emit reads. A throw from the compiler propagates: the caller
+ * decides what an unreadable file means.
+ */
+export function declarationSurface(ts, file, text, module) {
+    const emit = ts.transpileDeclaration;
+    if (emit === undefined)
+        return null;
+    const declared = emit.call(ts, text, { compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest, ...(module === undefined ? {} : { module }) }, fileName: file, reportDiagnostics: true });
+    const diagnostics = (declared.diagnostics ?? []);
+    if (diagnostics.length === 0)
+        return { outputText: declared.outputText, problems: [] };
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const problems = [];
+    for (const diagnostic of diagnostics) {
+        const exempt = (diagnostic.code === 9007 || diagnostic.code === 9008) && diagnostic.start !== undefined && returnsOnlyJsx(ts, source, diagnostic.start);
+        if (exempt)
+            continue;
+        const start = diagnostic.start ?? 0;
+        problems.push({
+            code: diagnostic.code, start, length: diagnostic.length ?? 0, name: nameOf(ts, source, start), annotate: ANNOTATE.get(diagnostic.code) ?? 'exported value',
+            reason: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').split('\n')[0] ?? '',
+        });
+    }
+    return { outputText: declared.outputText, problems };
+}

package/runtime/scripts/lib/sonar-syntax-rules.mjs

@@ -1,6 +1,6 @@
 // sonar-syntax-rules.mjs - the ESLint rules that keep a TypeScript app clear of the smells SonarCloud flagged in the example apps, judged on
 // the syntax tree alone (no type information, no dependency). Both lint canons (@starci/eslint-canon-be and -fe) publish them from their
-// bundled runtime copy under the names below, so a product inherits them and `starci app lint` refuses the finding before the scan sees it.
+// bundled runtime copy under the names below, so a product inherits them and `starci app check --gate lint` refuses the finding before the scan sees it.
 // Each message names the Sonar rule it stands for, and a rule judges the files the example scans judge: a unit or end-to-end spec is outside the
 // scan (`sonar.exclusions`), so it is outside these rules. The rules that need the type checker (S1874, S6551, S7503) are borrowed from
 // typescript-eslint by the canon factories; the one that needs a regex ambiguity analysis (S8786) runs in the runtime's own `sonar-rules` check.

package/runtime/scripts/lib/sonar-way.mjs

@@ -1,5 +1,5 @@
 // sonar-way.mjs - the Sonar way TypeScript profile (the default quality profile sonar.starci.org and SonarCloud apply) as ESLint rules:
-// the one mapping both lint canons (@starci/eslint-canon-be and -fe) publish, so `starci app lint` in the op loop refuses what the scan would
+// the one mapping both lint canons (@starci/eslint-canon-be and -fe) publish, so `starci app check --gate lint` in the op loop refuses what the scan would
 // raise while the code is written. The base is eslint-plugin-sonarjs's recommended config, SonarSource's own port of Sonar way (each rule's
 // docs url names its S-id); its rules the canons already publish in another form stay with that owner (SONAR_WAY_OWNED), and the Sonar way
 // rules SonarSource builds on other ESLint rules are SONAR_WAY_EXTRA. Every rule is `error`; no rule is left to the server because its port