@starci/eslint-canon-be 3.0.8 → 3.0.10

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+
+- New: `feature-thin` (R203 `BE_FEATURE_THIN`, law `feature-thin`): a feature-tier file of a role of `ruleParams.be.thinRoles` (handler, resolver, controller, consumer, processor, step, saga, saga-step, compensation, webhook, gateway, subscription, cli, mapper, the saga orchestrator service) maps its parameters and makes ONE delegating call into modules/, with no branch, loop, ternary, try, throw or computation. The slot manifest copy gains `coverage` on every tracked be slot and `ruleParams.be.logicRoles` and `thinRoles`.
+- Changed: `unit-test-colocated` also allows `<name>.<role>.spec.ts` beside a logic role (policy, client, guard, mapper, ...) inside a slot whose coverage is required; the spec stays required only for the roles of `ruleParams.be.unitRoles`, and the texts say so.
+- Changed: `no-repository-class` (R83) accepts `platform/saga` as a platform persistence capability (state of a saga run with its version fence).
+- New: `service-isolation` (R168 `BE_SERVICE_ISOLATION`, new law `service-isolation`): a file of a service app imports no file of a sibling service app. The slot manifest copy gains `be.contract.events` and `events.ts`/`consumes.ts` in the api and worker app slots.
+- New: `no-ambient-id` (R142 `BE_AMBIENT_ID`): `randomUUID` of Node's crypto, the `uuid` generators `v1`/`v4`/`v6`/`v7`, `nanoid` and `ulid` are used only inside `platform/ids`, specs included; code asks the `Ids` port and specs use `fakeIds()`.
+- New: `response-cookie-attributes` (R141 `BE_COOKIE_ATTRIBUTES`): a cookie written through the Express or Fastify response states `httpOnly: true`, `secure: true` and `sameSite` `lax` or `strict` in typed options, and `Set-Cookie` is never written as a header.
+- New: `injected-param-name` (R85): a parameter that injects a port of the table `ruleParams.be.paramNames` of the slot manifest (`Clock`, `Logger`, `Cache`, `CommandBus`, `QueryBus`, `EntityManager`, `*Options`) carries the name that table gives it.
+- Changed: `secret-compare-timing-safe` (R41) also recognises, by type, the `.digest()` of a crypto `Hash` or `Hmac`.
+- Changed: the texts of `unit-test-colocated` and the law headers name the four test kinds and the pattern files; the bundled runtime copies follow.
+
 ## 3.0.7 - 2026-10-01
 
 - Changed: the runtime layer check moves test-secrets onto api/sops/decrypt.mjs; bundled copies follow.
@@ -199,7 +211,7 @@ Round 2 back-end rules (catalog R42, R68 to R76). Every rule below has RuleTeste
 HFS back-end rules (catalog R18, R20, R34, R36-R38, R40-R45, R48). Every rule below has RuleTester specs and a why code in `modules/kernel/failure-codes.yaml`.
 
 - New: `catch-must-account` (R40), `error-home` (R38), `no-runtime-schema` (R34), `sql-only-in-repository` (R36), `no-entity-in-contract` (R37), `no-untyped-body` and `public-needs-reason` (R41), `no-direct-env-read` (R43), `no-secret-default` (R44), `secret-compare-timing-safe` (R41), `global-module-allowlist`, `typed-module-definition`, `static-module-register`, `no-new-injectable`, `no-module-let`, `one-module-per-file` (R45), `no-inline-suppression` (R18), `file-size-growth` (R20 ratchet; the soft budget is a hfs check report item, not a lint warning), `spec-no-source-read` and `spec-typed-doubles` (R48).
-- Fixed: `import-owner-entry` (then under an older name) now holds the HFS owner surface. An aliased import names the owner and stops (`@modules/domain/plan`, `@features/plan`, or the explicit `/index`); a path into a file of another owner is refused, and a tier-only or root alias still is. The retired `lib` tier no longer counts as a tier. `no-folder-reexport` accepts a named `index.ts` surface (`export { X } from "./x"`, `export type { T } from "./contracts"`), and refuses `export *`, a `*_STORE` token, a whole `types` folder and an entry wider than the manifest's `indexExports` (60). Both are on again in `starciBeConfig`.
+- Fixed: `import-owner-entry` (then under an older name) now holds the HFS owner surface. An aliased import names the owner and stops (`@modules/domain/plan`, `@features/api/plan`, or the explicit `/index`); a path into a file of another owner is refused, and a tier-only or root alias still is. The retired `lib` tier no longer counts as a tier. `no-folder-reexport` accepts a named `index.ts` surface (`export { X } from "./x"`, `export type { T } from "./contracts"`), and refuses `export *`, a `*_STORE` token, a whole `types` folder and an entry wider than the manifest's `indexExports` (60). Both are on again in `starciBeConfig`.
 - Removed: no rule is off. The retired-rule list (`RETIRED`) and its export are gone, and so are the rules it switched off: `exception-name-ends-in-exception`, `exception-code-matches-class-name`, `exception-metadata-type-named-for-class`, `exception-extends-abstract`, `exception-in-errors-folder`, `require-exception-object-arg`, `throw-abstract-exception` (the Academy `AbstractException` family, replaced by `error-home`), `no-handler-encoded-failure` (expected refusals are typed unions), `handler-has-twin-spec`, `no-self-global-module` (replaced by `global-module-allowlist`), `no-line-suppression` and `require-vn-ok-reason` (replaced by `no-inline-suppression`), and the `vn-ok` exemption of `no-non-ascii-source`.
 - `starciBeConfig` refuses a recommendation that carries an `off`.
 - Slot parameters (the `@Global()` allowlist, the file line budget, the `index.ts` width) are read through `lib/slots.mjs` from `knowledge/hfs/slots.yaml` (`ruleParams.be.globalModules`, `ruleParams.be.fileLines.{soft,hardGrowth}`, and the `indexExports` budget of a `be.*` slot), with the rule catalog's values as the fallback.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) StarCi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,7 +12,7 @@ npm i -D @starci/eslint-canon-be
 
 ## Use it
 
-`eslint.config.mjs` of a back end is a managed file (`hfs sync` renders it; `hfs check` refuses any other content):
+`eslint.config.mjs` of a back end is a managed file (`starci app sync` renders it; `starci app check` refuses any other content):
 
 ```js
 import { loadHfs, starciBeConfig } from "@starci/eslint-canon-be"
@@ -40,6 +40,8 @@ A sample, not the list:
 | **Errors** | A `catch` rethrows, calls a method on a `Logger` receiver (typed, from `platform/logging`) or returns an outcome carrying its cause; a `DomainError` subclass lives only in `errors/<capability>.error.ts` of its owner, and that file is one code enum, one `Record<Code, ErrorKind>` table and one empty class; a `throw` throws a `DomainError`, never a bare `Error`, a framework exception or a platform error out of a domain (`catch-must-account`, `error-home`, `throw-domain-error`, `error-family-shape`) |
 | **Schema authority** | Migrations only: every DataSource or TypeORM options object states the literal `synchronize: false` (found by the contextual type), no `migrationsRun`, no DDL string outside a migration, no entity glob; no `@Entity` type reachable from a transport signature, a handler `execute`, a contract or a message, and no GraphQL or validator import in an entity file (`no-runtime-schema`, `no-entity-in-contract`) |
 | **Config and secrets** | `process.env` (any form), `@nestjs/config`, `dotenv` only in the file of `platform/config` that declares `EnvSource` (and the test world, slot `be.tests.world`, for `process.env`); a function exported by a `<capability>.config.ts` is called only from `apps/<app>/src/main.ts` and `<app>.options.ts`, its own config file or spec, the test world and a provider contract spec (`config-parsed-in-main`); no default of any kind for a value typed `Secret` or `Url`; secrets compare with `timingSafeEqual` (`no-direct-env-read`, `config-parsed-in-main`, `no-secret-default`, `secret-compare-timing-safe`) |
+| **Ambient ids** (R142) | `randomUUID` of Node's crypto (named, namespace or global), the `v1`, `v4`, `v6` and `v7` generators of `uuid`, `nanoid` and `ulid` are used only inside `platform/ids`, specs included: code asks the injected `Ids` port and a spec provides `fakeIds()`; the generators are found by the module they are imported from, never by a local name (`no-ambient-id`) |
+| **Cookies** (R141) | A cookie a door writes through the response of Express or Fastify (`cookie`, `setCookie`) states `httpOnly: true`, `secure: true` and `sameSite` `lax` or `strict` in options typed with those literals, and `Set-Cookie` is never written as a header; the call is recognised by where its signature is declared (`response-cookie-attributes`). A secret-derived value is compared with `timingSafeEqual`: a `Secret` of `platform/config` and the `.digest()` of a `Hash` or `Hmac` of Node's crypto are recognised by type (`secret-compare-timing-safe`) |
 | **Default deny** | Typed bodies and arguments, no `GraphQLJSON` tunnel, no `switch (operation)`, `@Public` carries a `PublicReason` member of `domain/identity`, and no `@UseGuards` (the global `APP_GUARD` chain decides) (`no-untyped-body`, `public-needs-reason`, `no-auth-use-guards`) |
 | **Module shape** | No `@Global()`; `isGlobal: true` only in an app's `app.module.ts`; no import of another owner's module; typed `ConfigurableModuleBuilder`; `static register` is the only factory; a capability's representative module extends the `ConfigurableModuleClass` of its own module definition and every sub-module or feature module is plain (`capability-module-shape`); one module per file; no `new` of a provider; no module-level `let` (`no-global-decorator`, `is-global-only-in-app`, `no-cross-owner-module-import`, `static-module-register`) |
 | **Suppression** | No `eslint-disable`, `eslint-env`, `/* global */`, `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, `istanbul`, `c8` or `v8 ignore`, `NOSONAR`, `sonar-disable`, `prettier-ignore` or `vn-ok` comment, anywhere (`no-inline-suppression`) |
@@ -52,22 +54,26 @@ A sample, not the list:
 | **Spec quality** | A spec does not read repository source with `fs` (`spec-no-source-read`); the borrowed `consistent-type-assertions` (`never`) and `no-non-null-assertion` leave no `as` and no `x!` in a spec, and `no-ambient-clock` and `no-direct-env-read` cover specs, so no `Date.now()`, argless `new Date()` or `process.env`. A unit spec is `<name>.service.spec.ts`: it builds its subject with `Test.createTestingModule({ providers })` from `@nestjs/testing`, `.compile()` and `moduleRef.get(...)` (`spec-builds-with-testing-module`), never `new` on the service (`spec-no-new-subject`), no `imports` key and no `override*` (`spec-module-definition-only-providers`), no `jest.mock`/`doMock`/`unstable_mockModule`/`requireMock` of an own module or a library (`spec-no-module-mock`), no cast-laundering helper in a spec or fixture: a return-only generic, an `unknown` handed back as another type, `JSON.parse(JSON.stringify(x))`, `Object.assign(new X(), y)` returned as another type (`no-return-only-generic`); a provider `{ provide: TOKEN, useValue: X }` takes X from the matching `@starci/jest-preset` double, the token table being `ruleParams.be.specDoubles` of the slot manifest (`spec-infra-double-from-kit`); a unit spec asserts exact values, never `expect.any(String)`, `expect.any(Number)` or `expect.any(Date)` (`expect` being the jest global or the `@jest/globals` import): ids come from `fakeIds()` and dates from `FakeClock` (`spec-exact-values`); the EntityManager double is the kit's `mockEntityManager()`/`fakeTransaction()`, never ad hoc (`spec-typed-entity-manager`); test data goes through builders, see the **Test data builders** row |
 | **Test data builders** (R98 to R101) | Builders live only in `src/tests/fixtures/builders/<area>.builder.ts`: a module of the test tree that exports a function creating persisted rows through an EntityManager, DataSource or QueryRunner is a builder wherever it sits (`persisting-builder-in-builders-slot`, R98); a spec never runs a raw INSERT/UPDATE/DELETE or a direct write (`save`, `insert`, `upsert`, `update`, `delete`, `remove`) on a typeorm receiver and never builds the same `@Entity` class as an object literal twice (`spec-no-raw-insert`, `spec-no-repeated-row-literal`, R99); a builder never asserts and has deterministic defaults (`builder-arranges-only`, R101); nothing under `src/tests` disables or drops a constraint (`tests-keep-constraints`, R100) |
 | **CQRS** | A message extends `Command<R>` / `Query<R>` from `@nestjs/cqrs`, carries one `readonly params: ExecuteParams<X>` (no entity reachable from `X`), a handler extends `ICQRSHandler` and overrides `process`; a handler is thin: it injects only `*Service` classes and the Logger, and `process` is one `return this.<service>.<method>(...)` with no branch, loop, EntityManager or second call (`handler-is-thin`); no `*.use-case.ts`, no forwarder service, no `EventBus`, `@nestjs/event-emitter`, `EventEmitter` or RxJS `Subject` constructed or extended, and no class that stores callbacks other code registers (`handler-overrides-process`, `message-carries-params-only`, `message-typed-result`, `execute-params-shape`, `no-use-case`, `no-event-bus`) |
-| **Module layering** | Another owner is imported through its public `index.ts` (`@modules/domain/plan`, `@features/plan`), never through a path into it, and a same-owner import is relative and never through the own index (`import-owner-entry`); an owner has one `index.ts` (a nested one is refused) that holds only named `export { }` lines, with no `export *`, and a bounded number of names (`no-folder-reexport`); self-aliases and relative escapes are refused (`no-self-module-alias`, `no-relative-capability-escape`). Owners come from the HFS slots, aliases from the program's `compilerOptions.paths`. |
-| **Data access** | The database is reached through the shared `EntityManager` only, received as a constructor parameter with the named injector of a declared connection - a lookalike name, property injection, an injected `DataSource` or `QueryRunner` outside `platform/database` and the migrate app, `getRepository` and repository types are refused, specs included (`must-inject-entity-manager`, `named-entity-manager-only`, `no-injected-repository`); a `DataSource` or `QueryRunner` is not written as a type, awaited value or `provide:` token outside those places, and a class that receives a wrapper exposing one is refused (`named-entity-manager-only`); a class outside an application handler, a domain service and a platform persistence capability takes, holds or returns no `EntityManager`, `Repository`, `DataSource` or `QueryRunner` whatever it is called, and no exported function takes an `EntityManager` first (a statement module); `src/tests` is exempt (`no-repository-class`); a `DataSource` or `QueryRunner` is not written as a type, awaited value or `provide:` token outside those places, and a class that receives a wrapper exposing one is refused (`named-entity-manager-only`); a class outside an application handler, a domain service and a platform persistence capability takes, holds or returns no `EntityManager`, `Repository`, `DataSource` or `QueryRunner`, whatever it is called, and no exported function takes an `EntityManager` first (a statement module); the test tree (`src/tests`) is exempt (`no-repository-class`); inside a transaction callback only the manager it received is used (`no-outer-manager-in-transaction`); no call through an integration, `HttpClient` or `MessagePublisher` typed receiver spans a transaction (`no-external-call-in-transaction`); the manager is injected only in application handlers, domain services and the platform database, inbox, outbox and lease capabilities (`em-injection-slots`) |
-| **Connections** | One database is one connection and one `Inject<Conn>EntityManager()` injector: `InjectEntityManager(`, `InjectDataSource(` and `getEntityManagerToken(` are called only in `platform/database/<conn>.decorators.ts`, the migrate app and the test database fixture; an exported EntityManager injector is exactly the declared connection's; `TypeOrmModule.forRoot*` and `new DataSource(` live in the platform database capability and the migrate app; the connection name is written once, in its `<conn>.connection.ts`; a `<conn>.config.ts` reads only keys of its `envPrefix` (`one-connection-per-database`) |
+| **Module layering** | Another owner is imported through its public `index.ts` (`@modules/domain/plan`, `@features/api/plan`), never through a path into it, and a same-owner import is relative and never through the own index (`import-owner-entry`); an owner has one `index.ts` (a nested one is refused) that holds only named `export { }` lines, with no `export *`, and a bounded number of names (`no-folder-reexport`); self-aliases and relative escapes are refused (`no-self-module-alias`, `no-relative-capability-escape`). Owners come from the HFS slots, aliases from the program's `compilerOptions.paths`. |
+| **Data access** | The database is reached through the shared `EntityManager` only, received as a constructor parameter with the named injector of a declared connection - a lookalike name, property injection, an injected `DataSource` or `QueryRunner` outside `platform/database` and the cli (`apps/cli`, `src/features/cli/`), `getRepository` and repository types are refused, specs included (`must-inject-entity-manager`, `named-entity-manager-only`, `no-injected-repository`); a `DataSource` or `QueryRunner` is not written as a type, awaited value or `provide:` token outside those places, and a class that receives a wrapper exposing one is refused (`named-entity-manager-only`); a class outside an application handler, a domain service and a platform persistence capability takes, holds or returns no `EntityManager`, `Repository`, `DataSource` or `QueryRunner` whatever it is called, and no exported function takes an `EntityManager` first (a statement module); `src/tests` is exempt (`no-repository-class`); a `DataSource` or `QueryRunner` is not written as a type, awaited value or `provide:` token outside those places, and a class that receives a wrapper exposing one is refused (`named-entity-manager-only`); a class outside an application handler, a domain service and a platform persistence capability takes, holds or returns no `EntityManager`, `Repository`, `DataSource` or `QueryRunner`, whatever it is called, and no exported function takes an `EntityManager` first (a statement module); the test tree (`src/tests`) is exempt (`no-repository-class`); inside a transaction callback only the manager it received is used (`no-outer-manager-in-transaction`); no call through an integration, `HttpClient` or `MessagePublisher` typed receiver spans a transaction (`no-external-call-in-transaction`); the manager is injected only in application handlers, domain services and the platform database, inbox, outbox and lease capabilities (`em-injection-slots`) |
+| **Connections** | One database is one connection and one `Inject<Conn>EntityManager()` injector: `InjectEntityManager(`, `InjectDataSource(` and `getEntityManagerToken(` are called only in `platform/database/<conn>.decorators.ts`, the cli and the test world; an exported EntityManager injector is exactly the declared connection's; `TypeOrmModule.forRoot*` and `new DataSource(` live in the platform database capability and the cli; the connection name is written once, in its `<conn>.connection.ts`; a `<conn>.config.ts` reads only keys of its `envPrefix` (`one-connection-per-database`) |
 | **Operations** | A versioned operation is declared once in the app's typed operation table (`query<Input, Output, RefusalCode>()` / `mutation<...>()` registered by `defineOperations`, declared by the platform capability `operations`): its input and output are closed types (no `any`, `unknown`, `Record<string, unknown>`, unbound generic, function or `Date`) and its refusal codes a closed union of string literals; a route that takes or answers the table's types takes `OperationRequest<Table>` and answers `Promise<OperationReply<Table>>` of one table (`operation-contract-decidable`, `operation-route-driven-by-table`) |
+| **Webhooks and realtime** | A provider webhook door injects only the `WebhookSignatureService` and domain services, starts with the unconditional `verify` call, makes exactly one domain call and returns nothing (`webhook-shape`, `webhook-verify-first`); a realtime door is one gateway or subscription that injects only the `RealtimeHub` and subscribes to a topic built from its `@CurrentPrincipal()` (`realtime-shape`, `realtime-read-only`, `realtime-topic-scope`) |
 | **Transport** | A door injects only `CommandBus` / `QueryBus` (and `RequestLocale` in REST) and dispatches exactly one message per handler, holding no branch, loop, EntityManager or call other than the bus, and pure `*.mapper.ts` functions and `unwrapOutcome` of `platform/primitives` (`transport-is-thin`); no response envelope, no `GraphQLJSON`, no `unknown` body, no `switch (input.operation)`; a REST door lives in `transport/http` and shows a public reason, a byte stream or a redirect; a capability never imports a feature (`transport-is-thin`, `no-response-envelope`, `no-graphql-json`, `door-lives-in-features`, `rest-door-needs-a-reason`, `no-capability-imports-features`) |
+| **Feature thin** (R203 BE_FEATURE_THIN) | A feature-tier file of a thin role (`<name>.handler.ts`, `.resolver.ts`, `.controller.ts`, `.consumer.ts`, `.processor.ts`, `.step.ts`, `.saga.ts`, `.saga-step.ts`, `.compensation.ts`, `.webhook.ts`, `.gateway.ts`, `.subscription.ts`, `.cli.ts`, `.mapper.ts`, `.service.ts`) maps its parameters and makes exactly one delegating call into the modules - an injected member, a bus `execute` or a modules function in statement position - with no branch, loop, `try`, `throw` or computation; free calls are pure `*.mapper.ts` functions, the `Logger` port and a webhook's `verify`; orchestration (step order, compensation, claim, fencing, retry) belongs to the platform (`feature-thin`) |
 | **Infrastructure owners** | Each raw library (HTTP, cache, queue, scheduler, logger, date, config, events) is imported or reached as a global only inside the capability the manifest names for it (`ruleParams.be.infraOwners`); `@nestjs/config`, `dotenv` and `@nestjs/event-emitter` nowhere; the `HttpClient` port of `platform/http` (found by the receiver's type) is called only in an `integrations` owner, `platform/http` and the test world (`infra-import-owner`, `http-client-only-in-integrations`) |
 | **Observability** | Logs leave through the `Logger` port of `platform/logging`, never the framework's `Logger`; a log call's first argument is a member of an owner's `<owner>.log-events.ts` enum; a failure log carries the exception's identity, not only its wording (`no-framework-logger`, `no-interpolated-log-message`, `no-error-wording-as-log-identity`) |
-| **Testing** | Only services are unit-tested: every `<name>.service.ts` has its `<name>.service.spec.ts` beside it, a service spec has its service beside it, and any other `*.spec.ts` outside `src/tests/{e2e,integration,contract,world}` and `apps/migrate` (handler, resolver, controller, consumer, mapper, entity, guard, module, policy, helper, composition) is a finding; there is no `.test.ts`, `int-spec` or `harness-spec`; a spec asserts a result or a state, not only a call; an e2e reads persisted state back through a typeorm `EntityManager` and reaches no model provider outside `src/tests/e2e/live/` (`unit-test-colocated`, `no-call-only-spec`, `e2e-asserts-persisted-state`, `no-model-call-in-e2e`, `no-api-shaped-e2e-filename`, `no-marker-model-stub`) |
+| **Testing** | A unit spec is `<name>.<role>.spec.ts` beside its subject: REQUIRED beside every file of a spec-required role of `ruleParams.be.unitRoles` (every `<name>.service.ts` its `<name>.service.spec.ts`, every `<name>.cli.ts` of `src/features/cli/` its `<name>.cli.spec.ts`) and beside a webhook or realtime door that has no service of its own; OPTIONAL beside any other file of a `ruleParams.be.logicRoles` role inside a slot whose `coverage` is `required` (the file owes 100 per file, not a spec of its own); any other `*.spec.ts` outside `src/tests/{e2e,integration,contract,world}` (handler, resolver, controller, consumer, entity, module, composition) is a finding; there is no `.test.ts`, `int-spec` or `harness-spec`; a spec asserts a result or a state, not only a call; an e2e reads persisted state back through a typeorm `EntityManager` and reaches no model provider outside `src/tests/e2e/live/` (`unit-test-colocated`, `no-call-only-spec`, `e2e-asserts-persisted-state`, `no-model-call-in-e2e`, `no-api-shaped-e2e-filename`, `no-marker-model-stub`) |
+| **Command line** | Every one-off action is a nest-commander command of the one cli app: `apps/cli/src/main.ts` boots with `CommandFactory.run` and never serves (`cli-bootstrap`); a `@Command` or `@SubCommand` is declared only in `src/features/cli/` as `<group>/<group>.cli.ts` or `<group>/subs/<name>.cli.ts`, one per file, each with its `<name>.cli.spec.ts` beside it (`cli-command-shape`, `unit-test-colocated`); `nest-commander` is imported only by the cli, and `process.argv`, `commander`, `yargs` and `minimist` nowhere (`cli-owner`) |
 | **End-to-end flows** | One file, one flow, named steps; the flow enters through transport (a `CommandBus`, `QueryBus` or a handler, consumer or job is never called), boots through `src/tests/e2e/setup` (no `Test.createTestingModule`), **never sleeps** — it polls with `waitFor` until the state settles, with a deadline — and takes no branch inside a step (`e2e-uses-production-transport`, `no-wiring-in-flow-spec`, `no-sleep-in-flow`, `no-branch-in-flow-step`) |
 | **CDC · event delivery** | Projections and events follow the declared delivery contract |
 | **Service dependencies · source form** | Production source declares no `Mock*`, `Fake*` or `Stub*` class, function or constant: the marker is a whole PascalCase or camelCase word of the identifier, a double lives in a spec or `src/tests`, and an offline driver is an options-driven adapter named for what it does (`no-test-double-in-source`); the provider, repository-class and connection rules of this law are listed under Dependency injection and Data access |
 | **Comments · naming · type safety** | Comments say why; no double cast through `unknown`; named exports only, the Jest `*.global-setup.ts` being the one default export; Vietnamese only in a message catalog or the `src/tests/fixtures/i18n/` fixtures slot (`be.tests.fixtures.i18n`), never in an identifier, string, comment or test title, specs included, in NFC or NFD spelling (`no-default-export`, `no-non-ascii-source`) |
 | **User copy** | A literal message of an error class (judged by the constructed type extending `Error`), a text property handed to an outbound port (a receiver typed from `integrations` or `platform/messaging`) or a response copy in a transport slot comes from the messages catalog through the typed `MessageCatalog` port, specs included (`user-copy-through-catalog`) |
 | **Temporal** | `Date.now`, a bare `new Date()`, `performance.now`, `process.hrtime` and `Temporal.Now` are referenced (not only called) only inside `platform/clock`, specs included (`no-ambient-clock`) |
-| **Dependency injection** | Raw `Inject(`, `InjectEntityManager(`, `InjectDataSource(`, `InjectQueue(`, `InjectRepository(` and any third-party `Inject*` are called only in a `<owner>.decorators.ts` at an owner root, and injectors decorate constructor parameters only; an injector is zero-argument, typed `TypedParameterDecorator<T>`, built with `injector<T>(token)`, documented, over a `unique symbol` token; `T` equals the parameter type; a parameter typed by a platform, integrations or package declaration carries an injector (only domain services and the same owner are class-injected); no `ModuleRef`, no `forwardRef`, no string token; a constructor parameter of a Nest provider is typed by a class or carries an `Inject<Thing>()`, never a bare primitive, `Map`, union or interface (`injector-only`, `injector-shape`, `injector-type-match`, `infra-needs-injector`, `provider-param-token`, `no-module-ref`, `no-forward-ref`, `no-string-token`) |
+| **Dependency injection** | Raw `Inject(`, `InjectEntityManager(`, `InjectDataSource(`, `InjectQueue(`, `InjectRepository(` and any third-party `Inject*` are called only in a `<owner>.decorators.ts` at an owner root, and injectors decorate constructor parameters only; an injector is zero-argument, typed `TypedParameterDecorator<T>`, built with `injector<T>(token)`, documented, over a `unique symbol` token; `T` equals the parameter type; a parameter typed by a platform, integrations or package declaration carries an injector (only domain services and the same owner are class-injected); no `ModuleRef`, no `forwardRef`, no string token; a constructor parameter of a Nest provider is typed by a class or carries an `Inject<Thing>()`, never a bare primitive, `Map`, union or interface; a parameter that injects a port of the table `ruleParams.be.paramNames` of the slot manifest (`Clock`, `Logger`, `Cache`, `CommandBus`, `QueryBus`, `EntityManager`, an `*Options`) carries the name that table gives it (`injector-only`, `injector-shape`, `injector-type-match`, `infra-needs-injector`, `provider-param-token`, `injected-param-name`, `no-module-ref`, `no-forward-ref`, `no-string-token`) |
 | **Idempotency** | The first awaited expression of a public service method whose first parameter has an `eventId` is `claim(source, eventId)` on a receiver typed as the `Inbox` port, followed by an early return on `false`; doors are thin and claim nothing (`inbox-dedupe-required`) |
+| **Service isolation** | A file of a service app (`apps/<service>/`) imports no file of a sibling service app, through a relative path or an alias of the program's own `paths`: the app that owns each file comes from the slot view, never from a name (`service-isolation`, R168 `BE_SERVICE_ISOLATION`). Services share only the `src` libraries and meet through the wire. |
 
 Every rule names the law that declares it — `ruleOwners` maps rule name to law, so a failing build
 line leads straight to the document that explains why.

package/ambient-id.mjs

@@ -0,0 +1,90 @@
+/**
+ * The rule that holds `platform/ids` (catalog R142 `BE_AMBIENT_ID`).
+ *
+ *   - `no-ambient-id` refuses every source of an identifier that does not come from the injected `Ids` port:
+ *     `randomUUID` of `node:crypto` (a named import, a namespace or default import, or the global `crypto`), the
+ *     generators of the `uuid` package that read the clock or a random source (`v1`, `v4`, `v6`, `v7`), and the `nanoid` and
+ *     `ulid` packages. Business code asks `ids.next()`; a spec provides `fakeIds()`, so an id is exactly what the spec said
+ *     and a failing run reproduces.
+ *
+ * The owner that may mint ids is asked of the slot view (`platform` tier, capability `ids`), as the clock is, and the test
+ * world (slot `be.tests.world`) is exempt like it is from the clock: it is the composition root of tests and names real
+ * resources. Specs are NOT exempt. The generators are found by the module they are imported from, never by a local name,
+ * so `import { randomUUID as newId } from "node:crypto"` is the same reference.
+ */
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
+import { isOwnedBy } from "./lib/ports.mjs"
+
+/** Modules of Node's crypto: `randomUUID` of them mints an id. */
+const CRYPTO_MODULES = new Set(["node:crypto", "crypto"])
+
+/** Packages whose named exports mint an id, and which of them (`null`: every export). */
+const ID_PACKAGES = Object.freeze({ uuid: ["v1", "v4", "v6", "v7"], nanoid: null, "nanoid/non-secure": null, ulid: null })
+
+/** The variable a name resolves to from `node`'s scope, or null when it is a global. */
+const variableOf = (context, node, name) => {
+    let scope = (context.sourceCode || context.getSourceCode()).getScope(node)
+    while (scope) {
+        const found = scope.set.get(name)
+        if (found) return found
+        scope = scope.upper
+    }
+    return null
+}
+
+/** Whether `node` is the global `crypto` (or `globalThis.crypto`) or an import of Node's crypto module as a whole. */
+const isCryptoObject = (context, node) => {
+    if (node.type === "MemberExpression" && !node.computed && node.object.type === "Identifier" && node.object.name === "globalThis" && node.property.type === "Identifier" && node.property.name === "crypto") return true
+    if (node.type !== "Identifier") return false
+    const variable = variableOf(context, node, node.name)
+    if (!variable || variable.defs.length === 0) return node.name === "crypto"
+    return variable.defs.every((def) => def.type === "ImportBinding" && CRYPTO_MODULES.has(def.parent.source.value) && def.node.type !== "ImportSpecifier")
+}
+
+/** No id is minted outside `platform/ids`. */
+export const noAmbientId = {
+    meta: {
+        type: "problem",
+        docs: { description: "`randomUUID`, the `uuid` generators, `nanoid` and `ulid` are used only inside `platform/ids`; code asks the injected `Ids` port." },
+        schema: [],
+        messages: {
+            id: "`{{call}}` mints an id from the ambient random source. Inject the `Ids` port (`@InjectIds() private readonly ids: Ids`, `ids.next()`); a spec then provides `fakeIds()` and every id is the one it said, which a direct call never allows.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const filename = context.filename || context.getFilename()
+        if (isOwnedBy(hfs, filename, "platform", "ids") || inTestWorld(hfs, filename)) return {}
+        return {
+            ImportDeclaration(node) {
+                const source = node.source.value
+                if (CRYPTO_MODULES.has(source)) {
+                    for (const specifier of node.specifiers) {
+                        if (specifier.type === "ImportSpecifier" && (specifier.imported.name ?? specifier.imported.value) === "randomUUID") context.report({ node: specifier, messageId: "id", data: { call: `randomUUID from ${source}` } })
+                    }
+                    return
+                }
+                if (!Object.hasOwn(ID_PACKAGES, source)) return
+                const banned = ID_PACKAGES[source]
+                for (const specifier of node.specifiers) {
+                    const imported = specifier.type === "ImportSpecifier" ? (specifier.imported.name ?? specifier.imported.value) : specifier.type === "ImportDefaultSpecifier" ? "default" : "*"
+                    if (banned === null || banned.includes(imported) || imported === "*") context.report({ node: specifier, messageId: "id", data: { call: `${imported === "default" ? source : imported} from ${source}` } })
+                }
+            },
+            MemberExpression(node) {
+                const member = !node.computed && node.property.type === "Identifier" ? node.property.name : node.computed && node.property.type === "Literal" ? node.property.value : null
+                if (member === "randomUUID" && isCryptoObject(context, node.object)) context.report({ node, messageId: "id", data: { call: "crypto.randomUUID" } })
+            },
+        }
+    },
+}
+
+/** The rule this law contributes to the plugin. */
+export const rules = {
+    "no-ambient-id": noAmbientId,
+}
+
+/** Starts at error: no baseline exists, and the repositories' fix lanes clear the debt with an Ids codemod. */
+export const recommended = {
+    "starci-be/no-ambient-id": "error",
+}

package/cli.mjs

@@ -0,0 +1,181 @@
+/**
+ * The rules of the one-off actions of a back end (catalog R148 `BE_CLI_BOOTSTRAP`, R149 `BE_CLI_COMMAND_SHAPE`, R150
+ * `BE_CLI_OWNER`). Every one-off action (migrate, seed, sync, backup, any operator command)
+ * lives in ONE app, `be/apps/cli` (slot `be.app.cli`), built on nest-commander, and its commands live in the cli feature root
+ * `src/features/cli/` (slot `be.cli`):
+ *
+ *   - `cli-bootstrap`: the cli app boots with `CommandFactory.run(...)` of nest-commander in its `main.ts`; it never creates an HTTP
+ *     application or a microservice (`NestFactory.create*` of `@nestjs/core`, `.listen()` on what it built, an HTTP platform adapter
+ *     or `@nestjs/microservices`);
+ *   - `cli-command-shape`: a nest-commander command class (`@Command` or `@SubCommand`, by the import that binds the decorator) is
+ *     declared only in the cli feature root: a group `@Command` in `<group>/<group>.cli.ts`, a `@SubCommand` in
+ *     `<group>/subs/<name>.cli.ts`, one class per file, and a sub-command extends `CommandRunner`. Its unit spec beside it
+ *     (`<name>.cli.spec.ts`) is required by `starci app check` (scripts/hfs/rules/cli.mjs);
+ *   - `cli-owner`: `nest-commander` is imported only by the cli app and the cli feature root; no back-end source parses the process
+ *     arguments itself (`process.argv`) or imports another argument parser (commander, yargs, minimist): an action door anywhere
+ *     else is refused.
+ *
+ * Where a file lives is asked of the slot view; what a name IS comes from the import that binds it. No path pattern is spelled here.
+ */
+import { hfsOf } from "./lib/hfs.mjs"
+import { decoratorCallee, importOf, isImportedFrom, moduleReferences } from "./lib/import-source.mjs"
+
+/** The slot of the cli app and of the cli feature root. */
+const CLI_APP_SLOT = "be.app.cli"
+const CLI_FEATURE_SLOT = "be.cli"
+const COMMANDER = "nest-commander"
+/** The argument parsers no back-end source imports: nest-commander (in the cli app and feature only) parses the arguments. */
+const FOREIGN_PARSERS = new Set(["commander", "yargs", "yargs/yargs", "yargs/helpers", "minimist"])
+/** The entry file of an app (the slot's first requirement): where the cli app boots. */
+const ENTRY = "main.ts"
+
+const relativeIn = (hfs, file) => hfs.allows(file)?.relative ?? null
+const isCliApp = (hfs, file) => hfs.slotOf(file) === CLI_APP_SLOT
+const isCliFeature = (hfs, file) => hfs.slotOf(file) === CLI_FEATURE_SLOT
+
+/** The cli app boots with CommandFactory.run and never serves HTTP or a microservice. */
+export const cliBootstrap = {
+    meta: {
+        type: "problem",
+        docs: { description: "The cli app boots with `CommandFactory.run` of nest-commander and never creates an HTTP application or a microservice." },
+        schema: [],
+        messages: {
+            missing: "The cli app's `main.ts` never calls `CommandFactory.run(AppModule, ...)` of nest-commander. The cli app is the command line of the back end: boot it with CommandFactory.run, which parses the arguments and runs the command.",
+            server: "`{{name}}` makes the cli app a server. The cli app runs one command and exits: boot it with `CommandFactory.run` of nest-commander; a server is an api app.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const filename = context.filename
+        if (!isCliApp(hfs, filename)) return {}
+        const entry = relativeIn(hfs, filename) === ENTRY
+        let boots = false
+        return {
+            ...moduleReferences(({ source, value }) => {
+                if (value === "@nestjs/microservices" || value.startsWith("@nestjs/platform-")) context.report({ node: source, messageId: "server", data: { name: value } })
+            }),
+            CallExpression(node) {
+                const callee = node.callee
+                if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier") return
+                const method = callee.property.name
+                if (method === "run" && isImportedFrom(context, callee.object, COMMANDER, "CommandFactory")) boots = true
+                if (isImportedFrom(context, callee.object, "@nestjs/core", "NestFactory")) context.report({ node, messageId: "server", data: { name: `NestFactory.${method}` } })
+                else if (method === "listen" || method === "connectMicroservice" || method === "startAllMicroservices") context.report({ node, messageId: "server", data: { name: `.${method}()` } })
+            },
+            "Program:exit"(program) {
+                if (entry && !boots) context.report({ node: program, messageId: "missing" })
+            },
+        }
+    },
+}
+
+/** The nest-commander decorator a class carries (Command or SubCommand), by the import that binds it. */
+const commanderDecorator = (context, klass) => {
+    for (const decorator of klass.decorators ?? []) {
+        const callee = decoratorCallee(decorator)
+        if (callee?.type !== "Identifier") continue
+        const bound = importOf(context, callee)
+        if (bound?.source === COMMANDER && (bound.imported === "Command" || bound.imported === "SubCommand")) return { decorator, kind: bound.imported }
+    }
+    return null
+}
+
+/** Where a command of each kind is declared in the cli feature root: `<group>/<group>.cli.ts` or `<group>/subs/<name>.cli.ts`. */
+const placeOf = (relative) => {
+    const parts = String(relative ?? "").split("/")
+    if (parts.length === 2 && parts[1] === `${parts[0]}.cli.ts`) return "Command"
+    if (parts.length === 3 && parts[1] === "subs" && parts[2].endsWith(".cli.ts") && !parts[2].endsWith(".spec.ts")) return "SubCommand"
+    return null
+}
+
+/** A nest-commander command is declared only where the cli feature root keeps it, one per file, a sub-command a CommandRunner. */
+export const cliCommandShape = {
+    meta: {
+        type: "problem",
+        docs: { description: "A nest-commander command is a group `@Command` in `src/features/cli/<group>/<group>.cli.ts` or a `@SubCommand` extending `CommandRunner` in `src/features/cli/<group>/subs/<name>.cli.ts`, one per file." },
+        schema: [],
+        messages: {
+            outside: "`@{{kind}}` declares a command outside the cli feature root (this file is in slot `{{slot}}`). Every one-off action is a command of `src/features/cli/`: a group in `<group>/<group>.cli.ts`, a sub-command in `<group>/subs/<name>.cli.ts`, compiled only into apps/cli.",
+            misplaced: "`@{{kind}}` sits in `{{relative}}`. A group `@Command` lives in `<group>/<group>.cli.ts` and a `@SubCommand` in `<group>/subs/<name>.cli.ts` of the cli feature root.",
+            second: "This file declares a second command. One command per file: move it to its own `<name>.cli.ts`.",
+            runner: "`@SubCommand` class `{{name}}` does not extend `CommandRunner` of nest-commander. A sub-command is a CommandRunner whose `run(...)` performs the action.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const filename = context.filename
+        const slot = hfs.slotOf(filename)
+        const place = isCliFeature(hfs, filename) ? placeOf(relativeIn(hfs, filename)) : null
+        let commands = 0
+        const check = (klass) => {
+            const found = commanderDecorator(context, klass)
+            if (!found) return
+            commands += 1
+            if (!isCliFeature(hfs, filename)) return context.report({ node: found.decorator, messageId: "outside", data: { kind: found.kind, slot: slot ?? "none" } })
+            if (place !== found.kind) return context.report({ node: found.decorator, messageId: "misplaced", data: { kind: found.kind, relative: relativeIn(hfs, filename) ?? filename } })
+            if (commands > 1) return context.report({ node: found.decorator, messageId: "second" })
+            if (found.kind === "SubCommand" && !(klass.superClass && isImportedFrom(context, klass.superClass, COMMANDER, "CommandRunner"))) context.report({ node: klass.id ?? klass, messageId: "runner", data: { name: klass.id?.name ?? "anonymous" } })
+        }
+        return { ClassDeclaration: check, ClassExpression: check }
+    },
+}
+
+/** Whether a member expression is `process.argv` of the Node global (or `globalThis.process.argv`). */
+const isProcessArgv = (context, node) => {
+    if (node.computed || node.property.type !== "Identifier" || node.property.name !== "argv") return false
+    const object = node.object
+    const isProcess = (expression) => {
+        if (expression.type !== "Identifier" || expression.name !== "process") return false
+        for (let scope = context.sourceCode.getScope(expression); scope; scope = scope.upper) {
+            const variable = scope.set.get("process")
+            if (variable) return variable.defs.length === 0
+        }
+        return true
+    }
+    if (isProcess(object)) return true
+    return object.type === "MemberExpression" && !object.computed && object.object.type === "Identifier" && object.object.name === "globalThis" && object.property.type === "Identifier" && object.property.name === "process"
+}
+
+/** nest-commander belongs to the cli app and the cli feature root; nothing else parses arguments or opens an action door. */
+export const cliOwner = {
+    meta: {
+        type: "problem",
+        docs: { description: "nest-commander is imported only by the cli app and the cli feature root; no back-end source reads `process.argv` or imports another argument parser." },
+        schema: [],
+        messages: {
+            commander: "`nest-commander` is imported outside the cli app and the cli feature root (this file is in slot `{{slot}}`). A one-off action is a command of `src/features/cli/` run by apps/cli; no other app or source opens an action door.",
+            parser: "`{{name}}` parses command-line arguments. The back end has one command line, apps/cli on nest-commander: write the action as a command of `src/features/cli/<group>/subs/<name>.cli.ts`.",
+            argv: "`process.argv` is read here. No back-end process parses its own arguments: a one-off action is a command of `src/features/cli/` that apps/cli runs through nest-commander.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const filename = context.filename
+        const slot = hfs.slotOf(filename)
+        const owner = isCliApp(hfs, filename) || isCliFeature(hfs, filename)
+        return {
+            ...moduleReferences(({ source, value }) => {
+                if (value === COMMANDER || value.startsWith(`${COMMANDER}/`)) {
+                    if (!owner) context.report({ node: source, messageId: "commander", data: { slot: slot ?? "none" } })
+                } else if (FOREIGN_PARSERS.has(value)) context.report({ node: source, messageId: "parser", data: { name: value } })
+            }),
+            MemberExpression(node) {
+                if (isProcessArgv(context, node)) context.report({ node, messageId: "argv" })
+            },
+        }
+    },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "cli-bootstrap": cliBootstrap,
+    "cli-command-shape": cliCommandShape,
+    "cli-owner": cliOwner,
+}
+
+/** Every rule is an error from the start: HFS keeps no baseline. */
+export const recommended = {
+    "starci-be/cli-bootstrap": "error",
+    "starci-be/cli-command-shape": "error",
+    "starci-be/cli-owner": "error",
+}

package/comments.mjs

@@ -10,7 +10,7 @@
  *     constructor and an index signature are not surface, overload signatures of one name share one doc, and a property
  *     set to a literal or a named constant is a data constant (COMMENT-1's reason). Product source only: the test tiers
  *     (`e2e`, `fixtures` of the slot manifest) document their spec-read shapes at the type.
- *   - `require-enum-member-jsdoc` can check that a doc EXISTS and never that it states a
+ *   - `require-enum-member-jsdoc` checks an adjacent non-empty description, never whether it states a
  *     consequence. That half is read by a person, and the rule says so rather than pretending.
  *   - `no-non-ascii-source` takes no exemption marker: HFS removed `vn-ok`, so text a program depends on
  *     lives in a message catalog (slot be.domain.messages, of any module tier, or be.feature.messages), the only place Vietnamese may appear. Specs
@@ -26,6 +26,7 @@
 import { hfsOf } from "./lib/hfs.mjs"
 import { normalizePath } from "./lib/path.mjs"
 import { hasSecondLanguage } from "./runtime/scripts/lib/language.mjs"
+import { jsdocBefore, jsdocDescription } from "./runtime/scripts/lib/jsdoc.mjs"
 
 /** The slots of the per-owner message catalogs: the only source files that may hold Vietnamese. */
 const CATALOG_SLOTS = new Set(["be.domain.messages", "be.feature.messages"])
@@ -65,7 +66,7 @@ const ORNAMENT = /[✅❌✔✖✗✘⭐⬆⬇➡⬅]/
 const FIXTURE_SLOTS = new Set(["be.tests.fixtures.i18n"])
 
 /** The Vietnamese language's own name, which is a label rather than prose. */
-const ENDONYM = /Tiếng Việt/
+const ENDONYM = /Ti\u1ebfng Vi\u1ec7t/
 
 /** Declarations whose surface other files depend on. */
 const DOCUMENTED_KINDS = new Set([
@@ -85,11 +86,21 @@ const offenceIn = (line) => {
   return null
 }
 
-/** Whether a JSDoc block sits immediately before a node. */
-const hasJsdocBefore = (sourceCode, node) =>
-  sourceCode
-    .getCommentsBefore(node)
-    .some((comment) => comment.type === "Block" && comment.value.startsWith("*"))
+/**
+ * Whether an exported declaration has a surface a caller documents: a data constant is already described by its name,
+ * and a kind outside DOCUMENTED_KINDS has no surface at all.
+ */
+const hasDocumentedSurface = (declaration) => {
+  if (declaration.type === "VariableDeclaration") {
+    // a later declarator can expose a function even when the first binding is plain data
+    return declaration.declarations.some(({ init }) => Boolean(init)
+      && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression"))
+  }
+  return DOCUMENTED_KINDS.has(declaration.type)
+}
+
+/** Whether the adjacent JSDoc has a declaration description rather than only tags or a file header. */
+const hasJsdocBefore = (sourceCode, node) => jsdocBefore(sourceCode, node) !== null
 
 /** The declared name, for the message. */
 const nameOf = (declaration) => {
@@ -108,7 +119,7 @@ export const requireExportJsdoc = {
     schema: [],
     messages: {
       jsdoc:
-        "`{{name}}` is exported with no doc block. This is surface other files depend on, and a name plus a signature says what it TAKES - never what it is for, or when to reach for it rather than the thing beside it.",
+        "`{{name}}` is exported without an adjacent JSDoc description. This is surface other files depend on, and a name plus a signature says what it TAKES - never what it is for, or when to reach for it rather than the thing beside it.",
     },
   },
   create(context) {
@@ -117,16 +128,7 @@ export const requireExportJsdoc = {
       const declaration = node.declaration
       // a re-export has nothing here to attach a doc to
       if (!declaration) return
-      if (declaration.type === "VariableDeclaration") {
-        // only a const bound to a function has a surface; a data constant is already described
-        const first = declaration.declarations[0]
-        const init = first && first.init
-        const isFunction = init
-          && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")
-        if (!isFunction) return
-      } else if (!DOCUMENTED_KINDS.has(declaration.type)) {
-        return
-      }
+      if (!hasDocumentedSurface(declaration)) return
       if (hasJsdocBefore(sourceCode, node)) return
       context.report({
         node: declaration.id || declaration,
@@ -208,7 +210,7 @@ export const requirePublicMemberJsdoc = {
     schema: [],
     messages: {
       jsdoc:
-        "`{{owner}}.{{name}}` is public surface with no doc block. A caller reaches the member, not the type's doc: say what it is for, what calling or reading it causes, or what it holds.",
+        "`{{owner}}.{{name}}` is public surface without an adjacent JSDoc description. A caller reaches the member, not the type's doc: say what it is for, what calling or reading it causes, or what it holds.",
     },
   },
   create(context) {
@@ -247,7 +249,7 @@ export const requireEnumMemberJsdoc = {
     schema: [],
     messages: {
       jsdoc:
-        "Enum member `{{name}}` has no doc. State what CHOOSING it causes, not what it is called - a member is picked at a call site far from the switch that gives it meaning. (A rule can only see that a doc exists; whether it states a consequence is read by a person.)",
+        "Enum member `{{name}}` has no adjacent JSDoc description. State what CHOOSING it causes, not what it is called - a member is picked at a call site far from the switch that gives it meaning. (A rule can only see that a doc exists; whether it states a consequence is read by a person.)",
     },
   },
   create(context) {
@@ -328,7 +330,7 @@ const RESTATEMENT_FILLER = new Set(["a", "an", "the", "is", "of", "for", "to", "
 
 /** The content words a doc comment contributes once filler is stripped out. */
 const docContentWords = (comment) =>
-  (comment.value.match(/[A-Za-z]+/g) || [])
+  (jsdocDescription(comment).match(/[A-Za-z]+/g) || [])
     .map((word) => word.toLowerCase())
     .filter((word) => !RESTATEMENT_FILLER.has(word))
 
@@ -344,11 +346,6 @@ const isPureRestatement = (comment, declaredName) => {
   return true
 }
 
-/** The doc block immediately before a node, or null. */
-const jsdocBefore = (sourceCode, node) =>
-  sourceCode.getCommentsBefore(node).find((comment) => comment.type === "Block" && comment.value.startsWith("*"))
-    || null
-
 /** A doc block that only re-spells the declared name is COMMENT-3's violation wearing COMMENT-1's shape. */
 export const noRestatedNameJsdoc = {
   meta: {
@@ -369,16 +366,7 @@ export const noRestatedNameJsdoc = {
       const declaration = node.declaration
       // a re-export has nothing here to attach a doc to
       if (!declaration) return
-      if (declaration.type === "VariableDeclaration") {
-        // only a const bound to a function has a surface; a data constant is already described
-        const first = declaration.declarations[0]
-        const init = first && first.init
-        const isFunction = init
-          && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")
-        if (!isFunction) return
-      } else if (!DOCUMENTED_KINDS.has(declaration.type)) {
-        return
-      }
+      if (!hasDocumentedSurface(declaration)) return
       const doc = jsdocBefore(sourceCode, node)
       if (!doc) return
       const name = nameOf(declaration)

package/config-owner.mjs

@@ -26,12 +26,12 @@
 import ts from "typescript"
 import { keyName, staticText, walk, wordsOf } from "./lib/ast.mjs"
 import { isOwnedBy, isOwnedType, originsOf } from "./lib/declared.mjs"
-import { hfsOf } from "./lib/hfs.mjs"
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
 import { isDeclarationFile, normalizePath } from "./lib/path.mjs"
-import { originsOfType, typed } from "./lib/types.mjs"
+import { moduleOf, originsOfType, typed } from "./lib/types.mjs"
 
 /** The test composition root (slot `be.tests.world`): it composes app options like `main.ts` and hands run state to jest workers through the environment. */
-const isTestWorld = (hfs, file) => hfs.slotOf(file) === "be.tests.world"
+const isTestWorld = inTestWorld
 
 const PROCESS_MODULES = new Set(["process", "node:process"])
 
@@ -304,6 +304,22 @@ const isSecretValue = (context, node) => {
     return isOwnedType(context, node, "Secret", "platform", "config") || (holder !== null && isOwnedType(context, holder, "Secret", "platform", "config"))
 }
 
+/** The packages that declare the Node crypto types: a digest read out of a `Hash` or `Hmac` is secret-derived material. */
+const CRYPTO_PACKAGES = new Set(["crypto", "node:crypto"])
+
+/** A `.digest(...)` of a `Hash` or `Hmac` of Node's crypto, found by where the called signature is declared, never by the receiver's name. */
+const isCryptoDigest = (context, node) => {
+    if (node.type !== "CallExpression" || node.callee.type !== "MemberExpression") return false
+    const { checker, toTs } = typed(context)
+    const tsCall = toTs(node)
+    const declaration = tsCall ? checker.getResolvedSignature(tsCall)?.declaration : undefined
+    if (!declaration || !declaration.name || declaration.name.getText() !== "digest") return false
+    const owner = declaration.parent
+    const ownerName = (ts.isInterfaceDeclaration(owner) || ts.isClassDeclaration(owner)) && owner.name ? owner.name.text : ""
+    if (ownerName !== "Hash" && ownerName !== "Hmac") return false
+    return CRYPTO_PACKAGES.has(moduleOf(declaration, String(declaration.getSourceFile().fileName).split("\\").join("/")))
+}
+
 /** A secret is compared with `timingSafeEqual`, never with an equality operator. */
 export const secretCompareTimingSafe = {
     meta: {
@@ -322,7 +338,7 @@ export const secretCompareTimingSafe = {
                 if (!["===", "!==", "==", "!="].includes(node.operator)) return
                 if (isPresenceOperand(node.left) || isPresenceOperand(node.right)) return
                 for (const side of [node.left, node.right]) {
-                    if (isSecretValue(context, side)) {
+                    if (isSecretValue(context, side) || isCryptoDigest(context, side)) {
                         context.report({ node, messageId: "compare", data: { name: context.sourceCode.getText(side), operator: node.operator } })
                         return
                     }