@starci/eslint-canon-be 1.2.2 → 1.7.0

package/module-shape.mjs

@@ -0,0 +1,202 @@
+/**
+ * The rules that hold the shape of a Nest module in HFS (catalog R45 `BE_MODULE_SHAPE`).
+ *
+ *   - `global-module-allowlist` lets `@Global()` appear only on the platform capabilities the slot manifest
+ *     names (`ruleParams.be.globalModules`; read through `lib/slots.mjs`).
+ *     A global module hides who depends on whom, so it is reserved for the three every capability needs.
+ *   - `typed-module-definition` requires `ConfigurableModuleBuilder<Options>` to state its options type.
+ *   - `static-module-register` requires `register`, `registerAsync`, `forRoot` and `forFeature` to be `static`.
+ *   - `no-new-injectable` refuses `new SomeService()` (and other injectable-shaped names) outside specs: the
+ *     container builds providers, so construction by hand bypasses its scope and its overrides.
+ *   - `no-module-let` refuses mutable module-level state (`let` and `var` at the top of a file).
+ *   - `one-module-per-file` allows one `@Module` class in a file, so one transport or application module has
+ *     one home.
+ *
+ * `no-self-global-module` of the earlier canon is gone: it refused `@Global()` everywhere, which also refused
+ * the three platform capabilities HFS requires to be global.
+ */
+import { decoratorName } from "./lib/ast.mjs"
+import { isDeclarationFile, isTestLane, normalizePath } from "./lib/path.mjs"
+import { hfsParams } from "./lib/slots.mjs"
+
+/** `platform/<capability>` of a file inside `src/modules/platform`, else null. */
+const platformCapability = (filename) => {
+    const match = /\/src\/modules\/(platform\/[^/]+)\//.exec(filename)
+    return match ? match[1] : null
+}
+
+/** `@Global()` only on an allowlisted platform capability. */
+export const globalModuleAllowlist = {
+    meta: {
+        type: "problem",
+        docs: { description: "`@Global()` only for the manifest's platform allowlist." },
+        schema: [
+            {
+                type: "object",
+                properties: { allowed: { type: "array", items: { type: "string" } } },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            global: "`@Global()` is allowed only on {{allowed}}. A global module hides its dependants; import the module where it is used, or pass options through `register`.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename) || isTestLane(filename)) return {}
+        const allowed = context.options[0]?.allowed ?? hfsParams.globalModules
+        const capability = platformCapability(filename)
+        if (capability !== null && allowed.includes(capability)) return {}
+        return {
+            Decorator(node) {
+                if (decoratorName(node) === "Global") context.report({ node, messageId: "global", data: { allowed: allowed.map((name) => `\`${name}\``).join(", ") } })
+            },
+        }
+    },
+}
+
+/** A configurable module builder names its options type. */
+export const typedModuleDefinition = {
+    meta: {
+        type: "problem",
+        docs: { description: "`new ConfigurableModuleBuilder<Options>()` states its options type." },
+        schema: [],
+        messages: {
+            untyped: "`ConfigurableModuleBuilder` has no options type. Write `new ConfigurableModuleBuilder<{{example}}Options>()` so `register` is checked.",
+        },
+    },
+    create(context) {
+        if (isDeclarationFile(context.filename || context.getFilename())) return {}
+        return {
+            NewExpression(node) {
+                if (node.callee.type !== "Identifier" || node.callee.name !== "ConfigurableModuleBuilder") return
+                const typed = (node.typeArguments ?? node.typeParameters)?.params?.length > 0
+                if (!typed) context.report({ node, messageId: "untyped", data: { example: "Capability" } })
+            },
+        }
+    },
+}
+
+const REGISTER_NAMES = new Set(["register", "registerAsync", "forRoot", "forRootAsync", "forFeature"])
+
+/** The dynamic-module factory methods are `static`. */
+export const staticModuleRegister = {
+    meta: {
+        type: "problem",
+        docs: { description: "`register`, `registerAsync`, `forRoot` and `forFeature` are static." },
+        schema: [],
+        messages: {
+            notStatic: "`{{name}}` builds a dynamic module and must be `static`; an instance method cannot be called from `imports`.",
+        },
+    },
+    create(context) {
+        if (isDeclarationFile(context.filename || context.getFilename())) return {}
+        return {
+            ClassDeclaration(node) {
+                if (!node.decorators?.some((decorator) => decoratorName(decorator) === "Module")) return
+                for (const member of node.body.body) {
+                    if (member.type !== "MethodDefinition" || member.static || member.computed) continue
+                    if (member.key.type === "Identifier" && REGISTER_NAMES.has(member.key.name)) {
+                        context.report({ node: member, messageId: "notStatic", data: { name: member.key.name } })
+                    }
+                }
+            },
+        }
+    },
+}
+
+const INJECTABLE_SUFFIX = /(?:Service|Repository|Guard|Interceptor|Resolver|Consumer|UseCase)$/
+
+/** Providers are built by the container, not by `new`. */
+export const noNewInjectable = {
+    meta: {
+        type: "problem",
+        docs: { description: "No `new SomeService()` for an injectable-shaped class outside a spec." },
+        schema: [],
+        messages: {
+            construct: "`new {{name}}()` builds a provider by hand, bypassing the container's scope and overrides. Inject it, or register it as a provider.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename) || isTestLane(filename)) return {}
+        return {
+            NewExpression(node) {
+                if (node.callee.type === "Identifier" && INJECTABLE_SUFFIX.test(node.callee.name)) {
+                    context.report({ node, messageId: "construct", data: { name: node.callee.name } })
+                }
+            },
+        }
+    },
+}
+
+/** No mutable state at module scope. */
+export const noModuleLet = {
+    meta: {
+        type: "problem",
+        docs: { description: "No `let` or `var` at module scope." },
+        schema: [],
+        messages: {
+            mutable: "`{{kind}}` at module scope is process-wide mutable state shared by every request and test. Keep the state in an injected provider.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename) || isTestLane(filename)) return {}
+        const check = (node) => {
+            if (node.type === "VariableDeclaration" && node.kind !== "const") context.report({ node, messageId: "mutable", data: { kind: node.kind } })
+        }
+        return {
+            Program(node) {
+                for (const statement of node.body) {
+                    check(statement)
+                    if (statement.type === "ExportNamedDeclaration" && statement.declaration) check(statement.declaration)
+                }
+            },
+        }
+    },
+}
+
+/** One `@Module` class per file. */
+export const oneModulePerFile = {
+    meta: {
+        type: "problem",
+        docs: { description: "A file declares at most one `@Module` class." },
+        schema: [],
+        messages: {
+            many: "This file declares a second `@Module` class. One transport or application module has one file; split this one out.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename) || isTestLane(filename)) return {}
+        let seen = 0
+        return {
+            ClassDeclaration(node) {
+                if (!node.decorators?.some((decorator) => decoratorName(decorator) === "Module")) return
+                seen += 1
+                if (seen > 1) context.report({ node, messageId: "many" })
+            },
+        }
+    },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "global-module-allowlist": globalModuleAllowlist,
+    "typed-module-definition": typedModuleDefinition,
+    "static-module-register": staticModuleRegister,
+    "no-new-injectable": noNewInjectable,
+    "no-module-let": noModuleLet,
+    "one-module-per-file": oneModulePerFile,
+}
+
+/** All start at error: HFS has one module shape and no baseline. */
+export const recommended = {
+    "starci-be/global-module-allowlist": "error",
+    "starci-be/typed-module-definition": "error",
+    "starci-be/static-module-register": "error",
+    "starci-be/no-new-injectable": "error",
+    "starci-be/no-module-let": "error",
+    "starci-be/one-module-per-file": "error",
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-be",
-  "version": "1.2.2",
+  "version": "1.7.0",
   "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
   "type": "module",
   "license": "UNLICENSED",

package/query-safety.mjs

@@ -0,0 +1,274 @@
+/**
+ * The rules that keep a database call safe to run in production.
+ *
+ * - `no-interpolated-sql` (R68 `BE_SQL_INTERPOLATED`) refuses SQL text built from a runtime value. A value
+ *   reaches the statement as a numbered parameter (`$1`), never as spliced text.
+ * - `query-needs-limit` (R69 `BE_QUERY_UNBOUNDED`) refuses a read that returns every matching row. A list read
+ *   states its bound: `take`, `limit`, `LIMIT`, or a page cursor.
+ *
+ * Both read one file's syntax only. Where the syntax cannot prove a call safe or unsafe (a statement held in a
+ * variable, an options object built elsewhere) the rule stays silent: a rule that guesses teaches authors to
+ * ignore it.
+ */
+import { keyName, staticText, walk } from "./lib/ast.mjs"
+import { isDeclarationFile, isTestLane, normalizePath } from "./lib/path.mjs"
+
+const SQL_VERB = /\b(?:SELECT|INSERT|UPDATE|DELETE|WITH)\b/i
+
+/** A migration writes DDL once, by hand, with no caller input: interpolation there is a build step, not a hole. */
+const isMigrationPath = (filename) => /\/migrations\/[^/]+\.[cm]?ts$/.test(normalizePath(filename))
+
+/** The property a call goes through: `manager.query(...)` gives `query`. */
+const calleeProperty = (node) =>
+  node.callee.type === "MemberExpression" && !node.callee.computed && node.callee.property.type === "Identifier"
+    ? node.callee.property.name
+    : null
+
+/** The last name of the receiver: `this.manager` gives `manager`, `em` gives `em`. */
+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
+}
+
+/** UPPER_SNAKE names a module constant: a fixed column list is code, not input. */
+const isConstantName = (name) => /^[A-Z][A-Z0-9_]*$/.test(name)
+
+/** Identifier helpers that quote an identifier are the sanctioned way to put a name into a statement. */
+const IDENT_HELPERS = new Set(["quoteIdent", "quoteIdentifier", "quoteIdentifiers", "sqlIdent", "sqlIdentifiers", "sqlSetClause", "escapeIdentifier"])
+
+/** Whether a substitution inside a SQL template is one of the shapes that cannot carry input. */
+const isSafeSubstitution = (expression, precedingText) => {
+  if (precedingText.endsWith("$")) return true
+  if (expression.type === "Identifier") return isConstantName(expression.name)
+  if (expression.type === "MemberExpression" && !expression.computed && expression.property.type === "Identifier") {
+    return isConstantName(expression.property.name)
+  }
+  if (expression.type === "CallExpression" && expression.callee.type === "Identifier") return IDENT_HELPERS.has(expression.callee.name)
+  // `${locked ? "FOR UPDATE" : ""}` chooses between fixed strings
+  if (expression.type === "ConditionalExpression") {
+    const fixed = (branch) => branch.type === "Literal" && typeof branch.value === "string"
+    return fixed(expression.consequent) && fixed(expression.alternate)
+  }
+  return false
+}
+
+// -- R68 -----------------------------------------------------------------------------------------------
+
+/** A statement is text plus parameters; a value never becomes part of the text. */
+export const noInterpolatedSql = {
+  meta: {
+    type: "problem",
+    docs: { description: "SQL text passed to `.query(...)` contains no runtime substitution; values are numbered parameters." },
+    schema: [],
+    messages: {
+      interpolated:
+        "This SQL text is built from `{{expression}}`. A value spliced into a statement is an injection hole and defeats the plan cache. Pass the value as a numbered parameter (`$1`) in the array argument. A column list is a module constant in UPPER_SNAKE case; a dynamic identifier goes through `quoteIdent(...)` or `sqlIdent(...)`; a variable SET list goes through `sqlSetClause(...)`, which checks every column against a fixed allowlist and numbers the placeholders. A choice between fixed strings is a ternary of literals.",
+      concatenated:
+        "This SQL text is joined with `+`. A value spliced into a statement is an injection hole. Pass the value as a numbered parameter (`$1`) in the array argument.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (isTestLane(filename) || isDeclarationFile(filename) || isMigrationPath(filename)) return {}
+    const sourceCode = context.sourceCode || context.getSourceCode()
+    return {
+      CallExpression(node) {
+        if (calleeProperty(node) !== "query") return
+        const first = node.arguments[0]
+        if (!first) return
+        if (first.type === "TemplateLiteral" && first.expressions.length > 0) {
+          const text = first.quasis.map((quasi) => quasi.value.cooked ?? "").join(" ")
+          if (!SQL_VERB.test(text)) return
+          first.expressions.forEach((expression, index) => {
+            const preceding = first.quasis[index]?.value.cooked ?? ""
+            if (isSafeSubstitution(expression, preceding)) return
+            context.report({ node: expression, messageId: "interpolated", data: { expression: sourceCode.getText(expression).slice(0, 60) } })
+          })
+        } else if (first.type === "BinaryExpression" && first.operator === "+") {
+          let sql = false
+          walk(first, (child) => {
+            if (child.type === "Literal" && typeof child.value === "string" && SQL_VERB.test(child.value)) sql = true
+          })
+          if (sql) context.report({ node: first, messageId: "concatenated" })
+        }
+      },
+    }
+  },
+}
+
+// -- R69 -----------------------------------------------------------------------------------------------
+
+const AGGREGATE_ONLY = /^\s*(?:WITH\b[\s\S]*?\)\s*)?SELECT\s+(?:COUNT|SUM|MAX|MIN|AVG|EXISTS|NEXTVAL|NOW|CURRENT_|PG_|SET_CONFIG|1\b|TRUE|FALSE|\(?\s*SELECT\s+1)/i
+const HAS_BOUND = /\bLIMIT\b|\bFETCH\s+FIRST\b/i
+/** A lookup by the primary key returns one row, so it needs no bound. */
+const BY_PRIMARY_KEY = /\bWHERE\s+"?(?:[a-z_]+\.)?id"?\s*=\s*\$\d+\s*(?:FOR\s+UPDATE\s*)?(?:RETURNING[^;]*)?$/i
+
+const QUERY_BUILDER_READS = new Set(["getMany", "getRawMany", "getManyAndCount", "getRawAndEntities"])
+const REPOSITORY_READS = new Set(["find", "findBy", "findAndCount", "findAndCountBy"])
+const REPOSITORY_RECEIVER = /^(?:manager|entityManager|em|repo|repository|[a-z]\w*Repository|[a-z]\w*Repo)$/
+
+/** The chain of calls a query builder read hangs off, as method names, innermost first. */
+const chainNames = (callee) => {
+  const names = []
+  let current = callee
+  while (current) {
+    if (current.type === "MemberExpression" && !current.computed && current.property.type === "Identifier") {
+      names.push(current.property.name)
+      current = current.object
+    } else if (current.type === "CallExpression") {
+      current = current.callee
+    } else if (current.type === "AwaitExpression") {
+      current = current.argument
+    } else break
+  }
+  return names
+}
+
+/** Whether an object literal names a property, by key. */
+const objectHasKey = (node, names) =>
+  node?.type === "ObjectExpression" && node.properties.some((property) => property.type === "Property" && names.includes(keyName(property.key)))
+
+/** Whether a `where` object states the primary key, which bounds the read to one row. */
+const whereHasPrimaryKey = (node) => {
+  if (node?.type !== "ObjectExpression") return false
+  if (objectHasKey(node, ["id"])) return true
+  const where = node.properties.find((property) => property.type === "Property" && keyName(property.key) === "where")
+  return where ? whereHasPrimaryKey(where.value) : false
+}
+
+/** A list read states its bound. */
+export const queryNeedsLimit = {
+  meta: {
+    type: "problem",
+    docs: { description: "A read that can return many rows states `take`, `limit` or `LIMIT`." },
+    schema: [],
+    messages: {
+      builder:
+        "`.{{method}}()` reads every matching row: one busy tenant turns it into a full scan held in memory. Add `.take(n)` (or `.limit(n)`) with a named bound, or page with a cursor.",
+      find:
+        "`.{{method}}(...)` on a repository reads every matching row and states no `take`. Pass `take` with a named bound (the entity manager form is `manager.find(Entity, { where, take })`), or page with a cursor. A lookup by `id` is exempt.",
+      findBy:
+        "`.findBy(...)` cannot take a bound, so it reads every matching row. Use `.find({ where, take })` with a named bound, or page with a cursor. A lookup by `id` is exempt.",
+      raw:
+        "This `SELECT` has no `LIMIT`. Add `LIMIT $n` with a named bound, or page by keyset. An aggregate (`COUNT`, `EXISTS`, `SUM`) and a lookup by `id` are exempt.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (isTestLane(filename) || isDeclarationFile(filename) || isMigrationPath(filename)) return {}
+    return {
+      CallExpression(node) {
+        const method = calleeProperty(node)
+        if (!method) return
+        if (QUERY_BUILDER_READS.has(method)) {
+          const names = chainNames(node.callee.object.type === "CallExpression" ? node.callee.object.callee : node.callee.object)
+          if (names.includes("take") || names.includes("limit") || names.includes("getOne") || names.includes("getOneOrFail")) return
+          if (!names.includes("createQueryBuilder") && !names.includes("select") && !names.includes("where") && !names.includes("andWhere") && !names.includes("leftJoinAndSelect") && !names.includes("innerJoinAndSelect") && !names.includes("orderBy") && !names.includes("from")) return
+          context.report({ node: node.callee.property, messageId: "builder", data: { method } })
+          return
+        }
+        if (REPOSITORY_READS.has(method) && REPOSITORY_RECEIVER.test(receiverName(node.callee) ?? "")) {
+          const args = node.arguments
+          // manager.find(Entity, options) has the entity first; repository.find(options) has the options first
+          const options = method === "find" || method === "findAndCount" ? args.find((arg) => arg.type === "ObjectExpression") : undefined
+          const where = method === "findBy" || method === "findAndCountBy" ? args.find((arg) => arg.type === "ObjectExpression") : undefined
+          if (method === "find" || method === "findAndCount") {
+            const argument = args[args.length - 1]
+            if (!argument || argument.type !== "ObjectExpression") return // no static options to judge
+            if (objectHasKey(options, ["take", "limit"]) || whereHasPrimaryKey(options)) return
+            context.report({ node: node.callee.property, messageId: "find", data: { method } })
+          } else if (where) {
+            if (whereHasPrimaryKey(where)) return
+            context.report({ node: node.callee.property, messageId: "findBy", data: { method } })
+          }
+          return
+        }
+        if (method === "query") {
+          const text = staticText(node.arguments[0])
+          const sql = text ?? (node.arguments[0]?.type === "TemplateLiteral" ? node.arguments[0].quasis.map((quasi) => quasi.value.cooked ?? "").join(" ") : null)
+          if (sql === null) return
+          if (!/^\s*(?:SELECT|WITH)\b/i.test(sql)) return
+          if (HAS_BOUND.test(sql) || AGGREGATE_ONLY.test(sql) || BY_PRIMARY_KEY.test(sql.trim().replace(/;$/, ""))) return
+          context.report({ node: node.arguments[0], messageId: "raw" })
+        }
+      },
+    }
+  },
+}
+
+// -- R77 -----------------------------------------------------------------------------------------------
+
+const LOOP_READS = new Set(["find", "findBy", "findOne", "findOneBy", "findOneOrFail", "findOneByOrFail", "findAndCount", "count", "countBy", "exists", "existsBy", "getOne", "getMany", "getRawMany", "getRawOne", "getCount", "query"])
+const LOOP_RECEIVER = /^(?:manager|entityManager|em|repo|repository|dataSource|queryRunner|[a-z]\w*Repository|[a-z]\w*Repo|[a-z]\w*Store)$/
+const ITERATION_METHODS = new Set(["map", "forEach", "flatMap", "filter", "reduce", "some", "every"])
+const LOOP_STATEMENTS = new Set(["ForStatement", "ForOfStatement", "ForInStatement"])
+
+/** Whether `node` runs once per element: inside a `for` loop, or inside a callback of an array iteration method. */
+const insideIteration = (node) => {
+  let current = node.parent
+  while (current) {
+    if (LOOP_STATEMENTS.has(current.type)) return true
+    if (current.type === "FunctionDeclaration" || current.type === "FunctionExpression" || current.type === "ArrowFunctionExpression") {
+      const call = current.parent
+      return (
+        call?.type === "CallExpression"
+        && call.callee.type === "MemberExpression"
+        && !call.callee.computed
+        && call.callee.property.type === "Identifier"
+        && ITERATION_METHODS.has(call.callee.property.name)
+        && call.arguments.includes(current)
+      )
+    }
+    current = current.parent
+  }
+  return false
+}
+
+/** A read inside an iteration is N+1: one round trip per element. */
+export const noQueryInLoop = {
+  meta: {
+    type: "problem",
+    docs: { description: "A repository, entity-manager or query-builder read does not run once per element of a loop." },
+    schema: [],
+    messages: {
+      inLoop:
+        "`.{{method}}(...)` runs once per element, so the number of round trips grows with the input (N+1) and one large request holds a connection for as long as it takes. Read the rows once before the loop with `find({ where: { <key>: In(keys) }, take })` or `WHERE <key> = ANY($1)`, index them in a `Map`, and look up inside the loop. A polling `while` loop is not this rule's business.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (isTestLane(filename) || isDeclarationFile(filename) || isMigrationPath(filename)) return {}
+    return {
+      CallExpression(node) {
+        const method = calleeProperty(node)
+        if (!method || !LOOP_READS.has(method)) return
+        const chain = chainNames(node.callee)
+        const builder = chain.includes("createQueryBuilder")
+        if (!builder && !LOOP_RECEIVER.test(receiverName(node.callee) ?? "")) return
+        if (method === "query") {
+          const first = node.arguments[0]
+          const sql = staticText(first) ?? (first?.type === "TemplateLiteral" ? first.quasis.map((quasi) => quasi.value.cooked ?? "").join(" ") : null)
+          if (sql === null || !/^\s*(?:SELECT|WITH)\b/i.test(sql)) return
+        }
+        if (!insideIteration(node)) return
+        context.report({ node: node.callee.property, messageId: "inLoop", data: { method } })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-interpolated-sql": noInterpolatedSql,
+  "query-needs-limit": queryNeedsLimit,
+  "no-query-in-loop": noQueryInLoop,
+}
+
+/** Both start at error: no baseline exists, and the repositories' fix lanes clear the debt. */
+export const recommended = {
+  "starci-be/no-interpolated-sql": "error",
+  "starci-be/query-needs-limit": "error",
+  "starci-be/no-query-in-loop": "error",
+}

package/resilience.mjs

@@ -0,0 +1,178 @@
+/**
+ * The rules that keep one slow or malformed dependency from taking a process down.
+ *
+ * - `http-needs-timeout` (R70 `BE_HTTP_TIMEOUT`): an outbound HTTP call states how long it may take. A socket
+ *   with no deadline holds a request, a connection and a worker slot for as long as the far side sleeps.
+ * - `json-parse-needs-guard` (R76 `BE_JSON_PARSE_UNGUARDED`): `JSON.parse` of text that came from outside the
+ *   function sits inside a `try`. A corrupt row or a hostile payload then becomes a typed outcome instead of a 500.
+ * - `no-hand-rolled-retry` (R81 `BE_HAND_ROLLED_RETRY`): a loop that catches an error and waits before trying
+ *   again re-implements retry by hand, outside `platform/retry`'s bounded, jittered, abortable helper.
+ *
+ * A call whose options are not an object literal cannot be judged from syntax, so it is left alone.
+ */
+import { keyName, walk } from "./lib/ast.mjs"
+import { isDeclarationFile, isTestLane, normalizePath } from "./lib/path.mjs"
+
+const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "request"])
+
+/** The receivers whose method calls are outbound HTTP, by the last name of the receiver. */
+const HTTP_RECEIVER = /^(?:axios|http|httpService|httpClient|axiosInstance)$/
+
+const lastName = (node) => {
+  if (node.type === "Identifier") return node.name
+  if (node.type === "MemberExpression" && !node.computed && node.property.type === "Identifier") return node.property.name
+  return null
+}
+
+const hasKey = (objectNode, names) =>
+  objectNode.properties.some((property) => property.type === "Property" && names.includes(keyName(property.key)))
+
+const hasSpread = (objectNode) => objectNode.properties.some((property) => property.type === "SpreadElement")
+
+/** Every outbound HTTP call carries a deadline. */
+export const httpNeedsTimeout = {
+  meta: {
+    type: "problem",
+    docs: { description: "`fetch`, axios and HttpService calls state a `timeout` or an abort `signal`." },
+    schema: [],
+    messages: {
+      fetchNoSignal:
+        "`fetch` without a `signal`. A peer that accepts the connection and then goes quiet holds this request for as long as it likes. Pass `{ signal: AbortSignal.timeout(<named ms>) }`.",
+      clientNoTimeout:
+        "`{{call}}` states no `timeout` or `signal`. A peer that goes quiet holds this request, its socket and a worker slot indefinitely. Pass `{ timeout: <named ms> }` (or an abort `signal`) in the request config, or set it once on `axios.create({ timeout })`.",
+      createNoTimeout:
+        "`axios.create` without a `timeout`. Every call through this instance inherits no deadline. Set `timeout: <named ms>` here.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (isTestLane(filename) || isDeclarationFile(filename)) return {}
+    return {
+      CallExpression(node) {
+        const { callee } = node
+        if (callee.type === "Identifier" && callee.name === "fetch") {
+          const init = node.arguments[1]
+          if (!init) {
+            context.report({ node, messageId: "fetchNoSignal" })
+          } else if (init.type === "ObjectExpression" && !hasSpread(init) && !hasKey(init, ["signal"])) {
+            context.report({ node, messageId: "fetchNoSignal" })
+          }
+          return
+        }
+        if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier") return
+        const method = callee.property.name
+        const receiver = lastName(callee.object)
+        if (receiver === "axios" && method === "create") {
+          const config = node.arguments[0]
+          if (!config || (config.type === "ObjectExpression" && !hasSpread(config) && !hasKey(config, ["timeout", "signal"]))) {
+            context.report({ node, messageId: "createNoTimeout" })
+          }
+          return
+        }
+        if (!HTTP_METHODS.has(method) || !receiver || !HTTP_RECEIVER.test(receiver)) return
+        // Node's own `http.get(url, callback)` is not this rule's business: a bare `http` receiver is not an injected client
+        if (receiver === "http" && callee.object.type !== "MemberExpression") return
+        const configAt = method === "request" ? 0 : ["post", "put", "patch"].includes(method) ? 2 : 1
+        const config = node.arguments[configAt]
+        if (config === undefined) {
+          context.report({ node, messageId: "clientNoTimeout", data: { call: `${receiver}.${method}` } })
+        } else if (config.type === "ObjectExpression" && !hasSpread(config) && !hasKey(config, ["timeout", "signal"])) {
+          context.report({ node, messageId: "clientNoTimeout", data: { call: `${receiver}.${method}` } })
+        }
+      },
+    }
+  },
+}
+
+/** Whether `node` sits inside a `try` block of its own function. */
+const insideTry = (node) => {
+  let child = node
+  let current = node.parent
+  while (current) {
+    if (current.type === "TryStatement" && current.block === child) return true
+    if (current.type === "FunctionDeclaration" || current.type === "FunctionExpression" || current.type === "ArrowFunctionExpression") return false
+    child = current
+    current = current.parent
+  }
+  return false
+}
+
+/** `JSON.parse` of outside text fails inside a guard. */
+export const jsonParseNeedsGuard = {
+  meta: {
+    type: "problem",
+    docs: { description: "`JSON.parse` sits inside a `try` in its own function." },
+    schema: [],
+    messages: {
+      unguarded:
+        "`JSON.parse` outside a `try`. Stored text, a webhook body and a provider reply can all be malformed, and the throw surfaces far from here as an unmasked 500. Wrap it and return a typed outcome (or a `DomainError`) naming what was being parsed.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (isTestLane(filename) || isDeclarationFile(filename)) return {}
+    return {
+      CallExpression(node) {
+        const { callee } = node
+        if (callee.type !== "MemberExpression" || callee.computed) return
+        if (callee.object.type !== "Identifier" || callee.object.name !== "JSON") return
+        if (callee.property.type !== "Identifier" || callee.property.name !== "parse") return
+        if (insideTry(node)) return
+        context.report({ node, messageId: "unguarded" })
+      },
+    }
+  },
+}
+
+const PLATFORM_RETRY = /\/src\/modules\/platform\/retry\//
+const DELAY_NAMES = /^(?:sleep|delay|wait|backoff)$/i
+const LOOP_TYPES = new Set(["ForStatement", "WhileStatement", "DoWhileStatement"])
+
+/** Whether `node` is a call shaped like a delay: `sleep(ms)`, `x.delay(ms)`, or `setTimeout(...)`. */
+const isDelayCall = (node) => {
+  if (node.type !== "CallExpression") return false
+  const { callee } = node
+  if (callee.type === "Identifier") return DELAY_NAMES.test(callee.name) || callee.name === "setTimeout"
+  return callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && DELAY_NAMES.test(callee.property.name)
+}
+
+/** A loop that both catches an error and waits is retrying by hand. */
+export const noHandRolledRetry = {
+  meta: {
+    type: "problem",
+    docs: { description: "A loop that catches an error and waits before trying again goes through `platform/retry`, not a hand-written loop." },
+    schema: [],
+    messages: {
+      handRolled:
+        "This loop catches an error and waits before trying again - a hand-rolled retry with no attempt bound visible here, no jitter and no way to honor an abort signal. Retry through the shared `platform/retry` helper (bounded attempts, exponential backoff with jitter, an abort signal) instead of a loop written at the call site.",
+    },
+  },
+  create(context) {
+    const filename = normalizePath(context.filename || context.getFilename())
+    if (isTestLane(filename) || isDeclarationFile(filename) || PLATFORM_RETRY.test(filename)) return {}
+    const check = (node) => {
+      let hasCatch = false
+      let hasDelay = false
+      walk(node.body, (child) => {
+        if (child.type === "CatchClause") hasCatch = true
+        else if (isDelayCall(child)) hasDelay = true
+      }, { intoFunctions: false })
+      if (hasCatch && hasDelay) context.report({ node, messageId: "handRolled" })
+    }
+    return Object.fromEntries([...LOOP_TYPES].map((type) => [type, check]))
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "http-needs-timeout": httpNeedsTimeout,
+  "json-parse-needs-guard": jsonParseNeedsGuard,
+  "no-hand-rolled-retry": noHandRolledRetry,
+}
+
+/** All three start at error: no baseline exists, and the repositories' fix lanes clear the debt. */
+export const recommended = {
+  "starci-be/http-needs-timeout": "error",
+  "starci-be/json-parse-needs-guard": "error",
+  "starci-be/no-hand-rolled-retry": "error",
+}