@starci/eslint-canon-fe 9.2.0 → 9.4.0

package/dist/env-owner.js

@@ -0,0 +1,291 @@
+/**
+ * The rules that hold `env-owner.md` (HFS R49, `FE_ENV_OWNER`).
+ *
+ * TWO FACTS, ONE OWNER. The environment is read in exactly one place, `modules/config`, and what it
+ * reads has no default that stands in for a real deployment value. They are one law because they
+ * fail together: an app with nine copies of `process.env.API_URL ?? "http://localhost:3068"` had
+ * nine readers and nine silent defaults, so a production build with the variable missing talked to
+ * a developer's laptop and looked healthy.
+ *
+ * The rules cannot see whether `modules/config` throws when a variable is missing in production -
+ * that is a behaviour, and the module's own spec is where it is proven. What they hold is the
+ * shape that makes it provable: one reader, and no literal fallback next to it.
+ */
+import { defineRule } from "./lib/rule.js";
+import { isConfigModule } from "./lib/scope.js";
+/** `process.env`, or `import.meta.env`. */
+const isEnvObject = (node) => {
+    if (!node || node.type !== "MemberExpression" || node.computed)
+        return false;
+    const name = node.property && node.property.name;
+    if (name !== "env")
+        return false;
+    const object = node.object;
+    if (object.type === "Identifier" && object.name === "process")
+        return true;
+    return (object.type === "MetaProperty" && object.meta.name === "import" && object.property.name === "meta");
+};
+/** The variable name of `process.env.NAME` / `process.env["NAME"]`, or null. */
+const envVariableName = (node) => {
+    if (!node || node.type !== "MemberExpression" || !isEnvObject(node.object))
+        return null;
+    if (!node.computed && node.property.type === "Identifier")
+        return node.property.name;
+    if (node.computed && node.property.type === "Literal" && typeof node.property.value === "string") {
+        return node.property.value;
+    }
+    return null;
+};
+/** Static text of a literal or an expression-free template, else null. */
+const staticText = (node) => {
+    if (!node)
+        return null;
+    if (node.type === "Literal" && typeof node.value === "string")
+        return node.value;
+    if (node.type === "TemplateLiteral") {
+        return node.quasis.map((quasi) => quasi.value.cooked ?? "").join("");
+    }
+    return null;
+};
+/** An absolute or protocol-relative URL: what a fallback must never carry. */
+const URL_TEXT = /^(?:https?:)?\/\/\S+/i;
+/** Variable names whose value is a secret or an address: a default for one is a hole in a deployment. */
+const SENSITIVE_NAME = /(?:SECRET|TOKEN|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY|URL|URI|HOST|ENDPOINT|ORIGIN)$/i;
+/** Type assertions and optional chains preserve the identity of the wrapped value. */
+const unwrapped = (node) => {
+    while (node && (node.type === "TSAsExpression" || node.type === "TSTypeAssertion" || node.type === "TSNonNullExpression" || node.type === "TSSatisfiesExpression" || node.type === "ChainExpression"))
+        node = node.expression;
+    return node;
+};
+/** The binding of this identifier, rather than every variable with the same spelling. */
+const bindingOf = (sourceCode, identifier) => {
+    for (let scope = sourceCode.getScope(identifier); scope; scope = scope.upper) {
+        const variable = scope.set.get(identifier.name);
+        if (variable)
+            return variable;
+    }
+    return null;
+};
+/** Prior writes in the use's execution scope or its parents; a closure can capture a later initializer. */
+const writeBefore = (sourceCode, variable, node) => {
+    const scopes = new Set();
+    for (let scope = sourceCode.getScope(node); scope; scope = scope.upper)
+        scopes.add(scope.variableScope);
+    const writes = variable.references.filter((reference) => reference.isWrite()
+        && scopes.has(reference.from.variableScope)
+        && !(reference.writeExpr && reference.writeExpr.range[0] <= node.range[0] && node.range[1] <= reference.writeExpr.range[1]));
+    return writes
+        .filter((reference) => reference.identifier.range[0] < node.range[0])
+        .sort((left, right) => right.identifier.range[0] - left.identifier.range[0])[0]
+        ?? writes.find((reference) => reference.init);
+};
+/** Property extraction between a write's source and its destructured binding. */
+const propertyPath = (identifier) => {
+    const properties = [];
+    for (let node = identifier; node.parent; node = node.parent) {
+        const parent = node.parent;
+        if (parent.type === "Property" && parent.value === node)
+            properties.unshift(parent);
+        else if (parent.type !== "ObjectPattern" && !(parent.type === "AssignmentPattern" && parent.left === node))
+            break;
+    }
+    return properties;
+};
+/** The first quasi of a template literal: the parser always gives one. */
+const firstQuasi = (node) => {
+    const quasi = node.quasis[0];
+    if (quasi === undefined)
+        throw new TypeError("a template literal without a quasi");
+    return quasi;
+};
+/** The module an import binding comes from; an import-equals declaration has no `source`, which stops the run as it always has. */
+const importSource = (parent) => {
+    if (parent.type !== "ImportDeclaration")
+        throw new TypeError("Cannot read properties of undefined (reading 'value')");
+    return parent.source.value;
+};
+/** True for the specifier of Node's process module. */
+const isProcessModule = (source) => source === "process" || source === "node:process";
+/** The import kind of the declaration that holds an import binding. */
+const importKindOf = (parent) => parent.importKind;
+/** Known environment containers and constant computed keys, followed through local aliases. */
+const environmentIdentity = (sourceCode) => {
+    const textOf = (start, seen = new Set()) => {
+        let node = start;
+        node = unwrapped(node);
+        if (!node || seen.has(node))
+            return null;
+        if (node.type === "Literal" && typeof node.value === "string")
+            return node.value;
+        if (node.type === "TemplateLiteral" && node.expressions.length === 0)
+            return firstQuasi(node).value.cooked;
+        if (node.type !== "Identifier")
+            return null;
+        const variable = bindingOf(sourceCode, node);
+        if (!variable)
+            return null;
+        const write = writeBefore(sourceCode, variable, node);
+        if (!write?.writeExpr || propertyPath(write.identifier).length > 0)
+            return null;
+        return textOf(write.writeExpr, new Set([...seen, node]));
+    };
+    const keyOf = (node) => {
+        const key = node.type === "Property" ? node.key : node.property;
+        if (node.computed)
+            return textOf(key);
+        if (key.type === "Identifier" || key.type === "PrivateIdentifier")
+            return key.name;
+        return key.type === "Literal" ? key.value : undefined;
+    };
+    const propertyKind = (kind, key) => {
+        if (kind === "global" && key === "process")
+            return "process";
+        if ((kind === "process" || kind === "meta") && key === "env")
+            return "env";
+        return null;
+    };
+    const kindOf = (start, seen = new Set()) => {
+        const node = unwrapped(start);
+        if (!node || seen.has(node))
+            return null;
+        if (node.type === "MetaProperty" && node.meta.name === "import" && node.property.name === "meta")
+            return "meta";
+        if (node.type === "MemberExpression")
+            return propertyKind(kindOf(node.object, new Set([...seen, node])), keyOf(node));
+        if (node.type !== "Identifier")
+            return null;
+        const variable = bindingOf(sourceCode, node);
+        if (!variable || variable.defs.length === 0) {
+            if (node.name === "process")
+                return "process";
+            return ["globalThis", "global"].includes(node.name) ? "global" : null;
+        }
+        const imported = variable.defs.find((definition) => definition.type === "ImportBinding" && isProcessModule(importSource(definition.parent)));
+        if (imported && imported.type === "ImportBinding") {
+            if (importKindOf(imported.parent) === "type" || (imported.node.type === "ImportSpecifier" && imported.node.importKind === "type"))
+                return null;
+            if (imported.node.type !== "ImportSpecifier")
+                return "process";
+            const name = imported.node.imported.type === "Identifier" ? imported.node.imported.name : imported.node.imported.value;
+            return name === "default" ? "process" : name === "env" ? "env" : null;
+        }
+        const write = writeBefore(sourceCode, variable, node);
+        if (!write?.writeExpr)
+            return null;
+        let kind = kindOf(write.writeExpr, new Set([...seen, node]));
+        for (const property of propertyPath(write.identifier))
+            kind = propertyKind(kind, keyOf(property));
+        return kind;
+    };
+    const readsEnv = (pattern, kind) => {
+        if (pattern.type === "AssignmentPattern")
+            return readsEnv(pattern.left, kind);
+        if (pattern.type !== "ObjectPattern")
+            return false;
+        return pattern.properties.some((property) => {
+            if (property.type !== "Property")
+                return false;
+            const valueKind = propertyKind(kind, keyOf(property));
+            return valueKind === "env" || readsEnv(property.value, valueKind);
+        });
+    };
+    return { kindOf, readsEnv };
+};
+// -- FE-ENV-1 --------------------------------------------------------------------------------------
+/** Only `modules/config` reads the environment. */
+export const noEnvOutsideConfig = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "`process.env` and `import.meta.env` are read only in `modules/config`." },
+        schema: [],
+        messages: {
+            env: "This file reads the environment. Only `modules/config` may: it is the one place that can fail loudly when a production variable is missing. Read the value from the config module's typed export instead.",
+        },
+    },
+    create(context) {
+        if (isConfigModule(context))
+            return {};
+        const members = [];
+        const destructures = [];
+        return {
+            ImportDeclaration(node) {
+                if (node.importKind === "type" || !["process", "node:process"].includes(node.source.value))
+                    return;
+                for (const specifier of node.specifiers) {
+                    if (specifier.type === "ImportSpecifier" && specifier.importKind !== "type" && (specifier.imported.type === "Identifier" ? specifier.imported.name : specifier.imported.value) === "env")
+                        context.report({ node: specifier, messageId: "env" });
+                }
+            },
+            MemberExpression(node) {
+                members.push(node);
+            },
+            VariableDeclarator(node) {
+                if (node.id.type === "ObjectPattern" && node.init)
+                    destructures.push({ node, pattern: node.id, value: node.init });
+            },
+            AssignmentExpression(node) {
+                if (node.operator === "=" && node.left.type === "ObjectPattern")
+                    destructures.push({ node, pattern: node.left, value: node.right });
+            },
+            AssignmentPattern(node) {
+                if (node.left.type === "ObjectPattern")
+                    destructures.push({ node, pattern: node.left, value: node.right });
+            },
+            "Program:exit"() {
+                const { kindOf, readsEnv } = environmentIdentity(context.sourceCode ?? context.getSourceCode());
+                for (const node of members) {
+                    if (kindOf(node) === "env")
+                        context.report({ node, messageId: "env" });
+                }
+                for (const { node, pattern, value } of destructures) {
+                    if (readsEnv(pattern, kindOf(value)))
+                        context.report({ node, messageId: "env" });
+                }
+            },
+        };
+    },
+});
+// -- FE-ENV-2 --------------------------------------------------------------------------------------
+/** A fallback never stands in for a deployment address or secret. */
+export const noHardcodedEndpointFallback = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "No URL literal as a fallback, and no literal default for an address or secret variable." },
+        schema: [],
+        messages: {
+            url: "A URL literal used as a fallback (`?? \"http://...\"`, `|| \"http://...\"` or a parameter default). A missing variable then silently points production at a developer's machine. Read the address from `modules/config`, which throws when it is absent.",
+            variable: "`{{name}}` is an address or secret variable with a literal default. A default here makes a misconfigured deployment look healthy. Remove the default and let `modules/config` fail loudly when it is missing.",
+        },
+    },
+    create(context) {
+        return {
+            LogicalExpression(node) {
+                if (node.operator !== "??" && node.operator !== "||")
+                    return;
+                const text = staticText(node.right);
+                if (text === null)
+                    return;
+                if (URL_TEXT.test(text)) {
+                    context.report({ node: node.right, messageId: "url" });
+                    return;
+                }
+                const name = envVariableName(node.left);
+                if (name && text !== "" && SENSITIVE_NAME.test(name)) {
+                    context.report({ node: node.right, messageId: "variable", data: { name } });
+                }
+            },
+            AssignmentPattern(node) {
+                const text = staticText(node.right);
+                if (text !== null && URL_TEXT.test(text))
+                    context.report({ node: node.right, messageId: "url" });
+            },
+        };
+    },
+});
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "no-env-outside-config": noEnvOutsideConfig,
+    "no-hardcoded-endpoint-fallback": noHardcodedEndpointFallback,
+};
+/** Both are exact syntactic shapes, and both are errors. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]));

package/dist/fe-stack.d.ts

@@ -0,0 +1,10 @@
+import { type Rules, type Recommended } from "./lib/rule.js";
+/**
+ * No import (static, re-export, dynamic or `require`) of a package the fe-stack catalog forbids, and no `@supabase/*` outside
+ * `modules/auth`. Type-only imports count: a type import still makes the package a dependency of the front end.
+ */
+export declare const feStackImport: import("./lib/rule.js").Rule<"forbidden" | "supabase", []>;
+/** The rules this law contributes to the plugin. */
+export declare const rules: Rules;
+/** Every rule is an error: a second library for a concern is the defect, not a style. */
+export declare const recommended: Recommended;

package/dist/fe-stack.js

@@ -0,0 +1,73 @@
+import { defineRule } from "./lib/rule.js";
+import { forbiddingConcern, packageNameOf } from "./lib/fe-stack.js";
+import { globalReferences, inSlot, isProductSource } from "./lib/scope.js";
+/** The package scope only the identity-provider client may import. */
+const SUPABASE_SCOPE = "@supabase/";
+/**
+ * No import (static, re-export, dynamic or `require`) of a package the fe-stack catalog forbids, and no `@supabase/*` outside
+ * `modules/auth`. Type-only imports count: a type import still makes the package a dependency of the front end.
+ */
+export const feStackImport = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "A front end imports no library the fe-stack catalog forbids, and `@supabase/*` only in `modules/auth`." },
+        schema: [],
+        messages: {
+            forbidden: "`{{name}}` is a forbidden alternative for the {{concern}} concern of the front-end stack. The stack has one library per concern, the same in every app and both editions: use {{canonical}} ({{pattern}}). {{why}}",
+            supabase: "`{{name}}` is imported outside `modules/auth`. Supabase on the front end is the auth client only, held by `modules/auth` (the session, the access token the Apollo link attaches, sign-in and sign-out); data is read and written through the GraphQL operations of `modules/api`, never through Supabase from the browser.",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context))
+            return {};
+        const authOwner = inSlot(context, "fe.modules.auth");
+        const judge = (node, source) => {
+            const name = packageNameOf(source);
+            if (name === null || name === undefined)
+                return;
+            const concern = forbiddingConcern(source);
+            if (concern) {
+                const named = (concern.packages?.length ?? 0) > 0 ? concern.packages ?? [] : concern.home ?? [];
+                const canonical = named.map((entry) => `\`${entry}\``).join(", ");
+                context.report({ node, messageId: "forbidden", data: { name, concern: concern.id, canonical, pattern: concern.pattern ?? "", why: concern.why ?? "" } });
+                return;
+            }
+            if (name.startsWith(SUPABASE_SCOPE) && !authOwner)
+                context.report({ node, messageId: "supabase", data: { name } });
+        };
+        return {
+            ImportDeclaration(node) {
+                judge(node, node.source.value);
+            },
+            ExportNamedDeclaration(node) {
+                if (node.source)
+                    judge(node, node.source.value);
+            },
+            ExportAllDeclaration(node) {
+                judge(node, node.source.value);
+            },
+            ImportExpression(node) {
+                if (node.source.type === "Literal")
+                    judge(node, node.source.value);
+            },
+            TSImportEqualsDeclaration(node) {
+                // `import x = require("moment")`
+                if (node.moduleReference?.type === "TSExternalModuleReference" && node.moduleReference.expression?.type === "Literal")
+                    judge(node, node.moduleReference.expression.value);
+            },
+            CallExpression(node) {
+                // `require("moment")` where `require` is the CommonJS global.
+                if (node.callee.type !== "Identifier" || node.callee.name !== "require" || node.arguments[0]?.type !== "Literal")
+                    return;
+                if (globalReferences(context, new Set(["require"])).includes(node.callee))
+                    judge(node, node.arguments[0].value);
+            },
+        };
+    },
+});
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "fe-stack-import": feStackImport,
+};
+/** Every rule is an error: a second library for a concern is the defect, not a style. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]));

package/dist/file-layout.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The rules that hold `file-layout.md`.
+ *
+ * Four rules locking the same habit: stuffing a cluster into the folder of one screen. It always
+ * starts harmlessly - "only this page uses it" - and ends as a page folder holding four components,
+ * a constants folder, a utils folder and three hand-copied resting shapes, at which point the
+ * screen is a second codebase with its own private vocabulary that nobody else can reuse.
+ *
+ * Every rule here asks the HFS slot view where the file sits (slot, layer kind, role, tier) rather than
+ * reading the contents, which is what makes them cheap and exact. The cost of that choice is stated where it
+ * bites: a slot cannot tell a component from a helper, only a folder from a folder, so each rule below names the
+ * destination it sends things to rather than merely refusing.
+ */
+import { type Rules, type Recommended } from "./lib/rule.js";
+/** A page, layout or overlay folder holds its two halves and its colocated class-name module. */
+export declare const surfaceFolderTwoFilesOnly: import("./lib/rule.js").Rule<"extra", []>;
+/** What is not component code does not live in the component tree. */
+export declare const noHelperFolderInComponents: import("./lib/rule.js").Rule<"helper", []>;
+/** A PascalCase folder exports a family whose name belongs to the folder. */
+export declare const exportMatchesFolder: import("./lib/rule.js").Rule<"mismatch", []>;
+/** A folder exports a family, never one runtime object standing in for a namespace. */
+export declare const noRuntimeNamespace: import("./lib/rule.js").Rule<"namespace", []>;
+/**
+ * In a front end with two or more apps, the shared package stops below the block.
+ *
+ * WHY THE SLOT IS ENOUGH HERE. The feature line is already drawn by the layer: a leaf knows
+ * no domain and a block is a domain sentence, so which side of the workspace each belongs on
+ * follows from the layer the slot reports. The layers a shared package may hold are the `kinds` of
+ * `fe.package.ui`; an app holds the shared ones only when the repository declares that package and another app can
+ * consume them. A one-app front end has nothing to share, so every tier may stay with that app.
+ *
+ * WHAT IT COST TO LEARN. A shared package carried one `blocks/WorkerRow/` while its own header
+ * insisted that "a block carries feature meaning and therefore belongs to the app that owns the
+ * feature". The document was right, the tree disagreed, and nothing turned red for either of them -
+ * which is the whole argument for this rule rather than the paragraph.
+ */
+export declare const monorepoTierBelongsToItsSide: import("./lib/rule.js").Rule<"featureInPackage" | "vocabularyInApp", []>;
+/**
+ * A file under `app/` names which page renders at which URL, and does nothing else.
+ *
+ * WHY THIS RULE EXISTS RATHER THAN THE PARAGRAPH ALONE. The law said "the route file mounts and
+ * nothing else" and had said so for as long as the tier list existed. Nothing checked it. A page
+ * owner was written to `app/<segment>/workers-page.tsx`, carried through a build, a lint run, a
+ * typecheck, four sealed screenshots and an approval, and arrived at the edge of a production write
+ * with every gate green - because every gate was reading rules, and this one was only prose.
+ *
+ * WHY IT READS THE SLOT AND NOT THE CONTENTS. "Drawing" is not a property this can measure: a
+ * route that mounts one component and a route that arranges six both return JSX. What CAN be
+ * measured exactly is whether a file in the routing tree (slot `fe.route`) is one of the framework's own slots. A page
+ * owner is a component, a component has a name, and a named component belongs in the tier that
+ * groups it with its siblings - `components/pages/<Name>/`, where the next author looks for it.
+ *
+ * The cost is stated where it bites: a route file that draws inside `page.tsx` still passes. That is
+ * FILE-2's `component.tsx` split to catch, and no path rule can see it.
+ */
+export declare const routeTreeHoldsRoutesOnly: import("./lib/rule.js").Rule<"stray", []>;
+/** `meta.shape` must tell the same truth as the source path. */
+export declare const sourceTierMarkerMatchesFolder: import("./lib/rule.js").Rule<"mismatch", []>;
+/** `shells/` is not a tier; vendor mechanics are closed named branches. */
+export declare const noShellTier: import("./lib/rule.js").Rule<"shell", []>;
+export declare const routeSlotFixedName: import("./lib/rule.js").Rule<"missing" | "wrong" | "anonymous", []>;
+export declare const rules: Rules;
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * A consuming repository's `eslint.config.mjs` stays the authority on what is actually switched on.
+ * `export-matches-folder` is the one worth adopting at `warn` first in an existing tree: it fires
+ * on every folder whose convention predates the rule, and that count is a migration rather than a
+ * defect.
+ */
+export declare const recommended: Recommended;