@starci/eslint-canon-be 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 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,70 @@
-# @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
+
+**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 carries its own identity and metadata. Concrete exceptions live in their owning feature or module capability's `errors/` folder; the shared abstract base may live at the capability root. |
+| **CQRS** | A handler does not assemble an aggregate inline; reads and writes do not share one path |
+| **Module layering** | Cross-capability imports may use an explicit public `index.ts`; self-aliases, tier-only aliases, folder re-exports, and export-star public entries are refused. |
+| **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 |
+| **Testing** | Unit specs sit beside their subjects, including structural specs in HFS `src/tests` categories; model-quality harness specs still call providers directly. |
+| **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+.

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",
+}