@starci/hfs 5.0.7 → 5.1.0

package/report/stylelint-findings.d.mts

@@ -0,0 +1,23 @@
+/** A stylelint result as the `--formatter json` output carries it: the stylesheet and its warnings. */
+export interface StylelintFileResult {
+    source?: string;
+    warnings?: readonly {
+        rule?: string;
+        text: string;
+        line?: number;
+        column?: number;
+    }[];
+}
+/** One stylelint warning as a check finding. */
+export interface StylelintFinding {
+    engine: 'stylelint';
+    rule: string;
+    code: string;
+    level: 'error';
+    path: string;
+    line: number | null;
+    column: number | null;
+    message: string;
+}
+/** The findings of stylelint results; `appRoot` makes their paths app-relative. */
+export declare function stylelintFindings(results: readonly StylelintFileResult[], appRoot: string): StylelintFinding[];

package/report/stylelint-findings.mjs

@@ -0,0 +1,9 @@
+// stylelint-findings.mts - the stylelint results of the lint gate of `starci app check` as findings, one per warning, paths app-relative.
+import path from 'node:path';
+/** The findings of stylelint results; `appRoot` makes their paths app-relative. */
+export function stylelintFindings(results, appRoot) {
+    return results.flatMap((result) => (result.warnings ?? []).map((warning) => {
+        const rule = warning.rule || 'stylelint-error';
+        return { engine: 'stylelint', rule, code: rule, level: 'error', path: path.relative(appRoot, result.source ?? '').replace(/\\/g, '/'), line: warning.line ?? null, column: warning.column ?? null, message: warning.text };
+    }));
+}

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/hfs/ci-standard.yaml

@@ -37,7 +37,7 @@ defaults:
 # The steps that need a raised Node heap on the GitHub runner, matched on their `run` text, and the least heap they must declare in NODE_OPTIONS.
 heap:
   minMiB: 6144
-  steps: ['npm run typecheck', 'npm run lint', 'app lint', 'app coverage verify', 'npm run db:lint']
+  steps: ['npm run typecheck', 'npm run lint', 'app check --gate lint', 'app coverage verify', 'npm run db:lint']
 
 items:
   - id: candidate-trigger
@@ -77,7 +77,7 @@ items:
     check: ci-standard
   - id: sonar-lint-per-side
     title: the Sonar lint runs per side
-    requires: "a lint with a Sonar import (--out) names its side (--side be|fe); the reports are merged into reports/lint.sonar.json afterwards; no combined lint with Sonar"
+    requires: "a lint with a Sonar import (`starci app check --gate lint --out`) names its side (--side be|fe); the reports are merged into reports/lint.sonar.json afterwards; no combined lint with Sonar"
     covers: [app-ci, runtime]
     check: ci-standard
   - id: test-sharding

package/runtime/knowledge/hfs/rules.yaml

@@ -21,9 +21,9 @@ version: 3.1.0
 gates:
   pre-commit: the managed L0 hook runs app check --staged, managed-file drift, ESLint per side and stylelint on staged source, and prettier on staged files; typecheck and targeted specs belong to the op gate under R225
   pre-push: the managed app hook invokes the bundled push policy under R225; it starts no source check, build or test
-  settle: the op gate `starci gate run` over the op's changed files (merge guard, starci app lint --changed, codegen, tsc, the slice's specs; only findings new against the workflow's previous checkpoint block), re-read at starci kernel settle, which refuses a red done; a green settle commits the op's checkpoint on wf-<workflowId>
+  settle: the op gate `starci gate run` over the op's changed files (merge guard, starci app check, codegen, tsc, the slice's specs; only findings new against the workflow's previous checkpoint block), re-read at starci kernel settle, which refuses a red done; a green settle commits the op's checkpoint on wf-<workflowId>
   land: the workflow's finish, the only time main is touched - gate.mjs over the whole workflow branch against its merge-base with main, the merge guard, review.verify of the exact head that lands, the branch rebased onto main, then main fast-forwarded and pushed
-  ci: GitHub Actions runs the same pinned starci app lint, format:check, typecheck, unit with the per-file coverage threshold, build:be and build:fe, then the Sonar scan and gate
+  ci: GitHub Actions runs the same pinned starci app check --gate lint, format:check, typecheck, unit with the per-file coverage threshold, build:be and build:fe, then the Sonar scan and gate
   sonar: Sonar quality gate (knowledge/sonar-gate.yaml) - the imported lint findings, duplication, cognitive complexity and the coverage of the logic of be/src/modules at 100
   runtime: "`starci runtime check` (npm run check) of the StarCi runtime repository itself: scripts/checks/check-runtime.mjs runs node --check, scripts/hfs/runtime-check.mjs with knowledge/hfs/runtime-slots.yaml, and the retained self-checks"
 enforcerKinds:
@@ -229,7 +229,7 @@ rules:
     editions: [lite, full]
     docs: [docs/hfs-legacy-tooling.md#ci-and-hooks]
     code: "HFS_CI_MISSING_CANON"
-    law: "CI runs the pinned `starci app lint` (`npm run lint`), a clone never redirects `core.hooksPath` away from husky, and the folder a set `core.hooksPath` names holds the installed hooks in every checkout (husky's dispatcher in `.husky/_`), so no commit lands without the pre-commit gate."
+    law: "CI runs the pinned `starci app check --gate lint` (`npm run lint`), a clone never redirects `core.hooksPath` away from husky, and the folder a set `core.hooksPath` names holds the installed hooks in every checkout (husky's dispatcher in `.husky/_`), so no commit lands without the pre-commit gate."
     kinds: [check, codemod]
     gates: [land, ci]
     failureCodes: ["HFS_CI_MISSING_CANON", "HFS_HOOKS_PATH_REDIRECTED", "HFS_HOOKS_NOT_INSTALLED"]
@@ -924,7 +924,7 @@ rules:
     code: "BE_TEST_TOPOLOGY"
     editions: [lite, full]
     docs: [docs/quality-bar.md#r47-test-topology]
-    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`."
+    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`."
     kinds: [check, codemod, lint]
     gates: [land, ci]
     failureCodes: ["BE_TEST_TOPOLOGY", "BE_CONTRACT_UNGUARDED", "BE_UNIT_SPEC_NOT_STAGED"]
@@ -2503,7 +2503,7 @@ rules:
       - {path: packages/hfs/src/legacy-monorepo-coverage.spec.mjs, edition: full, codes: [HFS_MONO_WORKSPACES]}
   - id: R144
     code: "HFS_MONO_FE_WORKSPACE"
-    law: "Every fe app `fe/apps/<app>` is an npm workspace: its `package.json` is named `@<project>/<app>`, is private, declares its own runtime dependencies and has exactly the scripts `build: next build`, `dev: next dev`, `lint: starci app lint --workspace .`, `start: next start` and `typecheck: tsc --noEmit`; every fe package `fe/packages/<pkg>` is private with `build`, `typecheck` and the same workspace `lint` script."
+    law: "Every fe app `fe/apps/<app>` is an npm workspace: its `package.json` is named `@<project>/<app>`, is private, declares its own runtime dependencies and has exactly the scripts `build: next build`, `dev: next dev`, `start: next start` and `typecheck: tsc --noEmit`; every fe package `fe/packages/<pkg>` is private with `build` and `typecheck`; no workspace has a `lint` script, the app is linted once from the root with `starci app check --gate lint`."
     kinds: [check]
     gates: [settle, land, ci]
     failureCodes: ["HFS_MONO_FE_WORKSPACE"]
@@ -6525,3 +6525,54 @@ rules:
         source: owner
         quote: "The skeleton is the ready structure with its data missing; it is drawn from isLoading alone and from the reads the region shows."
         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."
+  - id: R368
+    code: "HFS_EXPLICIT_EXPORT_SURFACE"
+    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."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["HFS_EXPLICIT_EXPORT_SURFACE"]
+    enforcers:
+      - {kind: eslint-fe, id: explicit-export-surface}
+      - {kind: eslint-be, id: explicit-export-surface}
+    editions: [lite, full]
+    docs: [contexts/code/shared/typing.md]
+    templateNa: "A template exports nothing the lint result cache keys on."
+    proves:
+      - {path: packages/eslint-canon-fe/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+      - {path: packages/eslint-canon-be/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+      - {path: packages/hfs/src/explicit-surface.spec.mts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+    exemplifiedBy:
+      - {path: packages/eslint-canon-fe/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+    witness:
+      - {path: packages/eslint-canon-fe/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+      - {path: packages/eslint-canon-be/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+      - {path: packages/hfs/src/explicit-surface.spec.mts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+    cases:
+      - id: case-1
+        date: "2026-11-03"
+        source: owner
+        quote: "enforce it by lint"
+        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."
+  - id: R369
+    code: "FE_DIRECTIVE_FIRST"
+    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."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_DIRECTIVE_FIRST"]
+    enforcers:
+      - {kind: eslint-fe, id: directive-first}
+    editions: [lite, full]
+    docs: [contexts/code/fe/boundaries.md]
+    templateNa: "A template places its directives first."
+    proves:
+      - {path: packages/eslint-canon-fe/src/directive-first.spec.ts, editions: [lite, full], codes: [FE_DIRECTIVE_FIRST]}
+    exemplifiedBy:
+      - {path: packages/eslint-canon-fe/src/directive-first.spec.ts, editions: [lite, full], codes: [FE_DIRECTIVE_FIRST]}
+    witness:
+      - {path: packages/eslint-canon-fe/src/directive-first.spec.ts, editions: [lite, full], codes: [FE_DIRECTIVE_FIRST]}
+    cases:
+      - id: case-1
+        date: "2026-11-03"
+        source: owner
+        quote: "no lint caught it"
+        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."

package/runtime/knowledge/hfs/slots.yaml

@@ -1037,7 +1037,7 @@ slots:
     rules: [HFS_MANAGED_FILE_DRIFT]
   - id: app.starcistacks.cache
     profiles: [app]
-    # The committed result cache of `starci app check` and `starci app lint` (ruling app-check-cache, contexts/project/check-cache.md): JSON Lines records keyed by
+    # The committed result cache of `starci app check` (ruling app-check-cache, contexts/project/check-cache.md): JSON Lines records keyed by
     # content, one folder per family. App-owned and written only by the CLI; sync never renders, overwrites or judges it. Both editions.
     path: ".starcistacks/cache/"
     presence: optional

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/modules/kernel/failure-codes.yaml

@@ -3305,11 +3305,11 @@ HFS_CANON_PIN_DRIFT:
   kind: check-finding
 
 HFS_CI_MISSING_CANON:
-  title: "CI runs the pinned `starci app lint`; pre-push runs typecheck and lint"
+  title: "CI runs the pinned `starci app check --gate lint`; pre-push runs typecheck and lint"
   title_vi: "CI thiếu bước canon"
   meaning_vi: "Workflow/husky thiếu bước `<step>`. Cấu trúc chỉ được kiểm khi agent chạy — CI phải tự kiểm."
   causes_vi:
-    - "Vi phạm luật R13: CI phải chạy `starci app lint`; pre-push phải có `typecheck` + `lint`."
+    - "Vi phạm luật R13: CI phải chạy `starci app check --gate lint`; pre-push phải có `typecheck` + `lint`."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
   owner: op-retry
   kind: check-finding
@@ -3698,7 +3698,7 @@ HFS_CHECK_CACHE_MISSING:
 HFS_FORMAT:
   title: "Prettier is the only formatter"
   title_vi: "Chưa format bằng Prettier"
-  meaning_vi: "`<file>` chưa được format. Chạy `starci app lint --fix`."
+  meaning_vi: "`<file>` chưa được format. Chạy `npm run format`."
   causes_vi:
     - "Vi phạm luật R19: Prettier (config `@starci/prettier-config`) là formatter duy nhất; ESLint không còn luật định dạng."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
@@ -3899,7 +3899,7 @@ HFS_MODULE_TIER_INVALID:
 HFS_MONO_FE_WORKSPACE:
   title: "An fe workspace manifest breaks the workspace shape"
   title_vi: "Manifest của một workspace fe sai hình dạng"
-  meaning_vi: "Mỗi app fe `fe/apps/<app>` là workspace `@<project>/<app>`, private, có đúng các script build, dev, lint (`starci app lint --workspace .`), start và typecheck; mỗi gói `fe/packages/<pkg>` là private và có build, typecheck cùng script lint của workspace."
+  meaning_vi: "Mỗi app fe `fe/apps/<app>` là workspace `@<project>/<app>`, private, có đúng các script build, dev, start và typecheck; mỗi gói `fe/packages/<pkg>` là private và có build, typecheck; workspace không có script lint, lint chạy một lần từ gốc bằng `starci app check --gate lint`."
   causes_vi:
     - "Vi phạm luật R144: turbo chạy các task theo script của từng workspace; tên, script hoặc cờ private sai khiến build, lint hoặc typecheck của app bị bỏ qua hoặc chạy khác chuẩn."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: đặt tên `@<project>/<app>`, `\"private\": true` và đúng bộ script trong `package.json` của workspace đó."

package/runtime/scripts/api/node/run-node.d.mts

@@ -8,6 +8,11 @@ export interface HeavyNodeRequest {
     /** When supplied, this is the entire child environment, not an overlay. */
     readonly env?: NodeJS.ProcessEnv | undefined;
     readonly timeoutMs?: number | undefined;
+    /**
+     * The number of source files the child judges, when it is a whole-program lint of them. The CLI scales the liveness budget of the kind with it
+     * (ops/liveness.yaml heavy.timeoutMinutesPer1000Files): a larger side legitimately runs longer, and the budget still ends a hung child.
+     */
+    readonly files?: number | undefined;
     readonly maxBuffer: number;
 }
 /** Normal red exits are measurements; an interrupted child is not one. */

package/runtime/scripts/hfs/architecture/test-world-files.d.mts

@@ -18,9 +18,10 @@ interface WorldViolation {
  *    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

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/check.d.mts

@@ -1,5 +1,6 @@
-import { type SlotManifest } from './slots.mjs';
+import { type RepoView, type Resolver, type SlotManifest } from './slots.mjs';
 import { type Finding, type Summary, type Why } from './check-results.mjs';
+import { type FileRule } from './rule-memo.mjs';
 import type { Surface } from './architecture/index.mjs';
 export { REFUSAL_CODES } from './refusal-codes.mjs';
 export { checkDatabase } from './rules/database.mjs';
@@ -65,10 +66,24 @@ export interface RepositoryResult extends CheckResult {
     [key: string]: unknown;
 }
 type CheckManifest = SlotManifest;
+type CheckRepo = RepoView;
+type CheckResolver = Resolver;
 /** {code: {title, title_vi, meaning_vi, nextStep_vi}} for the codes asked for, read from the failure-code catalog under `root`. */
 export declare function readWhy(root?: string, codes?: readonly string[]): Record<string, Why>;
 /** Repository-relative tracked paths (git ls-files, posix separators; what the index holds, whatever the work tree shows). A directory that is not a Git work tree is a refusal. */
 export declare function trackedFiles(repoRoot: string): string[];
+/**
+ * The rules whose findings for a file depend on that file alone (and the files `deps` names), so the result cache keeps them per file by content hash
+ * (contexts/project/check-cache.md "Which step reuses what"): the plaintext secrets (R06 and the lite custody L17), the bypass markers (R303) and, in a side, the soft file size.
+ * Each rule's findings carry the path of the file they judge; `check-cache-structure-rules.spec.mts` proves that and the declared `deps` under a file-system recorder.
+ */
+export declare function perFileRules({ repoRoot, repo, resolver, inScope, isRoot }: {
+    repoRoot: string;
+    repo: CheckRepo;
+    resolver: CheckResolver;
+    inScope: (file: string) => boolean;
+    isRoot: boolean;
+}): FileRule[];
 /**
  * The check of one app. `repoRoot` is the app root (a side folder is checked as that side alone). `harness` ({ version }) is the CLI
  * that runs the check, whose version is the app's starci-harness pin (canon-pins.mjs). `declaration` overrides hfs.json

package/runtime/scripts/hfs/check.mjs

@@ -84,7 +84,8 @@ import { lintSuppressionFindings } from './rules/lint-suppression.mjs';
 import { bypassMarkerFindings } from './rules/bypass-markers.mjs';
 import { repoLocalCheckFindings } from './rules/repo-local-checks.mjs';
 import { liteSecretFindings } from './rules/lite-secrets.mjs';
-import { untrackedSecretFindings } from './rules/secrets.mjs';
+import { readmeManifestOf, untrackedSecretFindings } from './rules/secrets.mjs';
+import { memoFiles } from './rule-memo.mjs';
 import { liteStarciworkFinding, pathFindings } from './path-findings.mjs';
 import { onLintSurface } from './architecture/surface.mjs';
 import { checkAppRoot, trackedTreeView } from './architecture/hfs.mjs';
@@ -207,15 +208,26 @@ function minimumInstanceFindings(resolver, required, instances) {
     }
     return findings;
 }
-function contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, inScope, isRoot, appSide, editionDeclaration, manifest, phase }) {
+/**
+ * The rules whose findings for a file depend on that file alone (and the files `deps` names), so the result cache keeps them per file by content hash
+ * (contexts/project/check-cache.md "Which step reuses what"): the plaintext secrets (R06 and the lite custody L17), the bypass markers (R303) and, in a side, the soft file size.
+ * Each rule's findings carry the path of the file they judge; `check-cache-structure-rules.spec.mts` proves that and the declared `deps` under a file-system recorder.
+ */
+export function perFileRules({ repoRoot, repo, resolver, inScope, isRoot }) {
+    return [
+        { id: 'secret', run: (list) => liteSecretFindings({ repoRoot, files: list.filter((file) => inScope(file)), resolver, repo }), deps: (file) => readmeManifestOf(file) ?? [] },
+        { id: 'bypass-marker', run: (list) => bypassMarkerFindings({ repoRoot, files: list.filter((file) => inScope(file)) }) },
+        ...(isRoot ? [] : [{ id: 'size-soft', run: (list) => sizeSoftFindings({ repoRoot, resolver, files: list, inScope }) }]),
+    ];
+}
+function contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, fileFindings, inScope, isRoot, appSide, editionDeclaration, manifest, phase }) {
     const findings = [
         ...pinFindings({ repoRoot, files, profile: repo.profile, pins, only: scoped }),
-        ...liteSecretFindings({ repoRoot, files: files.filter((file) => inScope(file)), resolver, repo }),
+        ...fileFindings,
         ...editionFindings({ repoRoot, files: files.filter((file) => inScope(file)), repo, resolver, manifest, withDeclaration: editionDeclaration }),
         ...feStackFindings({ repoRoot, files: files.filter((file) => inScope(file)), repo, manifest }),
         ...repoLocalCheckFindings({ repoRoot, files }),
         ...lintSuppressionFindings({ repoRoot, files }),
-        ...bypassMarkerFindings({ repoRoot, files: files.filter((file) => inScope(file)) }),
         ...a15Findings({ repoRoot, files, all, repo, resolver, manifest, isRoot, appSide, inScope }),
     ];
     findings.push(...trackedStacksGateFindings({ repoRoot, files, all, repo, resolver, manifest, isRoot, inScope, existingFindings: findings }));
@@ -262,9 +274,8 @@ function scopeFindings({ repoRoot, root, harness, repo, resolver, files, all = f
     if (repo.kind === RUNTIME_KIND)
         return findings;
     const pins = canonPins({ root, ...(harness ? { harness } : {}) });
-    findings.push(...contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, inScope, isRoot, appSide, editionDeclaration, manifest, phase }));
-    if (!isRoot)
-        findings.push(...sizeSoftFindings({ repoRoot, resolver, files, inScope }));
+    const fileFindings = memoFiles(repoRoot, files, perFileRules({ repoRoot, repo, resolver, inScope, isRoot }));
+    findings.push(...contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, fileFindings, inScope, isRoot, appSide, editionDeclaration, manifest, phase }));
     return findings;
 }
 export function checkRepo({ repoRoot, root = skillRoot, harness, declaration, files, only, extraFindings = [], tree = files === undefined, manifest = loadSlotManifest({ root }), surface = 'all', phase = 'workspace' }) {

package/runtime/scripts/hfs/explicit-surface-rule.d.mts

@@ -0,0 +1,58 @@
+import type { TypeScript } from '../lib/ts-ast.mjs';
+/** The part of an ESLint rule context the rule reads (typescript-eslint's context satisfies it). */
+export interface SurfaceContext {
+    readonly filename: string;
+    readonly sourceCode: {
+        readonly text: string;
+        getLocFromIndex(index: number): {
+            line: number;
+            column: number;
+        };
+        readonly parserServices?: {
+            readonly program?: {
+                getCompilerOptions(): {
+                    module?: number;
+                };
+            } | null;
+        } | undefined;
+    };
+    report(descriptor: {
+        loc: {
+            start: {
+                line: number;
+                column: number;
+            };
+            end: {
+                line: number;
+                column: number;
+            };
+        };
+        messageId: string;
+        data: Record<string, string>;
+    }): void;
+}
+/** The rule module the factory returns: a plain ESLint rule with one message. */
+export interface SurfaceRule {
+    meta: {
+        type: 'problem';
+        docs: {
+            description: string;
+        };
+        schema: [];
+        messages: {
+            inferred: string;
+        };
+    };
+    create(context: SurfaceContext): {
+        Program(): void;
+    };
+}
+/**
+ * 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 declare const explicitSurfaceRule: ({ ts }: {
+    ts: TypeScript;
+}) => SurfaceRule;

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/gate-threshold.mjs

@@ -1,4 +1,4 @@
-// gate-threshold.mjs - the verdict of `starci app check` and `starci app lint` (owner ruling gate-threshold-20, 2026-10-30): green
+// gate-threshold.mjs - the verdict of `starci app check` (owner ruling gate-threshold-20, 2026-10-30): green
 // while fewer than GATE_ERROR_LIMIT error findings remain and none of them is a hard blocker, so a release is not held back finding
 // by finding (5, 4, 3, ...) by the last few structural nits. A plaintext secret, a failed boot proof, a forged check cache record and a broken migration block at
 // any count. Every finding is still printed; only the exit code changes. Typecheck, build and the tests are not judged here.