@starci/eslint-canon-be 1.8.0 → 2.0.0

package/type-safety.mjs

@@ -1,222 +1,26 @@
 /**
- * The rules that hold `type-safety.md`.
+ * The rules that hold the type-safety law (catalog R72 `BE_TYPE_ESCAPE` and the type-shape rows).
  *
- * 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
- * that rule; a house-written twin of `no-explicit-any` would be the two-homes-for-one-law failure
- * this canon exists to prevent, so rule 1 is deliberately not reimplemented here.
+ * WHAT THE FACTORY BORROWS, SO THIS FILE DOES NOT REIMPLEMENT IT. `starciBeConfig` turns on, at `error`, in every file
+ * of the repository and with no lane of exemption (a spec, a fixture and an e2e setup file get the same law):
+ * `@typescript-eslint/consistent-type-assertions` with `assertionStyle: "never"` (no `x as T`, no `<T>x`, hence no
+ * `as never`, no `as unknown as T`, no cast out of an `unknown` value; only `as const` stays),
+ * `@typescript-eslint/no-non-null-assertion` (no `x!`) and `@typescript-eslint/no-explicit-any`. One obligation, one
+ * rule: this canon writes no second copy of any of them, so the four house rules that once restated them
+ * (`no-never-cast`, `no-non-null-assertion`, `no-double-cast`, `no-unguarded-unknown-cast`) are deleted.
  *
- * 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 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
- * 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.
+ * What is house-written is what the borrowed set does not cover: `Function` as a type and `eval` (R72), the inline
+ * parameter type and the inline object type in every other position (TYPE-3), the const enum (TYPE-4) and the
+ * handler return type (R75).
  *
- * 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
- * withdrawn after being measured against the reference backend.
+ * TYPE-5 (the boolean-flag product) is NOT among them, and that absence was tested rather than assumed: a rule was
+ * written, measured against the reference backend and withdrawn because both of its real firings were wrong. It stays
+ * a reader's job, exactly as the law's own `Layer held` table says.
  */
 
-import { normalizePath } from "./lib/path.mjs"
-
-/** The spec family and the test tree may build a deliberately wrong value on purpose. */
-const isTestFile = (filename) => {
-  const file = normalizePath(filename)
-  return /\.(?:spec|test|e2e-spec)\.ts$/.test(file) || file.includes("/src/tests/")
-}
-
 /** A parameter property (`private readonly x: T`) wraps the parameter it declares. */
 const unwrapParam = (param) => (param.type === "TSParameterProperty" ? param.parameter : param)
 
-// -- TYPE-2 ----------------------------------------------------------------------------------------
-
-/** A cast through `unknown` is the compiler being overruled twice. */
-export const noDoubleCast = {
-  meta: {
-    type: "problem",
-    docs: { description: "No `x as unknown as T` outside the test lanes." },
-    schema: [],
-    messages: {
-      doubleCast:
-        "`as unknown as` is the compiler saying these types do not overlap, and being overruled twice. It is worse than `any` in one specific way: the result CLAIMS to be the target type, so everything downstream trusts it completely and the failure surfaces far from this line. Fix the type, or narrow with a guard that actually checks.",
-    },
-  },
-  create(context) {
-    if (isTestFile(context.filename || context.getFilename())) return {}
-    return {
-      TSAsExpression(node) {
-        // the OUTER cast of the pair: its operand is itself a cast, to `unknown`
-        const inner = node.expression
-        if (!inner || inner.type !== "TSAsExpression") return
-        const innerType = inner.typeAnnotation
-        if (!innerType || innerType.type !== "TSUnknownKeyword") return
-        context.report({ node, messageId: "doubleCast" })
-      },
-    }
-  },
-}
-
-// -- TYPE-1, second half (rule 2) -------------------------------------------------------------------
-
-/** typeof/instanceof/in/null-equality/Array.isArray are the sanctioned ways to narrow an `unknown`. */
-const isNullOrUndefinedLiteral = (node) =>
-  (node.type === "Literal" && node.value === null) || (node.type === "Identifier" && node.name === "undefined")
-
-/** The nearest enclosing function, so narrowing found in one function never covers another. */
-const enclosingFunction = (node) => {
-  let current = node.parent
-  while (current) {
-    if (
-      current.type === "FunctionDeclaration"
-      || current.type === "FunctionExpression"
-      || current.type === "ArrowFunctionExpression"
-    ) {
-      return current
-    }
-    current = current.parent
-  }
-  return null
-}
-
-/** Whether a parameter or variable is explicitly declared `: unknown` at the point it enters. */
-const isUnknownAnnotation = (typeAnnotation) =>
-  !!typeAnnotation && !!typeAnnotation.typeAnnotation && typeAnnotation.typeAnnotation.type === "TSUnknownKeyword"
-
-/**
- * A value declared `unknown` is cast straight to a concrete type with no visible check first.
- *
- * `unknown` refuses every operation until narrowed -- except a cast, which TypeScript allows
- * FREELY from `unknown` to anything, no guard required. `no-double-cast` catches the pair that
- * launders a wrong type through `unknown`; it does not catch a single cast that starts already
- * `unknown` and asserts straight past the type system with nothing behind it. That gap is TYPE-1's
- * second half: the law asks for "unknown, narrowed exactly once, visibly", and a bare cast narrows
- * nothing -- it only claims to.
- *
- * Scoped to identifiers explicitly annotated `unknown` (a parameter or a `const x: unknown`), and
- * to narrowing found anywhere earlier in the SAME enclosing function -- not a full control-flow
- * proof, because this plugin carries no type information to build one. The forms it accepts as
- * narrowing are `typeof`, `instanceof`, `in`, a null/undefined equality check, and -- deliberately
- * loose -- passing the value into ANY function call, because the law names "a predicate" beside
- * `typeof`/`instanceof` and a custom guard is exactly that predicate; this rule cannot read what
- * is inside the call, so it trusts that a call taking the value is a check on it. That looseness
- * trades missed gaps for avoided false positives on purpose. The test lanes are exempt for the
- * same reason `no-double-cast` exempts them: a harness helper that hands a caller-supplied
- * generic type back unchecked (`nextMessage<TPayload>`) is deliberate, not a gap. Measured against
- * the reference backend, this rule still stays at `warn` -- the debt is real and small enough to
- * burn down, not yet zero.
- */
-export const noUnguardedUnknownCast = {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "A value declared `unknown` is narrowed by a visible check before it is cast to a concrete type (TYPE-1, law 2).",
-    },
-    schema: [],
-    messages: {
-      unguarded:
-        "`{{name}}` entered as `unknown` and is cast straight to `{{target}}` with no `typeof`, `instanceof`, `in` or null check on `{{name}}` anywhere earlier in this function. A cast out of `unknown` is unrestricted by design -- TypeScript will not stop you -- so the check has to be the thing that stops you. Add one before the cast: `typeof {{name}} === \"...\"`, `{{name}} instanceof ...`, or `{{name}} !== null`.",
-    },
-  },
-  create(context) {
-    // the harness lane builds generic pass-through helpers on purpose (`nextMessage<TPayload>`
-    // handing back whatever the event bus produced as the caller's declared type) -- the same
-    // "deliberately unchecked on purpose" property TYPE-2 already carves the test lanes out for
-    if (isTestFile(context.filename || context.getFilename())) return {}
-    const sourceCode = context.sourceCode || context.getSourceCode()
-    const trackedByScope = new Map()
-    const narrowedByScope = new Map()
-    const scopeKey = (node) => enclosingFunction(node) || "module"
-
-    const track = (name, scope) => {
-      if (!trackedByScope.has(scope)) trackedByScope.set(scope, new Set())
-      trackedByScope.get(scope).add(name)
-    }
-    const markNarrowed = (name, scope) => {
-      if (!narrowedByScope.has(scope)) narrowedByScope.set(scope, new Set())
-      narrowedByScope.get(scope).add(name)
-    }
-
-    const checkParams = (fnNode) => {
-      for (const raw of fnNode.params) {
-        const param = unwrapParam(raw)
-        if (param.type === "Identifier" && isUnknownAnnotation(param.typeAnnotation)) {
-          track(param.name, fnNode)
-        }
-      }
-    }
-
-    return {
-      FunctionDeclaration(node) {
-        checkParams(node)
-      },
-      FunctionExpression(node) {
-        checkParams(node)
-      },
-      ArrowFunctionExpression(node) {
-        checkParams(node)
-      },
-      VariableDeclarator(node) {
-        if (node.id.type === "Identifier" && isUnknownAnnotation(node.id.typeAnnotation)) {
-          track(node.id.name, scopeKey(node))
-        }
-      },
-      UnaryExpression(node) {
-        if (node.operator !== "typeof") return
-        if (node.argument.type !== "Identifier") return
-        markNarrowed(node.argument.name, scopeKey(node))
-      },
-      BinaryExpression(node) {
-        if (node.operator === "instanceof") {
-          if (node.left.type === "Identifier") markNarrowed(node.left.name, scopeKey(node))
-          return
-        }
-        if (node.operator === "in") {
-          if (node.right.type === "Identifier") markNarrowed(node.right.name, scopeKey(node))
-          return
-        }
-        if (!["===", "!==", "==", "!="].includes(node.operator)) return
-        if (node.left.type === "Identifier" && isNullOrUndefinedLiteral(node.right)) {
-          markNarrowed(node.left.name, scopeKey(node))
-        }
-        if (node.right.type === "Identifier" && isNullOrUndefinedLiteral(node.left)) {
-          markNarrowed(node.right.name, scopeKey(node))
-        }
-      },
-      CallExpression(node) {
-        // any predicate call that TAKES the value narrows it, the same way `typeof` does -- the
-        // law names "a predicate" beside `typeof`/`instanceof` on purpose, and a custom guard
-        // (`this.isPlainObject(current)`, `Array.isArray(value)`) is exactly that predicate. This
-        // side is deliberately loose: the cost of missing a real gap here is smaller than the cost
-        // of flagging a guard this rule cannot read the inside of.
-        for (const arg of node.arguments) {
-          if (arg.type === "Identifier") markNarrowed(arg.name, scopeKey(node))
-        }
-      },
-      TSAsExpression(node) {
-        if (node.expression.type !== "Identifier") return
-        const name = node.expression.name
-        const scope = scopeKey(node)
-        if (!trackedByScope.get(scope) || !trackedByScope.get(scope).has(name)) return
-        const target = node.typeAnnotation
-        if (target && target.type === "TSUnknownKeyword") return
-        if (narrowedByScope.get(scope) && narrowedByScope.get(scope).has(name)) return
-        context.report({
-          node,
-          messageId: "unguarded",
-          data: { name, target: sourceCode.getText(target) },
-        })
-      },
-    }
-  },
-}
-
 // -- TYPE-3 ----------------------------------------------------------------------------------------
 
 /** A destructured parameter's type is named, so a second caller can reference it. */
@@ -271,7 +75,7 @@ export const noInlineParamType = {
  *   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.
+ *   the vendor changes theirs, so the ambient lane is out of scope.
  * - 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
@@ -315,8 +119,6 @@ export const noInlineObjectType = {
     },
   },
   create(context) {
-    if (isTestFile(context.filename || context.getFilename())) return {}
-
     const reportLiteral = (node, position) => {
       context.report({ node, messageId: "inlineObjectType", data: { position } })
     }
@@ -389,43 +191,46 @@ export const noConstEnum = {
 
 // -- R72 -------------------------------------------------------------------------------------------
 
-/** `as never` asserts that a value is of no type at all, which satisfies every parameter and checks nothing. */
-export const noNeverCast = {
-  meta: {
-    type: "problem",
-    docs: { description: "No `x as never` outside the test lanes." },
-    schema: [],
-    messages: {
-      neverCast:
-        "`as never` makes this value assignable to anything, so the compiler stops checking the call it is passed to. It hides a real mismatch between the value and the parameter. Give the value the type the parameter wants, narrow it with a guard, or fix the signature.",
-    },
-  },
-  create(context) {
-    if (isTestFile(context.filename || context.getFilename())) return {}
-    return {
-      TSAsExpression(node) {
-        if (node.typeAnnotation?.type === "TSNeverKeyword") context.report({ node, messageId: "neverCast" })
-      },
-    }
-  },
+/** A global name (`Function`, `eval`) that no declaration of this file shadows. */
+const isGlobalName = (context, node, name) => {
+  let scope = (context.sourceCode || context.getSourceCode()).getScope(node)
+  while (scope) {
+    const variable = scope.set.get(name)
+    if (variable) return variable.defs.length === 0
+    scope = scope.upper
+  }
+  return true
 }
 
-/** `x!` claims a value is present without checking. */
-export const noNonNullAssertion = {
+/** `Function` as a type, `eval` and `new Function` run or accept code the compiler cannot see. */
+export const noFunctionOrEval = {
   meta: {
     type: "problem",
-    docs: { description: "No non-null assertion (`x!`) outside the test lanes." },
+    docs: { description: "No `Function` type, no `eval`, no `new Function` (the type escapes the borrowed assertion rules do not cover)." },
     schema: [],
     messages: {
-      nonNull:
-        "`!` claims this value is present and checks nothing; when it is not, the failure is a `TypeError` far from here. Narrow with a check that returns or throws a typed error, or change the type so absence is impossible.",
+      functionType:
+        "The `Function` type accepts any callable and returns `any`, so the compiler stops checking every call through it. Write the signature: `(input: Input) => Result`.",
+      evaluated:
+        "`{{name}}` builds code from a string, which the compiler cannot type and a reader cannot follow. Call a real function, or map a key to a function in a typed record.",
     },
   },
   create(context) {
-    if (isTestFile(context.filename || context.getFilename())) return {}
     return {
-      TSNonNullExpression(node) {
-        context.report({ node, messageId: "nonNull" })
+      TSTypeReference(node) {
+        if (node.typeName.type === "Identifier" && node.typeName.name === "Function" && isGlobalName(context, node, "Function")) {
+          context.report({ node, messageId: "functionType" })
+        }
+      },
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== "Identifier" || (callee.name !== "eval" && callee.name !== "Function")) return
+        if (isGlobalName(context, node, callee.name)) context.report({ node, messageId: "evaluated", data: { name: callee.name } })
+      },
+      NewExpression(node) {
+        if (node.callee.type === "Identifier" && node.callee.name === "Function" && isGlobalName(context, node, "Function")) {
+          context.report({ node, messageId: "evaluated", data: { name: "new Function" } })
+        }
       },
     }
   },
@@ -458,7 +263,6 @@ export const explicitHandlerReturnType = {
     },
   },
   create(context) {
-    if (isTestFile(context.filename || context.getFilename())) return {}
     return {
       MethodDefinition(node) {
         if (node.kind !== "method" || node.static || !node.value.body || node.value.returnType) return
@@ -497,55 +301,23 @@ export const explicitHandlerReturnType = {
 
 /** The rules this law contributes to the plugin. */
 export const rules = {
-  "no-double-cast": noDoubleCast,
+  "no-function-or-eval": noFunctionOrEval,
   "no-inline-param-type": noInlineParamType,
   "no-inline-object-type": noInlineObjectType,
   "no-const-enum": noConstEnum,
-  "no-unguarded-unknown-cast": noUnguardedUnknownCast,
-  "no-never-cast": noNeverCast,
-  "no-non-null-assertion": noNonNullAssertion,
   "explicit-handler-return-type": explicitHandlerReturnType,
 }
 
 /**
- * The level this law asks for, as the plugin's own opinion.
- *
- * The two standard rules are listed beside the house ones so a consuming repository switches the
- * set on together -- `no-explicit-any` in particular is the one everybody already has and the one
- * whose absence makes the rest decorative.
- *
- * 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.
+ * The level this law asks for: every rule at `error`, in every file, specs included.
  *
- * 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`.
+ * The borrowed type-escape rules (`consistent-type-assertions` never, `no-non-null-assertion`, `no-explicit-any`)
+ * are added by the factory (`lib/config.mjs`), not listed here. The array spelling rule stays with this law.
  */
 export const recommended = {
-  "starci-be/no-double-cast": "error",
+  "starci-be/no-function-or-eval": "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-never-cast": "error",
-  "starci-be/no-non-null-assertion": "error",
   "starci-be/explicit-handler-return-type": "error",
-  "@typescript-eslint/no-explicit-any": "error",
-  "@typescript-eslint/array-type": ["error", {
-    default: "generic",
-    readonly: "generic",
-  }],
 }