@starci/eslint-canon-be 1.1.0 → 1.2.0

package/testing.mjs

@@ -10,6 +10,34 @@
  * whose every assertion is about a call rather than a result, and an end-to-end spec that never
  * reads any state back. Both were measured before being written: eight specs and one e2e file in
  * the source repository, which is why the second lands with a carve-out rather than at zero.
+ *
+ * Two more codes turned out to have a genuinely mechanical HALF, added later and kept narrow on
+ * purpose:
+ *
+ *   - TESTING-1. A filename cannot be checked against a business sentence - but the anti-pattern
+ *     the law names by example (`rewards-queries.e2e-spec.ts`) IS a closed, denylisted shape: a
+ *     filename whose last segment is an API noun rather than a business one. The rule refuses only
+ *     that shape; it does not claim to certify a good name, and it is the same requirement E2E-1 in
+ *     `e2e-flow.md` states on the same file, so one rule holds both codes rather than reporting the
+ *     same file twice under two names.
+ *   - TESTING-7. "A stub of a model returns a payload the production parser can actually parse" -
+ *     the rule cannot verify the payload parses, but it CAN refuse the one shape the law names by
+ *     example: a bare marker string (`"stubbed"`, `"ok"`, `"test"`) standing in for the whole
+ *     answer. An object literal, or a `JSON.stringify(...)` call, is out of the rule's reach on
+ *     purpose - that is where a false positive would start.
+ *
+ * TESTING-5 / TESTING-8 ("a configured lane either holds tests or does not exist") was drafted as a
+ * filesystem-reading rule and then WITHDRAWN. It reads correctly as JS to `@typescript-eslint/parser`
+ * (`{"rootDir": "..."}` parses as an `ExpressionStatement` over an `ObjectExpression` under this
+ * parser, no wrapping needed) and its own file-scoped RuleTester cases passed. It is left out anyway,
+ * because the question it would answer is not "does this repository's config have this shape" but
+ * "does the CONSUMING repository's `eslint.config.mjs` even point a linter at this file at all" - and
+ * in the measured reference repository it does not: `files` there is five TypeScript globs under
+ * `src`, `apps`, `libs`, `test` and `tests` - none of them `.json` - so `jest-e2e.json` and
+ * `jest-harness.json` sit outside every one of them. A rule that cannot be reached by the config
+ * that would run it is not a `warn`-with-a-count away from correct; it is dead code reporting a "0"
+ * that means "never asked", not "already true" - the one measurement this family refuses to publish
+ * as if it were the other.
  */
 
 /** Forward-slash form of a filename, so Windows paths compare like every other path. */
@@ -277,12 +305,118 @@ export const harnessCallsProviderDirectly = {
   },
 }
 
+// -- TESTING-1 (and E2E-1 in e2e-flow.md, the same requirement on the same file) -------------------
+
+/** Nouns that name an API shape rather than a business promise. `rewards-queries` is the anchor. */
+const API_SHAPED_FILENAME_NOUNS = new Set([
+  "queries", "query", "mutations", "mutation",
+  "resolvers", "resolver", "endpoints", "endpoint",
+  "controllers", "controller", "handlers", "handler",
+  "modules", "module", "apis", "api",
+])
+
+/** The hyphen-separated words of an e2e filename, with the lane suffix stripped. */
+const e2eFilenameSegments = (filename) => {
+  const base = normalizePath(filename).split("/").pop() || ""
+  return base.replace(/\.e2e-spec\.ts$/, "").split("-").filter(Boolean)
+}
+
+/** An e2e file is one business flow; the filename may not be an API-shape noun wearing its clothes. */
+export const noApiShapedE2eFilename = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "An e2e filename reads as a business sentence (TESTING-1; E2E-1 in e2e-flow.md), not a resolver/endpoint/module group.",
+    },
+    schema: [],
+    messages: {
+      apiShaped:
+        "`{{segment}}` names an API shape - a resolver group, an endpoint, a module - not a business promise. TESTING-1 / E2E-1: one e2e file is one business flow and the filename IS that flow; `rewards-queries.e2e-spec.ts` is exactly the shape this refuses. Name the file for the sentence it proves (`course-purchase.e2e-spec.ts`), not the API surface it happens to hit.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (!isE2eSpec(filename)) return {}
+    const segments = e2eFilenameSegments(filename)
+    if (segments.length === 0) return {}
+    const last = segments[segments.length - 1].toLowerCase()
+    if (!API_SHAPED_FILENAME_NOUNS.has(last)) return {}
+    return {
+      Program(node) {
+        context.report({ node, messageId: "apiShaped", data: { segment: last } })
+      },
+    }
+  },
+}
+
+// -- TESTING-7 -------------------------------------------------------------------------------------
+
+/** Test-infra helpers, where the shared model stub this code governs actually lives. */
+const isTestHelperFile = (filename) => /\/tests\/helpers\//.test(normalizePath(filename))
+
+/** Bare markers a stub returns when nobody gave it a real answer to stand in for. */
+const MARKER_STRINGS = new Set(["stubbed", "stub", "ok", "test", "mock", "fake", "todo", "tbd", "n/a", "pending", ""])
+
+/** A string literal that is nothing but a marker - not an object, not a `JSON.stringify(...)` call. */
+const isMarkerLiteral = (node) => Boolean(
+  node && node.type === "Literal" && typeof node.value === "string" && MARKER_STRINGS.has(node.value.trim().toLowerCase()),
+)
+
+/** The world's default model stub returns a payload the production parser can actually parse. */
+export const noMarkerModelStub = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "A model stub in test infra returns a parseable payload (TESTING-7), never a bare marker string.",
+    },
+    schema: [],
+    messages: {
+      marker:
+        "This stub resolves to `{{value}}`, a marker rather than an answer. TESTING-7: a stub of a model returns a payload the production parser can actually parse - a marker string means the strict-JSON parser the real flow depends on never runs, so the most fragile seam in the flow is never exercised. Return the shape the production parser expects (an object, or a `JSON.stringify(...)` of one), the way `DEFAULT_MODEL_ANSWER` does.",
+    },
+  },
+  create(context) {
+    if (!isTestHelperFile(context.filename || context.getFilename())) return {}
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (!callee || callee.type !== "MemberExpression" || callee.computed) return
+        const method = callee.property.name
+        if (method === "mockResolvedValue" || method === "mockReturnValue") {
+          const argument = node.arguments[0]
+          if (isMarkerLiteral(argument)) {
+            context.report({ node: argument, messageId: "marker", data: { value: JSON.stringify(argument.value) } })
+          }
+          return
+        }
+        if (method !== "mockImplementation") return
+        const fn = node.arguments[0]
+        if (!fn || (fn.type !== "ArrowFunctionExpression" && fn.type !== "FunctionExpression")) return
+        if (fn.body.type !== "BlockStatement") {
+          if (isMarkerLiteral(fn.body)) {
+            context.report({ node: fn.body, messageId: "marker", data: { value: JSON.stringify(fn.body.value) } })
+          }
+          return
+        }
+        for (const statement of fn.body.body) {
+          if (statement.type === "ReturnStatement" && isMarkerLiteral(statement.argument)) {
+            context.report({ node: statement.argument, messageId: "marker", data: { value: JSON.stringify(statement.argument.value) } })
+          }
+        }
+      },
+    }
+  },
+}
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "no-call-only-spec": noCallOnlySpec,
   "e2e-asserts-persisted-state": e2eAssertsPersistedState,
   "no-model-call-in-e2e": noModelCallInE2e,
   "harness-calls-provider-directly": harnessCallsProviderDirectly,
+  "no-api-shaped-e2e-filename": noApiShapedE2eFilename,
+  "no-marker-model-stub": noMarkerModelStub,
 }
 
 /**
@@ -298,10 +432,23 @@ export const rules = {
  * config never loaded. Count only the reports carrying this rule's own id.
  *
  * Both land at `warn` with the count, get burned down, and flip to `error` at zero.
+ *
+ * The two later rules were measured the same way, against the same repository:
+ *
+ *   - `no-api-shaped-e2e-filename` found TWO of 77 - `installment-plan-queries.e2e-spec.ts` and
+ *     `rewards-queries.e2e-spec.ts`, the exact anchor example the law names. Real, pre-existing debt
+ *     this task does not fix, so it lands at `warn` rather than claiming a burn-down that has not
+ *     happened.
+ *   - `no-marker-model-stub` found ZERO of the world's own stub in `tests/helpers/flow-world.ts`:
+ *     the default answer is `JSON.stringify({ answer: "..." })`, which is a `CallExpression`, not a
+ *     `Literal`, so the rule does not even see it as a candidate. It ships at `error` as a
+ *     regression guard on a shape that is already correct.
  */
 export const recommended = {
   "starci-be/no-call-only-spec": "error", // no=0 of 182 - burned down from 1
   "starci-be/e2e-asserts-persisted-state": "error", // no=0 of 47 - burned down from 1
   "starci-be/no-model-call-in-e2e": "error", // no=0 of 47
   "starci-be/harness-calls-provider-directly": "error",
+  "starci-be/no-api-shaped-e2e-filename": "warn", // no=2 of 77 - pre-existing, not burned down here
+  "starci-be/no-marker-model-stub": "error", // no=0 - the world's stub already returns JSON.stringify(...)
 }

package/transport.mjs

@@ -1,103 +1,168 @@
-const normalize = (filename) => String(filename || "").replace(/\\/g, "/")
-
-/** The decorator's own name, whether it was written `@Controller` or `@Controller("x")`. */
-const decoratorName = (node) => {
-  const expression = node.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
-}
-
-/** The route string, or "" for `@Controller()` and for a path given as an object. */
-const routeOf = (node) => {
-  const expression = node.expression
-  if (!expression || expression.type !== "CallExpression") return ""
-  const first = expression.arguments[0]
-  if (first && first.type === "Literal" && typeof first.value === "string") return first.value
-  return ""
-}
-
-/**
- * Which of the four sanctioned reasons this file shows, if any.
- *
- * READ OFF THE FILE, NOT OFF A LIST. A registry of blessed routes rots the moment somebody adds a
- * route and forgets it; the evidence here is the same evidence a reader would use.
- */
-const reasonFor = (route, filename, text) => {
-  const path = normalize(filename)
-  // a probe answers when the app is degraded, before the feature layer is necessarily up
-  if (/^healthz?$/.test(route) || /\/health(z)?[./]/.test(path)) return "probe"
-  // something outside posts to a URL we gave it, and it will never send a GraphQL document
-  if (/webhook/i.test(route) || /webhook/i.test(path)) return "external"
-  // bytes, not fields: multipart in, stream out
-  if (/FileInterceptor|FilesInterceptor|AnyFilesInterceptor|StreamableFile|@Res\s*\(|createReadStream/.test(text)) {
-    return "bytes"
-  }
-  // a machine registering itself, with no user session to carry
-  if (/^(pods|internal|agents)\//.test(route)) return "machine"
-  // an identity that is not a user session - a platform operator or a service token
-  if (/^api\/ops(\/|$)/.test(route) || /Operator[A-Za-z]*Guard|ServiceToken|OPS_TOKEN/.test(text)) {
-    return "operator"
-  }
-  return null
-}
-
-/** A REST door exists only where GraphQL cannot go, and the file has to show which case it is. */
-export const restDoorNeedsAReason = {
-  meta: {
-    type: "problem",
-    docs: { description: "A @Controller is permitted only where GraphQL cannot serve." },
-    schema: [],
-    messages: {
-      unjustified:
-        "This REST door shows none of the four reasons a door may not be GraphQL: an external system posting to a fixed URL, a payload of bytes rather than fields, a machine with no user session, or an identity that is not one. A plain JSON read belongs in the GraphQL schema, where the client already is.",
-    },
-  },
-  create(context) {
-    const filename = context.filename || context.getFilename()
-    const text = (context.sourceCode || context.getSourceCode()).getText()
-    return {
-      Decorator(node) {
-        if (decoratorName(node) !== "Controller") return
-        if (reasonFor(routeOf(node), filename, text)) return
-        context.report({ node, messageId: "unjustified" })
-      },
-    }
-  },
-}
-
-/** A door is a door whatever its transport, and every door in this repository lives in features/. */
-export const doorLivesInFeatures = {
-  meta: {
-    type: "problem",
-    docs: { description: "HTTP doors sit under features/, beside the GraphQL ones." },
-    schema: [],
-    messages: {
-      wrongTree:
-        "A @Controller under src/modules/ is a door parked among the capabilities it calls, where it reads as one and gets imported like one. Every GraphQL door in this repository already lives under features/; transport was never what decided the address.",
-    },
-  },
-  create(context) {
-    const path = normalize(context.filename || context.getFilename())
-    if (!/\/src\/modules\//.test(path)) return {}
-    return {
-      Decorator(node) {
-        if (decoratorName(node) !== "Controller") return
-        context.report({ node, messageId: "wrongTree" })
-      },
-    }
-  },
-}
-
-export const rules = {
-  "rest-door-needs-a-reason": restDoorNeedsAReason,
-  "door-lives-in-features": doorLivesInFeatures,
-}
-
-export const recommended = {
-  "starci-be/rest-door-needs-a-reason": "error",
-  "starci-be/door-lives-in-features": "error",
-}
+const normalize = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** The decorator's own name, whether it was written `@Controller` or `@Controller("x")`. */
+const decoratorName = (node) => {
+  const expression = node.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
+}
+
+/** The route string, or "" for `@Controller()` and for a path given as an object. */
+const routeOf = (node) => {
+  const expression = node.expression
+  if (!expression || expression.type !== "CallExpression") return ""
+  const first = expression.arguments[0]
+  if (first && first.type === "Literal" && typeof first.value === "string") return first.value
+  return ""
+}
+
+/**
+ * Which of the four sanctioned reasons this file shows, if any.
+ *
+ * READ OFF THE FILE, NOT OFF A LIST. A registry of blessed routes rots the moment somebody adds a
+ * route and forgets it; the evidence here is the same evidence a reader would use.
+ */
+const reasonFor = (route, filename, text) => {
+  const path = normalize(filename)
+  // a probe answers when the app is degraded, before the feature layer is necessarily up
+  if (/^healthz?$/.test(route) || /\/health(z)?[./]/.test(path)) return "probe"
+  // something outside posts to a URL we gave it, and it will never send a GraphQL document
+  if (/webhook/i.test(route) || /webhook/i.test(path)) return "external"
+  // bytes, not fields: multipart in, stream out
+  if (/FileInterceptor|FilesInterceptor|AnyFilesInterceptor|StreamableFile|@Res\s*\(|createReadStream/.test(text)) {
+    return "bytes"
+  }
+  // a machine registering itself, with no user session to carry
+  if (/^(pods|internal|agents)\//.test(route)) return "machine"
+  // an identity that is not a user session - a platform operator or a service token
+  if (/^api\/ops(\/|$)/.test(route) || /Operator[A-Za-z]*Guard|ServiceToken|OPS_TOKEN/.test(text)) {
+    return "operator"
+  }
+  return null
+}
+
+/** A REST door exists only where GraphQL cannot go, and the file has to show which case it is. */
+export const restDoorNeedsAReason = {
+  meta: {
+    type: "problem",
+    docs: { description: "A @Controller is permitted only where GraphQL cannot serve." },
+    schema: [],
+    messages: {
+      unjustified:
+        "This REST door shows none of the four reasons a door may not be GraphQL: an external system posting to a fixed URL, a payload of bytes rather than fields, a machine with no user session, or an identity that is not one. A plain JSON read belongs in the GraphQL schema, where the client already is.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const text = (context.sourceCode || context.getSourceCode()).getText()
+    return {
+      Decorator(node) {
+        if (decoratorName(node) !== "Controller") return
+        if (reasonFor(routeOf(node), filename, text)) return
+        context.report({ node, messageId: "unjustified" })
+      },
+    }
+  },
+}
+
+/** A door is a door whatever its transport, and every door in this repository lives in features/. */
+export const doorLivesInFeatures = {
+  meta: {
+    type: "problem",
+    docs: { description: "HTTP doors sit under features/, beside the GraphQL ones." },
+    schema: [],
+    messages: {
+      wrongTree:
+        "A @Controller under src/modules/ is a door parked among the capabilities it calls, where it reads as one and gets imported like one. Every GraphQL door in this repository already lives under features/; transport was never what decided the address.",
+    },
+  },
+  create(context) {
+    const path = normalize(context.filename || context.getFilename())
+    if (!/\/src\/modules\//.test(path)) return {}
+    return {
+      Decorator(node) {
+        if (decoratorName(node) !== "Controller") return
+        context.report({ node, messageId: "wrongTree" })
+      },
+    }
+  },
+}
+
+/** An import specifier's alias prefix for a door. */
+const FEATURES_ALIAS = "@features/"
+
+/** A relative or deep specifier climbing into `features/`, once the alias form is ruled out. */
+const FEATURES_SEGMENT = /(^|\/)features\//
+
+/** Whether an import specifier reaches into `features/`, by alias or by path. */
+const reachesFeatures = (specifier) => {
+  if (typeof specifier !== "string") return false
+  if (specifier.startsWith(FEATURES_ALIAS)) return true
+  return FEATURES_SEGMENT.test(specifier)
+}
+
+/**
+ * Rule 6: "A capability stays under `modules/` and is called by a door, never reached directly."
+ * A door under `features/` importing a capability under `modules/` is the entire shape TRANSPORT-3
+ * sets up, and this rule is not that edge - it fires only the other way: a file living under
+ * `modules/` reaching back into `features/`. That reversal makes the capability the caller and the
+ * door the thing being reached, which is backwards from what a capability is - it is CALLED, and it
+ * stays ignorant of who calls it. One capability importing another capability under `modules/` is
+ * untouched here; this rule polices one edge, not the whole graph.
+ */
+export const noCapabilityImportsFeatures = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "TRANSPORT Rule 6: a capability under modules/ never imports from features/ - a door calls into a capability, never the other way round.",
+    },
+    schema: [],
+    messages: {
+      reversed:
+        "`{{specifier}}` reaches from a capability under modules/ into features/, where doors live. A capability is CALLED by a door and stays ignorant of who calls it; importing back into features/ makes the capability the caller, which is the exact edge this law forbids. Move the shared code under modules/, or invert the call so the door reaches in.",
+    },
+  },
+  create(context) {
+    const path = normalize(context.filename || context.getFilename())
+    if (!/\/src\/modules\//.test(path)) return {}
+    const check = (node, specifier) => {
+      if (reachesFeatures(specifier)) context.report({ node, messageId: "reversed", data: { specifier } })
+    }
+    return {
+      ImportDeclaration(node) {
+        check(node.source, node.source.value)
+      },
+      ExportNamedDeclaration(node) {
+        if (node.source) check(node.source, node.source.value)
+      },
+      ExportAllDeclaration(node) {
+        if (node.source) check(node.source, node.source.value)
+      },
+    }
+  },
+}
+
+export const rules = {
+  "rest-door-needs-a-reason": restDoorNeedsAReason,
+  "door-lives-in-features": doorLivesInFeatures,
+  "no-capability-imports-features": noCapabilityImportsFeatures,
+}
+
+/**
+ * `no-capability-imports-features` measures at 9 offenders across 6 files in the reference
+ * repository (`src/**`, probed against source directly since the published package predates this
+ * rule) -- every one a capability under `modules/bussiness/**` importing a single shared helper
+ * published under `@features/api/processors/ai/shared/xp/write-coin-history`. That is standing debt,
+ * not zero, so it ships at `warn` with the count on record, matching this module's own Exceptions
+ * section: measured debt arrives at `warn` and flips to `error` once it reaches zero.
+ */
+export const recommended = {
+  "starci-be/rest-door-needs-a-reason": "error",
+  "starci-be/door-lives-in-features": "error",
+  "starci-be/no-capability-imports-features": "warn",
+}