@starci/eslint-canon-fe 9.2.0 → 9.4.0

package/type-safety.mjs

@@ -1,147 +0,0 @@
-/**
- * The rules that hold `type-safety.md`.
- *
- * FOUR RULES, ONE IDEA: the compiler is told the truth or it is not told at all. The double cast, the
- * plain assertion, the non-null assertion and `any` are the four spellings of "trust me". They live
- * here rather than in a repository's own `eslint.config.mjs` because a repository carries no rule of
- * its own: a rule that exists only in one repository's config is a rule the next repository forgets.
- * The array spelling is a formatting question and stays with the formatter.
- *
- * THE EXEMPTION IS A SPEC, and it has to be. Proving a closed API refuses bad input means building
- * bad input, and there is no way to construct a value the types forbid without telling the compiler
- * to forget them. A judgement-based exemption would be argued at every call site; a spec is decided
- * once, by its name.
- */
-
-import { isProductSource } from "./lib/scope.mjs"
-
-/** True when a type node is the `unknown` keyword. */
-const isUnknown = (node) => Boolean(node) && node.type === "TSUnknownKeyword"
-
-// -- TYPE-SAFETY-1 ---------------------------------------------------------------------------------
-
-/** A cast through `unknown` erases what the compiler knew, at the seam where it mattered. */
-export const noDoubleCast = {
-  meta: {
-    type: "problem",
-    docs: { description: "No cast through `unknown`; it turns checking off at the boundary." },
-    schema: [],
-    messages: {
-      double:
-        "Casting through `unknown` tells the compiler to forget everything it knew about this value, because the two types have nothing in common. That is not a narrowing - a narrowing is a claim the compiler can still partly check - it is an erasure, and the seam it erases is the one worth checking: where a value crosses from outside the program to inside it. Narrow from `unknown` with a check the compiler can follow, or fix the shape.",
-    },
-  },
-  create(context) {
-    if (!isProductSource(context)) return {}
-    return {
-      TSAsExpression(node) {
-        // The outer cast of a `x as unknown as T` pair: its operand is itself a cast to `unknown`.
-        const inner = node.expression
-        if (!inner || inner.type !== "TSAsExpression") return
-        if (!isUnknown(inner.typeAnnotation)) return
-        context.report({ node, messageId: "double" })
-      },
-    }
-  },
-}
-
-// -- TYPE-SAFETY-2 ---------------------------------------------------------------------------------
-
-/** True for `as const`, the one assertion that narrows without claiming anything. */
-const isConstAssertion = (type) => type.type === "TSTypeReference" && type.typeName.type === "Identifier" && type.typeName.name === "const"
-
-/**
- * A type assertion is a claim the compiler cannot check, made at the place it was going to check.
- *
- * WHAT IS LEFT ALLOWED. `as const` (it narrows), `as unknown` (it widens, and everything is assignable
- * to it), and `satisfies` (it checks). The cast through `unknown` to a real type is refused by
- * `no-double-cast`, so this rule leaves the outer half of that pair to it and reports each once.
- */
-export const noTypeAssertion = {
-  meta: {
-    type: "problem",
-    docs: { description: "No `as T` or `<T>x`; narrow with a check, a guard or a parser." },
-    schema: [],
-    messages: {
-      assertion:
-        "`as {{type}}` tells the compiler to believe something it could not verify. When the claim is wrong the type system keeps saying it is right and the failure moves to a reader. Narrow with a check the compiler can follow (a type guard, `in`, a discriminant), parse the value where it enters, or use `satisfies` when the goal is only to check a literal.",
-    },
-  },
-  create(context) {
-    if (!isProductSource(context)) return {}
-    const source = context.sourceCode ?? context.getSourceCode()
-    const report = (node) =>
-      context.report({ node, messageId: "assertion", data: { type: source.getText(node.typeAnnotation) } })
-    return {
-      TSAsExpression(node) {
-        if (isConstAssertion(node.typeAnnotation) || isUnknown(node.typeAnnotation)) return
-        const inner = node.expression
-        if (inner && inner.type === "TSAsExpression" && isUnknown(inner.typeAnnotation)) return
-        report(node)
-      },
-      TSTypeAssertion(node) {
-        if (isConstAssertion(node.typeAnnotation)) return
-        report(node)
-      },
-    }
-  },
-}
-
-// -- TYPE-SAFETY-3 ---------------------------------------------------------------------------------
-
-/** `x!` says a value is present without proving it. */
-export const noNonNullAssertion = {
-  meta: {
-    type: "problem",
-    docs: { description: "No non-null assertion (`x!`); prove the value is there." },
-    schema: [],
-    messages: {
-      bang:
-        "`!` asserts the value is not null or undefined and proves nothing: the day it is one, the failure is a TypeError in a reader's browser rather than a branch in the code. Handle the absent case (`if`, `??`, an early return) or make the type say it cannot be absent.",
-    },
-  },
-  create(context) {
-    if (!isProductSource(context)) return {}
-    return { TSNonNullExpression: (node) => context.report({ node, messageId: "bang" }) }
-  },
-}
-
-// -- TYPE-SAFETY-4 ---------------------------------------------------------------------------------
-
-/** `any` switches checking off for everything it touches. */
-export const noExplicitAny = {
-  meta: {
-    type: "problem",
-    docs: { description: "No `any`; use a real type or `unknown` and narrow." },
-    schema: [],
-    messages: {
-      any:
-        "`any` turns type checking off for this value and everything derived from it, silently. Use the real type, a generic, or `unknown` and narrow it where it is used.",
-    },
-  },
-  create(context) {
-    if (!isProductSource(context)) return {}
-    return { TSAnyKeyword: (node) => context.report({ node, messageId: "any" }) }
-  },
-}
-
-/** The rules this law contributes to the plugin. */
-export const rules = {
-  "no-double-cast": noDoubleCast,
-  "no-type-assertion": noTypeAssertion,
-  "no-non-null-assertion": noNonNullAssertion,
-  "no-explicit-any": noExplicitAny,
-}
-
-/**
- * The level this law asks for, as the plugin's own opinion.
- *
- * Exact - it matches one syntactic shape - but a repository adopting it with history should expect
- * each report to be real work: a double cast is usually load-bearing by the time anybody notices,
- * and removing one means giving the value a shape it did not have.
- *
- * `any` and the array spelling are NOT published here. They belong to the TypeScript plugin's own
- * rules, which a consuming repository already has: `@typescript-eslint/no-explicit-any` and
- * `@typescript-eslint/array-type` with the generic default.
- */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/ui-rulings.mjs

@@ -1,134 +0,0 @@
-/** Owner UI rulings: selection uses fill, and applications respect Grammar styling ownership. */
-import { attribute, attributeValue, staticText } from "./lib/ast.mjs";
-import { importOf } from "./lib/bindings.mjs";
-import { isProductSource } from "./lib/scope.mjs";
-import { typedClassStrings } from "./lib/typed-class-values.mjs";
-
-/** Resolve a named or namespace import at its use, preserving lexical shadowing. */
-const grammarComponent = (context, opening, expected) => {
-  const name = opening.name;
-  const root = name.type === "JSXMemberExpression" ? name.object : name;
-  if (root.type !== "JSXIdentifier") return false;
-  const binding = importOf(context, root);
-  if (
-    !binding ||
-    !/^@starci\/grammar(?:\/(?:common|core|offset-pop))?$/.test(
-      binding.source,
-    )
-  )
-    return false;
-  return name.type === "JSXMemberExpression"
-    ? binding.imported === null && name.property.name === expected
-    : binding.imported === expected;
-};
-
-/** Only a final explicit attribute is proof when an opaque spread could override a value. */
-const propText = (opening, key) => {
-  let value = null;
-  for (const entry of opening.attributes) {
-    if (entry.type === "JSXSpreadAttribute") value = null;
-    else if (entry.name.name === key) value = staticText(entry.value);
-  }
-  return value;
-};
-
-/** Navigation and rail/list placement are structurally identifiable without guessing from product names. */
-const navigationList = (context, opening) => {
-  for (let node = opening.parent; node; node = node.parent) {
-    if (node.type !== "JSXElement") continue;
-    const parent = node.openingElement;
-    if (
-      ["nav", "ul", "ol"].includes(parent.name.name) ||
-      ["navigation", "list"].includes(propText(parent, "role"))
-    )
-      return true;
-    if (
-      ["Rail", "Sidebar"].some((role) =>
-        grammarComponent(context, parent, role),
-      )
-    )
-      return true;
-  }
-  return false;
-};
-
-/** Navigation-like single selection uses the row fill instead of a second check indicator. */
-export const selectionFillNoCheck = {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "Navigation-like single-select ListBox rows use selectionIndicator=none.",
-    },
-    schema: [],
-    messages: {
-      indicator:
-        'Use selectionIndicator="none" on this navigation-like single-select ListBox; the row fill carries selection.',
-    },
-  },
-  create(context) {
-    return {
-      JSXOpeningElement(node) {
-        if (
-          !grammarComponent(context, node, "ListBox") ||
-          !navigationList(context, node)
-        )
-          return;
-        if (["none", "multiple"].includes(propText(node, "selectionMode")))
-          return;
-        if (propText(node, "selectionIndicator") !== "none")
-          context.report({ node, messageId: "indicator" });
-      },
-    };
-  },
-};
-
-/** Grammar internal selectors belong to Grammar, including selectors in colocated class declarations. */
-export const noGrammarInternalSelector = {
-  meta: {
-    type: "problem",
-    docs: {
-      description: "Application styles cannot target starci-core internals.",
-    },
-    schema: [],
-    messages: {
-      internal:
-        "Remove this starci-core- selector. Compose the Grammar public API; message actions belong in the ChatBubble floating toolbar.",
-    },
-  },
-  create(context) {
-    if (!isProductSource(context)) return {};
-    const selector = /(?:\.|_|\[class[^\]]*)starci-core-/;
-    const report = (node, text) => {
-      if (text && selector.test(text))
-        context.report({ node, messageId: "internal" });
-    };
-    return {
-      Literal(node) {
-        if (typeof node.value === "string") report(node, node.value);
-      },
-      TemplateElement(node) {
-        report(node, node.value.cooked);
-      },
-      JSXAttribute(node) {
-        if (node.name.name !== "className") return;
-        const value = attributeValue(attribute(node.parent, "className"));
-        if (value?.type !== "Identifier" && value?.type !== "MemberExpression")
-          return;
-        const strings = typedClassStrings(context, value, "classes");
-        if (strings.some((entry) => selector.test(entry.text)))
-          context.report({ node, messageId: "internal" });
-      },
-    };
-  },
-};
-
-export const rules = {
-  "selection-fill-no-check": selectionFillNoCheck,
-  "no-grammar-internal-selector": noGrammarInternalSelector,
-};
-
-/** Both owner rulings are universal errors in the frontend canon. */
-export const recommended = Object.fromEntries(
-  Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]),
-);