@starci/eslint-canon-be 1.2.0 → 1.2.1

package/package.json

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

package/testing.mjs

@@ -99,7 +99,7 @@ const matcherOf = (expectCall) => {
 // -- TESTING-6 -------------------------------------------------------------------------------------
 
 /** A spec whose every assertion is about a call restates the source instead of testing it. */
-export const noCallOnlySpec = {
+export const noCallOnlySpec = {
   meta: {
     type: "problem",
     docs: { description: "A unit spec asserts a result or a state change, not only that a call happened." },
@@ -131,7 +131,36 @@ export const noCallOnlySpec = {
       },
     }
   },
-}
+}
+
+// -- TESTING-7 -------------------------------------------------------------------------------------
+
+const UNIT_TEST_BUCKET = /\/(?:src\/tests|tests?\/unit)(?:\/|$)/
+
+/** Backend units are colocated `.spec.ts` files; only backend E2E owns a separate tree. */
+export const unitTestColocated = {
+  meta: {
+    type: "problem",
+    docs: { description: "Backend unit tests are colocated `.spec.ts` files; generic `.test.ts` and unit buckets are forbidden." },
+    schema: [],
+    messages: {
+      suffix: "`{{name}}` uses `.test.ts`. A backend unit is a colocated `.spec.ts` file beside its production owner.",
+      bucket: "`{{path}}` files a unit in a separate test bucket. Move it beside its production owner; only backend E2E owns a separate test tree.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    const genericUnit = /\.test\.ts$/.test(file)
+    const bucketedUnit = isUnitSpec(file) && UNIT_TEST_BUCKET.test(file)
+    if (!genericUnit && !bucketedUnit) return {}
+    return {
+      Program(node) {
+        if (genericUnit) context.report({ node, messageId: "suffix", data: { name: file.slice(file.lastIndexOf("/") + 1) } })
+        if (bucketedUnit) context.report({ node, messageId: "bucket", data: { path: file } })
+      },
+    }
+  },
+}
 
 // -- TESTING-2 -------------------------------------------------------------------------------------
 
@@ -410,8 +439,9 @@ export const noMarkerModelStub = {
 }
 
 /** The rules this law contributes to the plugin. */
-export const rules = {
-  "no-call-only-spec": noCallOnlySpec,
+export const rules = {
+  "no-call-only-spec": noCallOnlySpec,
+  "unit-test-colocated": unitTestColocated,
   "e2e-asserts-persisted-state": e2eAssertsPersistedState,
   "no-model-call-in-e2e": noModelCallInE2e,
   "harness-calls-provider-directly": harnessCallsProviderDirectly,
@@ -444,8 +474,9 @@ export const rules = {
  *     `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
+export const recommended = {
+  "starci-be/no-call-only-spec": "error", // no=0 of 182 - burned down from 1
+  "starci-be/unit-test-colocated": "error",
   "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",

package/type-safety.mjs

@@ -1,7 +1,7 @@
 /**
  * The rules that hold `type-safety.md`.
  *
- * Five house rules plus two standard ones, and the split is worth knowing. `no-explicit-any` and
+ * Six house rules plus two standard ones, and the split is worth knowing. `no-explicit-any` and
  * the array-type spelling already exist in the TypeScript plugin and are named in `recommended`
  * rather than reimplemented -- a second implementation of a rule everybody has is a maintenance
  * cost with no gain. Rule 1 (`any` in a declaration, cast target or generic argument) is exactly
@@ -9,11 +9,14 @@
  * this canon exists to prevent, so rule 1 is deliberately not reimplemented here.
  *
  * What is house-written is what the standard set does not cover: the double cast (TYPE-2, rule 3),
- * the inline parameter type (TYPE-3, rule 4), the const enum (TYPE-4, rule 5), the unguarded cast
- * off an `unknown` value (TYPE-1's second half, rule 2), and the per-line suppression standing in
- * for a lane (TYPE-6, rule 7). Each is a way of switching the compiler off -- or of leaving it
- * turned further down than the law asks -- that looks locally reasonable, which is exactly the
- * class a rule is for.
+ * the inline parameter type (TYPE-3, rule 4), the inline object type in every other position --
+ * property, return, variable -- that rule 4 names once it is read without the word "destructured"
+ * (TYPE-3, rule 4, extended; see the export below for its `recommended` level and the measurement
+ * that set it), the const enum
+ * (TYPE-4, rule 5), the unguarded cast off an `unknown` value (TYPE-1's second half, rule 2), and
+ * the per-line suppression standing in for a lane (TYPE-6, rule 7). Each is a way of switching the
+ * compiler off -- or of leaving it turned further down than the law asks -- that looks locally
+ * reasonable, which is exactly the class a rule is for.
  *
  * TYPE-5 (rule 6, the boolean-flag product) is NOT among them, and that absence was tested rather
  * than assumed. See the comment where TYPE-5 would sit, below, for what was tried and why it was
@@ -253,6 +256,115 @@ export const noInlineParamType = {
   },
 }
 
+// -- TYPE-3, extended (law 4) ------------------------------------------------------------------------
+
+/**
+ * `no-inline-param-type` holds only the destructured-parameter half of law 4: "a destructured
+ * parameter's type has a name and a home a second caller can import from." The same sentence, read
+ * without the word "destructured", covers every inline object type -- a positional parameter, a
+ * property signature, a function return, a variable -- because the failure is identical in all four:
+ * the shape cannot be referenced, imported or extended, so a second site retypes it and the two
+ * copies drift apart in silence.
+ *
+ * Three things are deliberately left alone, and each is a different reason:
+ *
+ * - An EMPTY `{}` means "no properties", not "an unnamed shape". That is a different smell (the
+ *   fix is a stricter type, not a name) and this rule does not touch it.
+ * - A type literal inside a `declare module` / module augmentation describes a vendor's own shape.
+ *   It cannot be pulled into a named type this repository owns without the two drifting the moment
+ *   the vendor changes theirs, so the ambient lane is out of scope the same way the test lanes are.
+ * - A type literal that is already the right-hand side of a named type alias (`type Foo = { ... }`)
+ *   IS the fix this rule asks for. Flagging it would make the rule unsatisfiable -- there would be no
+ *   way to hold an object type by name that this rule accepted. A type literal declared elsewhere is
+ *   still checked in the ordinary way; only the exact node a type alias names is exempt.
+ */
+
+/** A type literal with no members means "no properties" -- a different smell with a different fix. */
+const isEmptyTypeLiteral = (typeLiteral) => !typeLiteral.members || typeLiteral.members.length === 0
+
+/** A vendor's own declaration lives in a `declare module` / module augmentation and cannot be named separately. */
+const isInsideAmbientModule = (node) => {
+  let current = node.parent
+  while (current) {
+    if (current.type === "TSModuleDeclaration" && current.declare) return true
+    current = current.parent
+  }
+  return false
+}
+
+/** The non-empty inline object type at `typeAnnotation.typeAnnotation`, or null if this is out of scope. */
+const inlineObjectTypeOf = (typeAnnotation, scopeNode) => {
+  if (!typeAnnotation) return null
+  const literal = typeAnnotation.typeAnnotation
+  if (!literal || literal.type !== "TSTypeLiteral") return null
+  if (isEmptyTypeLiteral(literal)) return null
+  if (isInsideAmbientModule(scopeNode)) return null
+  return literal
+}
+
+export const noInlineObjectType = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "A TypeScript object type written inline takes a named type instead, in every position (TYPE-3, law 4).",
+    },
+    schema: [],
+    messages: {
+      inlineObjectType:
+        "This inline object type ({{position}}) cannot be referenced, imported or extended, so a second site retypes it and the two copies drift apart in silence the moment a third field arrives on only one of them. Give it a name in the module's `types/` and reference that name here instead.",
+    },
+  },
+  create(context) {
+    if (isTestFile(context.filename || context.getFilename())) return {}
+
+    const reportLiteral = (node, position) => {
+      context.report({ node, messageId: "inlineObjectType", data: { position } })
+    }
+
+    const checkParams = (fnNode) => {
+      for (const raw of fnNode.params || []) {
+        const param = unwrapParam(raw)
+        if (inlineObjectTypeOf(param.typeAnnotation, param)) {
+          reportLiteral(param.typeAnnotation, "parameter")
+        }
+      }
+    }
+
+    const checkReturnType = (fnNode) => {
+      if (inlineObjectTypeOf(fnNode.returnType, fnNode)) {
+        reportLiteral(fnNode.returnType, "return type")
+      }
+    }
+
+    return {
+      FunctionDeclaration(node) {
+        checkParams(node)
+        checkReturnType(node)
+      },
+      FunctionExpression(node) {
+        checkParams(node)
+        checkReturnType(node)
+      },
+      ArrowFunctionExpression(node) {
+        checkParams(node)
+        checkReturnType(node)
+      },
+      TSPropertySignature(node) {
+        if (inlineObjectTypeOf(node.typeAnnotation, node)) {
+          reportLiteral(node.typeAnnotation, "property signature")
+        }
+      },
+      VariableDeclarator(node) {
+        if (node.id.type !== "Identifier") return
+        if (inlineObjectTypeOf(node.id.typeAnnotation, node)) {
+          reportLiteral(node.id.typeAnnotation, "variable")
+        }
+      },
+    }
+  },
+}
+
 // -- TYPE-4 ----------------------------------------------------------------------------------------
 
 /** An enum keeps its runtime object. */
@@ -297,6 +409,7 @@ export const noConstEnum = {
 const TYPE_SAFETY_RULE_NAMES = [
   "no-double-cast",
   "no-inline-param-type",
+  "no-inline-object-type",
   "no-const-enum",
   "no-unguarded-unknown-cast",
 ]
@@ -350,6 +463,7 @@ export const noLineSuppression = {
 export const rules = {
   "no-double-cast": noDoubleCast,
   "no-inline-param-type": noInlineParamType,
+  "no-inline-object-type": noInlineObjectType,
   "no-const-enum": noConstEnum,
   "no-unguarded-unknown-cast": noUnguardedUnknownCast,
   "no-line-suppression": noLineSuppression,
@@ -365,10 +479,27 @@ export const rules = {
  * The test exit for `no-double-cast` is inside the rule rather than in a config glob, because
  * building a deliberately wrong value is how a spec proves a closed API refuses it, and that is a
  * property of the lane rather than of any repository's file layout.
+ *
+ * `no-inline-object-type` was published at `"off"`, not `"error"` or `"warn"` like its siblings, until
+ * it was measured against the reference backend. The gate this package ships (`index.test.mjs`)
+ * requires every published rule to carry a level, so `"off"` -- not absence -- was how the rule stayed
+ * registered and switched-off at once: present for a consuming repository to opt into deliberately,
+ * silent until the owner had the debt count in hand.
+ *
+ * That measurement is done: an ESLint Linter-API run, per file, across every file the reference
+ * backend's own `eslint.config.mjs` lints (`src/**`, `apps/**`, `libs/**`, `test/**`, `tests/**` --
+ * 4,738 files at measurement time) found zero remaining product-code fires once the three real
+ * ones (two in `apps/mock/src/main.ts`, one in `apps/playground-rag-agent/src/rag-agent.service.ts`,
+ * plus a fourth the same sweep turned up in `src/modules/ai/utils/extract-json-block.ts` that an
+ * earlier pass had missed) were each given a named type. The rule's own test-file exemption held
+ * throughout: every other hit was inside `*.spec.ts`. Zero debt is exactly the condition this
+ * canon's own convention requires before a rule moves from `off` to `error` -- the same standard
+ * `no-unguarded-unknown-cast` is still waiting to clear before its own `warn` becomes `error`.
  */
 export const recommended = {
   "starci-be/no-double-cast": "error",
   "starci-be/no-inline-param-type": "error",
+  "starci-be/no-inline-object-type": "error",
   "starci-be/no-const-enum": "error",
   "starci-be/no-unguarded-unknown-cast": "warn", // no=3 -- see type-safety.mjs's doc comment
   "starci-be/no-line-suppression": "error",