@starci/eslint-canon-fe 9.2.0 → 9.4.0

package/dist/lib/bindings.js

@@ -0,0 +1,168 @@
+import { stringOf } from "./ast.js";
+/** The globals that all name the browser's global object. */
+const GLOBAL_OBJECT = new Set(["window", "globalThis", "self"]);
+/** Wrappers that change a node's type, not its identity. */
+const TRANSPARENT = new Set(["TSAsExpression", "TSNonNullExpression", "TSSatisfiesExpression", "TSTypeAssertion", "ChainExpression", "ParenthesizedExpression"]);
+/** True for a node that only wraps the type of its `expression`. */
+const isTransparent = (node) => TRANSPARENT.has(node.type);
+export function unwrap(node) {
+    let current = node;
+    while (current && isTransparent(current))
+        current = current.expression;
+    return current;
+}
+/**
+ * The node's parent with the type-only wrappers skipped upward.
+ *
+ * @param node - An ESTree node.
+ * @returns The first parent that is not a type-only wrapper.
+ */
+export const parentOf = (node) => {
+    let current = node.parent;
+    while (current && TRANSPARENT.has(current.type))
+        current = current.parent;
+    return current ?? null;
+};
+/** True for a function expression, an arrow function or a function declaration. */
+export const isFn = (node) => Boolean(node) && (node?.type === "FunctionExpression" || node?.type === "ArrowFunctionExpression" || node?.type === "FunctionDeclaration");
+/**
+ * The scope-manager variable an identifier resolves to, or null for a global.
+ *
+ * @param context - The ESLint rule context.
+ * @param identifier - An ESTree identifier.
+ * @returns The variable.
+ */
+export const variableOf = (context, identifier) => {
+    for (let scope = context.sourceCode.getScope(identifier); scope; scope = scope.upper) {
+        const variable = scope.set.get(identifier.name);
+        if (variable)
+            return variable;
+    }
+    return null;
+};
+/**
+ * Where an identifier was imported from.
+ *
+ * @param context - The ESLint rule context.
+ * @param identifier - An ESTree identifier.
+ * @returns The origin, or null when the identifier is not an import.
+ */
+export const importOf = (context, identifier) => {
+    const variable = variableOf(context, identifier);
+    const definition = variable?.defs.find((entry) => entry.type === "ImportBinding");
+    if (!definition || definition.type !== "ImportBinding")
+        return null;
+    const specifier = definition.node;
+    const parent = definition.parent;
+    const source = String(parent.type === "ImportDeclaration" ? parent.source.value : undefined);
+    if (specifier.type === "ImportSpecifier") {
+        return { source, imported: specifier.imported.type === "Identifier" ? specifier.imported.name : String(specifier.imported.value) };
+    }
+    return { source, imported: null };
+};
+/** The property path a destructured binding selects from its initializer; null for an unselected or rest binding. */
+export const patternPath = (pattern, name) => {
+    if (pattern.type === "Identifier")
+        return pattern.name === name ? [] : null;
+    if (pattern.type === "AssignmentPattern")
+        return patternPath(pattern.left, name);
+    if (pattern.type !== "ObjectPattern")
+        return null;
+    for (const property of pattern.properties) {
+        if (property.type !== "Property")
+            continue;
+        const nested = patternPath(property.value, name);
+        if (nested !== null) {
+            const key = property.key;
+            const step = property.computed ? stringOf(key) : key.type === "Identifier" ? key.name : key.type === "Literal" ? propertyValue(key.value) : null;
+            return [step, ...nested];
+        }
+    }
+    return null;
+};
+/** The value of a literal property key, as the path step it names. */
+const propertyValue = (value) => typeof value === "string" || typeof value === "number" ? value : value === null ? null : String(value);
+/**
+ * The function an expression stands for: the function itself, or the function a same-file variable or declaration holds.
+ *
+ * @param context - The ESLint rule context.
+ * @param node - An ESTree expression.
+ * @returns The function node, or null when it cannot be resolved in this file.
+ */
+export const functionOf = (context, node) => {
+    const inner = unwrap(node);
+    if (!inner)
+        return null;
+    if (isFn(inner))
+        return inner;
+    if (inner.type !== "Identifier")
+        return null;
+    const variable = variableOf(context, inner);
+    for (const definition of variable?.defs ?? []) {
+        if (definition.type === "FunctionName" && definition.node.type === "FunctionDeclaration")
+            return definition.node;
+        if (definition.type === "Variable" && definition.node.id.type === "Identifier") {
+            const init = unwrap(definition.node.init);
+            if (isFn(init))
+                return init;
+        }
+    }
+    return null;
+};
+/** A stable numeric id per scope-manager variable, so keys compare by binding and not by spelling. */
+const VARIABLE_IDS = new WeakMap();
+let nextVariableId = 1;
+const idOf = (variable) => {
+    const known = VARIABLE_IDS.get(variable);
+    if (known !== undefined)
+        return known;
+    const id = nextVariableId++;
+    VARIABLE_IDS.set(variable, id);
+    return id;
+};
+/**
+ * The key of an expression that names a place: `v12` for a variable, `v12.current` for a member path, `this.timer` for
+ * a member of `this`, `g:window` for the browser's global object under any of its names. Anything else has no key.
+ *
+ * @param context - The ESLint rule context.
+ * @param node - An ESTree expression.
+ * @returns The key.
+ */
+export const keyOf = (context, node) => {
+    const inner = unwrap(node);
+    if (!inner)
+        return null;
+    if (inner.type === "Identifier") {
+        const variable = variableOf(context, inner);
+        if (variable && variable.defs.length > 0)
+            return `v${idOf(variable)}`;
+        return GLOBAL_OBJECT.has(inner.name) ? "g:window" : `g:${inner.name}`;
+    }
+    if (inner.type === "ThisExpression")
+        return "this";
+    if (inner.type === "MemberExpression") {
+        const head = keyOf(context, inner.object);
+        if (head === null)
+            return null;
+        if (!inner.computed && inner.property.type === "Identifier")
+            return `${head}.${inner.property.name}`;
+        if (inner.computed && inner.property.type === "Literal")
+            return `${head}[${String(inner.property.value)}]`;
+        return null;
+    }
+    return null;
+};
+/**
+ * The receiver and the member name of a call written as `receiver.name(...)`, or the bare name of `name(...)`.
+ *
+ * @param call - An ESTree call expression.
+ * @returns The parts, or null for a computed or exotic callee.
+ */
+export const calleeParts = (call) => {
+    const callee = unwrap(call.callee);
+    if (callee.type === "Identifier")
+        return { receiver: null, name: callee.name };
+    if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier")
+        return { receiver: callee.object, name: callee.property.name };
+    return null;
+};

package/dist/lib/class-text.d.ts

@@ -0,0 +1,3 @@
+import type { AnyContext, Listener, Node } from "./rule.js";
+/** Visit class strings in product JSX, declarations and named class arrays. */
+export declare const classTextVisitors: (context: AnyContext, report: (node: Node, text: string | null) => void) => Listener;

package/dist/lib/class-text.js

@@ -0,0 +1,30 @@
+import { isClassAttribute, staticText } from "./ast.js";
+import { isProductSource } from "./scope.js";
+/** Static strings in JSX, constants and arrays, preserving the authored class order. */
+const classText = (value) => {
+    if (value?.type === "JSXExpressionContainer")
+        return classText(value.expression);
+    if (value?.type === "ArrayExpression") {
+        const members = value.elements.map((element) => classText(element)).filter((text) => Boolean(text));
+        return members.length > 0 ? members.join(" ") : null;
+    }
+    return staticText(value);
+};
+/** Visit class strings in product JSX, declarations and named class arrays. */
+export const classTextVisitors = (context, report) => {
+    if (!isProductSource(context))
+        return {};
+    return {
+        JSXAttribute(node) {
+            if (isClassAttribute(node))
+                report(node, classText(node.value));
+        },
+        VariableDeclarator(node) {
+            report(node, classText(node.init));
+        },
+        Property(node) {
+            if (!node.computed && node.key.type === "Identifier" && node.key.name === "classes")
+                report(node, classText(node.value));
+        },
+    };
+};

package/dist/lib/config.d.ts

@@ -0,0 +1,81 @@
+import type { ESLint, Linter } from "eslint";
+import type { Rules } from "./rule.js";
+/** The canon plugin as this package builds it: its name and its rules. */
+export interface CanonPlugin {
+    readonly meta: {
+        readonly name: string;
+    };
+    readonly rules: Rules;
+}
+/** The plugins of the Sonar way rules (scripts/lib/sonar-way.mjs). */
+export interface SonarPlugins {
+    readonly sonarjs: ESLint.Plugin;
+    readonly unicorn: ESLint.Plugin;
+}
+/** A disable directive is a weakening of lint, and one that suppresses nothing is dead weight. */
+export declare const linterOptions: Readonly<{
+    noInlineConfig: true;
+    reportUnusedDisableDirectives: "error";
+}>;
+/** The product source of a front end: every app's `src/` and every workspace package's `src/` (slots fe.* and repo.packages). */
+export declare const SOURCE_FILES: readonly string[];
+/** Build output, installed packages, generated wire types and the harness's report directory are never linted. */
+export declare const IGNORED: readonly string[];
+/**
+ * The type-aware typescript-eslint rules the canon borrows, all `error` and the same set the back-end canon borrows for the type-aware laws: a promise is awaited or
+ * handled (`no-floating-promises`, `no-misused-promises`), a `switch` over a union names every member, nothing flows out of an `any` (the `no-unsafe-*` family),
+ * and the Sonar rules that need the checker: S1874 (a deprecated API), S6551 (an object turned into text) and S7503 (an `async` function that never awaits).
+ */
+export declare const BORROWED: Readonly<Record<string, "error">>;
+/**
+ * The flat config of one front-end repository.
+ *
+ * @param input - Attachment options.
+ * @param input.hfs - The HFS view of the repository (`loadHfs(import.meta.url)`).
+ * @param input.plugin - The canon plugin.
+ * @param input.source - The source-tree levels (canon rules plus the React Hooks rules).
+ * @param input.reactHooks - The React Hooks plugin.
+ * @param input.tsPlugin - The typescript-eslint plugin.
+ * @param input.sonar - The plugins of the Sonar way rules (scripts/lib/sonar-way.mjs).
+ * @returns The flat config: one ignore block, one typed source block and the Sonar way block.
+ */
+export declare const buildFeConfig: ({ hfs, plugin, source, reactHooks, tsPlugin, sonar }: {
+    readonly hfs: unknown;
+    readonly plugin: CanonPlugin;
+    readonly source: Linter.RulesRecord;
+    readonly reactHooks: ESLint.Plugin;
+    readonly tsPlugin: ESLint.Plugin;
+    readonly sonar: SonarPlugins;
+}) => Linter.Config[];
+/**
+ * The canon rules that need no slot view: they judge a node and its types, never where the file sits in an app. A tree that is no HFS front end (a
+ * runtime package, the harness UI) is linted by exactly these plus the type-aware, React Hooks and Sonar way rules. The set is closed by
+ * config.spec.mjs: every other rule of the plugin refuses to run without `settings.starci.hfs`, so a rule added to the plugin is either listed here
+ * or proven slot-bound there.
+ */
+export declare const SLOT_FREE_RULES: readonly string[];
+/** The source of a plain front-end tree: its `src/`. */
+export declare const PLAIN_SOURCE_FILES: readonly string[];
+/**
+ * The flat config of a TypeScript front-end tree that is no HFS app: the same fences as an app (typed linting, no inline directive, every rule at
+ * `error`) over the rules that need no slot view. It takes the root of the tree and nothing else.
+ *
+ * @param input - Attachment options.
+ * @param input.root - The absolute directory holding the tree's `tsconfig.json` and `src/`.
+ * @param input.plugin - The canon plugin.
+ * @param input.hooks - The React Hooks rules at error.
+ * @param input.reactHooks - The React Hooks plugin.
+ * @param input.tsPlugin - The typescript-eslint plugin.
+ * @param input.sonar - The plugins of the Sonar way rules.
+ * @param input.canon - Whether the slot-free canon rules are on.
+ * @returns The flat config: one ignore block, one typed source block and the Sonar way block.
+ */
+export declare const buildPlainSourceConfig: ({ root, plugin, hooks, reactHooks, tsPlugin, sonar, canon }: {
+    readonly root: unknown;
+    readonly plugin: CanonPlugin;
+    readonly hooks: Linter.RulesRecord;
+    readonly reactHooks: ESLint.Plugin;
+    readonly tsPlugin: ESLint.Plugin;
+    readonly sonar: SonarPlugins;
+    readonly canon?: boolean;
+}) => Linter.Config[];

package/dist/lib/config.js

@@ -0,0 +1,141 @@
+/**
+ * The one flat config of a StarCi front end.
+ *
+ * A repository's `eslint.config.mjs` is managed by `starci app sync` (R05/R16/R17). Its template composes this universal
+ * factory with the explicitly selected Grammar family's factory, passing the same HFS view to both.
+ *
+ * The factory owns everything else: which files are linted (the source of every app and every workspace package), typed linting on the source (`parserOptions.projectService`, so a rule asks what a node IS rather than what
+ * it is called), the ignores, the linter options that make a disable comment impossible, every canon rule at `error`,
+ * the React Hooks rules at `error`, and `settings.starci.hfs` - the slot view each path-scoped rule asks instead of a path
+ * pattern. It takes no rule overrides, globs or ignores: there is no parameter through which a repository could weaken
+ * the canon.
+ */
+import tsParser from "@typescript-eslint/parser";
+import { OUTSIDE_THE_SCAN_FILES } from "#runtime/scripts/lib/sonar-syntax-rules.mjs";
+import { sonarWayRules } from "#runtime/scripts/lib/sonar-way.mjs";
+import { eslintPlugin } from "./eslint-boundary.js";
+import { isHfsView } from "./hfs.js";
+/** A disable directive is a weakening of lint, and one that suppresses nothing is dead weight. */
+export const linterOptions = Object.freeze({ noInlineConfig: true, reportUnusedDisableDirectives: "error" });
+/** The product source of a front end: every app's `src/` and every workspace package's `src/` (slots fe.* and repo.packages). */
+export const SOURCE_FILES = Object.freeze(["apps/*/src/**/*.{ts,tsx}", "packages/*/src/**/*.{ts,tsx}"]);
+/** Build output, installed packages, generated wire types and the harness's report directory are never linted. */
+export const IGNORED = Object.freeze(["**/node_modules/**", "**/.next/**", "**/dist/**", "**/coverage/**", "**/__generated__/**", ".starci/**"]);
+/**
+ * The type-aware typescript-eslint rules the canon borrows, all `error` and the same set the back-end canon borrows for the type-aware laws: a promise is awaited or
+ * handled (`no-floating-promises`, `no-misused-promises`), a `switch` over a union names every member, nothing flows out of an `any` (the `no-unsafe-*` family),
+ * and the Sonar rules that need the checker: S1874 (a deprecated API), S6551 (an object turned into text) and S7503 (an `async` function that never awaits).
+ */
+export const BORROWED = Object.freeze({
+    "@typescript-eslint/no-floating-promises": "error",
+    "@typescript-eslint/no-misused-promises": "error",
+    "@typescript-eslint/switch-exhaustiveness-check": "error",
+    "@typescript-eslint/no-unsafe-assignment": "error",
+    "@typescript-eslint/no-unsafe-member-access": "error",
+    "@typescript-eslint/no-unsafe-call": "error",
+    "@typescript-eslint/no-unsafe-return": "error",
+    "@typescript-eslint/no-unsafe-argument": "error",
+    "@typescript-eslint/no-deprecated": "error",
+    "@typescript-eslint/no-base-to-string": "error",
+    "@typescript-eslint/require-await": "error",
+});
+const levelOf = (setting) => (Array.isArray(setting) ? setting[0] : setting);
+/**
+ * The flat config of one front-end repository.
+ *
+ * @param input - Attachment options.
+ * @param input.hfs - The HFS view of the repository (`loadHfs(import.meta.url)`).
+ * @param input.plugin - The canon plugin.
+ * @param input.source - The source-tree levels (canon rules plus the React Hooks rules).
+ * @param input.reactHooks - The React Hooks plugin.
+ * @param input.tsPlugin - The typescript-eslint plugin.
+ * @param input.sonar - The plugins of the Sonar way rules (scripts/lib/sonar-way.mjs).
+ * @returns The flat config: one ignore block, one typed source block and the Sonar way block.
+ */
+export const buildFeConfig = ({ hfs, plugin, source, reactHooks, tsPlugin, sonar }) => {
+    if (!isHfsView(hfs) || typeof hfs.repoRoot !== "string") {
+        throw new Error("starciFeConfig needs { hfs: loadHfs(import.meta.url) } - the rules read the repository's slots through it");
+    }
+    if (hfs.profile !== "fe")
+        throw new Error(`starciFeConfig lints the fe side of an app (its eslint.config.mjs lives in fe/); this view is ${hfs.side ? `the ${hfs.side} side` : "the app root"}`);
+    if (Object.keys(source).length === 0)
+        throw new Error("starciFeConfig received an empty source recommendation - a config with no rules is not adoption");
+    const weak = Object.entries(source).filter(([, setting]) => levelOf(setting) !== "error").map(([name]) => name);
+    if (weak.length > 0)
+        throw new Error(`starciFeConfig refuses source rules not at error: ${weak.join(", ")}`);
+    const settings = { starci: { hfs } };
+    return [
+        { ignores: [...IGNORED] },
+        {
+            files: [...SOURCE_FILES],
+            languageOptions: {
+                parser: tsParser,
+                ecmaVersion: "latest",
+                sourceType: "module",
+                parserOptions: { projectService: true, tsconfigRootDir: hfs.repoRoot, ecmaFeatures: { jsx: true } },
+            },
+            linterOptions: { ...linterOptions },
+            plugins: { "starci-fe": eslintPlugin(plugin), "react-hooks": reactHooks, "@typescript-eslint": tsPlugin },
+            settings,
+            rules: { ...source, ...BORROWED },
+        },
+        // Sonar way: what the scan raises is refused while the code is written; a spec is outside the scan, so outside this block.
+        { files: [...SOURCE_FILES], ignores: [...OUTSIDE_THE_SCAN_FILES], plugins: { sonarjs: sonar.sonarjs, unicorn: sonar.unicorn }, rules: sonarWayRules(sonar.sonarjs, "fe").rules },
+    ];
+};
+/**
+ * The canon rules that need no slot view: they judge a node and its types, never where the file sits in an app. A tree that is no HFS front end (a
+ * runtime package, the harness UI) is linted by exactly these plus the type-aware, React Hooks and Sonar way rules. The set is closed by
+ * config.spec.mjs: every other rule of the plugin refuses to run without `settings.starci.hfs`, so a rule added to the plugin is either listed here
+ * or proven slot-bound there.
+ */
+export const SLOT_FREE_RULES = Object.freeze([
+    "client-no-server-import", "no-server-action", "no-dangerous-html", "response-cookie-attributes", "require-export-jsdoc", "no-vietnamese-in-source",
+    "no-hardcoded-endpoint-fallback", "no-runtime-namespace", "list-item-has-key", "no-index-key", "no-inline-literal-prop-in-list", "prefer-arrow-export",
+    "handler-on-prefix", "no-native-form-control", "no-native-img", "image-has-size", "no-second-i18n-stack", "html-lang-from-locale", "no-null-suspense-fallback",
+    "no-native-anchor", "no-inline-parameter-type", "no-hand-rolled-polling", "no-copy-in-call", "no-alert", "no-failure-collapse",
+    "outcome-kinds-exhaustive", "no-await-in-loop", "prefer-code-point", "prefer-string-raw", "no-nested-conditional", "no-void-operator", "no-unused-import",
+    "prefer-export-from", "no-unused-prop-types", "media-has-caption", "max-params",
+    "nested-control-variant", "no-list-panel-padding", "no-app-surface-paint", "divider-full-bleed", "control-height", "selection-fill-no-check", "no-grammar-shim",
+    "button-intent-required", "button-no-variant", "destructive-confirm-in-dialog", "single-commit-per-render", "no-commit-in-collection-item",
+]);
+/** The source of a plain front-end tree: its `src/`. */
+export const PLAIN_SOURCE_FILES = Object.freeze(["src/**/*.{ts,tsx}"]);
+/**
+ * The flat config of a TypeScript front-end tree that is no HFS app: the same fences as an app (typed linting, no inline directive, every rule at
+ * `error`) over the rules that need no slot view. It takes the root of the tree and nothing else.
+ *
+ * @param input - Attachment options.
+ * @param input.root - The absolute directory holding the tree's `tsconfig.json` and `src/`.
+ * @param input.plugin - The canon plugin.
+ * @param input.hooks - The React Hooks rules at error.
+ * @param input.reactHooks - The React Hooks plugin.
+ * @param input.tsPlugin - The typescript-eslint plugin.
+ * @param input.sonar - The plugins of the Sonar way rules.
+ * @param input.canon - Whether the slot-free canon rules are on.
+ * @returns The flat config: one ignore block, one typed source block and the Sonar way block.
+ */
+export const buildPlainSourceConfig = ({ root, plugin, hooks, reactHooks, tsPlugin, sonar, canon = true }) => {
+    if (typeof root !== "string" || root === "")
+        throw new Error("starciPlainSourceConfig needs { root } - the directory of the tree's tsconfig.json and src/");
+    const canonRules = canon ? Object.fromEntries(SLOT_FREE_RULES.map((name) => [`starci-fe/${name}`, "error"])) : {};
+    const missing = SLOT_FREE_RULES.filter((name) => !(name in plugin.rules));
+    if (missing.length > 0)
+        throw new Error(`starciPlainSourceConfig lists rules the canon plugin does not publish: ${missing.join(", ")}`);
+    return [
+        { ignores: [...IGNORED] },
+        {
+            files: [...PLAIN_SOURCE_FILES],
+            languageOptions: {
+                parser: tsParser,
+                ecmaVersion: "latest",
+                sourceType: "module",
+                parserOptions: { projectService: true, tsconfigRootDir: root, ecmaFeatures: { jsx: true } },
+            },
+            linterOptions: { ...linterOptions },
+            plugins: { "starci-fe": eslintPlugin(plugin), "react-hooks": reactHooks, "@typescript-eslint": tsPlugin },
+            rules: { ...canonRules, ...hooks, ...BORROWED },
+        },
+        { files: [...PLAIN_SOURCE_FILES], ignores: [...OUTSIDE_THE_SCAN_FILES], plugins: { sonarjs: sonar.sonarjs, unicorn: sonar.unicorn }, rules: sonarWayRules(sonar.sonarjs, "fe").rules },
+    ];
+};

package/dist/lib/drawing-scope.d.ts

@@ -0,0 +1,5 @@
+import type { AnyContext } from "./rule.js";
+/** Whether the file belongs to an HFS owner with a connected/presentational pair. */
+export declare const inSplitTier: (context: AnyContext) => boolean;
+/** The paired presentation file's component kind, or null outside that scope. */
+export declare const pureHalf: (context: AnyContext) => string | null;

package/{lib/drawing-scope.mjs → dist/lib/drawing-scope.js}

@@ -1,15 +1,10 @@
 /** Shared HFS scope of connected/presentational component pairs. */
-import { hfsOf } from "./hfs.mjs"
-import { fileOf, inSlot, kindOfFile, roleOfFile } from "./scope.mjs"
-
-const SPLIT_KINDS = new Set(["blocks", "pages", "layouts", "overlays"])
-
+import { hfsOf } from "./hfs.js";
+import { fileOf, inSlot, kindOfFile, roleOfFile } from "./scope.js";
+const SPLIT_KINDS = new Set(["blocks", "pages", "layouts", "overlays"]);
 /** The owning surface folder of the linted entry or presentation file. */
-const surfaceName = (context) => hfsOf(context).relative(fileOf(context)).split("/").slice(-2)[0]
-
+const surfaceName = (context) => hfsOf(context).relative(fileOf(context)).split("/").slice(-2)[0];
 /** Whether the file belongs to an HFS owner with a connected/presentational pair. */
-export const inSplitTier = (context) => inSlot(context, "fe.components", "fe.feature") && SPLIT_KINDS.has(kindOfFile(context))
-
+export const inSplitTier = (context) => inSlot(context, "fe.components", "fe.feature") && SPLIT_KINDS.has(kindOfFile(context));
 /** The paired presentation file's component kind, or null outside that scope. */
-export const pureHalf = (context) =>
-  inSplitTier(context) && roleOfFile(context) === "drawing" && /^[A-Z][A-Za-z0-9]*$/.test(surfaceName(context)) ? kindOfFile(context) : null
+export const pureHalf = (context) => inSplitTier(context) && roleOfFile(context) === "drawing" && /^[A-Z][A-Za-z0-9]*$/.test(String(surfaceName(context))) ? kindOfFile(context) : null;

package/dist/lib/eslint-boundary.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Where a canon rule meets ESLint's own types.
+ *
+ * The canon writes its rules against typescript-eslint's `RuleModule` (lib/rule.ts): its AST carries the JSX and
+ * TypeScript nodes the rules read, which ESLint's ESTree types lack. ESLint's `RuleTester`, `Linter` and flat-config types
+ * describe the same runtime objects with ESLint's own context and visitor types, and neither declaration is assignable to
+ * the other (typescript-eslint's context still declares the scope readers ESLint 9 removed). The objects are identical at
+ * run time, so the two views are joined here, in one place, and nowhere else.
+ */
+import type { TSESLint } from "@typescript-eslint/utils";
+import type { ESLint, Rule as EslintRule } from "eslint";
+import type { Rule, Rules } from "./rule.js";
+/** A canon rule (or a rule already written at ESLint's type, as the Grammar families write theirs) as ESLint's rule type: the same object. */
+export declare const eslintRule: (rule: Rule<string, readonly unknown[]> | EslintRule.RuleModule) => EslintRule.RuleModule;
+/** A rule at typescript-eslint's rule type with mutable options, the type the shared back-end fixtures declare their testers with: the same object. */
+export declare const sharedRule: (rule: Rule<string, readonly unknown[]> | EslintRule.RuleModule) => TSESLint.RuleModule<string, unknown[]>;
+/** The canon's rules as an ESLint plugin: the same objects, under ESLint's plugin type. */
+export declare const eslintPlugin: (plugin: {
+    readonly meta: {
+        readonly name: string;
+    };
+    readonly rules: Rules;
+}) => ESLint.Plugin;

package/dist/lib/eslint-boundary.js

@@ -0,0 +1,6 @@
+/** A canon rule (or a rule already written at ESLint's type, as the Grammar families write theirs) as ESLint's rule type: the same object. */
+export const eslintRule = (rule) => rule;
+/** A rule at typescript-eslint's rule type with mutable options, the type the shared back-end fixtures declare their testers with: the same object. */
+export const sharedRule = (rule) => rule;
+/** The canon's rules as an ESLint plugin: the same objects, under ESLint's plugin type. */
+export const eslintPlugin = (plugin) => plugin;

package/dist/lib/fe-stack.d.ts

@@ -0,0 +1,49 @@
+/** A concern of the catalog: its canonical packages, its HFS home and the packages it forbids (the catalog's own schema). */
+export interface FeConcern {
+    readonly id: string;
+    readonly tier?: string;
+    readonly packages?: readonly string[];
+    readonly home?: readonly string[];
+    readonly pattern?: string;
+    readonly forbids?: readonly string[];
+    readonly why?: string;
+}
+/** A forbidden package glob and the concern that forbids it. */
+export interface FeForbiddenPattern {
+    readonly expression: RegExp;
+    readonly concern: FeConcern;
+}
+/** The parsed catalog. */
+export interface FeStack {
+    readonly concerns: readonly FeConcern[];
+    readonly forbidden: ReadonlyMap<string, FeConcern>;
+    readonly patterns: readonly FeForbiddenPattern[];
+}
+/**
+ * The parsed catalog: its concerns, and every forbidden package mapped to the concern that forbids it.
+ *
+ * @returns The catalog.
+ */
+export declare const feStack: () => FeStack;
+/**
+ * The package a module specifier names (`@scope/name` or `name`, its subpath dropped), or null for a relative, aliased,
+ * node-builtin or empty specifier.
+ *
+ * @param specifier - The module specifier.
+ * @returns The package name.
+ */
+export declare const packageNameOf: (specifier: unknown) => string | null;
+/**
+ * The concern whose `forbids` lists the package a specifier names, else null.
+ *
+ * @param specifier - The module specifier.
+ * @returns The concern (`{ id, packages, home, pattern, forbids, why }`).
+ */
+export declare const forbiddingConcern: (specifier: unknown) => FeConcern | null;
+/**
+ * The canonical packages of a concern.
+ *
+ * @param id - The concern id (`icons`, `graphql`, ...).
+ * @returns Its packages; empty for an unknown concern.
+ */
+export declare const canonicalPackages: (id: string) => readonly string[];

package/dist/lib/fe-stack.js

@@ -0,0 +1,98 @@
+/**
+ * The one door between the front-end lint rules and the fe-stack catalog (`knowledge/hfs/fe-stack.yaml`): for each common
+ * front-end concern the ONE canonical library, its HFS home and the alternatives a front end never imports.
+ *
+ * The catalog is read from this package's `runtime/` copy, the same way the slot manifest and the canon pins are (a byte copy
+ * of the runtime's knowledge file, refreshed by `scripts/hfs/sync-runtime.mjs`), so a rule in a product repository judges
+ * against the catalog of the canon version it installed. A rule that needs the catalog and finds none stops the lint run
+ * with an error naming the fix: a rule must not guess which libraries are forbidden.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseYaml } from "#runtime/engine/yaml.mjs";
+import { globExpression } from "#runtime/scripts/lib/glob.mjs";
+import { RUNTIME_ROOT } from "./package-root.js";
+const CATALOG = join(RUNTIME_ROOT, "knowledge", "hfs", "fe-stack.yaml");
+/**
+ * True for a concern row. The catalog is this package's own shipped file, its schema proved by fe-stack.spec; a row is read
+ * as a concern once it is an object, as the catalog has always been read.
+ */
+const isConcern = (row) => typeof row === "object" && row !== null;
+/** The `concerns` of a parsed catalog document. */
+const concernsOf = (document) => typeof document === "object" && document !== null && "concerns" in document ? document.concerns : undefined;
+/** The code or message of a read failure. */
+const reasonOf = (error) => {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    if ("code" in error && error.code !== undefined && error.code !== null)
+        return error.code;
+    return "message" in error ? error.message : undefined;
+};
+let loaded = null;
+/**
+ * The parsed catalog: its concerns, and every forbidden package mapped to the concern that forbids it.
+ *
+ * @returns The catalog.
+ */
+export const feStack = () => {
+    if (loaded)
+        return loaded;
+    let text;
+    try {
+        text = readFileSync(CATALOG, "utf8");
+    }
+    catch (error) {
+        throw new Error(`@starci/eslint-canon-fe reads the fe-stack catalog from runtime/knowledge/hfs/fe-stack.yaml and it is missing (${String(reasonOf(error))}): regenerate the runtime copy (scripts/hfs/sync-runtime.mjs)`);
+    }
+    const concerns = concernsOf(parseYaml(text));
+    if (!Array.isArray(concerns) || concerns.length === 0)
+        throw new Error("runtime/knowledge/hfs/fe-stack.yaml declares no concerns: the fe-stack catalog is malformed");
+    const rows = concerns.map((row) => {
+        if (!isConcern(row))
+            throw new TypeError(`runtime/knowledge/hfs/fe-stack.yaml has a concern that is not an object: ${String(row)}`);
+        return row;
+    });
+    const forbidden = new Map();
+    for (const concern of rows)
+        for (const name of concern.forbids ?? [])
+            forbidden.set(String(name), concern);
+    const patterns = [...forbidden].filter(([name]) => name.includes("*")).map(([name, concern]) => ({ expression: globExpression(name), concern }));
+    loaded = Object.freeze({ concerns: Object.freeze(rows), forbidden, patterns: Object.freeze(patterns) });
+    return loaded;
+};
+/**
+ * The package a module specifier names (`@scope/name` or `name`, its subpath dropped), or null for a relative, aliased,
+ * node-builtin or empty specifier.
+ *
+ * @param specifier - The module specifier.
+ * @returns The package name.
+ */
+export const packageNameOf = (specifier) => {
+    const text = typeof specifier === "string" ? specifier : "";
+    if (text === "" || text.startsWith(".") || text.startsWith("/") || text.startsWith("@/") || text.startsWith("~/") || text.startsWith("node:"))
+        return null;
+    const parts = text.split("/");
+    if (text.startsWith("@"))
+        return parts.length >= 2 && parts[1] !== "" ? `${parts[0]}/${parts[1]}` : null;
+    return parts[0] ?? null;
+};
+/**
+ * The concern whose `forbids` lists the package a specifier names, else null.
+ *
+ * @param specifier - The module specifier.
+ * @returns The concern (`{ id, packages, home, pattern, forbids, why }`).
+ */
+export const forbiddingConcern = (specifier) => {
+    const name = packageNameOf(specifier);
+    if (name === null)
+        return null;
+    const { forbidden, patterns } = feStack();
+    return forbidden.get(name) ?? patterns.find(({ expression }) => expression.test(name))?.concern ?? null;
+};
+/**
+ * The canonical packages of a concern.
+ *
+ * @param id - The concern id (`icons`, `graphql`, ...).
+ * @returns Its packages; empty for an unknown concern.
+ */
+export const canonicalPackages = (id) => feStack().concerns.find((concern) => concern.id === id)?.packages ?? [];