@starci/eslint-canon-be 1.2.2 → 1.7.1

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/cdc.mjs

@@ -1,150 +0,0 @@
-const isProjectionListener = (filename) => /projection\.listener\.ts$/.test(
-  String(filename || "").replace(/\\/g, "/"),
-) && !String(filename || "").replace(/\\/g, "/").endsWith("/abstract-projection.listener.ts")
-
-const isProjectionService = (filename) => /-projection\.service\.ts$/.test(
-  String(filename || "").replace(/\\/g, "/"),
-)
-
-const memberName = (member) => member.key && (member.key.name || member.key.value)
-
-/** A groupId literal is safe: a plain string, or a template with no `${}` substitution. */
-const isStaticStringValue = (node) => {
-  if (!node) return false
-  if (node.type === "Literal" && typeof node.value === "string") return true
-  if (node.type === "TemplateLiteral" && node.expressions.length === 0) return true
-  return false
-}
-
-/** Flatten a function's parameter list to the names it binds, through destructuring/defaults/rest. */
-const collectParamNames = (params, names = []) => {
-  for (const param of params || []) {
-    if (!param) continue
-    if (param.type === "Identifier") {
-      names.push(param.name)
-    } else if (param.type === "AssignmentPattern") {
-      collectParamNames([param.left], names)
-    } else if (param.type === "RestElement") {
-      collectParamNames([param.argument], names)
-    } else if (param.type === "ObjectPattern") {
-      for (const prop of param.properties || []) {
-        if (prop.type === "Property" && prop.key) {
-          names.push(prop.key.name || prop.key.value)
-        } else if (prop.type === "RestElement") {
-          collectParamNames([prop.argument], names)
-        }
-      }
-    }
-  }
-  return names
-}
-
-const DELTA_LIKE_PARAMS = new Set(["amount", "delta", "points", "increment"])
-
-/** A projection listener declares mapping while AbstractProjectionListener owns Kafka lifecycle. */
-export const projectionListenerContract = {
-  meta: {
-    type: "problem",
-    docs: { description: "Projection CDC listeners share one Kafka lifecycle contract." },
-    schema: [],
-    messages: {
-      base: "A projection CDC listener extends AbstractProjectionListener; the shared base owns subscription, envelope parsing and failure isolation.",
-      member: "A projection CDC listener must declare `{{name}}`.",
-      lifecycle: "A concrete projection listener must not override `onModuleInit`; Kafka lifecycle belongs to AbstractProjectionListener.",
-    },
-  },
-  create(context) {
-    if (!isProjectionListener(context.filename || context.getFilename())) return {}
-    return {
-      ClassDeclaration(node) {
-        if (!node.superClass || node.superClass.name !== "AbstractProjectionListener") {
-          context.report({ node: node.id || node, messageId: "base" })
-        }
-        const members = node.body.body || []
-        const names = new Set(members.map(memberName))
-        for (const name of ["groupId", "topics", "deriveTargets", "recomputeTarget"]) {
-          if (!names.has(name)) {
-            context.report({ node: node.id || node, messageId: "member", data: { name } })
-          }
-        }
-        const lifecycle = members.find((member) => memberName(member) === "onModuleInit")
-        if (lifecycle) context.report({ node: lifecycle.key, messageId: "lifecycle" })
-      },
-    }
-  },
-}
-
-/** CDC Rule 3 (CDC-2): a projection's consumer group id is a constant, not computed at boot. */
-export const noDynamicProjectionGroupId = {
-  meta: {
-    type: "problem",
-    docs: {
-      description: "CDC Rule 3 (CDC-2): `groupId` is a stable string literal, not a value computed at boot.",
-    },
-    schema: [],
-    messages: {
-      dynamic: "CDC Rule 3 (CDC-2): `groupId` must be a constant string literal. A template substitution, a call (`Date.now()`, `randomUUID()`, `hostname()`), or an env/instance read makes the consumer group unstable across restarts, so each restart replays the whole history in a fresh group instead of resuming from the committed offset.",
-    },
-  },
-  create(context) {
-    if (!isProjectionListener(context.filename || context.getFilename())) return {}
-    return {
-      PropertyDefinition(node) {
-        if (memberName(node) !== "groupId") return
-        if (node.value && !isStaticStringValue(node.value)) {
-          context.report({ node: node.value, messageId: "dynamic" })
-        }
-      },
-    }
-  },
-}
-
-/** CDC Rules 1 and 6 (CDC-4): recompute rebuilds from source by UPSERT, never by applying a delta. */
-export const projectionRecomputeMustUpsert = {
-  meta: {
-    type: "problem",
-    docs: {
-      description: "CDC Rules 1 and 6 (CDC-4): a projection recomputes from source rows by UPSERT; it is never updated by applying an event's delta.",
-    },
-    schema: [],
-    messages: {
-      delta: "CDC Rules 1 and 6 (CDC-4): `recompute` must not take a `{{name}}` parameter. Recompute takes only the target's identity and rebuilds the value from authoritative source rows -- a delta/amount/points parameter means a duplicate delivery doubles the projection and a lost delivery never heals.",
-      upsert: "CDC Rules 1 and 6 (CDC-4): a projection service with a `recompute` method must write through an UPSERT (`ON CONFLICT`). A value assembled without one is not safe to replay, and replay is the one guarantee a broker actually offers.",
-    },
-  },
-  create(context) {
-    if (!isProjectionService(context.filename || context.getFilename())) return {}
-    let hasRecompute = false
-    return {
-      MethodDefinition(node) {
-        if (memberName(node) !== "recompute") return
-        hasRecompute = true
-        const params = collectParamNames(node.value.params)
-        for (const name of params) {
-          if (DELTA_LIKE_PARAMS.has(String(name).toLowerCase())) {
-            context.report({ node, messageId: "delta", data: { name } })
-          }
-        }
-      },
-      "Program:exit"(node) {
-        if (!hasRecompute) return
-        const source = context.sourceCode || context.getSourceCode()
-        if (!/on\s*conflict/i.test(source.getText())) {
-          context.report({ node, messageId: "upsert" })
-        }
-      },
-    }
-  },
-}
-
-export const rules = {
-  "projection-listener-contract": projectionListenerContract,
-  "no-dynamic-projection-group-id": noDynamicProjectionGroupId,
-  "projection-recompute-must-upsert": projectionRecomputeMustUpsert,
-}
-
-export const recommended = {
-  "starci-be/projection-listener-contract": "error",
-  "starci-be/no-dynamic-projection-group-id": "error",
-  "starci-be/projection-recompute-must-upsert": "error",
-}

package/event-delivery.mjs

@@ -1,93 +0,0 @@
-import { normalizePath } from "./lib/path.mjs"
-
-/** The NATS bridge rejects self-echo and claims redelivery before local fan-out. */
-export const natsBridgeDeliveryContract = {
-  meta: {
-    type: "problem",
-    docs: { description: "The central NATS bridge preserves cross-instance delivery invariants." },
-    schema: [],
-    messages: {
-      origin: "Drop envelopes whose producer id matches this instance before local emit.",
-      digest: "Claim/check the envelope digest before local emit so redelivery is idempotent.",
-    },
-  },
-  create(context) {
-    if (!normalizePath(context.filename || context.getFilename()).endsWith(
-      "/event/nats/nats-bridge.service.ts",
-    )) return {}
-    return {
-      "Program:exit"(node) {
-        const source = context.sourceCode || context.getSourceCode()
-        const text = source.getText()
-        const originIndex = text.search(/parsed\.id\s*===\s*this\.instanceService\.getId\(\)/)
-        const digestIndex = text.indexOf("parsed.digest")
-        const emitIndex = text.indexOf("this.eventEmitter.emit")
-        if (originIndex < 0 || emitIndex < 0 || originIndex > emitIndex) {
-          context.report({ node, messageId: "origin" })
-        }
-        if (digestIndex < 0 || emitIndex < 0 || digestIndex > emitIndex) {
-          context.report({ node, messageId: "digest" })
-        }
-      },
-    }
-  },
-}
-
-const isEmitCallOnEventEmitterService = (node) =>
-  node.callee.type === "MemberExpression" &&
-  !node.callee.computed &&
-  node.callee.property.type === "Identifier" &&
-  node.callee.property.name === "emit" &&
-  node.callee.object.type === "MemberExpression" &&
-  !node.callee.object.computed &&
-  node.callee.object.property.type === "Identifier" &&
-  node.callee.object.property.name === "eventEmitterService"
-
-const findObjectProperty = (objectExpression, name) => {
-  if (!objectExpression || objectExpression.type !== "ObjectExpression") return null
-  return objectExpression.properties.find(
-    (property) => property.type === "Property" &&
-      !property.computed &&
-      (property.key.name === name || property.key.value === name),
-  ) || null
-}
-
-/** DELIVERY Rule 2 (DELIVERY-2): transport is declared per event in one config, never at the call site. */
-export const noCallSiteTransportOverride = {
-  meta: {
-    type: "problem",
-    docs: {
-      description: "DELIVERY Rule 2 (DELIVERY-2): transport is declared per event in the central config; it is never chosen at the call site.",
-    },
-    schema: [],
-    messages: {
-      callsite: "DELIVERY Rule 2 (DELIVERY-2): do not pass `options.useLocal`/`options.useNats` to `eventEmitterService.emit(...)`. Transport is part of the event's definition in the central config, not a per-call decision -- a call site choosing it is a promise the config never made and a reader has to guess at.",
-    },
-  },
-  create(context) {
-    return {
-      CallExpression(node) {
-        if (!isEmitCallOnEventEmitterService(node)) return
-        const args = node.arguments[0]
-        const optionsProperty = findObjectProperty(args, "options")
-        if (!optionsProperty) return
-        const optionsValue = optionsProperty.value
-        const hasUseLocal = findObjectProperty(optionsValue, "useLocal")
-        const hasUseNats = findObjectProperty(optionsValue, "useNats")
-        if (hasUseLocal || hasUseNats) {
-          context.report({ node: optionsProperty, messageId: "callsite" })
-        }
-      },
-    }
-  },
-}
-
-export const rules = {
-  "nats-bridge-delivery-contract": natsBridgeDeliveryContract,
-  "no-call-site-transport-override": noCallSiteTransportOverride,
-}
-
-export const recommended = {
-  "starci-be/nats-bridge-delivery-contract": "error",
-  "starci-be/no-call-site-transport-override": "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
-}