@starci/eslint-canon-be 1.2.2 → 1.7.0

package/error-handling.mjs

@@ -0,0 +1,207 @@
+/**
+ * The rules that hold HFS errors and their handling (catalog R38 `BE_ERROR_HOME`, R40 `BE_LOGGER_REQUIRED`).
+ *
+ * TWO RULES, ONE HABIT: a failure is either named where its owner lives, or it is visible.
+ *
+ *   - `catch-must-account` refuses a `catch` (and a promise `.catch`) that swallows. A handler passes when it
+ *     rethrows, when it logs through a logger port, or when it returns an outcome that carries the caught
+ *     error as its `cause`. An empty handler, and one that returns `null` or `false` and moves on, turns a
+ *     real failure into "nothing happened" - the payment error that became `unavailable` with no trace.
+ *   - `error-home` keeps every error where its semantic owner is. A class deriving from `DomainError` lives in
+ *     `<capability>/errors/`; the retired `exceptions/` capability, the retired `AbstractException` base, a bare
+ *     `throw new Error(...)`, a framework `HttpException`, and a domain that throws a platform error are all
+ *     refused. Expected business results are typed unions, not exceptions, and are outside this rule.
+ *
+ * This file replaces the Academy `AbstractException` laws: those rules pinned a central exception family that
+ * HFS no longer has, and a rule that survives its standard as "off" is a rule nobody can trust.
+ */
+import { some, walk } from "./lib/ast.mjs"
+import { isDeclarationFile, isTestLane, normalizePath } from "./lib/path.mjs"
+
+const LOG_METHODS = new Set(["error", "warn", "info", "debug", "log", "fatal", "verbose", "trace"])
+
+/** The object a member call is made on, as the last identifier of its chain (`this.logger.error` gives `logger`). */
+const receiverName = (callee) => {
+    const object = callee.object
+    if (object.type === "Identifier") return object.name
+    if (object.type === "MemberExpression" && !object.computed && object.property.type === "Identifier") return object.property.name
+    return null
+}
+
+/** `logger.error(...)`, `this.log.warn(...)`: a call on a logger port. `console` is never one. */
+const isLoggerCall = (node) => {
+    if (node.type !== "CallExpression" || node.callee.type !== "MemberExpression" || node.callee.computed) return false
+    if (node.callee.property.type !== "Identifier" || !LOG_METHODS.has(node.callee.property.name)) return false
+    const receiver = receiverName(node.callee)
+    return receiver !== null && receiver !== "console" && /log/i.test(receiver)
+}
+
+/** True when `name` is used as a value in `node` (not just as the object of `name.message`). */
+const carriesCaught = (node, name) => {
+    if (!name) return false
+    let carried = false
+    walk(node, (child) => {
+        if (child.type !== "Identifier" || child.name !== name) return
+        const parent = child.parent
+        if (parent?.type === "MemberExpression" && parent.object === child) return
+        carried = true
+    })
+    return carried
+}
+
+/**
+ * Whether a handler block accounts for the failure.
+ *
+ * @param {object} body - The block of the handler.
+ * @param {string | null} param - The caught error's name, when the handler names it.
+ * @returns {boolean} True when it rethrows, logs, or returns an outcome carrying the error.
+ */
+const accounts = (body, param) =>
+    some(
+        body,
+        (node) =>
+            node.type === "ThrowStatement" ||
+            isLoggerCall(node) ||
+            (node.type === "ReturnStatement" && node.argument !== null && carriesCaught(node.argument, param)),
+        { intoFunctions: false },
+    )
+
+const paramName = (fn) => (fn.params?.[0]?.type === "Identifier" ? fn.params[0].name : null)
+
+/** Every failure is rethrown, logged, or returned as an outcome carrying its cause. */
+export const catchMustAccount = {
+    meta: {
+        type: "problem",
+        docs: { description: "A catch rethrows, logs through a logger port, or returns an outcome that carries the cause." },
+        schema: [],
+        messages: {
+            empty: "This `catch` is empty, so the failure vanishes. Rethrow it, log it through the logger port, or return a typed outcome carrying it as `cause`.",
+            swallowed:
+                "This `catch` neither rethrows, logs, nor returns an outcome carrying the caught error, so the failure leaves no trace. Rethrow it, log it through the logger port, or return a typed outcome with `cause`.",
+        },
+    },
+    create(context) {
+        const checkBlock = (reportNode, body, param) => {
+            if (body.body.length === 0) context.report({ node: reportNode, messageId: "empty" })
+            else if (!accounts(body, param)) context.report({ node: reportNode, messageId: "swallowed" })
+        }
+        return {
+            CatchClause(node) {
+                checkBlock(node, node.body, node.param?.type === "Identifier" ? node.param.name : null)
+            },
+            CallExpression(node) {
+                if (node.callee.type !== "MemberExpression" || node.callee.computed) return
+                if (node.callee.property.type !== "Identifier" || node.callee.property.name !== "catch") return
+                const handler = node.arguments[0]
+                if (!handler || (handler.type !== "ArrowFunctionExpression" && handler.type !== "FunctionExpression")) return
+                if (handler.body.type === "BlockStatement") {
+                    checkBlock(handler, handler.body, paramName(handler))
+                } else if (!isLoggerCall(handler.body) && !carriesCaught(handler.body, paramName(handler))) {
+                    context.report({ node: handler, messageId: "swallowed" })
+                }
+            },
+        }
+    },
+}
+
+/** The framework exceptions that carry an HTTP status and no identity. */
+const FRAMEWORK_EXCEPTIONS = new Set([
+    "BadRequestException",
+    "NotFoundException",
+    "UnauthorizedException",
+    "ForbiddenException",
+    "InternalServerErrorException",
+    "HttpException",
+    "ConflictException",
+    "NotAcceptableException",
+    "RequestTimeoutException",
+    "GoneException",
+    "PayloadTooLargeException",
+    "UnsupportedMediaTypeException",
+    "UnprocessableEntityException",
+    "NotImplementedException",
+    "BadGatewayException",
+    "ServiceUnavailableException",
+    "GatewayTimeoutException",
+])
+
+const BUILTIN_ERRORS = new Set(["Error", "TypeError", "RangeError", "SyntaxError", "ReferenceError", "EvalError", "URIError"])
+
+/** `<capability>/errors/` under a module tier or a feature, or the platform `errors` capability itself. */
+const ERRORS_HOME =
+    /\/src\/(?:modules\/(?:domain|platform|integrations)\/[^/]+|features\/[^/]+)\/(?:[^/]+\/)*errors\/|\/src\/modules\/platform\/errors\//
+const PLATFORM_ERRORS = /\/src\/modules\/platform\/errors\//
+const RETIRED_HOME = /\/src\/modules\/(?:domain|platform|integrations)\/exceptions\//
+const DOMAIN_TIER = /\/src\/modules\/domain\//
+const HEALTH_PROBE = /\/health(?:z)?\.controller\.ts$|\/health\//
+
+/** An error class is declared at its owner, extends `DomainError`, and is never a bare or framework throw. */
+export const errorHome = {
+    meta: {
+        type: "problem",
+        docs: { description: "Errors live in `<capability>/errors/`, extend DomainError, and no bare or framework error escapes." },
+        schema: [],
+        messages: {
+            place: "`{{name}}` is an error of this capability but is declared outside its `errors/` folder. Move it to the `errors/` folder of the capability that owns its meaning.",
+            retiredHome: "This file sits in a retired `exceptions/` capability. Errors belong to the capability that owns their meaning, in its `errors/` folder.",
+            retiredBase: "`{{name}}` extends `AbstractException`, the retired central base. Extend `DomainError` from `platform/errors` and keep the class in its capability's `errors/`.",
+            mustExtendDomainError: "`{{name}}` extends the built-in `{{parent}}`. Extend `DomainError` so the error carries a stable `code` and a `cause`.",
+            bareError: "`throw new Error(...)` carries a sentence and no code, so nothing downstream can group or map it. Throw a `DomainError` subclass of the owning capability.",
+            framework: "`throw new {{name}}(...)` carries an HTTP status and no identity. Throw a `DomainError` subclass and let the transport map its code to a status.",
+            platformThrown: "A domain capability throws `{{name}}`, a platform error. Translate it into an error of this capability so platform details do not cross the boundary.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename)) return {}
+        const listeners = {}
+        if (RETIRED_HOME.test(filename)) {
+            listeners.Program = (node) => context.report({ node, messageId: "retiredHome" })
+        }
+        if (isTestLane(filename)) return listeners
+        const inHome = ERRORS_HOME.test(filename)
+        const platformImports = new Set()
+        listeners.ImportDeclaration = (node) => {
+            if (typeof node.source.value !== "string" || !/(?:^|\/)platform\//.test(node.source.value)) return
+            for (const specifier of node.specifiers) platformImports.add(specifier.local.name)
+        }
+        listeners.ClassDeclaration = (node) => {
+            const parent = node.superClass
+            if (!node.id || !parent || parent.type !== "Identifier") return
+            if (parent.name === "AbstractException") {
+                context.report({ node: parent, messageId: "retiredBase", data: { name: node.id.name } })
+            } else if (BUILTIN_ERRORS.has(parent.name)) {
+                if (!PLATFORM_ERRORS.test(filename)) {
+                    context.report({ node: parent, messageId: "mustExtendDomainError", data: { name: node.id.name, parent: parent.name } })
+                }
+            } else if (/Error$/.test(parent.name) && !inHome) {
+                context.report({ node: node.id, messageId: "place", data: { name: node.id.name } })
+            }
+        }
+        listeners.ThrowStatement = (node) => {
+            const thrown = node.argument
+            if (!thrown || thrown.type !== "NewExpression" || thrown.callee.type !== "Identifier") return
+            const name = thrown.callee.name
+            if (name === "Error") {
+                context.report({ node: thrown, messageId: "bareError" })
+            } else if (FRAMEWORK_EXCEPTIONS.has(name) && !HEALTH_PROBE.test(filename)) {
+                context.report({ node: thrown, messageId: "framework", data: { name } })
+            } else if (DOMAIN_TIER.test(filename) && name !== "DomainError" && /Error$/.test(name) && platformImports.has(name)) {
+                context.report({ node: thrown, messageId: "platformThrown", data: { name } })
+            }
+        }
+        return listeners
+    },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "catch-must-account": catchMustAccount,
+    "error-home": errorHome,
+}
+
+/** Both start at error: HFS has no baseline, and the migration lanes clear the debt before a repository adopts them. */
+export const recommended = {
+    "starci-be/catch-must-account": "error",
+    "starci-be/error-home": "error",
+}

package/idempotency.mjs

@@ -0,0 +1,101 @@
+/**
+ * The rule that holds inbox dedupe (catalog R80 `BE_INBOX_DEDUPE_MISSING`).
+ *
+ * A sender that gets no timely reply resends: a payment provider retries a webhook, a queue
+ * redelivers a message it never saw acknowledged. The standard is one inbox table keyed by
+ * `(source, event id)` in front of every door delivery can repeat through, so a repeat is a no-op
+ * instead of a second charge, a second email or a second state transition.
+ *
+ *   - `inbox-dedupe-required` refuses a `@Public()` webhook controller method, or an outbox/queue
+ *     consumer, whose file shows no reference to an inbox or dedupe port. A consumer is recognized
+ *     by more than its filename: `<event>.consumer.ts` under `transport/message/` (the
+ *     `be.transport.message` slot) still counts, and so does a method decorated `@EventPattern`,
+ *     `@MessagePattern`, `@OnEvent` or `@Process`, or a class whose name ends `Consumer` or
+ *     `OutboxConsumer`, wherever that file sits. A class that only PUBLISHES - the producer half of
+ *     an outbox, typically `*-outbox.service.ts` / `*OutboxService` - carries none of those shapes
+ *     and is not flagged: it has no repeat delivery to dedupe unless it also consumes.
+ *
+ * This reads one file's text for the shape of a claim (`inbox`, `dedupe`, `idempoten*` naming a
+ * port, a field or a call) - it cannot see whether the call actually runs before the side effect,
+ * which needs the call graph and stays a review question, same as `no-outer-manager-in-transaction`
+ * says for its own undecidable half.
+ */
+import { decoratorName, keyName, staticText } from "./lib/ast.mjs"
+import { isTestLane, normalizePath } from "./lib/path.mjs"
+
+const INBOX_REFERENCE = /inbox|dedupe|idempoten/i
+const CONSUMER_FILE = /\/transport\/message\/[^/]+\.consumer\.ts$/
+const WEBHOOK_FILE = /\/transport\/http\/[^/]*webhook[^/]*\.controller\.ts$/i
+/** A class whose name alone says it consumes a delivery, regardless of where the file sits. */
+const CONSUMER_CLASS_NAME = /(?:Outbox)?Consumer$/
+/** A method decorator that binds a handler to an incoming message or event, not just a filename convention. */
+const CONSUMER_DECORATORS = new Set(["EventPattern", "MessagePattern", "OnEvent", "Process"])
+
+/** The route or reason text a `@Public()` decorator's argument carries, lower-cased. */
+const publicReason = (node) => {
+    const expression = node.expression
+    const argument = expression.type === "CallExpression" ? expression.arguments[0] : undefined
+    if (argument?.type !== "ObjectExpression") return ""
+    const property = argument.properties.find((item) => item.type === "Property" && keyName(item.key) === "reason")
+    return (property ? staticText(property.value) : null)?.toLowerCase() ?? ""
+}
+
+/** A webhook door: the file is named for one, the open door names its reason, or the route itself does. */
+const isWebhookController = (filename, sourceText, publicDecorators) =>
+    WEBHOOK_FILE.test(filename)
+    || publicDecorators.some((node) => /webhook/.test(publicReason(node)))
+    || /@Controller\(\s*["'`][^"'`]*webhook/i.test(sourceText)
+
+/** Delivery this instance can receive more than once shows a claim against the inbox before it acts. */
+export const inboxDedupeRequired = {
+    meta: {
+        type: "problem",
+        docs: { description: "A `@Public()` webhook handler and an outbox/queue consumer claim the event through the shared inbox before they act." },
+        schema: [],
+        messages: {
+            webhook: "This webhook controller has no reference to an inbox or dedupe port. A sender that gets no timely reply resends the same event; claim `(source, event id)` in the shared inbox before acting, so a repeat delivery is a no-op.",
+            consumer: "This consumer has no reference to an inbox or dedupe port. A queue redelivers a message it never saw acknowledged; claim `(source, event id)` in the shared inbox before acting, so a redelivery is a no-op.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isTestLane(filename)) return {}
+        let isConsumer = CONSUMER_FILE.test(filename)
+        const publicDecorators = []
+        return {
+            Decorator(node) {
+                const name = decoratorName(node)
+                if (name === "Public") publicDecorators.push(node)
+                else if (CONSUMER_DECORATORS.has(name)) isConsumer = true
+            },
+            ClassDeclaration(node) {
+                if (node.id && CONSUMER_CLASS_NAME.test(node.id.name)) isConsumer = true
+            },
+            ClassExpression(node) {
+                if (node.id && CONSUMER_CLASS_NAME.test(node.id.name)) isConsumer = true
+            },
+            "Program:exit"(node) {
+                const sourceCode = context.sourceCode || context.getSourceCode()
+                const text = sourceCode.getText()
+                if (INBOX_REFERENCE.test(text)) return
+                if (isConsumer) {
+                    context.report({ node, messageId: "consumer" })
+                    return
+                }
+                if (publicDecorators.length && isWebhookController(filename, text, publicDecorators)) {
+                    context.report({ node, messageId: "webhook" })
+                }
+            },
+        }
+    },
+}
+
+/** The rule this law contributes to the plugin. */
+export const rules = {
+    "inbox-dedupe-required": inboxDedupeRequired,
+}
+
+/** Starts at error: a duplicate charge or a duplicate side effect is never a warning. */
+export const recommended = {
+    "starci-be/inbox-dedupe-required": "error",
+}

package/index.mjs

@@ -16,39 +16,67 @@
  * every conversation about the failure. Aliasing one here to match a target's older spelling would
  * leave two names for one rule and no way to tell which a message came from.
  */
+import { recommended as asyncDisciplineRecommended, rules as asyncDisciplineRules } from "./async-discipline.mjs"
 import { recommended as authorizationRecommended, rules as authorizationRules } from "./authorization.mjs"
 import { recommended as cdcRecommended, rules as cdcRules } from "./cdc.mjs"
 import { recommended as commentsRecommended, rules as commentsRules } from "./comments.mjs"
+import { recommended as configOwnerRecommended, rules as configOwnerRules } from "./config-owner.mjs"
 import { recommended as cqrsRecommended, rules as cqrsRules } from "./cqrs.mjs"
 import { recommended as dataAccessRecommended, rules as dataAccessRules } from "./data-access.mjs"
+import { recommended as defaultDenyRecommended, rules as defaultDenyRules } from "./default-deny.mjs"
 import { recommended as e2eFlowRecommended, rules as e2eFlowRules } from "./e2e-flow.mjs"
+import { recommended as errorHandlingRecommended, rules as errorHandlingRules } from "./error-handling.mjs"
 import { recommended as eventDeliveryRecommended, rules as eventDeliveryRules } from "./event-delivery.mjs"
-import { recommended as exceptionIdentityRecommended, rules as exceptionIdentityRules } from "./exception-identity.mjs"
-import { recommended as exceptionsRecommended, rules as exceptionsRules } from "./exceptions.mjs"
+import { recommended as idempotencyRecommended, rules as idempotencyRules } from "./idempotency.mjs"
+import { recommended as inputBoundsRecommended, rules as inputBoundsRules } from "./input-bounds.mjs"
+import { recommended as logSafetyRecommended, rules as logSafetyRules } from "./log-safety.mjs"
 import { recommended as moduleLayeringRecommended, rules as moduleLayeringRules } from "./module-layering.mjs"
+import { recommended as moduleShapeRecommended, rules as moduleShapeRules } from "./module-shape.mjs"
 import { recommended as namingRecommended, rules as namingRules } from "./naming.mjs"
 import { recommended as observabilityRecommended, rules as observabilityRules } from "./observability.mjs"
+import { recommended as querySafetyRecommended, rules as querySafetyRules } from "./query-safety.mjs"
+import { recommended as resilienceRecommended, rules as resilienceRules } from "./resilience.mjs"
+import { recommended as schemaAuthorityRecommended, rules as schemaAuthorityRules } from "./schema-authority.mjs"
+import { recommended as sizeBudgetRecommended, rules as sizeBudgetRules } from "./size-budget.mjs"
+import { recommended as specQualityRecommended, rules as specQualityRules } from "./spec-quality.mjs"
+import { recommended as suppressionRecommended, rules as suppressionRules } from "./suppression.mjs"
+import { recommended as temporalRecommended, rules as temporalRules } from "./temporal.mjs"
 import { recommended as testingRecommended, rules as testingRules } from "./testing.mjs"
 import { recommended as transportRecommended, rules as transportRules } from "./transport.mjs"
 import { recommended as typeSafetyRecommended, rules as typeSafetyRules } from "./type-safety.mjs"
+import { recommended as userCopyRecommended, rules as userCopyRules } from "./user-copy.mjs"
 
 /** Each law's contribution, kept separate so a duplicate name is detectable rather than silent. */
 const CONTRIBUTIONS = [
+    { law: "async-discipline", rules: asyncDisciplineRules, recommended: asyncDisciplineRecommended },
     { law: "authorization", rules: authorizationRules, recommended: authorizationRecommended },
     { law: "cdc", rules: cdcRules, recommended: cdcRecommended },
     { law: "comments", rules: commentsRules, recommended: commentsRecommended },
+    { law: "config-owner", rules: configOwnerRules, recommended: configOwnerRecommended },
     { law: "cqrs", rules: cqrsRules, recommended: cqrsRecommended },
     { law: "data-access", rules: dataAccessRules, recommended: dataAccessRecommended },
+    { law: "default-deny", rules: defaultDenyRules, recommended: defaultDenyRecommended },
     { law: "e2e-flow", rules: e2eFlowRules, recommended: e2eFlowRecommended },
+    { law: "error-handling", rules: errorHandlingRules, recommended: errorHandlingRecommended },
     { law: "event-delivery", rules: eventDeliveryRules, recommended: eventDeliveryRecommended },
-    { law: "exception-identity", rules: exceptionIdentityRules, recommended: exceptionIdentityRecommended },
-    { law: "exceptions", rules: exceptionsRules, recommended: exceptionsRecommended },
+    { law: "idempotency", rules: idempotencyRules, recommended: idempotencyRecommended },
+    { law: "input-bounds", rules: inputBoundsRules, recommended: inputBoundsRecommended },
+    { law: "log-safety", rules: logSafetyRules, recommended: logSafetyRecommended },
     { law: "module-layering", rules: moduleLayeringRules, recommended: moduleLayeringRecommended },
+    { law: "module-shape", rules: moduleShapeRules, recommended: moduleShapeRecommended },
     { law: "naming", rules: namingRules, recommended: namingRecommended },
     { law: "observability", rules: observabilityRules, recommended: observabilityRecommended },
+    { law: "query-safety", rules: querySafetyRules, recommended: querySafetyRecommended },
+    { law: "resilience", rules: resilienceRules, recommended: resilienceRecommended },
+    { law: "schema-authority", rules: schemaAuthorityRules, recommended: schemaAuthorityRecommended },
+    { law: "size-budget", rules: sizeBudgetRules, recommended: sizeBudgetRecommended },
+    { law: "spec-quality", rules: specQualityRules, recommended: specQualityRecommended },
+    { law: "suppression", rules: suppressionRules, recommended: suppressionRecommended },
+    { law: "temporal", rules: temporalRules, recommended: temporalRecommended },
     { law: "testing", rules: testingRules, recommended: testingRecommended },
     { law: "transport", rules: transportRules, recommended: transportRecommended },
     { law: "type-safety", rules: typeSafetyRules, recommended: typeSafetyRecommended },
+    { law: "user-copy", rules: userCopyRules, recommended: userCopyRecommended },
 ]
 
 /** Every gathered law. */
@@ -105,3 +133,5 @@ export default {
     meta: { name: "eslint-plugin-starci-be" },
     rules,
 }
+
+export { starciBeConfig, linterOptions } from "./lib/config.mjs"

package/input-bounds.mjs

@@ -0,0 +1,84 @@
+/**
+ * The rules that keep input bounded (R42 `BE_INPUT_BOUNDED`).
+ *
+ * `dto-needs-validator` refuses an input class whose property carries no `class-validator` decorator. A property with
+ * no validator accepts any value the wire delivers: a string of any length, a number of any size, an array of any
+ * count. The transport layer states what it accepts; the use case never re-checks shape.
+ *
+ * An input class is one decorated `@InputType` or `@ArgsType`, or declared in a file named `*.dto.ts`, `*.input.ts`,
+ * `*.args.ts` or `*.request.ts`. A class decorated `@ObjectType` is a response and is left alone. A decorator counts as
+ * a validator only when it is imported from `class-validator`, so a `@Field` or a `@Type` does not satisfy the rule.
+ */
+import { decoratorName } from "./lib/ast.mjs"
+import { isDeclarationFile, isTestLane, normalizePath } from "./lib/path.mjs"
+
+const INPUT_FILE = /\.(?:dto|input|args|request)\.ts$/
+
+const decoratorsOf = (node) => node.decorators ?? []
+
+/** Names imported from `class-validator`, by local name. */
+const validatorImports = (program) => {
+  const names = new Set()
+  for (const statement of program.body) {
+    if (statement.type !== "ImportDeclaration" || statement.source.value !== "class-validator") continue
+    for (const specifier of statement.specifiers) names.add(specifier.local.name)
+  }
+  return names
+}
+
+/** Every property of an input class has a validator. */
+export const dtoNeedsValidator = {
+  meta: {
+    type: "problem",
+    docs: { description: "A property of an input class carries a `class-validator` decorator." },
+    schema: [],
+    messages: {
+      missing:
+        "`{{name}}` has no `class-validator` decorator, so the wire may deliver any value here: a string of any length, a number of any size, an array of any count. Add the validators the field needs (`@IsString() @MaxLength(n)`, `@IsInt() @Min(0) @Max(n)`, `@IsArray() @ArrayMaxSize(n)`, `@IsOptional()` for a nullable field).",
+    },
+  },
+  create(context) {
+    const filename = normalizePath(context.filename || context.getFilename())
+    if (isTestLane(filename) || isDeclarationFile(filename)) return {}
+    const sourceCode = context.sourceCode || context.getSourceCode()
+    let validators = null
+    return {
+      Program(node) {
+        validators = validatorImports(node)
+      },
+      ClassDeclaration(node) {
+        checkClass(node)
+      },
+      ClassExpression(node) {
+        checkClass(node)
+      },
+    }
+    function checkClass(node) {
+      const decorators = decoratorsOf(node).map(decoratorName)
+      const target = node.parent?.type === "ExportNamedDeclaration" || node.parent?.type === "ExportDefaultDeclaration" ? node.parent : node
+      const classDecorators = [...decorators, ...decoratorsOf(target).map(decoratorName)]
+      if (classDecorators.includes("ObjectType")) return
+      const isInput = classDecorators.includes("InputType") || classDecorators.includes("ArgsType") || INPUT_FILE.test(filename)
+      if (!isInput) return
+      for (const member of node.body.body) {
+        if (member.type !== "PropertyDefinition" || member.static || member.computed) continue
+        if (member.key.type !== "Identifier") continue
+        const validated = decoratorsOf(member).some((decorator) => {
+          const name = decoratorName(decorator)
+          return name !== null && validators.has(name)
+        })
+        if (!validated) context.report({ node: member.key, messageId: "missing", data: { name: sourceCode.getText(member.key) } })
+      }
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "dto-needs-validator": dtoNeedsValidator,
+}
+
+/** Starts at error: no baseline exists, and the repositories' fix lanes clear the debt. */
+export const recommended = {
+  "starci-be/dto-needs-validator": "error",
+}

package/lib/ast.mjs

@@ -0,0 +1,81 @@
+/**
+ * Small AST helpers the HFS laws share, so each rule states its question instead of its traversal.
+ *
+ * Nothing here touches disk or the type checker: a rule reads one file's syntax and its path.
+ */
+
+const SKIP_KEYS = new Set(["parent", "loc", "range", "tokens", "comments"])
+
+const isNode = (value) => value !== null && typeof value === "object" && typeof value.type === "string"
+
+const FUNCTION_TYPES = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"])
+
+/**
+ * Visits `node` and every descendant, depth first.
+ *
+ * @param {object} node - The subtree root.
+ * @param {(child: object) => void} visit - Called with each node.
+ * @param {{ intoFunctions?: boolean }} [options] - `intoFunctions: false` stops at nested function boundaries.
+ * @returns {void}
+ */
+export const walk = (node, visit, { intoFunctions = true } = {}) => {
+    if (!isNode(node)) return
+    visit(node)
+    for (const [key, value] of Object.entries(node)) {
+        if (SKIP_KEYS.has(key)) continue
+        if (Array.isArray(value)) {
+            for (const child of value) {
+                if (!isNode(child)) continue
+                if (!intoFunctions && FUNCTION_TYPES.has(child.type)) continue
+                walk(child, visit, { intoFunctions })
+            }
+        } else if (isNode(value)) {
+            if (!intoFunctions && FUNCTION_TYPES.has(value.type)) continue
+            walk(value, visit, { intoFunctions })
+        }
+    }
+}
+
+/** True when any node of the subtree satisfies `predicate`. */
+export const some = (node, predicate, options) => {
+    let found = false
+    walk(node, (child) => {
+        if (!found && predicate(child)) found = true
+    }, options)
+    return found
+}
+
+/** The name a property key, identifier or string literal spells, else null. */
+export const keyName = (node) => {
+    if (!node) return null
+    if (node.type === "Identifier") return node.name
+    if (node.type === "Literal" && typeof node.value === "string") return node.value
+    if (node.type === "PrivateIdentifier") return node.name
+    return null
+}
+
+/** The name of a decorator (`@Foo` or `@Foo(...)`), else null. */
+export const decoratorName = (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
+}
+
+/** True for a string literal or a template without substitutions, giving its text via `staticText`. */
+export const staticText = (node) => {
+    if (!node) return null
+    if (node.type === "Literal" && typeof node.value === "string") return node.value
+    if (node.type === "TemplateLiteral" && node.expressions.length === 0) return node.quasis.map((q) => q.value.cooked ?? "").join("")
+    return null
+}
+
+/** Splits `webhookSecret`, `WEBHOOK_SECRET` and `webhook-secret` into lower-case words. */
+export const wordsOf = (name) =>
+    String(name)
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((word) => word.toLowerCase())

package/lib/config.mjs

@@ -0,0 +1,49 @@
+/**
+ * The one flat-config block that attaches the back-end canon to a repository.
+ *
+ * A consuming `eslint.config.mjs` used to hand-copy three things: the list of rules it switches off, the
+ * helper that lifts `warn` to `error`, and the source globs. Copies drift - two repositories held
+ * byte-identical files, a third had grown its own variant - and a rule that a copy switched off with the words
+ * "replaced by checks" was enforced by nothing when the replacing check ran in no gate. This factory owns the
+ * levels, so a repository states only its source globs.
+ *
+ * NO RULE IS OFF. HFS has no retired-rule list: a rule the standard no longer holds is deleted from the
+ * plugin, and a rule that stays is on. The factory refuses a recommendation that carries an `off`, so a rule
+ * cannot be published switched off and still look adopted.
+ */
+
+/** A disable directive is a weakening of lint, and one that suppresses nothing is dead weight. */
+export const linterOptions = Object.freeze({ noInlineConfig: true, reportUnusedDisableDirectives: "error" })
+
+/** The zero-warning gate reads a warning as a failure, so the canon's `warn` level is stated as `error`. */
+const asError = (setting) =>
+    setting === "warn" ? "error" : Array.isArray(setting) && setting[0] === "warn" ? ["error", ...setting.slice(1)] : setting
+
+const levelOf = (setting) => (Array.isArray(setting) ? setting[0] : setting)
+
+/**
+ * @param {object} input - Attachment options.
+ * @param {string[]} input.sources - The globs of the repository's production and spec source.
+ * @param {object} input.plugin - The plugin object, imported from this canon.
+ * @param {Record<string, unknown>} input.recommended - The recommendation, imported from this canon.
+ * @returns {object} One flat-config block.
+ */
+export const starciBeConfig = ({ sources, plugin, recommended }) => {
+    if (!Array.isArray(sources) || sources.length === 0) {
+        throw new Error("starciBeConfig needs the repository's source globs - a block that matches no file governs nothing")
+    }
+    const rules = recommended?.rules ?? recommended
+    if (!rules || Object.keys(rules).length === 0) {
+        throw new Error("starciBeConfig received an empty recommendation - a config with no rules is not adoption")
+    }
+    const off = Object.entries(rules)
+        .filter(([, setting]) => levelOf(setting) === "off")
+        .map(([name]) => name)
+    if (off.length > 0) {
+        throw new Error(`starciBeConfig refuses a recommendation with rules switched off: ${off.join(", ")}`)
+    }
+    const configured = Object.fromEntries(
+        Object.entries(rules).map(([name, setting]) => [name, asError(setting)]),
+    )
+    return { files: sources, linterOptions: { ...linterOptions }, plugins: { "starci-be": plugin }, rules: configured }
+}

package/lib/path.mjs

@@ -1,2 +1,17 @@
 /** Forward-slash form of a filename, so Windows paths compare like every other path. */
 export const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** A spec file: the unit lane, where a fixture may build a deliberately wrong value. */
+export const isSpecFile = (filename) => /\.(?:spec|test)\.[cm]?[jt]sx?$|-spec\.[cm]?[jt]sx?$/.test(normalizePath(filename))
+
+/** Any file of the test lanes: a spec, or anything under `src/tests/`. */
+export const isTestLane = (filename) => {
+    const file = normalizePath(filename)
+    return isSpecFile(file) || file.includes("/src/tests/")
+}
+
+/** A migration: the one place schema-changing SQL is allowed to be written. */
+export const isMigrationFile = (filename) => /\/persistence\/migrations\/[^/]+\.[cm]?[jt]s$/.test(normalizePath(filename))
+
+/** A declaration file carries types only and no runtime behaviour to police. */
+export const isDeclarationFile = (filename) => /\.d\.[cm]?ts$/.test(normalizePath(filename))