@starci/eslint-canon-be 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.7.1 - 2026-09-30
+
+- Fixed: eslint no longer fails to start in a product repository with `HFS slot manifest not found at <repo>/knowledge/hfs/slots.yaml`. `lib/slots.mjs` used to look for the manifest at a path above the package (the product repository, or a linked runtime copy that no longer exists). The package now depends on `@starci/hfs` and resolves the manifest and the YAML reader as `@starci/hfs/runtime/knowledge/hfs/slots.yaml` and `@starci/hfs/runtime/engine/yaml.mjs`, so what the canon reads travels with the installed packages. `STARCI_HFS_SLOTS` still overrides the manifest file.
+
 ## 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.

package/README.md

@@ -1,6 +1,6 @@
 # @starci/eslint-canon-be
 
-**78 ESLint rules, from 26 laws, that hold a NestJS-shaped back end to one way of being written.**
+**ESLint rules, grouped by law (the count is `Object.keys(rules)`; knowledge/hfs/rules.yaml names the HFS rule each one enforces), 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
@@ -103,43 +103,7 @@ 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.
+Every rule of this plugin is an enforcer of one HFS rule. The relation (rule id -> HFS rule -> catalogued Vietnamese why code)
+lives in exactly one place, `knowledge/hfs/rules.yaml` (`enforcers`), and `scripts/checks/check-hfs-rules.mjs` refuses a
+rule of this plugin that no catalog entry names. There is no second table here.
+

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