@starci/eslint-canon-be 1.1.0 → 1.2.1

package/cdc.mjs

@@ -1,44 +1,150 @@
-const isProjectionListener = (filename) => /projection\.listener\.ts$/.test(
-  String(filename || "").replace(/\\/g, "/"),
-) && !String(filename || "").replace(/\\/g, "/").endsWith("/abstract-projection.listener.ts")
-
-const memberName = (member) => member.key && (member.key.name || member.key.value)
-
-/** 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" })
-      },
-    }
-  },
-}
-
-export const rules = { "projection-listener-contract": projectionListenerContract }
-
-export const recommended = {
-  "starci-be/projection-listener-contract": "error",
-}
+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/comments.mjs

@@ -1,7 +1,7 @@
 /**
  * The rules that hold `comments.md`.
  *
- * Three rules, and each is careful about a different false positive:
+ * Five rules, and each is careful about a different false positive:
  *
  *   - `require-export-jsdoc` skips plain data constants. `export const MAX_ATTEMPTS = 3` is already
  *     fully described by its own name, and demanding a sentence there produces sentences that
@@ -10,6 +10,15 @@
  *     consequence. That half is read by a person, and the rule says so rather than pretending.
  *   - `no-non-ascii-source` exempts a marked line, because text a program matches on or emits is
  *     data wearing prose, and translating it breaks the program.
+ *   - `require-vn-ok-reason` (law 6) holds the half `no-non-ascii-source` cannot: that marker is a
+ *     bare escape hatch unless it says why the line stays, so a bare `vn-ok` is treated the same as
+ *     no marker at all.
+ *   - `no-restated-name-jsdoc` (law 7) holds the decidable slice of law 3 - a doc block whose only
+ *     content is the declared name re-spelled in words teaches nothing beyond the import line, so it
+ *     is COMMENT-3's violation wearing COMMENT-1's shape. It fires only on an exact match between the
+ *     doc's content words and the name's own words, so a doc that adds any real information is left
+ *     alone - the rest of law 3 (whether a sentence explains something outside the line) is not
+ *     decidable and stays a human read.
  */
 
 /** Forward-slash form of a filename, so Windows paths compare like every other path. */
@@ -221,11 +230,146 @@ export const noNonAsciiSource = {
   },
 }
 
+// -- law 6 -------------------------------------------------------------------------------------
+
+/** The line-level test for law 6: `vn-ok` present, with a colon and at least one reason character after it. */
+const REASON_AFTER_MARKER = /\bvn-ok\s*:\s*\S/
+
+/** Every `vn-ok` marker carries a reason; a bare marker is not an exemption. */
+export const requireVnOkReason = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "COMMENT-5, law 6: a `vn-ok` marker carries a reason - a bare marker is not an exemption.",
+    },
+    schema: [],
+    messages: {
+      bareMarker:
+        "`vn-ok` on this line has no reason after it. The marker exists so the next sweep can read WHY the line stays instead of \"fixing\" it into a bug - a bare marker is only a way of switching that check off. Write `vn-ok: <reason>` and say what the marker is protecting.",
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode || context.getSourceCode()
+    return {
+      "Program:exit"(node) {
+        const lines = sourceCode.getLines()
+        for (let index = 0; index < lines.length; index += 1) {
+          const line = lines[index]
+          if (!KEEP_MARKER.test(line)) continue
+          if (REASON_AFTER_MARKER.test(line)) continue
+          context.report({
+            node,
+            loc: { line: index + 1, column: 0 },
+            messageId: "bareMarker",
+          })
+        }
+      },
+    }
+  },
+}
+
+// -- law 7 -------------------------------------------------------------------------------------
+
+/** Splits a declared name into its lowercase words, so `readUser` compares against "read user". */
+const wordsOf = (name) =>
+  (String(name || "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[_-]+/g, " ")
+    .toLowerCase()
+    .match(/[a-z0-9]+/g) || [])
+
+/**
+ * Filler a doc contributes no information by using: articles and linking words, plus the two generic
+ * nouns the law's own anchor examples restate with ("the pending state", "the read user function").
+ * Nothing here strips a word that could carry real content, so a doc that explains anything beyond
+ * the name keeps enough leftover words to fail the equality check below.
+ */
+const RESTATEMENT_FILLER = new Set(["a", "an", "the", "is", "of", "for", "to", "this", "that", "function", "state"])
+
+/** The content words a doc comment contributes once filler is stripped out. */
+const docContentWords = (comment) =>
+  (comment.value.match(/[A-Za-z]+/g) || [])
+    .map((word) => word.toLowerCase())
+    .filter((word) => !RESTATEMENT_FILLER.has(word))
+
+/** Whether a doc's leftover content words are exactly the declared name's own words - nothing added. */
+const isPureRestatement = (comment, declaredName) => {
+  const content = docContentWords(comment)
+  const identifier = wordsOf(declaredName)
+  if (content.length === 0 || identifier.length === 0) return false
+  const contentSet = new Set(content)
+  const identifierSet = new Set(identifier)
+  if (contentSet.size !== identifierSet.size) return false
+  for (const word of contentSet) if (!identifierSet.has(word)) return false
+  return true
+}
+
+/** The doc block immediately before a node, or null. */
+const jsdocBefore = (sourceCode, node) =>
+  sourceCode.getCommentsBefore(node).find((comment) => comment.type === "Block" && comment.value.startsWith("*"))
+    || null
+
+/** A doc block that only re-spells the declared name is COMMENT-3's violation wearing COMMENT-1's shape. */
+export const noRestatedNameJsdoc = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "COMMENT-3, law 7: a doc block that restates the declared name is a COMMENT-3 violation wearing a COMMENT-1 shape, even while the lint gate that checks a doc EXISTS stays green.",
+    },
+    schema: [],
+    messages: {
+      restated:
+        "This doc block only re-spells `{{name}}` in words. A name plus a signature already says what it TAKES; the doc has to say what it is FOR, or what choosing it causes, or it is a COMMENT-3 violation wearing a COMMENT-1 shape. Delete the restatement and write the reason instead.",
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode || context.getSourceCode()
+    const checkExport = (node) => {
+      const declaration = node.declaration
+      // a re-export has nothing here to attach a doc to
+      if (!declaration) return
+      if (declaration.type === "VariableDeclaration") {
+        // only a const bound to a function has a surface; a data constant is already described
+        const first = declaration.declarations[0]
+        const init = first && first.init
+        const isFunction = init
+          && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")
+        if (!isFunction) return
+      } else if (!DOCUMENTED_KINDS.has(declaration.type)) {
+        return
+      }
+      const doc = jsdocBefore(sourceCode, node)
+      if (!doc) return
+      const name = nameOf(declaration)
+      if (!isPureRestatement(doc, name)) return
+      context.report({ node: declaration.id || declaration, messageId: "restated", data: { name } })
+    }
+    return {
+      ExportNamedDeclaration: checkExport,
+      ExportDefaultDeclaration: checkExport,
+      TSEnumDeclaration(node) {
+        if (!node.parent || node.parent.type !== "ExportNamedDeclaration") return
+        for (const member of node.members || []) {
+          const doc = jsdocBefore(sourceCode, member)
+          if (!doc) continue
+          const name = member.id && (member.id.name || member.id.value)
+          if (!name || !isPureRestatement(doc, name)) continue
+          context.report({ node: member, messageId: "restated", data: { name } })
+        }
+      },
+    }
+  },
+}
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "require-export-jsdoc": requireExportJsdoc,
   "require-enum-member-jsdoc": requireEnumMemberJsdoc,
   "no-non-ascii-source": noNonAsciiSource,
+  "require-vn-ok-reason": requireVnOkReason,
+  "no-restated-name-jsdoc": noRestatedNameJsdoc,
 }
 
 /**
@@ -240,4 +384,6 @@ export const recommended = {
   "starci-be/require-export-jsdoc": "error",
   "starci-be/require-enum-member-jsdoc": "error",
   "starci-be/no-non-ascii-source": "error",
+  "starci-be/require-vn-ok-reason": "error",
+  "starci-be/no-restated-name-jsdoc": "error",
 }

package/cqrs.mjs

@@ -1,15 +1,31 @@
 /**
  * The rules that hold `cqrs.md`.
  *
- * Three of the seven rules are shapes a parser can see. The other four - where the work lives, how
- * thin the service is, whether an event is one the caller waits on - are judgements, and a rule
- * that guessed at them would fire on correct code often enough that everybody would learn to
- * disable it.
+ * Four of the eight rules are shapes a parser can see. The other four - where the work lives, how
+ * thin the service is, whether the folder is split, whether an event is one the caller waits on -
+ * are judgements, and a rule that guessed at them would fire on correct code often enough that
+ * everybody would learn to disable it.
  *
  * The one worth explaining is CQRS-3. A handler that overrides `execute` still compiles and still
  * runs; the template method in the base is simply skipped. Nothing goes red, and the file stays
  * wrong until the day a cross-cutting concern is added to the base and silently misses it. That is
  * exactly the class of mistake a rule is for: invisible at the call site, expensive later.
+ *
+ * Rule 2 (CQRS-1, one operation one folder) was measured and NOT added here, and that absence is
+ * itself a finding. A per-file check can only compare a filename's operation slug to its immediate
+ * parent directory - and against this reference repository that comparison mismatched on 462 files
+ * even after allowing an operation-prefixed suffix (`course-enroll-crypto.service.ts` beside
+ * `course-enroll.handler.ts`). The mismatches were not CQRS-1 violations: multi-step operations
+ * nested under a shared parent (`sign-in/init/`, `sign-in/resend/`), aggregator modules named for
+ * their parent (`ai-balancer/balancer.module.ts`), and an unrelated lesson-content tree
+ * (`features/mock/**`) all failed the comparison while being correct. A rule that guessed here would
+ * have reported on more correct files than wrong ones, which is precisely the failure mode this law
+ * warns against - it would have taught everybody to disable it. The law's own "documented" tier for
+ * CQRS-1 is the honest answer, not a gap to close.
+ *
+ * Rule 5 (CQRS-5) is the opposite case: a handler returning `{ success: false }` or `{ error }`
+ * instead of throwing is a shape a parser CAN see, narrowly, without guessing at intent - and this
+ * reference repository has two real handlers doing exactly that today.
  */
 
 /** Forward-slash form of a filename, so Windows paths compare like every other path. */
@@ -177,20 +193,99 @@ export const handlerHasTwinSpec = {
   },
 }
 
+// -- CQRS-5 ----------------------------------------------------------------------------------------
+
+/** The property name that turns a returned object into an encoded failure, or null. */
+const encodedFailureKey = (node) => {
+  if (!node || node.type !== "ObjectExpression") return null
+  for (const prop of node.properties || []) {
+    if (prop.type !== "Property") continue
+    const key = prop.key
+    const name = key.type === "Identifier" ? key.name : key.type === "Literal" && typeof key.value === "string" ? key.value : null
+    if (!name) continue
+    // `error` is the encode regardless of what carries it - a caught exception, a message string,
+    // an upstream response. Its presence on a RETURNED object is the tell: the branch that found
+    // the failure chose to hand it back instead of throwing it.
+    if (name === "error") return name
+    // `success`/`ok` only encode failure at `false` - `success: true` on the happy path is not
+    // this pattern, and flagging it would report the correct half of every handler that uses this
+    // shape at all.
+    if ((name === "success" || name === "ok") && prop.value && prop.value.type === "Literal" && prop.value.value === false) {
+      return name
+    }
+  }
+  return null
+}
+
+/** The nearest enclosing method named `process`, or null. */
+const enclosingProcessMethod = (node) => {
+  for (let current = node.parent; current; current = current.parent) {
+    if (current.type === "MethodDefinition" && current.key && current.key.name === "process") return current
+  }
+  return null
+}
+
+/** The nearest enclosing class declaration, or null. */
+const enclosingClass = (node) => {
+  for (let current = node.parent; current; current = current.parent) {
+    if (current.type === "ClassDeclaration") return current
+  }
+  return null
+}
+
+/** A handler that cannot do its work throws the domain exception naming why - it does not return one. */
+export const noHandlerEncodedFailure = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "A CQRS handler throws the domain exception that names a failure; it does not return a success/error shape (Law 5, CQRS-5).",
+    },
+    schema: [],
+    messages: {
+      encoded:
+        "`{{name}}`'s `process` returns an object carrying `{{key}}` instead of throwing. CQRS-5: a handler that cannot do its work throws the domain exception naming why; an encoded `{{key}}` field asks every caller to decode this shape its own way, and the REASON for the refusal never arrives - only the fact that there was one. Throw the exception that names why, in the branch that discovers it, and let the success path return the value itself.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const operation = handlerFile(filename)
+    if (!operation) return {}
+    return {
+      ReturnStatement(node) {
+        const key = encodedFailureKey(node.argument)
+        if (!key) return
+        // Scoped to `process` on a decorated handler, same as CQRS-3 - a private mapper in the
+        // same file returning an unrelated object shaped like `{ error: ... }` is not this
+        // handler's refusal path, and a rule that fired anywhere in the file would not be able to
+        // tell the two apart.
+        if (!enclosingProcessMethod(node)) return
+        const klass = enclosingClass(node)
+        if (!klass || !decoratorNames(klass).some((name) => HANDLER_DECORATORS.test(name))) return
+        context.report({ node: node.argument, messageId: "encoded", data: { name: operation, key } })
+      },
+    }
+  },
+}
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "handler-overrides-process": handlerOverridesProcess,
   "message-carries-params-only": messageCarriesParamsOnly,
   "handler-has-twin-spec": handlerHasTwinSpec,
+  "no-handler-encoded-failure": noHandlerEncodedFailure,
 }
 
 /**
  * The level this law asks for, as the plugin's own opinion.
  *
  * MEASURED AGAINST THE REFERENCE REPOSITORY, not estimated: 3 of 141 handlers override `execute`,
- * and 2 of 138 messages carry something other than a single `params`. Debt above zero means the
- * rule lands at `warn` with the count beside it, gets burned down, and flips to `error` at zero -
- * shipping at `error` with debt outstanding blocks every commit that touches an offender.
+ * 2 of 138 messages carry something other than a single `params`, and 2 of 152 handlers return an
+ * encoded failure (`sync-flashcard-quiz-session-progress.handler.ts` and
+ * `sync-mock-interview-session-turns.handler.ts` both `return { success: false }` where a late sync
+ * finds its session already closed). Debt above zero means the rule lands at `warn` with the count
+ * beside it, gets burned down, and flips to `error` at zero - shipping at `error` with debt
+ * outstanding blocks every commit that touches an offender.
  *
  * COUNT ONLY THIS RULE'S REPORTS when measuring. Inline `eslint-disable` comments in the source
  * refer to rules a minimal measuring config never loads, and eslint reports each of those as a
@@ -204,4 +299,5 @@ export const recommended = {
   "starci-be/handler-overrides-process": "error", // no=0 of 141 - burned down from 3
   "starci-be/message-carries-params-only": "error", // no=0 of 138 - burned down from 2
   "starci-be/handler-has-twin-spec": "off", // needs the folder listing as an option; a repo that wires it turns this on
+  "starci-be/no-handler-encoded-failure": "warn", // no=2 of 152 handlers - debt outstanding, burn down before flipping to error
 }