@starci/eslint-canon-be 1.2.1 → 1.7.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## 1.7.0 - 2026-09-30
+
+- New: `named-entity-manager-only` (R83 `BE_UNNAMED_DATA_ACCESS`, in `data-access`): a bare `@InjectEntityManager()` with no connection argument, any `.getRepository(...)` call (on a DataSource, an EntityManager or a transaction manager) and an injected `DataSource` (a constructor parameter typed `DataSource`, `@InjectDataSource()`, `@InjectConnection()`) are refused. A `DataSource` is allowed only under `platform/database/` or `platform/databases/` (also `platform/db`, `platform/datasource`, `platform/typeorm`) and `apps/migrate/`; spec files are skipped. The message says to inject the shared EntityManager with the named injector and call it directly.
+- Changed: `no-injected-repository` now refuses `@InjectRepository(...)` wherever it is written (a property or a method parameter, not only a constructor parameter), and its message states the same one pattern.
+
+## 1.6.1 - 2026-09-30
+
+- Fixed: `inbox-dedupe-required` (R80 `BE_INBOX_DEDUPE_MISSING`) no longer relies only on `<event>.consumer.ts` under `transport/message/` to recognize a consumer. A method decorated `@EventPattern`, `@MessagePattern`, `@OnEvent` or `@Process`, or a class whose name ends `Consumer` or `OutboxConsumer`, is now a consumer wherever the file sits. The producer half of an outbox (typically `*-outbox.service.ts` / `*OutboxService`, which reads pending rows and publishes) carries none of those shapes and stays unflagged unless it also consumes.
+
+## 1.6.0 - 2026-09-30
+
+Round 3 back-end rules (catalog R78 to R82), each with RuleTester specs and a why code in `modules/kernel/failure-codes.yaml`.
+
+- New: `user-copy-through-catalog` (R78 `BE_USER_COPY_LITERAL`, new law `user-copy`): a literal exception message, a `subject`/`title`/`body`/`text`/`message` property of a `notify`/`send`/`publish` call, or a `message`/`description`/`title` property of a `transport/` response comes from the per-capability messages catalog through the typed `MessageCatalog` port; a short code-shaped literal (`UPPER_SNAKE`, a bare word) and a template literal are left alone. `no-ambient-clock` (R79 `BE_AMBIENT_CLOCK`, new law `temporal`): `Date.now()`, a bare `new Date()` and `performance.now()` are read only inside `platform/clock`; `new Date(value)` built from a value the caller already holds is exempt. `inbox-dedupe-required` (R80 `BE_INBOX_DEDUPE_MISSING`, new law `idempotency`): a `@Public()` webhook controller and an outbox/queue consumer (`<event>.consumer.ts`) show a reference to an inbox or dedupe port before they act. `no-hand-rolled-retry` (R81 `BE_HAND_ROLLED_RETRY`, in `resilience`): a `for`, `while` or `do...while` loop that both catches an error and calls something shaped like a delay (`sleep`, `delay`, `wait`, `backoff`, `setTimeout`) goes through `platform/retry`; a polling loop with no `catch` is exempt, same as `no-query-in-loop` exempts a polling `while`. `no-external-call-in-transaction` (R82 `BE_TRANSACTION_EXTERNAL_CALL`, in `data-access`): `fetch`, an HTTP client call or any method of a `*Client`/`*Sdk` receiver does not run inside `.transaction(async (tx) => ...)`.
+- Slot manifest (`knowledge/hfs/slots.yaml`, no version bump, additions stamped `since: 1.0.0`): `be.domain.messages` (`src/modules/{domain,integrations}/<capability>/messages/`) and `be.feature.messages` (`src/features/<feature>/messages/`), each an optional per-capability or per-feature vi/en catalog; `be.platform`'s required instances gain `clock` (the injected `Clock` port) and `i18n` (the `MessageCatalog` port); `be.domain` and `be.feature` allow a `messages/` folder.
+- Deferred (owner ruling, no rule): floating promises; core `no-await-in-loop` is not adopted.
+
+## 1.5.0 - 2026-09-30
+
+- New: `no-query-in-loop` (R77 `BE_QUERY_IN_LOOP`): a repository, entity-manager or query-builder read (`find`, `findOne`, `count`, `getOne`, a raw `SELECT`) inside a `for`, `for...of`, `for...in` or an array `map`, `forEach`, `flatMap`, `filter`, `reduce`, `some` or `every` callback is one round trip per element (N+1). A polling `while` loop and a write per element are not reported.
+
+## 1.4.0 - 2026-09-30
+
+Round 2 back-end rules (catalog R42, R68 to R76). Every rule below has RuleTester specs and a why code in `modules/kernel/failure-codes.yaml`; each was measured against nivo-backend, starci-next and mia-mia-backend before it shipped and is on at `error`.
+
+- New: `no-interpolated-sql` (R68: SQL text carries no runtime substitution; a constant column list, a `${n}` placeholder, `quoteIdent(...)`, `sqlSetClause(...)` and a ternary of fixed strings are the only substitutions), `query-needs-limit` (R69: `getMany`, `getRawMany`, `find`, `findBy` and a raw `SELECT` state a bound; a lookup by `id` and an aggregate are exempt), `http-needs-timeout` (R70: `fetch` carries a `signal`, axios and HttpService calls carry `timeout` or `signal`, `axios.create` a `timeout`), `no-secret-in-log` (R71: a logger call names no credential and no personal identifier), `no-never-cast` and `no-non-null-assertion` (R72), `async-needs-await` (R73: an `async` function that never awaits; a class that extends or implements, a decorated method and a generator are exempt), `migration-down-reversible` (R74: `down()` exists, is not empty and is not a bare throw), `explicit-handler-return-type` (R75), `json-parse-needs-guard` (R76), and `dto-needs-validator` (R42: every property of an input class carries a `class-validator` decorator).
+- New laws: `query-safety`, `resilience`, `log-safety`, `async-discipline`, `input-bounds`; `type-safety` and `schema-authority` gain rules.
+
+## 1.3.0 - 2026-09-29
+
+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: `must-deep-module-import` 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`.
+- 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.
+
+## 1.2.3 — 2026-09-29
+
+- `starciBeConfig({ sources, plugin, recommended })`, `linterOptions` and `RETIRED` are exported. The factory returns the one flat-config block a repository needs: the canon owns the retired-rule list (checked against the code-pattern manifest) and the warn-to-error lift, so a repository no longer hand-copies `replacedByChecks`.
+- `harness-calls-provider-directly` applies only to model harnesses, identified by an LLM provider SDK import, a house model helper or gateway symbol, or a `@harness-kind model` comment - never by the `src/tests/e2e/live/` folder. A live e2e for an identity provider (Keycloak) or any other third party is no longer reported as a model harness with no LLM SDK.
+
+## 1.2.2 — 2026-09-29
+
+- Align module aliases and explicit public `index.ts` exports with HFS capability boundaries. Keep self-aliases, tier-only aliases, folder re-exports, and export-star public entries invalid.
+- Accept concrete exceptions in their owning module or feature `errors/` directory, and accept the shared `AbstractException` declaration at its capability root.
+- Classify a `.spec.ts` beside its subject in an HFS `src/tests` category as a colocated structural spec. Ordinary unit specs without an adjacent subject remain invalid in test buckets; model-quality harness checks remain in force.

package/README.md

@@ -1,69 +1,145 @@
-# @starci/eslint-canon-be
-
-**37 ESLint rules, from 15 laws, that hold a NestJS-shaped back end to one way of being written.**
-
-Not a style pack. These rules enforce *architecture*: which layer may import which, whether a
-failure carries its own identity, where a query is allowed to be built, what an end-to-end test is
-permitted to assume. Prettier decides how code looks; this decides what it is allowed to be.
-
-```bash
-npm i -D @starci/eslint-canon-be
-```
-
-## Use it
-
-```js
-import starciBe, { recommended } from "@starci/eslint-canon-be"
-
-export default [
-    // …your own ignores, language options and other plugins…
-    {
-        files: ["src/**/*.ts"],
-        plugins: { "starci-be": starciBe },
-        rules: recommended,
-    },
-]
-```
-
-Which globs the law applies to is your repository's fact. What the law says is not — so there is no
-option to switch a rule off or lower it to a warning.
-
-Also exported: `rules`, `ruleOwners`, `lawOwners`.
-
-## What it actually catches
-
-A sample, not the list:
-
-| Area | What the rules hold |
-|---|---|
-| **Exceptions** | Every failure throws a domain exception carrying its own identity and metadata — never a bare `Error`, never a framework built-in, never an exception declared outside the exceptions folder |
-| **CQRS** | A handler does not assemble an aggregate inline; reads and writes do not share one path |
-| **Module layering** | An import that climbs a layer it was not given is a build failure, not a review comment |
-| **Data access** | Queries stay where the layer says they may be built |
-| **Transport** | The wire shape is declared, not inferred from whatever a handler happened to return |
-| **Observability** | A failure is logged as a typed exception, so a log line can be traced to the law that names it |
-| **End-to-end flows** | One file, one flow, named steps, and **never sleep** — poll until the state settles, with a deadline |
-| **CDC · event delivery** | Projections and events follow the declared delivery contract |
-| **Comments · naming · type safety** | Comments say why; no double cast through `unknown` |
-
-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.
-
-## Companion
-
-- **[@starci/eslint-canon-fe](https://www.npmjs.com/package/@starci/eslint-canon-fe)** — the
-  front-end half: 58 rules from 16 laws covering component tiers, structure contracts, the
-  fetch/draw split, vendor boundaries and the design-token scale.
-
-## Where the laws live
-
-Each rule is the enforceable half of a written law. The prose — why the rule exists, what it
-refuses, which cases sit just outside it — is published openly at
-[starci183/starci-claude-skills](https://github.com/starci183/starci-claude-skills).
-
-A rule that cannot be pointed at in real code is a proposal, not a law. Everything here is
-pointed at.
-
-## Requirements
-
-ESLint 9+ (flat config), Node 20.9+.
+# @starci/eslint-canon-be
+
+**78 ESLint rules, from 26 laws, that hold a NestJS-shaped back end to one way of being written.**
+
+Not a style pack. These rules enforce *architecture*: which layer may import which, whether a
+failure carries its own identity, where a query is allowed to be built, what an end-to-end test is
+permitted to assume. Prettier decides how code looks; this decides what it is allowed to be.
+
+```bash
+npm i -D @starci/eslint-canon-be
+```
+
+## Use it
+
+```js
+import starciBe, { recommended } from "@starci/eslint-canon-be"
+
+export default [
+    // …your own ignores, language options and other plugins…
+    {
+        files: ["src/**/*.ts"],
+        plugins: { "starci-be": starciBe },
+        rules: recommended,
+    },
+]
+```
+
+Which globs the law applies to is your repository's fact. What the law says is not — so there is no
+option to switch a rule off or lower it to a warning.
+
+Prefer the factory, which owns the levels for you:
+
+```js
+import starciBe, { recommended, starciBeConfig } from "@starci/eslint-canon-be"
+
+export default [
+    // …your own ignores, language options and other plugins…
+    starciBeConfig({ sources: ["apps/**/*.ts", "src/**/*.ts"], plugin: starciBe, recommended }),
+]
+```
+
+It states `warn` as `error` for a zero-warning gate, applies
+`noInlineConfig` and unused-disable reporting, and refuses a recommendation that carries a rule switched `off`. HFS
+keeps no retired-rule list: a rule the standard no longer holds is deleted from the plugin, and every rule that ships is on.
+The parameters a rule takes from the slot manifest (the `@Global()` allowlist, the file line budget, the width of an
+`index.ts`) come through `lib/slots.mjs`, which reads `knowledge/hfs/slots.yaml` and falls back to the rule catalog's values.
+
+Also exported: `rules`, `ruleOwners`, `lawOwners`, `starciBeConfig`, `linterOptions`.
+
+## What it actually catches
+
+A sample, not the list:
+
+| Area | What the rules hold |
+|---|---|
+| **Errors** | A `catch` rethrows, logs through the logger port or returns an outcome carrying its cause; an error lives in its capability's `errors/`, extends `DomainError`, and no bare `Error` or framework exception escapes (`catch-must-account`, `error-home`) |
+| **Schema authority** | Migrations only: no `synchronize`, no `migrationsRun`, no runtime DDL, no entity glob; raw SQL only in a persistence repository; no ORM entity in a contract (`no-runtime-schema`, `sql-only-in-repository`, `no-entity-in-contract`) |
+| **Config and secrets** | `process.env` only in `platform/config`; no literal default for a secret, password, token, key or URL; secrets compare with `timingSafeEqual` (`no-direct-env-read`, `no-secret-default`, `secret-compare-timing-safe`) |
+| **Default deny** | Typed bodies and arguments, no `GraphQLJSON` tunnel, no `switch (operation)`, and `@Public` carries a reason (`no-untyped-body`, `public-needs-reason`) |
+| **Module shape** | `@Global()` only on the manifest allowlist; typed `ConfigurableModuleBuilder`; static `register`; one module per file; no `new` of a provider; no module-level `let` |
+| **Suppression** | No `eslint-disable`, `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck` or `vn-ok` comment, anywhere (`no-inline-suppression`) |
+| **Size** | A file over its line budget is not new and does not grow past its size at the parent commit (`file-size-growth`) |
+| **Query safety** | SQL text carries no runtime substitution; a read states `take`, `limit` or `LIMIT` (`no-interpolated-sql`, `query-needs-limit`, `no-query-in-loop`) |
+| **Resilience** | An outbound HTTP call states a timeout or signal; `JSON.parse` of outside text sits in a `try`; a loop that catches and waits goes through `platform/retry` (`http-needs-timeout`, `json-parse-needs-guard`, `no-hand-rolled-retry`) |
+| **Log safety** | A logger call names no credential and no personal identifier (`no-secret-in-log`) |
+| **Async and types** | An `async` function awaits; no `as never`, no `x!`; handlers and public methods declare a return type (`async-needs-await`, `no-never-cast`, `no-non-null-assertion`, `explicit-handler-return-type`) |
+| **Migrations and input** | A migration's `down()` reverses its `up()`; every property of an input class has a `class-validator` decorator (`migration-down-reversible`, `dto-needs-validator`) |
+| **Spec quality** | A spec does not read repository source with `fs`, and doubles are `mock<T>()`, not `as never` (`spec-no-source-read`, `spec-typed-doubles`) |
+| **CQRS** | A handler does not assemble an aggregate inline; reads and writes do not share one path |
+| **Module layering** | Another owner is imported through its public `index.ts` (`@modules/domain/plan`, `@features/plan`), never through a path into it; an `index.ts` lists a bounded set of named exports, with no `export *`, storage token or types folder; self-aliases and tier-only aliases are refused. |
+| **Data access** | Queries stay where the layer says they may be built; no transaction spans an external call (`no-external-call-in-transaction`); the database is reached through the named shared `EntityManager` only (`named-entity-manager-only`) |
+| **Transport** | The wire shape is declared, not inferred from whatever a handler happened to return |
+| **Observability** | A failure is logged through the logger port with a typed identity, so a log line can be traced to the law that names it |
+| **Testing** | Unit specs sit beside their subjects, including structural specs in HFS `src/tests` categories; a model-quality harness (one that imports an LLM SDK, reaches a house model helper or declares `@harness-kind model`) calls its provider directly; other live e2e specs, such as an identity provider, are not judged as model harnesses. |
+| **End-to-end flows** | One file, one flow, named steps, and **never sleep** — poll until the state settles, with a deadline |
+| **CDC · event delivery** | Projections and events follow the declared delivery contract |
+| **Comments · naming · type safety** | Comments say why; no double cast through `unknown` |
+| **User copy** | A literal exception message, notification text or response copy comes from the per-capability messages catalog through the typed `MessageCatalog` port (`user-copy-through-catalog`) |
+| **Temporal** | `Date.now()`, a bare `new Date()` and `performance.now()` are read only inside `platform/clock` (`no-ambient-clock`) |
+| **Idempotency** | A `@Public()` webhook handler and an outbox/queue consumer claim the event through the shared inbox before they act (`inbox-dedupe-required`) |
+
+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.
+
+## Companion
+
+- **[@starci/eslint-canon-fe](https://www.npmjs.com/package/@starci/eslint-canon-fe)** — the
+  front-end half: 58 rules from 16 laws covering component tiers, structure contracts, the
+  fetch/draw split, vendor boundaries and the design-token scale.
+
+## Where the laws live
+
+Each rule is the enforceable half of a written law. The prose — why the rule exists, what it
+refuses, which cases sit just outside it — is published openly at
+[starci183/starci-claude-skills](https://github.com/starci183/starci-claude-skills).
+
+A rule that cannot be pointed at in real code is a proposal, not a law. Everything here is
+pointed at.
+
+## Requirements
+
+ESLint 9+ (flat config), Node 20.9+.
+
+## HFS rules and their why codes
+
+Each rule below reports through the code-pattern gate with a catalogued Vietnamese reason (`modules/kernel/failure-codes.yaml`,
+mapped by `scripts/checks/lint-why.mjs`). The catalog id is the rule number in `knowledge/hfs/rules.yaml`.
+
+| Rule | Catalog | Why code |
+|---|---|---|
+| `catch-must-account` | R40 | `BE_LOGGER_REQUIRED` |
+| `error-home` | R38 | `BE_ERROR_HOME` |
+| `no-runtime-schema` | R34 | `BE_SCHEMA_AUTHORITY` |
+| `sql-only-in-repository` | R36 | `BE_SQL_OUTSIDE_REPOSITORY` |
+| `no-entity-in-contract` | R37 | `BE_ENTITY_IN_CONTRACT` |
+| `no-untyped-body`, `public-needs-reason`, `secret-compare-timing-safe` | R41 | `BE_DEFAULT_DENY` |
+| `no-direct-env-read` | R43 | `BE_CONFIG_OWNER` |
+| `no-secret-default` | R44 | `BE_SECRET_DEFAULT` |
+| `global-module-allowlist`, `typed-module-definition`, `static-module-register`, `no-new-injectable`, `no-module-let`, `one-module-per-file` | R45 | `BE_MODULE_SHAPE` |
+| `no-inline-suppression` | R18 | `HFS_INLINE_SUPPRESSION` |
+| `file-size-growth` | R20 | `HFS_SIZE_GROWTH` |
+| `spec-no-source-read`, `spec-typed-doubles` | R48 | `BE_SPEC_QUALITY` |
+| `must-deep-module-import`, `no-folder-reexport` | R30 | `BE_PUBLIC_SURFACE` |
+| `dto-needs-validator` | R42 | `BE_INPUT_BOUNDED` |
+| `no-interpolated-sql` | R68 | `BE_SQL_INTERPOLATED` |
+| `query-needs-limit` | R69 | `BE_QUERY_UNBOUNDED` |
+| `no-query-in-loop` | R77 | `BE_QUERY_IN_LOOP` |
+| `http-needs-timeout` | R70 | `BE_HTTP_TIMEOUT` |
+| `no-secret-in-log` | R71 | `BE_LOG_SECRET` |
+| `no-never-cast`, `no-non-null-assertion` | R72 | `BE_TYPE_ESCAPE` |
+| `async-needs-await` | R73 | `BE_ASYNC_NO_AWAIT` |
+| `migration-down-reversible` | R74 | `BE_MIGRATION_REVERSIBLE` |
+| `explicit-handler-return-type` | R75 | `BE_RETURN_TYPE` |
+| `json-parse-needs-guard` | R76 | `BE_JSON_PARSE_UNGUARDED` |
+| `user-copy-through-catalog` | R78 | `BE_USER_COPY_LITERAL` |
+| `no-ambient-clock` | R79 | `BE_AMBIENT_CLOCK` |
+| `inbox-dedupe-required` | R80 | `BE_INBOX_DEDUPE_MISSING` |
+| `no-hand-rolled-retry` | R81 | `BE_HAND_ROLLED_RETRY` |
+| `no-external-call-in-transaction` | R82 | `BE_TRANSACTION_EXTERNAL_CALL` |
+| `named-entity-manager-only`, `no-injected-repository` | R83 | `BE_UNNAMED_DATA_ACCESS` |
+
+There is no soft size-limit lint rule: a warning under a zero-warning gate is an exception in disguise. Listing files over the soft budget (`ruleParams.be.fileLines.soft`) is a report item of the hfs check or the architecture machine, as migration backlog, and never blocks.
+
+The tier direction matrix and the feature-imports-feature ban (R26, R28) are owned by the architecture machine
+(`@starci/hfs`), not by a lint rule: they need the whole import graph.

package/async-discipline.mjs

@@ -0,0 +1,83 @@
+/**
+ * The rule that keeps `async` honest.
+ *
+ * `async-needs-await` (R73 `BE_ASYNC_NO_AWAIT`) refuses an `async` function that never awaits. Such a function
+ * promises asynchronous work and does none: it turns a thrown error into a rejected promise for no reason,
+ * hides that the body is synchronous, and reads as if a suspension point existed. Delete the `async` and return the
+ * value (or the promise the body already holds); where a signature must return a `Promise`, return `Promise.resolve(x)`.
+ *
+ * Three shapes are exempt because the `async` is not the author's choice:
+ *   - a method of a class that `implements` or `extends` something (the base contract fixes the return type);
+ *   - a method that carries a decorator (the framework contract fixes it: resolvers, event handlers, lifecycle hooks);
+ *   - an `async` generator, whose `yield` is its suspension.
+ */
+import { walk } from "./lib/ast.mjs"
+import { isDeclarationFile, isTestLane } from "./lib/path.mjs"
+
+/** Whether the function body awaits, ignoring nested functions (each is judged alone). */
+const awaits = (fn) => {
+  let found = false
+  walk(fn.body, (node) => {
+    if (found) return
+    if (node.type === "AwaitExpression") found = true
+    else if (node.type === "ForOfStatement" && node.await) found = true
+  }, { intoFunctions: false })
+  return found
+}
+
+/** Whether the function is a method whose `async` a base class, interface or decorator fixes. */
+const asyncIsContractual = (fn) => {
+  const method = fn.parent?.type === "MethodDefinition" ? fn.parent : null
+  if (!method) return false
+  if (method.decorators?.length > 0) return true
+  if (method.override) return true
+  const klass = method.parent?.parent
+  if (klass && (klass.superClass || (klass.implements && klass.implements.length > 0))) return true
+  return false
+}
+
+/** An `async` function awaits something. */
+export const asyncNeedsAwait = {
+  meta: {
+    type: "problem",
+    docs: { description: "An `async` function contains an `await`, or it is not `async`." },
+    schema: [],
+    messages: {
+      noAwait:
+        "This `async` function never awaits. It promises asynchronous work and does none, so a thrown error becomes a rejected promise for no reason and a reader looks for a suspension that is not there. Remove `async` and return the value or the promise the body already holds; where the signature must return a `Promise`, return `Promise.resolve(value)`.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (isTestLane(filename) || isDeclarationFile(filename)) return {}
+    const check = (node) => {
+      if (!node.async || node.generator || !node.body) return
+      if (node.body.type !== "BlockStatement" && node.type === "ArrowFunctionExpression") {
+        // an expression body has no statements to await inside; `async () => x` is judged by the expression itself
+        let has = false
+        walk(node.body, (child) => {
+          if (child.type === "AwaitExpression") has = true
+        }, { intoFunctions: false })
+        if (!has) context.report({ node, messageId: "noAwait" })
+        return
+      }
+      if (asyncIsContractual(node)) return
+      if (!awaits(node)) context.report({ node, messageId: "noAwait" })
+    }
+    return {
+      FunctionDeclaration: check,
+      FunctionExpression: check,
+      ArrowFunctionExpression: check,
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "async-needs-await": asyncNeedsAwait,
+}
+
+/** Starts at error: no baseline exists, and the repositories' fix lanes clear the debt. */
+export const recommended = {
+  "starci-be/async-needs-await": "error",
+}

package/authorization.mjs

@@ -1,106 +1,106 @@
-/**
- * The rule that holds `authorization.md`.
- *
- * ONE rule, and the honest reason is worth stating: authorization is decided against a row, and a
- * parser does not know which row a handler is reaching for or what owning it means. AUTHZ-3, -4 and
- * -5 all turn on that, so a rule aimed at them would fire on shape rather than on meaning - and a
- * rule that fires on shape is one authors learn to disable, which leaves the law worse off than when
- * nothing enforced it.
- *
- * AUTHZ-1 was measured and deliberately left alone. A handler checking `if (!user)` reads like
- * duplication of the door's guard and is not: the guard belongs to one door and the handler belongs
- * to every caller of the bus. A rule refusing it would fire on the majority of correct handlers in
- * this tree, which is a gate contradicting canon rather than holding it.
- *
- * What IS checkable in one file is the door: a resolver method that READS the authenticated user
- * while nothing on that method or its class establishes the identity. That failure looks like
- * nothing at all - the parameter still says `user`, the handler still receives one - and the only
- * missing piece is the line that proved it belonged to the caller.
- */
-
-/** Parameter decorators that read an already-authenticated identity off the request. */
-const IDENTITY_PARAM_DECORATORS = new Set([
-  "KeycloakGraphQLUser",
-  "KeycloakUser",
-  "CurrentUser",
-])
-
-/** The decorator that establishes the identity a door then reads. */
-const GUARD_DECORATOR = "UseGuards"
-
-/** Reads the callee name off a decorator expression, whether or not it is called. */
-const decoratorName = (decorator) => {
-  const expression = decorator.expression
-  if (!expression) return undefined
-  if (expression.type === "CallExpression") {
-    return expression.callee && expression.callee.type === "Identifier"
-      ? expression.callee.name
-      : undefined
-  }
-  return expression.type === "Identifier" ? expression.name : undefined
-}
-
-/** Whether any decorator in the list is the guard. */
-const hasGuard = (decorators) =>
-  (decorators || []).some((decorator) => decoratorName(decorator) === GUARD_DECORATOR)
-
-/** The identity parameter on a method, when it has one. */
-const identityParameter = (node) => {
-  for (const parameter of node.value && node.value.params ? node.value.params : []) {
-    // a decorated parameter carries its decorators on the parameter node itself, and TS-ESTree
-    // wraps a typed+decorated parameter in TSParameterProperty for constructor promotion
-    const carrier = parameter.type === "TSParameterProperty" ? parameter.parameter : parameter
-    const decorators = parameter.decorators || (carrier && carrier.decorators) || []
-    for (const decorator of decorators) {
-      if (IDENTITY_PARAM_DECORATORS.has(decoratorName(decorator))) return parameter
-    }
-  }
-  return undefined
-}
-
-// -- AUTHZ-2 ---------------------------------------------------------------------------------------
-
-/** A door that reads an identity carries the guard that establishes it. */
-export const identityNeedsGuard = {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "A resolver or controller method reading the authenticated user must carry a guard on that method or its class.",
-    },
-    schema: [],
-    messages: {
-      unguarded:
-        "This door reads the authenticated user through `@{{decorator}}()` while neither the method nor its class carries `@UseGuards(...)`. Nothing established the identity, so what reaches the handler is whatever the pipeline left there - and the failure is silent, because the parameter still says `user` and the handler still receives one. Put the guard on the door that reads the identity.",
-    },
-  },
-  create(context) {
-    return {
-      MethodDefinition(node) {
-        const parameter = identityParameter(node)
-        if (!parameter) return
-        if (hasGuard(node.decorators)) return
-
-        // the guard may sit on the class instead, covering every method on it
-        const classBody = node.parent
-        const classNode = classBody && classBody.parent
-        if (classNode && hasGuard(classNode.decorators)) return
-
-        const carrier = parameter.type === "TSParameterProperty" ? parameter.parameter : parameter
-        const decorators = parameter.decorators || (carrier && carrier.decorators) || []
-        const named = decorators.map(decoratorName).find((name) => IDENTITY_PARAM_DECORATORS.has(name))
-        context.report({ node: parameter, messageId: "unguarded", data: { decorator: named } })
-      },
-    }
-  },
-}
-
-/** Every rule this module ships, by the name a config switches it on under. */
-export const rules = {
-  "identity-needs-guard": identityNeedsGuard,
-}
-
-/** The level a consuming repository switches this on at. */
-export const recommended = {
-  "starci-be/identity-needs-guard": "error",
-}
+/**
+ * The rule that holds `authorization.md`.
+ *
+ * ONE rule, and the honest reason is worth stating: authorization is decided against a row, and a
+ * parser does not know which row a handler is reaching for or what owning it means. AUTHZ-3, -4 and
+ * -5 all turn on that, so a rule aimed at them would fire on shape rather than on meaning - and a
+ * rule that fires on shape is one authors learn to disable, which leaves the law worse off than when
+ * nothing enforced it.
+ *
+ * AUTHZ-1 was measured and deliberately left alone. A handler checking `if (!user)` reads like
+ * duplication of the door's guard and is not: the guard belongs to one door and the handler belongs
+ * to every caller of the bus. A rule refusing it would fire on the majority of correct handlers in
+ * this tree, which is a gate contradicting canon rather than holding it.
+ *
+ * What IS checkable in one file is the door: a resolver method that READS the authenticated user
+ * while nothing on that method or its class establishes the identity. That failure looks like
+ * nothing at all - the parameter still says `user`, the handler still receives one - and the only
+ * missing piece is the line that proved it belonged to the caller.
+ */
+
+/** Parameter decorators that read an already-authenticated identity off the request. */
+const IDENTITY_PARAM_DECORATORS = new Set([
+  "KeycloakGraphQLUser",
+  "KeycloakUser",
+  "CurrentUser",
+])
+
+/** The decorator that establishes the identity a door then reads. */
+const GUARD_DECORATOR = "UseGuards"
+
+/** Reads the callee name off a decorator expression, whether or not it is called. */
+const decoratorName = (decorator) => {
+  const expression = decorator.expression
+  if (!expression) return undefined
+  if (expression.type === "CallExpression") {
+    return expression.callee && expression.callee.type === "Identifier"
+      ? expression.callee.name
+      : undefined
+  }
+  return expression.type === "Identifier" ? expression.name : undefined
+}
+
+/** Whether any decorator in the list is the guard. */
+const hasGuard = (decorators) =>
+  (decorators || []).some((decorator) => decoratorName(decorator) === GUARD_DECORATOR)
+
+/** The identity parameter on a method, when it has one. */
+const identityParameter = (node) => {
+  for (const parameter of node.value && node.value.params ? node.value.params : []) {
+    // a decorated parameter carries its decorators on the parameter node itself, and TS-ESTree
+    // wraps a typed+decorated parameter in TSParameterProperty for constructor promotion
+    const carrier = parameter.type === "TSParameterProperty" ? parameter.parameter : parameter
+    const decorators = parameter.decorators || (carrier && carrier.decorators) || []
+    for (const decorator of decorators) {
+      if (IDENTITY_PARAM_DECORATORS.has(decoratorName(decorator))) return parameter
+    }
+  }
+  return undefined
+}
+
+// -- AUTHZ-2 ---------------------------------------------------------------------------------------
+
+/** A door that reads an identity carries the guard that establishes it. */
+export const identityNeedsGuard = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "A resolver or controller method reading the authenticated user must carry a guard on that method or its class.",
+    },
+    schema: [],
+    messages: {
+      unguarded:
+        "This door reads the authenticated user through `@{{decorator}}()` while neither the method nor its class carries `@UseGuards(...)`. Nothing established the identity, so what reaches the handler is whatever the pipeline left there - and the failure is silent, because the parameter still says `user` and the handler still receives one. Put the guard on the door that reads the identity.",
+    },
+  },
+  create(context) {
+    return {
+      MethodDefinition(node) {
+        const parameter = identityParameter(node)
+        if (!parameter) return
+        if (hasGuard(node.decorators)) return
+
+        // the guard may sit on the class instead, covering every method on it
+        const classBody = node.parent
+        const classNode = classBody && classBody.parent
+        if (classNode && hasGuard(classNode.decorators)) return
+
+        const carrier = parameter.type === "TSParameterProperty" ? parameter.parameter : parameter
+        const decorators = parameter.decorators || (carrier && carrier.decorators) || []
+        const named = decorators.map(decoratorName).find((name) => IDENTITY_PARAM_DECORATORS.has(name))
+        context.report({ node: parameter, messageId: "unguarded", data: { decorator: named } })
+      },
+    }
+  },
+}
+
+/** Every rule this module ships, by the name a config switches it on under. */
+export const rules = {
+  "identity-needs-guard": identityNeedsGuard,
+}
+
+/** The level a consuming repository switches this on at. */
+export const recommended = {
+  "starci-be/identity-needs-guard": "error",
+}