@starci/eslint-canon-fe 9.2.0 → 9.4.0

package/dist/props-and-slots.d.ts

@@ -0,0 +1,19 @@
+/** Rules for named React props, ordinary children, and local visual ownership. */
+import { type Rules, type Recommended } from "./lib/rule.js";
+/** Reject anonymous object types on named component parameters. */
+export declare const noInlineParameterType: import("./lib/rule.js").Rule<"inline", []>;
+/** Require exported React components to take no parameter, or one named props parameter. */
+export declare const publicComponentSignature: import("./lib/rule.js").Rule<"type" | "parameter", []>;
+/** Prevent callers from styling internal component parts through named CSS props. */
+export declare const noPerPartClassNameProp: import("./lib/rule.js").Rule<"perPart", []>;
+/** Keep component appearance local instead of exposing className placement doors. */
+export declare const noPublicClassNameProp: import("./lib/rule.js").Rule<"declaration" | "usage", []>;
+/** Keep layout APIs semantic rather than exposing raw CSS decisions above leaves. */
+export declare const noPublicFrameCssProps: import("./lib/rule.js").Rule<"css", []>;
+/** Prevent utility types from reintroducing public styling doors. */
+export declare const noCssDoorTypeLaundering: import("./lib/rule.js").Rule<"utility", []>;
+/** Props are readonly all the way down: every field, index signature, nested object and collection (FE-TYPING-2). */
+export declare const propsFieldsReadonly: import("./lib/rule.js").Rule<"index" | "field" | "collection", []>;
+export declare const rules: Rules;
+/** All rules in this law are mechanical errors once adopted. */
+export declare const recommended: Recommended;

package/dist/props-and-slots.js

@@ -0,0 +1,320 @@
+/** Rules for named React props, ordinary children, and local visual ownership. */
+import { defineRule } from "./lib/rule.js";
+import { declarationsOf, fileOf as declarationFile } from "./lib/types.js";
+import { isComponentFile, isComponentPath, isProductSource, kindOfFile } from "./lib/scope.js";
+/** The key of a node that names a member (`key`), or the property of a member access. */
+const memberKey = (node) => {
+    if (!node)
+        return undefined;
+    if ("key" in node && node.key)
+        return node.key;
+    return "property" in node ? node.property : undefined;
+};
+const propertyName = (node) => {
+    const key = memberKey(node);
+    if (!key)
+        return null;
+    if (key.type === "Identifier")
+        return key.name;
+    if (key.type === "Literal" && typeof key.value === "string")
+        return key.value;
+    return null;
+};
+/** Reject anonymous object types on named component parameters. */
+export const noInlineParameterType = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: { description: "A parameter uses a named props type, not an inline object shape." },
+        schema: [],
+        messages: { inline: "Name this parameter type in the module so the component API can be reused." },
+    },
+    create(context) {
+        const check = (node) => {
+            for (const param of node.params || []) {
+                const annotation = "typeAnnotation" in param ? param.typeAnnotation : undefined;
+                const type = annotation?.typeAnnotation;
+                if (type?.type === "TSTypeLiteral" || type?.type === "TSIntersectionType" && type.types.some((item) => item.type === "TSTypeLiteral")) {
+                    context.report({ node: annotation || param, messageId: "inline" });
+                }
+            }
+        };
+        return { ArrowFunctionExpression: check, FunctionExpression: check, FunctionDeclaration: check };
+    },
+});
+const isExported = (node) => node.parent?.type === "ExportNamedDeclaration" || node.parent?.parent?.type === "ExportNamedDeclaration";
+const containsJsx = (node, seen = new Set()) => {
+    if (!node || typeof node !== "object" || seen.has(node))
+        return false;
+    seen.add(node);
+    if ("type" in node && (node.type === "JSXElement" || node.type === "JSXFragment"))
+        return true;
+    return Object.entries(node).some(([key, value]) => key !== "parent" && (Array.isArray(value) ? value.some((item) => containsJsx(item, seen)) : containsJsx(value, seen)));
+};
+const componentNameOf = (node) => {
+    if (node.type !== "VariableDeclarator" || node.id?.type !== "Identifier" || !/^[A-Z]/.test(node.id.name) || !isExported(node))
+        return null;
+    return node.id.name;
+};
+/** Require exported React components to take no parameter, or one named props parameter. */
+export const publicComponentSignature = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "Exported React components take no parameter, or one parameter named props with a matching XProps type (XBase may also take XBaseProps)." },
+        schema: [],
+        messages: {
+            parameter: "Exported component {{name}} must be an arrow const with no parameter, or exactly one parameter named props.",
+            type: "Exported component {{name}} must type props as {{expected}}.",
+        },
+    },
+    create(context) {
+        const check = (name, fn) => {
+            if (!name || !fn)
+                return;
+            const params = fn.params || [];
+            if (params.length === 0)
+                return;
+            const [param] = params;
+            if (params.length !== 1 || param?.type !== "Identifier" || param.name !== "props") {
+                context.report({ node: fn, messageId: "parameter", data: { name } });
+                return;
+            }
+            const type = param.typeAnnotation?.typeAnnotation;
+            // XBase pairs with XBaseProps so the connected X keeps XProps for itself; XProps stays accepted for
+            // existing twins.
+            const expected = name.endsWith("Base") ? [`${name}Props`, `${name.slice(0, -4)}Props`] : [`${name}Props`];
+            const actual = type?.type === "TSTypeReference" && type.typeName?.type === "Identifier" ? type.typeName.name : null;
+            if (!actual || !expected.includes(actual))
+                context.report({ node: param, messageId: "type", data: { name, expected: expected.join(" or ") } });
+        };
+        if (!isComponentFile(context))
+            return {};
+        return {
+            VariableDeclarator(node) {
+                const name = componentNameOf(node);
+                if (name && node.init?.type === "ArrowFunctionExpression" && containsJsx(node.init))
+                    check(name, node.init);
+            },
+            FunctionDeclaration(node) {
+                if (!isExported(node) || !containsJsx(node))
+                    return;
+                context.report({ node, messageId: "parameter", data: { name: node.id?.name || "component" } });
+            },
+        };
+    },
+});
+/** Prevent callers from styling internal component parts through named CSS props. */
+export const noPerPartClassNameProp = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "Components do not expose per-part class name props." },
+        schema: [],
+        messages: { perPart: "Keep internal part styling owned by the component." },
+    },
+    create(context) {
+        if (!isComponentFile(context))
+            return {};
+        return { TSPropertySignature(node) { const name = propertyName(node); if (name && name !== "className" && /^[a-z][A-Za-z0-9]*ClassName$/.test(name))
+                context.report({ node, messageId: "perPart" }); } };
+    },
+});
+/** Keep component appearance local instead of exposing className placement doors. */
+export const noPublicClassNameProp = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "House components do not expose className or classNames props." },
+        schema: [],
+        messages: { declaration: "Component props must not expose {{prop}}.", usage: "Do not pass {{prop}} to house component {{component}}." },
+    },
+    create(context) {
+        const declared = isComponentFile(context);
+        /** A house component: the identifier resolves (through its import) to a file of a component layer. */
+        const isHouseComponent = (identifier) => declarationsOf(context, identifier).some((declaration) => isComponentPath(context, declarationFile(declaration)));
+        return {
+            TSPropertySignature(node) { if (declared && ["className", "classNames"].includes(propertyName(node) ?? ""))
+                context.report({ node, messageId: "declaration", data: { prop: propertyName(node) } }); },
+            JSXOpeningElement(node) {
+                const identifier = node.name?.type === "JSXIdentifier" ? node.name : null;
+                if (!identifier)
+                    return;
+                const styled = (node.attributes || []).filter((attribute) => attribute.type === "JSXAttribute" && attribute.name.type === "JSXIdentifier" && ["className", "classNames"].includes(attribute.name.name));
+                if (styled.length === 0 || !isHouseComponent(identifier))
+                    return;
+                for (const attribute of styled)
+                    context.report({ node: attribute, messageId: "usage", data: { prop: attribute.name.name, component: identifier.name } });
+            },
+        };
+    },
+});
+/** Keep layout APIs semantic rather than exposing raw CSS decisions above leaves. */
+export const noPublicFrameCssProps = defineRule({
+    meta: { type: "problem", docs: { description: "Non-leaf component props do not expose CSS-shaped frame decisions." }, schema: [], messages: { css: "Move {{prop}} into component-owned layout behavior." } },
+    create(context) {
+        if (!isComponentFile(context) || kindOfFile(context) === "leaves")
+            return {};
+        const cssProps = new Set(["gap", "padding", "align", "justify", "className", "classNames", "style", "inline", "nested"]);
+        return { TSPropertySignature(node) { const name = propertyName(node); if (name !== null && cssProps.has(name))
+                context.report({ node, messageId: "css", data: { prop: name } }); } };
+    },
+});
+/** Prevent utility types from reintroducing public styling doors. */
+export const noCssDoorTypeLaundering = defineRule({
+    meta: { type: "problem", docs: { description: "Omit, Pick, and Exclude cannot hide styling props." }, schema: [], messages: { utility: "Remove {{prop}} from the owning public type instead of hiding it with {{utility}}." } },
+    create(context) {
+        if (!isProductSource(context))
+            return {};
+        return { TSTypeReference(node) { const utility = node.typeName.type === "Identifier" ? node.typeName.name : null; const params = node.typeArguments?.params || []; if (!utility || !["Omit", "Pick", "Exclude"].includes(utility))
+                return; const second = params[1]; const keys = second?.type === "TSLiteralType" ? [literalValue(second)] : second !== undefined && "types" in second ? second.types.map((item) => (item.type === "TSLiteralType" ? literalValue(item) : undefined)) : []; const prop = keys.find((key) => typeof key === "string" && ["className", "classNames", "style"].includes(key)); if (prop)
+                context.report({ node, messageId: "utility", data: { utility, prop } }); } };
+    },
+});
+/** The top-level declaration of a type name in this file (`interface X` or `type X = ...`), or null. */
+/** The value a literal type spells (`"a"`, `1`, `true`); undefined for a template or unary literal type. */
+const literalValue = (type) => ("value" in type.literal ? type.literal.value : undefined);
+/** The node a finding on a props type is reported on. */
+const reportedNode = (type) => ("heritage" in type ? type.heritage : type);
+const localTypeDeclaration = (program, name) => {
+    for (const statement of program.body) {
+        const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+        if ((declaration?.type === "TSInterfaceDeclaration" || declaration?.type === "TSTypeAliasDeclaration") && declaration.id.name === name)
+            return declaration;
+    }
+    return null;
+};
+const firstParameterType = (fn) => {
+    const param = fn.params[0];
+    const annotated = param?.type === "AssignmentPattern" ? param.left : param;
+    return annotated !== undefined && "typeAnnotation" in annotated ? annotated.typeAnnotation?.typeAnnotation ?? null : null;
+};
+/** The exported functions of a file that render (contain JSX): a component, whatever it is called. */
+const exportedRenderers = (program) => program.body.flatMap((statement) => {
+    const declaration = statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration" ? statement.declaration : null;
+    if (!declaration)
+        return [];
+    const functions = declaration.type === "VariableDeclaration"
+        ? declaration.declarations.map((item) => item.init).filter((init) => init?.type === "ArrowFunctionExpression" || init?.type === "FunctionExpression")
+        : declaration.type === "FunctionDeclaration" || declaration.type === "ArrowFunctionExpression" || declaration.type === "FunctionExpression" ? [declaration] : [];
+    return functions.filter((fn) => fn.params.length === 1 && containsJsx(fn.body));
+});
+/** Props are readonly all the way down: every field, index signature, nested object and collection (FE-TYPING-2). */
+export const propsFieldsReadonly = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "Every field of a component's props type, nested objects and collections included, is readonly." },
+        schema: [],
+        messages: {
+            field: "Props field `{{name}}` is not readonly. A component reads its props and never writes them: mark it `readonly` so a write is a type error.",
+            index: "This props index signature is not readonly. Mark it `readonly [key: ...]` so no entry can be written through props.",
+            collection: "This props collection is mutable. Write `readonly T[]`, `readonly [A, B]` or `ReadonlyArray<T>` so the component cannot change what it was given.",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context))
+            return {};
+        const sourceCode = context.sourceCode || context.getSourceCode();
+        return {
+            "Program:exit"(program) {
+                const seen = new Set();
+                /** Checks one type: object members, collections and the local declarations it names. */
+                const checkType = (type) => {
+                    if (!type || seen.has(type))
+                        return;
+                    seen.add(type);
+                    if (type.type === "TSTypeOperator" && type.operator === "readonly") {
+                        checkElements(type.typeAnnotation);
+                        return;
+                    }
+                    if (type.type === "TSArrayType" || type.type === "TSTupleType") {
+                        context.report({ node: type, messageId: "collection" });
+                        checkElements(type);
+                        return;
+                    }
+                    if (type.type === "TSUnionType" || type.type === "TSIntersectionType") {
+                        for (const part of type.types)
+                            checkType(part);
+                        return;
+                    }
+                    if (type.type === "TSTypeLiteral") {
+                        checkMembers(type.members);
+                        return;
+                    }
+                    if (type.type !== "TSTypeReference" || type.typeName.type !== "Identifier")
+                        return;
+                    const name = type.typeName.name;
+                    const args = type.typeArguments?.params ?? [];
+                    // `Readonly<T>` makes the top level readonly; what T nests is still judged
+                    if (name === "Readonly" && args.length === 1 && !isShadowed(type.typeName)) {
+                        checkNested(args[0]);
+                        return;
+                    }
+                    if (name === "Array" && !isShadowed(type.typeName))
+                        context.report({ node: reportedNode(type), messageId: "collection" });
+                    if ((name === "Array" || name === "ReadonlyArray") && !isShadowed(type.typeName)) {
+                        for (const arg of args)
+                            checkType(arg);
+                        return;
+                    }
+                    const declaration = localTypeDeclaration(program, name);
+                    if (!declaration || seen.has(declaration))
+                        return;
+                    seen.add(declaration);
+                    if (declaration.type === "TSTypeAliasDeclaration")
+                        checkType(declaration.typeAnnotation);
+                    else {
+                        checkMembers(declaration.body.body);
+                        for (const heritage of declaration.extends ?? []) {
+                            if (heritage.expression.type === "Identifier")
+                                checkType({ type: "TSTypeReference", typeName: heritage.expression, typeArguments: heritage.typeArguments, heritage });
+                        }
+                    }
+                };
+                /** The element types of a collection, judged like any other props type. */
+                const checkElements = (collection) => {
+                    if (collection?.type === "TSArrayType")
+                        checkType(collection.elementType);
+                    else if (collection?.type === "TSTupleType")
+                        for (const element of collection.elementTypes)
+                            checkType(element.type === "TSNamedTupleMember" ? element.elementType : element);
+                    else
+                        checkType(collection);
+                };
+                /** A `Readonly<T>` argument: its own fields are readonly, its nested values are judged. */
+                const checkNested = (type) => {
+                    if (type?.type === "TSTypeLiteral")
+                        for (const member of type.members)
+                            checkType("typeAnnotation" in member ? member.typeAnnotation?.typeAnnotation : undefined);
+                    else
+                        checkType(type);
+                };
+                const checkMembers = (members) => {
+                    for (const member of members) {
+                        if (member.type === "TSPropertySignature") {
+                            if (!member.readonly)
+                                context.report({ node: member, messageId: "field", data: { name: sourceCode.getText(member.key) } });
+                            checkType(member.typeAnnotation?.typeAnnotation);
+                        }
+                        else if (member.type === "TSIndexSignature") {
+                            if (!member.readonly)
+                                context.report({ node: member, messageId: "index" });
+                            checkType(member.typeAnnotation?.typeAnnotation);
+                        }
+                    }
+                };
+                /** True when a built-in name is redeclared in this file, so it is not the built-in. */
+                const isShadowed = (identifier) => localTypeDeclaration(program, identifier.name) !== null;
+                for (const fn of exportedRenderers(program))
+                    checkType(firstParameterType(fn));
+            },
+        };
+    },
+});
+export const rules = {
+    "no-inline-parameter-type": noInlineParameterType,
+    "props-fields-readonly": propsFieldsReadonly,
+    "public-component-signature": publicComponentSignature,
+    "no-per-part-classname-prop": noPerPartClassNameProp,
+    "no-public-classname-prop": noPublicClassNameProp,
+    "no-public-frame-css-props": noPublicFrameCssProps,
+    "no-css-door-type-laundering": noCssDoorTypeLaundering,
+};
+/** All rules in this law are mechanical errors once adopted. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]));

package/dist/served-locale.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Rules for the SERVED LOCALE law - `patterns/fe/served-locale/INDEX.md`.
+ *
+ * WHY THESE EXIST. An application obeyed the translation law completely - every label resolved in a
+ * connected half, no literal below a block, both catalogues in step - and served a Vietnamese reader
+ * an English course on a `/vi/` URL. The chrome came from the dictionary and the content came from an
+ * API that was never told which language to serve, so the failure looked like a translation gap and
+ * was looked for in the dictionary, where there was nothing wrong. The header was missing, and no
+ * gate had anything to say about a header nobody wrote.
+ *
+ * WHAT THEY HOLD. That the transport chain declares a locale, and that exactly one place writes it.
+ * Both are file-at-a-time facts: the chain is assembled in one file, and a header is written where it
+ * is written.
+ *
+ * WHAT THEY CANNOT HOLD, stated rather than implied. Neither rule can tell whether the value the link
+ * computes is CORRECT - whether it reads the address, the cookie or a constant - because that is
+ * inside a function these rules only see the name of. A link that attaches `Accept-Language: "en"`
+ * unconditionally satisfies both and is wrong. That case is a review question and LOCALE-2 is where
+ * it is argued; pretending otherwise would be the rule claiming a guarantee it does not have.
+ *
+ * WHY THE FIRST RULE KEYS ON THE TERMINAL LINK RATHER THAN ON A FILE NAME. The clients folder (`modules/api/graphql/clients/`,
+ * slot `fe.transport.client`) holds the clients, their options and every link, and a file-name pattern that guessed which of
+ * them assembles the chain would either miss the real chain or fire on every helper beside it. The chain is identifiable by what it does: it builds the link
+ * that talks to the network.
+ *
+ * WITH ONE EXEMPTION THAT WAS FOUND BY RUNNING IT, NOT BY THINKING ABOUT IT. "Constructs the
+ * terminal link" is also true of the file that DEFINES that link, so the first version reported
+ * `links/http.ts` and its spec on a repository that had done everything right. There was no correct
+ * way to satisfy it there - a locale link inside the http link is a chain hiding in a link - and a
+ * rule with no correct way to satisfy it is a finding about the rule. A file under `links/` is one
+ * link; a chain is assembled elsewhere, which is where the locale belongs.
+ */
+import { type Recommended, type Rules } from "./lib/rule.js";
+/** The header a request declares its language in; HTTP header names are case-insensitive. */
+export declare const LOCALE_HEADER = "Accept-Language";
+export declare const rules: Rules;
+/** Every FE canon rule is an error; see `sources/fe/index.mjs` for why there is no warn tier. */
+export declare const recommended: Recommended;

package/dist/served-locale.js

@@ -0,0 +1,263 @@
+/**
+ * Rules for the SERVED LOCALE law - `patterns/fe/served-locale/INDEX.md`.
+ *
+ * WHY THESE EXIST. An application obeyed the translation law completely - every label resolved in a
+ * connected half, no literal below a block, both catalogues in step - and served a Vietnamese reader
+ * an English course on a `/vi/` URL. The chrome came from the dictionary and the content came from an
+ * API that was never told which language to serve, so the failure looked like a translation gap and
+ * was looked for in the dictionary, where there was nothing wrong. The header was missing, and no
+ * gate had anything to say about a header nobody wrote.
+ *
+ * WHAT THEY HOLD. That the transport chain declares a locale, and that exactly one place writes it.
+ * Both are file-at-a-time facts: the chain is assembled in one file, and a header is written where it
+ * is written.
+ *
+ * WHAT THEY CANNOT HOLD, stated rather than implied. Neither rule can tell whether the value the link
+ * computes is CORRECT - whether it reads the address, the cookie or a constant - because that is
+ * inside a function these rules only see the name of. A link that attaches `Accept-Language: "en"`
+ * unconditionally satisfies both and is wrong. That case is a review question and LOCALE-2 is where
+ * it is argued; pretending otherwise would be the rule claiming a guarantee it does not have.
+ *
+ * WHY THE FIRST RULE KEYS ON THE TERMINAL LINK RATHER THAN ON A FILE NAME. The clients folder (`modules/api/graphql/clients/`,
+ * slot `fe.transport.client`) holds the clients, their options and every link, and a file-name pattern that guessed which of
+ * them assembles the chain would either miss the real chain or fire on every helper beside it. The chain is identifiable by what it does: it builds the link
+ * that talks to the network.
+ *
+ * WITH ONE EXEMPTION THAT WAS FOUND BY RUNNING IT, NOT BY THINKING ABOUT IT. "Constructs the
+ * terminal link" is also true of the file that DEFINES that link, so the first version reported
+ * `links/http.ts` and its spec on a repository that had done everything right. There was no correct
+ * way to satisfy it there - a locale link inside the http link is a chain hiding in a link - and a
+ * rule with no correct way to satisfy it is a finding about the rule. A file under `links/` is one
+ * link; a chain is assembled elsewhere, which is where the locale belongs.
+ */
+import { isNode } from "./lib/ast.js";
+import { hfsOf } from "./lib/hfs.js";
+import { defineRule } from "./lib/rule.js";
+import { fileOf, isApiLayer, stem } from "./lib/scope.js";
+/**
+ * The name of the file when it sits directly in a `links/` folder of the API layer, else null.
+ *
+ * NO SLOT NAMES A LINK. The clients slots (`fe.transport.client`, `fe.package.api.client`) own their whole folder, so the API
+ * layer decides WHERE a link may be and the folder called `links` is the one fact left to the rule; the manifest would
+ * carry it as a role (`locale-link: links/locale.ts`) and this function would ask for that role instead.
+ */
+const linkFileName = (context) => {
+    if (!isApiLayer(context))
+        return null;
+    const parts = hfsOf(context).relative(fileOf(context)).split("/");
+    return parts.at(-2) === "links" ? parts.at(-1) ?? null : null;
+};
+/**
+ * The link file that owns the locale header.
+ *
+ * This is the ONE file allowed to write it: the `locale` link of a transport slot. The point of the second rule is that
+ * the header appears in one place, so that place has to be named somewhere, and a name is what the law and the rule can
+ * both refer to.
+ */
+const isLocaleLinkFile = (context) => {
+    const name = linkFileName(context);
+    return name !== null && stem(name) === "locale";
+};
+/**
+ * One link's own implementation, rather than a chain of them.
+ *
+ * WHY THIS EXEMPTION EXISTS, AND IT WAS MEASURED. The first version of the chain rule keyed only on
+ * "constructs the terminal link", which is true of the file that DEFINES that link - `links/http.ts`
+ * builds `new HttpLink(...)`, because that is its whole job. Run against real source it reported
+ * that file and its spec, and there was no correct way to satisfy it there: attaching a locale link
+ * inside the http link would be a chain hiding in a link.
+ *
+ * A file under `links/` is one link. A chain is assembled somewhere else, which is exactly where the
+ * locale belongs.
+ */
+const isLinkImplementationFile = (context) => linkFileName(context) !== null;
+/** The header a request declares its language in; HTTP header names are case-insensitive. */
+export const LOCALE_HEADER = "Accept-Language";
+/** The retired locale header is refused everywhere, including the locale link. */
+const RETIRED_LOCALE_HEADER = "x-locale";
+/** Callee names that construct the terminal link - the one that actually reaches the network. */
+const TERMINAL_LINK_CALLEES = new Set(["createHttpLink", "HttpLink", "createUploadLink", "BatchHttpLink"]);
+/** Callee names that attach the reader's locale to an operation. */
+const LOCALE_LINK_CALLEES = new Set(["createAttachLocaleLink", "createLocaleLink"]);
+/** The callee name of a call or `new` expression, when it has a plain one. */
+const calleeName = (node) => {
+    const callee = node.callee;
+    if (!callee)
+        return null;
+    if (callee.type === "Identifier")
+        return callee.name;
+    if (callee.type === "MemberExpression" && callee.property && callee.property.type === "Identifier") {
+        return callee.property.name;
+    }
+    return null;
+};
+/** Literal and expression-free template spellings identify the same header. */
+const stringOf = (node) => {
+    if (node?.type === "Literal" && typeof node.value === "string")
+        return node.value;
+    if (node?.type === "TemplateLiteral" && node.expressions.length === 0)
+        return firstQuasi(node).value.cooked;
+    return null;
+};
+/** The first quasi of a template literal: every template has one, so its absence stops the run as reading it always has. */
+const firstQuasi = (node) => {
+    const [first] = node.quasis;
+    if (first === undefined)
+        throw new TypeError("a template literal without a quasi");
+    return first;
+};
+/** Every static property spelling, without treating a computed variable as its identifier's name. */
+const keyOf = (node) => node.property.type === "Identifier" && !node.computed ? node.property.name : stringOf(node.property);
+/** Every string-ish key a property can carry, so `"Accept-Language"` and `["Accept-Language"]` read the same. */
+const propertyKeyOf = (property) => {
+    if (!property || property.type !== "Property")
+        return null;
+    const key = property.key;
+    if (!key)
+        return null;
+    if (key.type === "Identifier" && !property.computed)
+        return key.name;
+    return stringOf(key);
+};
+/** Resolve a receiver's binding, so an unrelated local `Headers` or `set` method stays unrelated. */
+const variableOf = (node, sourceCode) => {
+    for (let scope = sourceCode.getScope(node); scope; scope = scope.upper) {
+        const variable = scope.set.get(node.name);
+        if (variable)
+            return variable;
+    }
+    return null;
+};
+/** Global browser constructors and globals may be qualified, but cannot be shadowed. */
+const isNativeName = (node, name, sourceCode) => {
+    if (node?.type === "Identifier")
+        return node.name === name && !variableOf(node, sourceCode)?.defs.length;
+    return node?.type === "MemberExpression" && keyOf(node) === name &&
+        ["globalThis", "window"].some((global) => isNativeName(node.object, global, sourceCode));
+};
+/** Syntax establishes native Headers values and stable aliases; unknown or reassigned receivers are left alone. */
+/** The type a node is annotated with (`x: Headers`, `x as Headers`): the inside of a `: T` annotation, else the node's own `typeAnnotation`. */
+const annotationOf = (node) => {
+    const outer = Reflect.get(node, "typeAnnotation");
+    if (!isNode(outer))
+        return undefined;
+    const inner = Reflect.get(outer, "typeAnnotation");
+    return isNode(inner) ? inner : outer;
+};
+const isNativeInstance = (node, name, sourceCode, seen = new Set()) => {
+    if (!node || seen.has(node))
+        return false;
+    seen.add(node);
+    const annotation = annotationOf(node);
+    if (annotation?.type === "TSTypeReference" && isNativeName(annotation.typeName, name, sourceCode))
+        return true;
+    if (node.type === "TSAsExpression" || node.type === "TSNonNullExpression" || node.type === "ChainExpression")
+        return isNativeInstance(node.expression, name, sourceCode, seen);
+    if (node.type === "NewExpression")
+        return isNativeName(node.callee, name, sourceCode);
+    if (name === "Headers" && node.type === "MemberExpression" && keyOf(node) === "headers") {
+        return ["Request", "Response"].some((owner) => isNativeInstance(node.object, owner, sourceCode, new Set(seen)));
+    }
+    if (node.type !== "Identifier")
+        return false;
+    const variable = variableOf(node, sourceCode);
+    if (variable?.references.some((reference) => reference.isWrite() && !reference.init))
+        return false;
+    return (variable?.identifiers ?? []).some((identifier) => isNativeInstance(identifier, name, sourceCode, seen)) ||
+        (variable?.defs ?? []).some((definition) => definition.type === "Variable" && isNativeInstance(definition.node.init, name, sourceCode, seen));
+};
+/** The header-writing methods of `Headers`. */
+const HEADER_WRITES = ["set", "append"];
+export const rules = {
+    "api-client-attaches-the-locale": defineRule({
+        meta: {
+            type: "problem",
+            docs: {
+                description: "A transport chain that builds the terminal HTTP link must also attach the reader's locale, so every call declares the language it wants served.",
+            },
+            schema: [],
+            messages: {
+                missing: "This assembles the API transport but never attaches the reader's locale, so every call it makes is served the server's default language. Add the locale link to the chain, beside the auth link and unconditionally - a guest reads in a language too. A surface that is bilingual in its chrome and monolingual in its content reads as a translation gap, which is why it gets looked for in the dictionary rather than here.",
+            },
+        },
+        create(context) {
+            // A single link's implementation is not a chain - `links/http.ts` constructs the terminal link
+            // because defining it IS its job, and there is no correct way to attach a locale there. A
+            // spec asserts about a chain rather than being one.
+            if (isLinkImplementationFile(context))
+                return {};
+            let terminalNode = null;
+            let attachesLocale = false;
+            const note = (node) => {
+                const name = calleeName(node);
+                if (name === null)
+                    return;
+                if (TERMINAL_LINK_CALLEES.has(name))
+                    terminalNode = terminalNode || node;
+                if (LOCALE_LINK_CALLEES.has(name))
+                    attachesLocale = true;
+            };
+            return {
+                CallExpression: note,
+                NewExpression: note,
+                "Program:exit"() {
+                    if (terminalNode && !attachesLocale) {
+                        context.report({ node: terminalNode, messageId: "missing" });
+                    }
+                },
+            };
+        },
+    }),
+    "locale-header-belongs-to-the-link": defineRule({
+        meta: {
+            type: "problem",
+            docs: {
+                description: "The locale header is written by the locale link and nowhere else, so one place answers which language a request is in.",
+            },
+            schema: [],
+            messages: {
+                elsewhere: "Only the locale link may write `Accept-Language`. Setting it here is a second answer to which language this request is in, and the two diverge the first time one of them is updated - usually leaving a single hook correct and the rest of the surface on the server's default. Let the transport attach it.",
+                retired: "The `x-locale` header is retired. Declare the reader's language with `Accept-Language` in the locale link, the one place that owns it.",
+            },
+        },
+        create(context) {
+            const ownsLocale = isLocaleLinkFile(context);
+            const sourceCode = context.sourceCode ?? context.getSourceCode();
+            const checkHeader = (node, key) => {
+                const header = key?.toLowerCase();
+                if (header === RETIRED_LOCALE_HEADER) {
+                    context.report({ node, messageId: "retired" });
+                }
+                else if (header === LOCALE_HEADER.toLowerCase() && !ownsLocale) {
+                    context.report({ node, messageId: "elsewhere" });
+                }
+            };
+            return {
+                Property(node) {
+                    checkHeader(node, propertyKeyOf(node));
+                },
+                AssignmentExpression(node) {
+                    if (node.left.type === "MemberExpression")
+                        checkHeader(node, keyOf(node.left));
+                },
+                NewExpression(node) {
+                    const initial = node.arguments[0];
+                    if (!isNativeName(node.callee, "Headers", sourceCode) || initial?.type !== "ArrayExpression")
+                        return;
+                    for (const entry of initial.elements) {
+                        if (entry?.type === "ArrayExpression")
+                            checkHeader(entry, stringOf(entry.elements[0]));
+                    }
+                },
+                CallExpression(node) {
+                    const callee = node.callee;
+                    if (callee.type === "MemberExpression" && HEADER_WRITES.includes(keyOf(callee)) && isNativeInstance(callee.object, "Headers", sourceCode)) {
+                        checkHeader(node, stringOf(node.arguments[0]));
+                    }
+                },
+            };
+        },
+    }),
+};
+/** Every FE canon rule is an error; see `sources/fe/index.mjs` for why there is no warn tier. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]));