@starci/eslint-canon-be 3.8.18 → 3.8.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.8.20 - 2026-10-30
4
+
5
+ - Changed: the bundled canon pins name hfs 4.11.21 (the one-command urgent release), eslint-canon-be 3.8.20, eslint-canon-fe 9.5.22 and the Grammar family 0.15.33. No rule changed.
6
+
7
+ ## 3.8.19 - 2026-10-30
8
+
9
+ - Changed: `unit-test-colocated` (R47) accepts the spec beside a file its slot declares as logic (`HfsSlot.logic`, `src/lib/unit-spec.ts`) as an optional logic-role spec, so the lite passport specs are unit specs and the spec-form rules (R48, R281) apply to them; a spec beside an undeclared file that plays no role is still refused. Spec: `src/unit-spec-declared-logic.spec.ts`.
10
+ - Changed: the bundled slot manifest carries the `logic` field (passport declares its tokens, password and cookie files) and the object-storage slot's `object-storage.*` names; the bundled `allows.mjs` and manifest shape admit them; the bundled architecture machine takes a typed-configuration JWT audience (BE_AUTH_JWT_OWN_JWKS, hfs 4.11.20); the bundled canon pins name hfs 4.11.20, jest-preset 2.5.2, eslint-canon-be 3.8.19, eslint-canon-fe 9.5.21 and the Grammar family 0.15.32.
11
+
3
12
  ## 3.8.18 - 2026-10-30
4
13
 
5
14
  - Changed: the bundled canon pins name hfs 4.11.19 (the schedule scanner reads interpolated identifiers and const-named SQL), eslint-canon-be 3.8.18, eslint-canon-fe 9.5.20 and the Grammar family 0.15.31. No rule changed.
@@ -51,6 +51,8 @@ export interface HfsSlot {
51
51
  readonly trigger?: string;
52
52
  readonly coverage?: string;
53
53
  readonly allows?: readonly string[];
54
+ /** The files of the slot that carry logic without a logic-role suffix (names relative to the slot path): measured like a logic role, each with its optional spec beside it. */
55
+ readonly logic?: readonly string[];
54
56
  /** The one special part a file slot plays that a rule reads: `entity-registry` (persistence.md BE-PERSISTENCE-3). */
55
57
  readonly role?: string;
56
58
  /** The side-relative path patterns of the only files that may import this file by deep path. */
@@ -27,7 +27,7 @@ export declare const isServiceSpecFile: (hfs: HfsView, filename: string) => bool
27
27
  */
28
28
  export declare const unitRoles: (hfs: HfsView) => readonly HfsUnitRole[];
29
29
  /**
30
- * The unit-tested role whose spec a file is (`<name>.<role>.spec.ts`, in the role's slot), or null.
30
+ * The unit-tested role whose spec a file is (`<name>.<role>.spec.ts`, in the role's slot, or the spec beside a declared logic file), or null.
31
31
  *
32
32
  * @param {object} hfs - The HFS view.
33
33
  * @param {string} filename - The linted file.
@@ -5,7 +5,8 @@
5
5
  * only. Only a `<name>.<role>.spec.ts` beside `<name>.<role>.ts` is a legitimate unit spec (R47): of a spec-required unit role
6
6
  * (`ruleParams.be.unitRoles`: a service, a cli command) anywhere its slot admits, and of any other LOGIC role (`ruleParams.be.logicRoles`: a policy,
7
7
  * a client, a guard, a mapper, ...) inside a slot whose `coverage` is required, where the spec is optional (the file owes 100 per file, not a spec of
8
- * its own). So is the spec of a door of a feature kind that has no service of its own
8
+ * its own), and so is `<file>.spec.ts` beside a logic file its slot declares (`logic`), measured like a logic role. So is the spec of a door of a
9
+ * feature kind that has no service of its own
9
10
  * (`<provider>.webhook.spec.ts`, `<channel>.gateway.spec.ts`, `<channel>.subscription.spec.ts` beside its door, in the kind's slot);
10
11
  * the quality rules of R48 judge the service specs.
11
12
  */
@@ -45,8 +46,24 @@ const inCoverageSlot = (hfs, filename) => {
45
46
  const optionalRoles = (hfs) => (hfs.ruleParams.logicRoles ?? []).filter((role) => !unitRoles(hfs).some((unit) => unit.role === role)).map((role) => ({ role, spec: `${role}.spec`, optional: true }));
46
47
  /** Whether a role admits a file by its slot (a role with no slot admits any slot; an optional logic role only a coverage-required slot). */
47
48
  const inRoleSlot = (hfs, role, filename) => (role.optional === true ? inCoverageSlot(hfs, filename) : role.slot === undefined || hfs.slotOf(filename) === role.slot);
49
+ /** The path of a classified file below the instance root of its slot. */
50
+ const slotRelative = (found) => (found.root !== undefined && found.path.startsWith(`${found.root}/`) ? found.path.slice(found.root.length + 1) : baseOf(found.path));
48
51
  /**
49
- * The unit-tested role whose spec a file is (`<name>.<role>.spec.ts`, in the role's slot), or null.
52
+ * The optional spec role of a spec beside a logic file its slot declares (`logic`): `passport.tokens.spec.ts` beside the declared
53
+ * `passport.tokens.ts` gives `{ role: "tokens", spec: "tokens.spec" }`, so the subject resolves as a logic role's does. It holds for that
54
+ * one declared file only, never for another `*.tokens.ts`, and adds no role name to the manifest.
55
+ */
56
+ const declaredLogicRole = (hfs, filename) => {
57
+ const found = hfs.classify(filename);
58
+ const logic = found.slot === undefined ? undefined : hfs.slot(found.slot)?.logic;
59
+ const subject = slotRelative(found).replace(/\.spec\.ts$/, ".ts");
60
+ if (logic?.includes(subject) !== true)
61
+ return null;
62
+ const role = subject.slice(0, -".ts".length).split(".").pop() ?? "";
63
+ return { role, spec: `${role}.spec`, optional: true };
64
+ };
65
+ /**
66
+ * The unit-tested role whose spec a file is (`<name>.<role>.spec.ts`, in the role's slot, or the spec beside a declared logic file), or null.
50
67
  *
51
68
  * @param {object} hfs - The HFS view.
52
69
  * @param {string} filename - The linted file.
@@ -56,7 +73,7 @@ export const unitRoleOfSpec = (hfs, filename) => {
56
73
  if (!isUnitSpecFile(hfs, filename))
57
74
  return null;
58
75
  const name = baseOf(filename);
59
- return [...unitRoles(hfs), ...optionalRoles(hfs)].find((role) => name.endsWith(`.${role.spec}.ts`) && inRoleSlot(hfs, role, filename)) ?? null;
76
+ return [...unitRoles(hfs), ...optionalRoles(hfs)].find((role) => name.endsWith(`.${role.spec}.ts`) && inRoleSlot(hfs, role, filename)) ?? declaredLogicRole(hfs, filename);
60
77
  };
61
78
  /** Whether a file is the spec of a value role (`ruleParams.be.valueRoles`: a zod schema): its subject is a declared value, so the spec parses it and builds no testing module. */
62
79
  export const isValueRoleSpec = (hfs, filename) => {
package/dist/testing.js CHANGED
@@ -123,11 +123,11 @@ const BANNED_TEST_FILE = /(?:\.test|\.int-spec|\.harness-spec)\.[cm]?[jt]sx?$/;
123
123
  export const unitTestColocated = {
124
124
  meta: {
125
125
  type: "problem",
126
- docs: { description: "Only the unit-tested roles (`ruleParams.be.unitRoles`: a `<name>.service.ts`, a cli command `<name>.cli.ts` of `src/features/cli`) own a REQUIRED unit spec, each beside it as `<name>.<role>.spec.ts`; any other logic role (`ruleParams.be.logicRoles`: policy, client, guard, mapper, ...) inside a slot whose coverage is required may have one; any other unit spec is a finding, and there are only the spec kinds `spec`, `e2e-spec`, `integration-spec` and `contract-spec`." },
126
+ docs: { description: "Only the unit-tested roles (`ruleParams.be.unitRoles`: a `<name>.service.ts`, a cli command `<name>.cli.ts` of `src/features/cli`) own a REQUIRED unit spec, each beside it as `<name>.<role>.spec.ts`; any other logic role (`ruleParams.be.logicRoles`: policy, client, guard, mapper, ...) inside a slot whose coverage is required, and any logic file a slot declares (`logic`), may have one; any other unit spec is a finding, and there are only the spec kinds `spec`, `e2e-spec`, `integration-spec` and `contract-spec`." },
127
127
  schema: [],
128
128
  messages: {
129
129
  suffix: "`{{name}}` is a banned kind of test file. A test is a `<name>.service.spec.ts` unit beside its service, or a `*.e2e-spec.ts`, `*.integration-spec.ts` or `*.contract-spec.ts` under its `src/tests/` folder; there is no `.test.ts`, `.int-spec.ts` or `.harness-spec.ts`.",
130
- notService: "`{{name}}` is a unit spec of something that carries no unit-tested logic here. A unit spec sits beside a `<name>.<role>.ts` of a spec-required role (a service, a cli command of `src/features/cli`) or of a logic role (`ruleParams.be.logicRoles`: policy, client, guard, mapper, ...) inside the logic of `src/modules/**`, where every file owes 100 per file; a feature file (handler, resolver, controller, consumer, processor, step, ...) is thin (BE_FEATURE_THIN) and is proven by the integration and e2e flows, and an entity, module or composition is declaration. Delete this spec and move any business rule it checks into a service, policy or mapper of `src/modules/**`.",
130
+ notService: "`{{name}}` is a unit spec of something that carries no unit-tested logic here. A unit spec sits beside a `<name>.<role>.ts` of a spec-required role (a service, a cli command of `src/features/cli`) or of a logic role (`ruleParams.be.logicRoles`: policy, client, guard, mapper, ...) inside the logic of `src/modules/**`, or a logic file its slot declares (`logic`), where every file owes 100 per file; a feature file (handler, resolver, controller, consumer, processor, step, ...) is thin (BE_FEATURE_THIN) and is proven by the integration and e2e flows, and an entity, module or composition is declaration. Delete this spec and move any business rule it checks into a service, policy or mapper of `src/modules/**`.",
131
131
  orphan: "`{{name}}` has nothing beside it to test. A unit spec is `<name>.<role>.spec.ts` next to the `<name>.<role>.ts` it tests (a service, or a cli command of `src/features/cli`; the roles are `ruleParams.be.unitRoles`); move it beside its subject, or rename it after the subject it tests.",
132
132
  missing: "This unit-tested subject has no spec. Add `{{spec}}` beside it: it builds the subject with `Test.createTestingModule`, provides only its constructor dependencies as typed doubles and asserts results or state.",
133
133
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/eslint-canon-be",
3
- "version": "3.8.18",
3
+ "version": "3.8.20",
4
4
  "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -31,35 +31,35 @@ pins:
31
31
  source: packages/event-stream/package.json
32
32
  why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
33
33
  '@starci/grammar':
34
- version: 0.15.31
34
+ version: 0.15.33
35
35
  group: starci
36
36
  install: registry
37
37
  side: fe
38
38
  source: packages/grammar/package.json
39
39
  why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
40
40
  '@starci/eslint-canon-be':
41
- version: 3.8.18
41
+ version: 3.8.20
42
42
  group: starci
43
43
  install: registry
44
44
  side: be
45
45
  source: packages/eslint-canon-be/package.json
46
46
  why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
47
47
  '@starci/eslint-canon-fe':
48
- version: 9.5.20
48
+ version: 9.5.22
49
49
  group: starci
50
50
  install: registry
51
51
  side: fe
52
52
  source: packages/eslint-canon-fe/package.json
53
53
  why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
54
54
  '@starci/eslint-grammar-core':
55
- version: 0.15.31
55
+ version: 0.15.33
56
56
  group: starci
57
57
  install: registry
58
58
  side: fe
59
59
  source: packages/eslint-grammar-core/package.json
60
60
  why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
61
61
  '@starci/eslint-grammar-offset-pop':
62
- version: 0.15.31
62
+ version: 0.15.33
63
63
  group: starci
64
64
  install: registry
65
65
  side: fe
@@ -85,7 +85,7 @@ pins:
85
85
  side: both
86
86
  source: packages/prettier-config/package.json
87
87
  '@starci/jest-preset':
88
- version: 2.5.1
88
+ version: 2.5.2
89
89
  group: starci
90
90
  install: registry
91
91
  side: be
@@ -106,7 +106,7 @@ pins:
106
106
  source: packages/ai-router/package.json
107
107
  why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
108
108
  '@starci/hfs':
109
- version: 4.11.19
109
+ version: 4.11.21
110
110
  group: starci
111
111
  install: registry
112
112
  side: both
@@ -918,7 +918,7 @@ rules:
918
918
  code: "BE_TEST_TOPOLOGY"
919
919
  editions: [lite, full]
920
920
  docs: [docs/quality-bar.md#r47-test-topology]
921
- 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, 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 hygiene` 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 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`."
921
+ 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 hygiene` 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`."
922
922
  kinds: [check, codemod, lint]
923
923
  gates: [land, ci]
924
924
  failureCodes: ["BE_TEST_TOPOLOGY", "BE_CONTRACT_UNGUARDED", "BE_UNIT_SPEC_NOT_STAGED"]
@@ -3525,7 +3525,7 @@ rules:
3525
3525
  code: "HFS_COVERAGE_SCOPE_DRIFT"
3526
3526
  editions: [lite, full]
3527
3527
  docs: [docs/quality-bar.md#r204-coverage-scope]
3528
- law: "What a back end measures at 100 per file is derived once from the slot manifest (the `coverage: required|none` field of every be slot and ruleParams.be.logicRoles, scripts/hfs/coverage-scope.mjs), and the three files that state it are its render: be/jest.config.js (thresholds), the `sonar.coverage.exclusions` line of sonar-project.properties, and codecov.yml (paths and one component per service app plus platform, each at 100). A difference is drift; the scope is never edited by hand."
3528
+ law: "What a back end measures at 100 per file is derived once from the slot manifest (the `coverage: required|none` field of every be slot, ruleParams.be.logicRoles and the `logic` files a required slot declares, scripts/hfs/coverage-scope.mjs), and the three files that state it are its render: be/jest.config.js (thresholds), the `sonar.coverage.exclusions` line of sonar-project.properties, and codecov.yml (paths and one component per service app plus platform, each at 100). A difference is drift; the scope is never edited by hand."
3529
3529
  kinds: [check, codemod]
3530
3530
  gates: [land, ci]
3531
3531
  failureCodes: ["HFS_COVERAGE_SCOPE_DRIFT"]
@@ -4642,7 +4642,7 @@ rules:
4642
4642
  - {path: packages/hfs/src/hfs-boot-proof.spec.mjs, edition: lite}
4643
4643
  - id: R273
4644
4644
  code: "HFS_COVERAGE_BELOW"
4645
- law: "An app check supplied with a coverage-from lcov report proves 100 percent lines, functions and branches per tracked back-end logic file in the edition's slot-derived measured scope; a missing source record or unavailable metric is refused. The unit runner also enforces statement coverage. Reports list the measured scope and the source files outside it, including features, cli and webhooks."
4645
+ law: "An app check supplied with a coverage-from lcov report proves 100 percent lines, functions and branches per tracked back-end logic file (a logic-role file or a file its slot declares in `logic`) in the edition's slot-derived measured scope; a missing source record or unavailable metric is refused. The unit runner also enforces statement coverage. Reports list the measured scope and the source files outside it, including features, cli and webhooks."
4646
4646
  kinds: [check]
4647
4647
  gates: [ci]
4648
4648
  failureCodes: ["HFS_COVERAGE_BELOW"]
@@ -88,10 +88,14 @@ versioning:
88
88
  # allows / forbids names inside the instance; the loader exposes them, slot-check enforces them.
89
89
  # tests unit-beside | e2e | none.
90
90
  # coverage required | none, on every tracked slot of profile be. A required slot's subtree is measured at 100 per file on every
91
- # ruleParams.be.logicRoles file (lines, branches, functions, statements); a none slot's subtree is never measured and
92
- # is excluded from Sonar's coverage. scripts/hfs/coverage-scope.mjs derives the jest per-file thresholds, Sonar's
93
- # sonar.coverage.exclusions and the Codecov paths and components from this field and nowhere else (R204).
94
- # Orthogonal to the lite `editions`: an edition never changes what a slot measures.
91
+ # ruleParams.be.logicRoles file and on every file a slot of it declares in `logic` (lines, branches, functions,
92
+ # statements); a none slot's subtree is never measured and is excluded from Sonar's coverage. scripts/hfs/coverage-scope.mjs
93
+ # derives the jest per-file thresholds, Sonar's sonar.coverage.exclusions and the Codecov paths and components from this
94
+ # field and `logic` and nowhere else (R204). Orthogonal to the lite `editions`: an edition never changes what a slot measures.
95
+ # logic on a coverage-required unit-beside directory slot: the files of the slot that carry logic without a logic-role suffix
96
+ # (`<name>.<part>.ts`, relative to the slot path, each one the slot requires or allows, none of a logic role). Each is
97
+ # measured at 100 per file like a logic-role file, and its `<name>.<part>.spec.ts` beside it is a legitimate unit spec
98
+ # (R47, R48): the slot admits it without listing it. No role name is added to ruleParams.be.logicRoles.
95
99
  # composedBy the app kinds allowed to compose a transport slot (an app of another kind imports none of its modules); on an
96
100
  # owner slot (be.cli) the app kinds that list its root module, every folder of the root holding one static module.
97
101
  # budget size budgets (lines per file, files per slot, exports).
@@ -1981,6 +1985,7 @@ slots:
1981
1985
  owner: true
1982
1986
  requires: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.tokens.ts, passport.password.ts, passport.cookie.ts] # Secrets, no defaults (R44); options and named injectors (R83); tokens and JWKS; bcrypt; the refresh cookie
1983
1987
  allows: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.tokens.ts, passport.password.ts, passport.cookie.ts, strategies/, errors/]
1988
+ logic: [passport.tokens.ts, passport.password.ts, passport.cookie.ts] # JWT sign and verify over the own JWKS, bcrypt, the refresh cookie: measured at 100 per file
1984
1989
  tests: unit-beside
1985
1990
  rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_AUTH_PASSPORT_OWNER, BE_AUTH_JWT_OWN_JWKS, BE_AUTH_REFRESH_COOKIE]
1986
1991
  coverage: required
@@ -1997,8 +2002,8 @@ slots:
1997
2002
  tracked: tracked
1998
2003
  tier: integrations
1999
2004
  owner: true
2000
- requires: [index.ts, storage.config.ts, storage.options.ts, storage.decorators.ts, storage.client.ts]
2001
- allows: [index.ts, storage.config.ts, storage.options.ts, storage.decorators.ts, storage.client.ts, errors/]
2005
+ requires: [index.ts, object-storage.config.ts, object-storage.options.ts, object-storage.decorators.ts, object-storage.client.ts]
2006
+ allows: [index.ts, object-storage.module.ts, object-storage.module-definition.ts, object-storage.config.ts, object-storage.options.ts, object-storage.decorators.ts, object-storage.client.ts, errors/]
2002
2007
  tests: unit-beside
2003
2008
  rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_STORAGE_OWNER]
2004
2009
  coverage: required
@@ -1,5 +1,6 @@
1
1
  import path from 'node:path';
2
2
  import { braceVariants, globExpression } from '../lib/glob.mjs';
3
+ import { declaredLogicOf } from './manifest-shape.mjs';
3
4
 
4
5
  /**
5
6
  * What a slot's `requires`, `allows` and `forbids` entries (knowledge/hfs/slots.yaml) say about a file, read through the
@@ -8,9 +9,26 @@ import { braceVariants, globExpression } from '../lib/glob.mjs';
8
9
  *
9
10
  * An entry is a name relative to the slot instance root: `<var>` is the instance's bound variable when the slot binds it
10
11
  * (`<feature>`, `<capability>`) and one path segment of any text otherwise (`<action>`), `*` and `?` stay inside a segment,
11
- * `{a,b}` alternates, a trailing `/` names a directory and everything below it.
12
+ * `{a,b}` alternates, a trailing `/` names a directory and everything below it. A slot also admits, unlisted, the unit spec beside each
13
+ * measured file it names (isMeasuredSpec): a file it declares in `logic`, or a named file of a logic role.
12
14
  */
13
15
  const VAR = /<([A-Za-z][A-Za-z0-9-]*)>/g;
16
+ const SPEC = /\.spec\.ts$/;
17
+
18
+ /**
19
+ * Whether `relative` is the unit spec `<stem>.spec.ts` of a measured file beside it that the slot names: a file the slot declares in
20
+ * `logic`, or a `requires`/`allows` file of a logic role (ruleParams.be.logicRoles), in a slot whose coverage is required and whose tests
21
+ * are unit-beside. The slot admits that spec without listing it, as unit-test-colocated (R47) accepts it.
22
+ */
23
+ function isMeasuredSpec(resolver, classified, slot, relative, named) {
24
+ if (!SPEC.test(relative) || slot.coverage !== 'required' || slot.tests !== 'unit-beside') return false;
25
+ const subject = relative.replace(SPEC, '.ts');
26
+ if (declaredLogicOf(slot).includes(subject)) return true;
27
+ const role = /\.([a-z0-9-]+)\.ts$/.exec(subject)?.[1];
28
+ // An app resolver keeps no rule parameters of its own: a path on a side reads that side's.
29
+ const params = classified.side ? resolver.sides?.[classified.side]?.ruleParams() : resolver.ruleParams?.();
30
+ return (params?.logicRoles ?? []).includes(role) && named.some(matcher => matcher.expression.test(subject));
31
+ }
14
32
 
15
33
  function matchersOf(entries, bindings) {
16
34
  return (entries ?? []).flatMap(entry => {
@@ -36,7 +54,8 @@ export function slotAdmitsFile(resolver, file) {
36
54
  if (classified.status === 'no-slot' || classified.status === 'ambiguous' || !classified.slot) return null;
37
55
  const slot = resolver.slot(classified.slot);
38
56
  const relative = relativeToRoot(classified.path, classified.root);
39
- const hit = matchersOf([...(slot.requires ?? []), ...(slot.allows ?? [])], classified.bindings).some(matcher => matcher.expression.test(relative));
57
+ const named = matchersOf([...(slot.requires ?? []), ...(slot.allows ?? [])], classified.bindings);
58
+ const hit = named.some(matcher => matcher.expression.test(relative)) || isMeasuredSpec(resolver, classified, slot, relative, named);
40
59
  const forbidden = matchersOf(slot.forbids, classified.bindings).some(matcher => matcher.expression.test(relative) || matcher.expression.test(`${relative}/`));
41
60
  return hit && !forbidden;
42
61
  }
@@ -51,7 +70,9 @@ export function allowsFile(resolver, file) {
51
70
  const slot = resolver.slot(classified.slot);
52
71
  if (!slot?.allows?.length) return null;
53
72
  const relative = relativeToRoot(classified.path, classified.root);
54
- const hit = matchersOf([...(slot.requires ?? []), ...slot.allows], classified.bindings).find(matcher => matcher.expression.test(relative));
73
+ const named = matchersOf([...(slot.requires ?? []), ...slot.allows], classified.bindings);
74
+ const hit = named.find(matcher => matcher.expression.test(relative));
75
+ const spec = !hit && isMeasuredSpec(resolver, classified, slot, relative, named);
55
76
  const forbidden = matchersOf(slot.forbids, classified.bindings).find(matcher => matcher.expression.test(relative) || matcher.expression.test(`${relative}/`));
56
- return { slot: slot.id, root: classified.root, relative, allowed: Boolean(hit) && !forbidden, entry: hit?.entry, forbiddenBy: forbidden?.entry, allows: slot.allows };
77
+ return { slot: slot.id, root: classified.root, relative, allowed: (Boolean(hit) || spec) && !forbidden, entry: hit?.entry, forbiddenBy: forbidden?.entry, allows: slot.allows };
57
78
  }
@@ -4,7 +4,7 @@
4
4
  // In both editions every jwtVerify call holds the JWT policy (R260, jwtPolicyProblems).
5
5
  import path from 'node:path';
6
6
  import { machineKit } from './machine-ast.mjs';
7
- import { importedFrom, jwtPolicyProblems, reportAt, unwrap } from './jwt-ast.mjs';
7
+ import { fromConfig, importedFrom, jwtPolicyProblems, reportAt, unwrap } from './jwt-ast.mjs';
8
8
  import { accessName } from '../../lib/ts-ast.mjs';
9
9
 
10
10
  const PASSPORT_SLOT = 'be.integrations.passport';
@@ -87,7 +87,11 @@ function verifyJwtCall(kit, checker, file, node, counters, violations) {
87
87
  const issuer = property('issuer');
88
88
  const audience = values('audience');
89
89
  const algorithms = values('algorithms');
90
- const good = jwksArgument(kit, checker, node.arguments[1]) && issuer != null && audience !== null && audience.length > 0
90
+ // The audience is pinned by a literal or, as R260 accepts, by typed configuration (the skeleton's TokenOptions.audience).
91
+ const audienceEntry = property('audience');
92
+ const pinnedAudience = (audience !== null && audience.length > 0)
93
+ || (audienceEntry != null && fromConfig(kit.ts, checker, kit.valueOfProperty(audienceEntry)));
94
+ const good = jwksArgument(kit, checker, node.arguments[1]) && issuer != null && pinnedAudience
91
95
  && algorithms !== null && algorithms.length > 0;
92
96
  if (!good) {
93
97
  reportAt(violations, kit, BE_JWT_VERIFIED, file, node, 'jwtVerify must check the app\'s own key set (createLocalJWKSet(...) over the keys integrations/passport signs with) and pin issuer, audience and a non-empty algorithms list; jwtVerify then enforces signature and exp.');
@@ -62,7 +62,7 @@ const configType = (checker, node) => {
62
62
  };
63
63
 
64
64
  /** Trace an issuer or audience to typed configuration values through local URL/string transformations. */
65
- const fromConfig = (ts, checker, expression, seen = new Set()) => {
65
+ export const fromConfig = (ts, checker, expression, seen = new Set()) => {
66
66
  const node = unwrap(ts, expression);
67
67
  if (!node || seen.has(node)) return false;
68
68
  const next = new Set(seen).add(node);
@@ -58,6 +58,40 @@ export const unitRolesOf = (manifest) => manifest.ruleParams.be.unitRoles;
58
58
  /** The roles that carry logic (ruleParams.be.logicRoles): measured at 100 per file inside a coverage-required slot. */
59
59
  export const logicRolesOf = (manifest) => manifest.ruleParams.be.logicRoles;
60
60
 
61
+ /** A declared logic file: `<name>.<part>.ts` below the slot path, kebab-case parts, no placeholder, glob or spec. */
62
+ const LOGIC_FILE = /^(?:[a-z0-9]+(?:-[a-z0-9]+)*\/)*[a-z0-9]+(?:-[a-z0-9]+)*(?:\.[a-z0-9]+(?:-[a-z0-9]+)*)+\.ts$/;
63
+
64
+ /** The role suffix of a file name (`passport.tokens.ts` gives `tokens`). */
65
+ export const suffixOf = (file) => /\.([a-z0-9-]+)\.ts$/.exec(file)?.[1] ?? null;
66
+
67
+ /**
68
+ * The files a slot declares as logic (`logic`, names relative to the slot path): a file that carries logic without a logic-role suffix.
69
+ * Each is measured at 100 per file like a logic-role file (scripts/hfs/coverage-scope.mjs), and its `<stem>.spec.ts` beside it is a
70
+ * legitimate unit spec its slot admits (scripts/hfs/allows.mjs, eslint-canon-be unit-test-colocated). No role name is added for it.
71
+ */
72
+ export const declaredLogicOf = (slot) => (Array.isArray(slot?.logic) ? slot.logic : []);
73
+
74
+ /** The unit spec beside a declared logic file: `passport.tokens.ts` gives `passport.tokens.spec.ts`. */
75
+ export const declaredLogicSpecOf = (file) => file.replace(/\.ts$/, '.spec.ts');
76
+
77
+ /**
78
+ * Shape problems of a slot's `logic`: a non-empty list of unique `<name>.<part>.ts` files, each one the slot requires or allows by that
79
+ * exact name, on a tracked directory slot of profile be that is coverage: required and unit-beside, and (given the logic roles) none
80
+ * already of a logic role, which its role measures.
81
+ */
82
+ export function slotLogicProblems(slot, at, logicRoles = []) {
83
+ if (slot.logic === undefined) return [];
84
+ const list = slot.logic;
85
+ if (!strList(list) || !list.length || new Set(list).size !== list.length || !list.every((file) => LOGIC_FILE.test(file) && !file.endsWith('.spec.ts'))) return [`${at}: logic must be a non-empty list of unique <name>.<part>.ts files relative to the slot path`];
86
+ const bad = [];
87
+ const home = typeof slot.path === 'string' && slot.path.endsWith('/') && slot.tracked === 'tracked' && Array.isArray(slot.profiles) && slot.profiles.includes('be') && slot.coverage === 'required' && slot.tests === 'unit-beside';
88
+ if (!home) bad.push(`${at}: logic belongs to a tracked directory slot of profile be whose coverage is required and whose tests are unit-beside`);
89
+ const named = [...(slot.requires ?? []), ...(slot.allows ?? [])];
90
+ for (const file of list.filter((entry) => !named.includes(entry))) bad.push(`${at}: logic file ${file} must be one the slot requires or allows by that name`);
91
+ for (const file of list.filter((entry) => logicRoles.includes(suffixOf(entry)))) bad.push(`${at}: logic file ${file} is of the logic role ${suffixOf(file)}, which measures it already`);
92
+ return bad;
93
+ }
94
+
61
95
 
62
96
  /** Shape problems of ruleParams.be.unitRoles: unique roles of the suffix vocabulary, each spec `<role>.spec`. */
63
97
  export function unitRolesProblems(be) {
@@ -87,7 +121,7 @@ export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
87
121
  export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
88
122
  const strList = (v) => stringList(v);
89
123
 
90
- const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy'];
124
+ const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy', 'logic'];
91
125
  /** The roles a file slot may play that a rule reads (`role`): the entity registry of persistence.md BE-PERSISTENCE-3 (architecture/entity-registry.mjs). */
92
126
  const SLOT_ROLES = ['entity-registry'];
93
127
  /** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
@@ -266,7 +300,7 @@ function slotPolicyProblems(slot, at) {
266
300
  return bad;
267
301
  }
268
302
 
269
- export function slotProblems(slot, index, kind, { appScope = 'app', scopes = [] } = {}) {
303
+ export function slotProblems(slot, index, kind, { appScope = 'app', scopes = [], logicRoles = [] } = {}) {
270
304
  const runtime = kind === RUNTIME_KIND;
271
305
  const slotKeys = new Set(runtime ? RUNTIME_SLOT_KEYS : APP_SLOT_KEYS);
272
306
  const tracked = runtime ? RUNTIME_TRACKED : TRACKED;
@@ -276,6 +310,7 @@ export function slotProblems(slot, index, kind, { appScope = 'app', scopes = []
276
310
  bad.push(...slotLocationProblems(slot, at, runtime, tracked), ...slotPatternProblems(slot, at), ...slotListProblems(slot, at));
277
311
  if (!runtime) bad.push(...slotAppOptionProblems(slot, at), ...slotLiteOverlayProblems(slot, at));
278
312
  bad.push(...slotEntryProblems(slot, at), ...slotPolicyProblems(slot, at));
313
+ if (!runtime) bad.push(...slotLogicProblems(slot, at, logicRoles));
279
314
  return bad;
280
315
  }
281
316
 
@@ -53,7 +53,8 @@ function checkAppKindAndTierShapes(m, bad) {
53
53
 
54
54
  function checkSlotShapes(m, bad) {
55
55
  if (!Array.isArray(m.slots) || !m.slots.length) { bad.push('slots must be a non-empty list'); return false; }
56
- m.slots.forEach((slot, index) => bad.push(...slotProblems(slot, index, APP_KIND, { appScope: APP_SCOPE, scopes: SCOPES })));
56
+ const logicRoles = Array.isArray(m.ruleParams?.be?.logicRoles) ? m.ruleParams.be.logicRoles : [];
57
+ m.slots.forEach((slot, index) => bad.push(...slotProblems(slot, index, APP_KIND, { appScope: APP_SCOPE, scopes: SCOPES, logicRoles })));
57
58
  return true;
58
59
  }
59
60