@starci/eslint-canon-be 1.2.2 → 1.7.0

package/testing.mjs

@@ -43,21 +43,17 @@
 import { statSync } from "node:fs"
 import { normalizePath } from "./lib/path.mjs"
 
-/** The fast lane: a plain unit spec, excluding every other suffix that also ends in `spec.ts`. */
-const isUnitSpec = (filename) => {
-  const file = normalizePath(filename)
-  if (!/\.spec\.ts$/.test(file)) return false
-  return !/\.(?:e2e|int|harness)-spec\.ts$/.test(file)
-}
+/** Test kind 1 of exactly two: a unit spec, `<name>.spec.ts` beside its subject. */
+const isUnitSpec = (filename) => /\.spec\.ts$/.test(normalizePath(filename))
 
-/** The flow lane. */
+/** Test kind 2 of exactly two: `*.e2e-spec.ts`. */
 const isE2eSpec = (filename) => /\.e2e-spec\.ts$/.test(normalizePath(filename))
 
-/** The paid model-quality lane. */
-const isHarnessSpec = (filename) => /\.harness-spec\.ts$/.test(normalizePath(filename))
+/** The opt-in live e2e filter (`test:e2e:live`): e2e specs under `src/tests/e2e/live/` that need live third-party accounts. */
+const isLiveE2eSpec = (filename) => isE2eSpec(filename) && /\/src\/tests\/e2e\/live\//.test(normalizePath(filename))
 
-/** Test-only helpers whose only authority is the harness lane. */
-const isHarnessHelper = (filename) => /\/src\/tests\/helpers\//.test(normalizePath(filename))
+/** Test-only environment helpers whose only authority is the live e2e filter. */
+const isLiveE2eHelper = (filename) => /\/src\/tests\/e2e\/live\//.test(normalizePath(filename)) && !isE2eSpec(filename)
 
 /**
  * Matchers that assert a CALL happened rather than what came out of it.
@@ -136,7 +132,7 @@ export const noCallOnlySpec = {
 // -- TESTING-7 -------------------------------------------------------------------------------------
 
 const UNIT_TEST_BUCKET = /\/(?:src\/tests|tests?\/unit)(?:\/|$)/
-const HFS_TEST_CATEGORY = /\/src\/tests\/(?:integration|fixtures|harness|e2e)\//
+const HFS_TEST_CATEGORY = /\/src\/tests\/(?:fixtures|e2e)\//
 const SUBJECT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs"]
 
 /** A structural test in an HFS test category may test a source file beside it. */
@@ -219,7 +215,7 @@ const PROVIDER_PACKAGES = /^(?:@anthropic-ai\/|openai$|openai\/|ollama$|@google\
  */
 const HARNESS_MODEL_HELPERS = /helpers\/models(?:\.service)?$/
 
-/** An e2e never calls a model; the harness is the only lane that does. */
+/** An e2e never calls a model; only a live e2e (src/tests/e2e/live/) may reach a provider. */
 export const noModelCallInE2e = {
   meta: {
     type: "problem",
@@ -227,11 +223,12 @@ export const noModelCallInE2e = {
     schema: [],
     messages: {
       provider:
-        "`{{source}}` reaches a model provider from an e2e. A model call costs money, takes seconds and answers differently every time - so this makes the flow suite expensive, slow and flaky at once, and the assertion has to be loosened until it stops catching anything. Stub the model and assert what can actually break: the entitlement, the quota, the persisted answer. Judging the answer itself belongs in the harness.",
+        "`{{source}}` reaches a model provider from an e2e. A model call costs money, takes seconds and answers differently every time - so this makes the flow suite expensive, slow and flaky at once, and the assertion has to be loosened until it stops catching anything. Stub the model and assert what can actually break: the entitlement, the quota, the persisted answer. Judging the answer itself belongs in a live e2e under src/tests/e2e/live/.",
     },
   },
   create(context) {
-    if (!isE2eSpec(context.filename || context.getFilename())) return {}
+    const filename = context.filename || context.getFilename()
+    if (!isE2eSpec(filename) || isLiveE2eSpec(filename)) return {}
     return {
       ImportDeclaration(node) {
         const source = node.source && node.source.value
@@ -279,6 +276,16 @@ const aiInvokePickToken = (sourceCode) => {
   return null
 }
 
+/** A file declares itself a model harness with the comment `@harness-kind model`; any other kind is not one. */
+const DECLARED_MODEL_HARNESS = /@harness-kind\s+model\b/
+
+/**
+ * A model harness is identified by what it does, never by where it lives: it imports an LLM provider
+ * SDK, reaches for a house model helper or gateway symbol, or declares `@harness-kind model`. A live
+ * e2e for an identity provider (Keycloak), a payment gateway or any other third party sits in the same
+ * `src/tests/e2e/live/` folder and is not a model harness, so this rule leaves it alone.
+ */
+
 /** A harness calls one explicit provider SDK and never disguises it as `AiInvokeService`. */
 export const harnessCallsProviderDirectly = {
   meta: {
@@ -287,7 +294,7 @@ export const harnessCallsProviderDirectly = {
     schema: [],
     messages: {
       missingProvider:
-        "This harness imports no approved provider SDK. A model-quality harness calls the declared provider client directly; a house helper, tier or gateway override can make it green about a model production does not use.",
+        "This model harness (it reaches for a house model helper or gateway, or declares `@harness-kind model`) imports no approved provider SDK. A model-quality harness calls the declared provider client directly; a house helper, tier or gateway override can make it green about a model production does not use.",
       gateway:
         "`{{name}}` impersonates or replaces the production AI gateway from a harness. Reuse the production prompt builder and parser around a direct provider SDK call instead.",
       helper:
@@ -298,17 +305,19 @@ export const harnessCallsProviderDirectly = {
   },
   create(context) {
     const filename = context.filename || context.getFilename()
-    const harness = isHarnessSpec(filename)
-    const authScope = harness || isHarnessHelper(filename)
+    const harness = isLiveE2eSpec(filename)
+    const authScope = harness || isLiveE2eHelper(filename)
     if (!authScope) return {}
 
     let hasProviderImport = false
+    let modelSignal = false
     return {
       ImportDeclaration(node) {
         const source = node.source && node.source.value
         if (typeof source !== "string") return
         if (harness && DIRECT_PROVIDER_PACKAGES.test(source)) hasProviderImport = true
         if (harness && FORBIDDEN_HARNESS_HELPERS.test(source.replace(/\.(?:ts|js)$/, ""))) {
+          modelSignal = true
           context.report({ node, messageId: "helper", data: { source } })
         }
         if (!harness) return
@@ -317,6 +326,7 @@ export const harnessCallsProviderDirectly = {
           const local = specifier.local && specifier.local.name
           const name = imported || local
           if (!FORBIDDEN_HARNESS_SYMBOLS.has(name)) continue
+          modelSignal = true
           context.report({ node: specifier, messageId: "gateway", data: { name } })
         }
       },
@@ -341,9 +351,11 @@ export const harnessCallsProviderDirectly = {
         const sourceCode = context.sourceCode || context.getSourceCode()
         const pickToken = aiInvokePickToken(sourceCode)
         if (pickToken) {
+          modelSignal = true
           context.report({ node: pickToken, messageId: "gateway", data: { name: 'Pick<AiInvokeService, "run">' } })
         }
-        if (!hasProviderImport) context.report({ node, messageId: "missingProvider" })
+        const declared = sourceCode.getAllComments().some((comment) => DECLARED_MODEL_HARNESS.test(comment.value))
+        if ((modelSignal || declared) && !hasProviderImport) context.report({ node, messageId: "missingProvider" })
       },
     }
   },

package/type-safety.mjs

@@ -14,7 +14,7 @@
  * (TYPE-3, rule 4, extended; see the export below for its `recommended` level and the measurement
  * that set it), the const enum
  * (TYPE-4, rule 5), the unguarded cast off an `unknown` value (TYPE-1's second half, rule 2), and
- * the per-line suppression standing in for a lane (TYPE-6, rule 7). Each is a way of switching the
+ * a way of switching the
  * compiler off -- or of leaving it turned further down than the law asks -- that looks locally
  * reasonable, which is exactly the class a rule is for.
  *
@@ -28,7 +28,7 @@ import { normalizePath } from "./lib/path.mjs"
 /** The spec family and the test tree may build a deliberately wrong value on purpose. */
 const isTestFile = (filename) => {
   const file = normalizePath(filename)
-  return /\.(?:spec|test|e2e-spec|int-spec|harness-spec)\.ts$/.test(file) || file.includes("/src/tests/")
+  return /\.(?:spec|test|e2e-spec)\.ts$/.test(file) || file.includes("/src/tests/")
 }
 
 /** A parameter property (`private readonly x: T`) wraps the parameter it declares. */
@@ -387,77 +387,114 @@ export const noConstEnum = {
   },
 }
 
-// -- TYPE-5 (rule 6) -- ATTEMPTED, NOT SHIPPED ------------------------------------------------------
-//
-// A rule was written here: two-or-more `is`/`has`-prefixed booleans sharing a type literal with a
-// field that is optional and not itself boolean. It was measured against the reference backend
-// before shipping, per this canon's own standard -- and both of its two real firings were wrong.
-// `GlobalSearchItem` (`isEnrolled` / `isFree` / `isPremium` beside an unrelated optional
-// `parentPath`) and `AdvertisementSeedItem` (`isHouseAd` / `isActive` beside an unrelated optional
-// `ctaText`) are both genuinely independent facts about one entity, not a product of states -- the
-// exact "transport type" and "independent booleans" exceptions `type-safety.md` already names. A
-// rule reporting a defect on 2 of its 2 real firings is not a rule with debt to burn down; it is
-// wrong, and shipping it at any level would teach a reader to distrust the machine rather than the
-// code. TYPE-5 stays `documented`, exactly as the law's own `Layer held` table already says: seeing
-// past a transport DTO to whether its flags are truly one situation needs the meaning of the code,
-// which is a reader's job, not a decidable question of syntax.
+// -- R72 -------------------------------------------------------------------------------------------
+
+/** `as never` asserts that a value is of no type at all, which satisfies every parameter and checks nothing. */
+export const noNeverCast = {
+  meta: {
+    type: "problem",
+    docs: { description: "No `x as never` outside the test lanes." },
+    schema: [],
+    messages: {
+      neverCast:
+        "`as never` makes this value assignable to anything, so the compiler stops checking the call it is passed to. It hides a real mismatch between the value and the parameter. Give the value the type the parameter wants, narrow it with a guard, or fix the signature.",
+    },
+  },
+  create(context) {
+    if (isTestFile(context.filename || context.getFilename())) return {}
+    return {
+      TSAsExpression(node) {
+        if (node.typeAnnotation?.type === "TSNeverKeyword") context.report({ node, messageId: "neverCast" })
+      },
+    }
+  },
+}
+
+/** `x!` claims a value is present without checking. */
+export const noNonNullAssertion = {
+  meta: {
+    type: "problem",
+    docs: { description: "No non-null assertion (`x!`) outside the test lanes." },
+    schema: [],
+    messages: {
+      nonNull:
+        "`!` claims this value is present and checks nothing; when it is not, the failure is a `TypeError` far from here. Narrow with a check that returns or throws a typed error, or change the type so absence is impossible.",
+    },
+  },
+  create(context) {
+    if (isTestFile(context.filename || context.getFilename())) return {}
+    return {
+      TSNonNullExpression(node) {
+        context.report({ node, messageId: "nonNull" })
+      },
+    }
+  },
+}
 
-// -- TYPE-6 (rule 7) ----------------------------------------------------------------------------------
+// -- R75 -------------------------------------------------------------------------------------------
 
-/** This law's own published rule names -- the only ones this rule polices. */
-const TYPE_SAFETY_RULE_NAMES = [
-  "no-double-cast",
-  "no-inline-param-type",
-  "no-inline-object-type",
-  "no-const-enum",
-  "no-unguarded-unknown-cast",
-]
+const HANDLER_DECORATORS = new Set(["Query", "Mutation", "Subscription", "ResolveField", "Get", "Post", "Put", "Patch", "Delete", "MessagePattern", "EventPattern", "Cron", "Interval"])
+const SURFACE_CLASS_DECORATORS = new Set(["Injectable", "Resolver", "Controller"])
 
-const DISABLE_DIRECTIVE = /^eslint-disable(?:-next-line|-line)?\b/
+const decoratorIdentifier = (decorator) => {
+  const expression = decorator?.expression
+  if (!expression) return null
+  if (expression.type === "Identifier") return expression.name
+  if (expression.type === "CallExpression" && expression.callee.type === "Identifier") return expression.callee.name
+  return null
+}
 
-/**
- * A sanctioned exit is declared at the lane, once -- not suppressed per line.
- *
- * `no-double-cast`'s test-lane exemption already lives in `isTestFile`, consulted once, so every
- * place the exit is in force is derivable from that one function. A per-line `eslint-disable` for
- * any rule this law publishes is therefore never the lane speaking -- it is either redundant (the
- * lane already covers the file) or an undeclared second exit (the file needed one and reached for
- * a comment instead of a lane). Either way `type-safety.md` names this exact failure: "a per-line
- * suppression standing in for a lane-wide exit".
- *
- * Deliberately scoped to only the five rule names this law publishes -- a rule that policed every
- * `eslint-disable` in the repository would be reaching into every other family's lane, which is
- * outside this file's boundary.
- */
-export const noLineSuppression = {
+/** A method that a caller or the framework reaches states what it returns. */
+export const explicitHandlerReturnType = {
   meta: {
     type: "problem",
-    docs: {
-      description:
-        "No inline `eslint-disable` for a type-safety rule; the lane is the only sanctioned exit (TYPE-6, law 7).",
-    },
+    docs: { description: "Handlers and public methods of an Injectable, Resolver or Controller declare a return type." },
     schema: [],
     messages: {
-      suppression:
-        "This comment disables `starci-be/{{name}}` on one line. That rule's only sanctioned exit is declared once, at the lane, inside the rule itself -- a per-line suppression is never that declaration, it is a stand-in for one. Delete the comment; if the file genuinely needs the exemption, it belongs in the lane the rule already recognizes.",
+      handler:
+        "This handler declares no return type, so the transport contract is whatever the body happens to return today and a change of the body silently changes the wire. Declare the return type (`Promise<Type>`).",
+      publicMethod:
+        "This public method declares no return type, so its callers depend on an inferred shape that changes with the body. Declare the return type.",
     },
   },
   create(context) {
-    const sourceCode = context.sourceCode || context.getSourceCode()
+    if (isTestFile(context.filename || context.getFilename())) return {}
     return {
-      "Program:exit"(node) {
-        for (const comment of sourceCode.getAllComments()) {
-          const text = comment.value.trim()
-          if (!DISABLE_DIRECTIVE.test(text)) continue
-          const named = TYPE_SAFETY_RULE_NAMES.find((name) => text.includes(`starci-be/${name}`))
-          if (!named) continue
-          context.report({ node: comment ?? node, messageId: "suppression", data: { name: named } })
+      MethodDefinition(node) {
+        if (node.kind !== "method" || node.static || !node.value.body || node.value.returnType) return
+        if (node.computed || node.key.type !== "Identifier") return
+        const isHandler = (node.decorators ?? []).some((decorator) => HANDLER_DECORATORS.has(decoratorIdentifier(decorator)))
+        if (isHandler) {
+          context.report({ node: node.key, messageId: "handler" })
+          return
         }
+        if (node.accessibility === "private" || node.accessibility === "protected" || node.override) return
+        const klass = node.parent?.parent
+        if (!klass || klass.type !== "ClassDeclaration") return
+        const exported = klass.parent?.type === "ExportNamedDeclaration" || klass.parent?.type === "ExportDefaultDeclaration"
+        const decorators = [...(klass.decorators ?? []), ...(klass.parent?.decorators ?? [])].map(decoratorIdentifier)
+        if (!exported || !decorators.some((name) => SURFACE_CLASS_DECORATORS.has(name))) return
+        context.report({ node: node.key, messageId: "publicMethod" })
       },
     }
   },
 }
 
+// -- TYPE-5 (rule 6) -- ATTEMPTED, NOT SHIPPED ------------------------------------------------------
+//
+// A rule was written here: two-or-more `is`/`has`-prefixed booleans sharing a type literal with a
+// field that is optional and not itself boolean. It was measured against the reference backend
+// before shipping, per this canon's own standard -- and both of its two real firings were wrong.
+// `GlobalSearchItem` (`isEnrolled` / `isFree` / `isPremium` beside an unrelated optional
+// `parentPath`) and `AdvertisementSeedItem` (`isHouseAd` / `isActive` beside an unrelated optional
+// `ctaText`) are both genuinely independent facts about one entity, not a product of states -- the
+// exact "transport type" and "independent booleans" exceptions `type-safety.md` already names. A
+// rule reporting a defect on 2 of its 2 real firings is not a rule with debt to burn down; it is
+// wrong, and shipping it at any level would teach a reader to distrust the machine rather than the
+// code. TYPE-5 stays `documented`, exactly as the law's own `Layer held` table already says: seeing
+// past a transport DTO to whether its flags are truly one situation needs the meaning of the code,
+// which is a reader's job, not a decidable question of syntax.
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "no-double-cast": noDoubleCast,
@@ -465,7 +502,9 @@ export const rules = {
   "no-inline-object-type": noInlineObjectType,
   "no-const-enum": noConstEnum,
   "no-unguarded-unknown-cast": noUnguardedUnknownCast,
-  "no-line-suppression": noLineSuppression,
+  "no-never-cast": noNeverCast,
+  "no-non-null-assertion": noNonNullAssertion,
+  "explicit-handler-return-type": explicitHandlerReturnType,
 }
 
 /**
@@ -501,7 +540,9 @@ export const recommended = {
   "starci-be/no-inline-object-type": "error",
   "starci-be/no-const-enum": "error",
   "starci-be/no-unguarded-unknown-cast": "warn", // no=3 -- see type-safety.mjs's doc comment
-  "starci-be/no-line-suppression": "error",
+  "starci-be/no-never-cast": "error",
+  "starci-be/no-non-null-assertion": "error",
+  "starci-be/explicit-handler-return-type": "error",
   "@typescript-eslint/no-explicit-any": "error",
   "@typescript-eslint/array-type": ["error", {
     default: "generic",

package/user-copy.mjs

@@ -0,0 +1,106 @@
+/**
+ * The rule that holds the messages catalog (catalog R78 `BE_USER_COPY_LITERAL`).
+ *
+ * Text a user reads - an exception's message, a notification's subject or body, a response's
+ * `message` or `description` - lives in a per-capability `messages` catalog (Vietnamese and
+ * English), reached through the typed `platform/i18n` `MessageCatalog` port by a key with named
+ * interpolation. A literal in source cannot be translated, cannot be found by the key a test
+ * asserts on, and drifts the moment one call site is edited and the others are not.
+ *
+ *   - `user-copy-through-catalog` refuses a literal string in the three places copy is written by
+ *     hand: the message argument of a `*Error`/`*Exception` constructor, a `subject`/`title`/
+ *     `body`/`text`/`message` property of an object passed to `notify`/`send`/`publish`, and a
+ *     `message`/`description`/`title` property of an object literal built in a `transport/` file.
+ *
+ * A short, code-shaped literal (`UPPER_SNAKE`, or a single bare word with no space or punctuation -
+ * `"PLAN_NOT_FOUND"`, `"pending"`) is a key or an enum value, not copy, and is left alone; so is a
+ * template literal, which this reads one file's syntax for and cannot split into its static and
+ * interpolated halves without guessing. `no-non-ascii-source` already refuses Vietnamese text
+ * anywhere; this rule is the English half, scoped to the three places copy is written.
+ */
+import { keyName, staticText } from "./lib/ast.mjs"
+import { isDeclarationFile, isTestLane, normalizePath } from "./lib/path.mjs"
+
+const BUILTIN_ERRORS = new Set(["Error", "TypeError", "RangeError", "SyntaxError", "EvalError", "URIError", "ReferenceError", "AggregateError"])
+const NOTIFY_METHODS = new Set(["notify", "send", "publish"])
+const NOTIFY_TEXT_PROPS = new Set(["subject", "title", "body", "text", "message"])
+const RESPONSE_TEXT_PROPS = new Set(["message", "description", "title"])
+
+/** A literal that reads as prose rather than a code, an enum value or a key. */
+const looksLikeCopy = (text) => {
+    const trimmed = text.trim()
+    if (!trimmed) return false
+    if (/^[A-Z][A-Z0-9_]*$/.test(trimmed)) return false // a code: PLAN_NOT_FOUND
+    if (/^[A-Za-z][A-Za-z0-9_-]*$/.test(trimmed)) return false // a single bare word: pending, plan-not-found
+    return true
+}
+
+const isNotifyCall = (node) =>
+    node?.type === "CallExpression"
+    && node.callee.type === "MemberExpression"
+    && !node.callee.computed
+    && node.callee.property.type === "Identifier"
+    && NOTIFY_METHODS.has(node.callee.property.name)
+
+/** User-facing text is looked up in the catalog by key, never written where it is used. */
+export const userCopyThroughCatalog = {
+    meta: {
+        type: "problem",
+        docs: { description: "A literal exception message, notification text or response copy comes from the messages catalog, not from source." },
+        schema: [],
+        messages: {
+            exception: "`{{name}}`'s message is a literal string. A user-facing exception message comes from the per-capability messages catalog (`messages.get('<key>', params)`) through the typed `MessageCatalog` port, in Vietnamese and English, not written in source.",
+            notification: "`{{property}}` of this {{call}} call is a literal string. Notification copy comes from the messages catalog through the `MessageCatalog` port, not written at the call site.",
+            response: "`{{property}}` of this response is a literal string. Response copy comes from the messages catalog through the `MessageCatalog` port, not written in source.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename) || isTestLane(filename)) return {}
+        const inTransport = filename.includes("/transport/")
+        return {
+            NewExpression(node) {
+                const name = node.callee.type === "Identifier" ? node.callee.name : null
+                if (!name || BUILTIN_ERRORS.has(name) || !/(?:Error|Exception)$/.test(name)) return
+                const first = node.arguments[0]
+                if (!first) return
+                const text = staticText(first)
+                if (text !== null && looksLikeCopy(text)) context.report({ node: first, messageId: "exception", data: { name } })
+            },
+            CallExpression(node) {
+                if (!isNotifyCall(node)) return
+                const callName = node.callee.property.name
+                const objectArg = node.arguments.find((argument) => argument.type === "ObjectExpression")
+                if (!objectArg) return
+                for (const property of objectArg.properties) {
+                    if (property.type !== "Property") continue
+                    const key = keyName(property.key)
+                    if (!key || !NOTIFY_TEXT_PROPS.has(key)) continue
+                    const text = staticText(property.value)
+                    if (text !== null && looksLikeCopy(text)) {
+                        context.report({ node: property.value, messageId: "notification", data: { property: key, call: callName } })
+                    }
+                }
+            },
+            Property(node) {
+                if (!inTransport) return
+                const key = keyName(node.key)
+                if (!key || !RESPONSE_TEXT_PROPS.has(key)) return
+                const text = staticText(node.value)
+                if (text === null || !looksLikeCopy(text)) return
+                if (isNotifyCall(node.parent?.parent)) return // already judged as notification copy
+                context.report({ node: node.value, messageId: "response", data: { property: key } })
+            },
+        }
+    },
+}
+
+/** The rule this law contributes to the plugin. */
+export const rules = {
+    "user-copy-through-catalog": userCopyThroughCatalog,
+}
+
+/** Starts at error: a hand-written user-facing string is never a warning. */
+export const recommended = {
+    "starci-be/user-copy-through-catalog": "error",
+}

package/exception-identity.mjs

@@ -1,200 +0,0 @@
-/**
- * The rules that hold `exception-identity.md`.
- *
- * THREE RULES OVER ONE DECLARATION, AND THE FIRST IS WHAT MAKES THE OTHER GATES REAL. The
- * metadata-object rule, the base-class rule and the folder rule in `exceptions.mjs` all key on a name
- * ending in `Exception`, and the throw-site rule recognises only `Error` and the framework names. A
- * failure declared as `SomethingError` therefore sits inside the errors folder, extends the house
- * base, and is reported by none of them; the gate says nothing and that reads as agreement.
- *
- * The second rule is the one a client feels. The code is what Apollo stamps onto every GraphQL error
- * (`formatError` in the monolithic server module says so in as many words: code matching, not status,
- * is the front end's primary signal), so a code that drifts from its class is a wire contract nobody
- * can predict from the name - and a code copied from the exception above it makes two unrelated
- * failures arrive identical, which is the exact defect `EXCEPTION-1` refuses framework exceptions for.
- *
- * The third keeps the payload's type named after the failure it belongs to, so the shape a throw site
- * must satisfy is reachable from the exception's own name.
- */
-
-/** The house base every exception extends. */
-const EXCEPTION_BASE = "AbstractException"
-
-/** Anything named like an exception. */
-const EXCEPTION_NAME = /Exception$/
-
-/** A class declaration that extends the house base - the only shape these rules govern. */
-const isHouseException = (node) =>
-  Boolean(node.id) && Boolean(node.superClass) && node.superClass.type === "Identifier" && node.superClass.name === EXCEPTION_BASE
-
-/** The constructor of a class body, when it declares one. */
-const constructorOf = (node) =>
-  node.body.body.find((member) => member.type === "MethodDefinition" && member.kind === "constructor")
-
-/** The `super(...)` call inside a constructor, which is where the message and the code are passed. */
-const superCallOf = (ctor) => {
-  const found = []
-  const visit = (statements) => {
-    for (const statement of statements ?? []) {
-      if (
-        statement.type === "ExpressionStatement" &&
-        statement.expression.type === "CallExpression" &&
-        statement.expression.callee.type === "Super"
-      ) {
-        found.push(statement.expression)
-      }
-    }
-  }
-  visit(ctor.value.body?.body)
-  return found[0]
-}
-
-/** Letters only, upper case: `COURSE_NOT_FOUND_EXCEPTION` and `CourseNotFoundException` compare equal. */
-const letters = (text) => String(text).replace(/_/g, "").toUpperCase()
-
-// -- IDENTITY-1 ------------------------------------------------------------------------------------
-
-/** The class name ends in `Exception`, because that suffix is what every other exception rule sees. */
-export const exceptionNameEndsInException = {
-  meta: {
-    type: "problem",
-    docs: { description: "A class extending `AbstractException` is named `*Exception`." },
-    schema: [],
-    messages: {
-      suffix:
-        "`{{name}}` extends `AbstractException` but is not named `*Exception`. Every rule guarding exceptions matches on that suffix - the throw-site rule, the metadata-object rule, the base-class rule and the folder rule all skip this class, so it is a failure NOTHING checks while the gate stays green. Rename it `{{suggestion}}`.",
-    },
-  },
-  create(context) {
-    return {
-      ClassDeclaration(node) {
-        if (!isHouseException(node) || EXCEPTION_NAME.test(node.id.name)) return
-        context.report({
-          node: node.id,
-          messageId: "suffix",
-          data: {
-            name: node.id.name,
-            suggestion: `${node.id.name.replace(/Error$/, "")}Exception`,
-          },
-        })
-      },
-    }
-  },
-}
-
-// -- IDENTITY-2 ------------------------------------------------------------------------------------
-
-/** The code is the class name, so nothing has to be looked up and nothing can be quietly reused. */
-export const exceptionCodeMatchesClassName = {
-  meta: {
-    type: "problem",
-    docs: { description: "The code passed to `super()` spells the class name." },
-    schema: [],
-    messages: {
-      mismatch:
-        "`{{name}}` reports the code `{{code}}`. The code is what a client matches on, so it is derived from the class name and nothing else: `{{expected}}`. A code that says something different cannot be predicted from the name, cannot be found by searching for the class, and - when it was copied from the exception above it - makes two unrelated failures arrive at the client identical.",
-      notLiteral:
-        "`{{name}}` builds its code instead of stating one. A code assembled at runtime cannot be found by searching for it, which is the one thing every consumer of it does - the client matching on it, the alert grouping by it, the reader asking where this failure comes from. Pass the literal `{{expected}}`.",
-    },
-  },
-  create(context) {
-    return {
-      ClassDeclaration(node) {
-        if (!isHouseException(node)) return
-        const ctor = constructorOf(node)
-        if (!ctor) return
-        const call = superCallOf(ctor)
-        if (!call || call.arguments.length < 2) return
-        const code = call.arguments[1]
-        const expected = `${node.id.name
-          .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
-          .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
-          .toUpperCase()}`
-        if (code.type !== "Literal" || typeof code.value !== "string") {
-          context.report({ node: code, messageId: "notLiteral", data: { name: node.id.name, expected } })
-          return
-        }
-        // Underscore placement is not the ruling - `GRAPHQL_DATA` and `GRAPH_QL_DATA` name the same
-        // class, and an acronym has no single correct split. The letters are the ruling.
-        if (letters(code.value) === letters(node.id.name)) return
-        context.report({
-          node: code,
-          messageId: "mismatch",
-          data: { name: node.id.name, code: code.value, expected },
-        })
-      },
-    }
-  },
-}
-
-// -- IDENTITY-3 ------------------------------------------------------------------------------------
-
-/** The metadata type carries the exception's name, so the payload shape is reachable from it. */
-export const exceptionMetadataTypeNamedForClass = {
-  meta: {
-    type: "problem",
-    docs: { description: "The constructor's metadata parameter is typed `<Class>Metadata`." },
-    schema: [],
-    messages: {
-      untyped:
-        "`{{name}}`'s metadata parameter states no type. The parameter is the whole contract a throw site has to satisfy, and an untyped one accepts every object - including the one missing the id the failure exists to carry. Type it `{{expected}}`.",
-      named:
-        "`{{name}}` types its metadata as `{{actual}}`. Name the type after the exception - `{{expected}}` - so the payload is reachable from the failure's own name, and so the day this failure gains its first field there is already a place to put it that no call site has to learn.",
-    },
-  },
-  create(context) {
-    return {
-      ClassDeclaration(node) {
-        if (!isHouseException(node)) return
-        const ctor = constructorOf(node)
-        if (!ctor) return
-        // `{ ... }: Metadata = {}` parses as an assignment pattern wrapping the destructuring, and
-        // reading only the outer node skipped exactly the declarations that had given up on a named
-        // type - the ones this rule exists for.
-        const declared = ctor.value.params[0]
-        const param = declared?.type === "AssignmentPattern" ? declared.left : declared
-        if (!param || param.type !== "ObjectPattern") return
-        const expected = `${node.id.name}Metadata`
-        const annotation = param.typeAnnotation?.typeAnnotation
-        if (!annotation) {
-          context.report({ node: param, messageId: "untyped", data: { name: node.id.name, expected } })
-          return
-        }
-        if (annotation.type !== "TSTypeReference" || annotation.typeName.type !== "Identifier") return
-        if (annotation.typeName.name === expected) return
-        context.report({
-          node: annotation,
-          messageId: "named",
-          data: { name: node.id.name, actual: annotation.typeName.name, expected },
-        })
-      },
-    }
-  },
-}
-
-/** The rules this law contributes to the plugin. */
-export const rules = {
-  "exception-name-ends-in-exception": exceptionNameEndsInException,
-  "exception-code-matches-class-name": exceptionCodeMatchesClassName,
-  "exception-metadata-type-named-for-class": exceptionMetadataTypeNamedForClass,
-}
-
-/**
- * The levels this law asks for.
- *
- * All three measured with debt when they landed and all three are at zero now, which is the only
- * state that earns `error`: a rule switched on over existing offenders trains its readers to scroll
- * past it, and a reader who has learned to scroll past one rule reads none of them. Each arrived at
- * `warn` with a ledger entry naming its offenders and flipped as that entry closed - metadata types
- * first, because renaming one costs no caller anything, then the codes and the class names, which
- * are wire-visible and were measured against every client before being moved.
- *
- * What that measurement found is worth keeping: across three front ends, five exception codes are
- * matched in total, and none of them belonged to a drifted declaration. The assumption that a code
- * change means a coordinated release was expensive to believe and cheap to check.
- */
-export const recommended = {
-  "starci-be/exception-name-ends-in-exception": "error", // debt paid 2026-08-14
-  "starci-be/exception-code-matches-class-name": "error", // debt paid 2026-08-14
-  "starci-be/exception-metadata-type-named-for-class": "error", // debt paid 2026-08-14
-}