@starci/eslint-canon-fe 9.2.0 → 9.4.0

package/dist/swr-family.js

@@ -0,0 +1,419 @@
+/** R285: API operations are wrapped by the SWR family before product code calls them. */
+import { hfsOf } from "./lib/hfs.js";
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { stringOf, walk } from "./lib/ast.js";
+import { functionOf } from "./lib/bindings.js";
+import { defineRule } from "./lib/rule.js";
+import { classOf, fileOf, globalReferences, isApiLayer, isProductSource, resolveImport } from "./lib/scope.js";
+import { why } from "./lib/why.js";
+/** The SWR family names its wrapper files; entries and side-effect components are not wrappers. */
+const isSwrHook = (context) => {
+    const found = classOf(context);
+    return found.slot === "fe.hooks.swr" && !found.role && hfsOf(context).allows(fileOf(context))?.allowed === true;
+};
+/** Cache providers and revalidation may be used by consumers; only request hooks own operations. */
+const isRequestHook = (name) => /^useSWR(?:Immutable|Infinite|Mutation|Subscription)?$/.test(String(name)) || name === "default";
+const swrSource = (value) => value === "swr" || value.startsWith("swr/");
+const propertyName = (node) => node.computed ? (node.property.type === "Literal" ? node.property.value : undefined) : node.property.name;
+/** The name a module export specifier spells: an identifier, or a string such as `"a-b"`. */
+const exportName = (node) => (node.type === "Identifier" ? node.name : node.value);
+/** True for a specifier written `type x` inside a value import or export. */
+const isTypeSpecifier = (specifier) => (specifier.type === "ImportSpecifier" && specifier.importKind === "type") || (specifier.type === "ExportSpecifier" && specifier.exportKind === "type");
+/** The parent of a reference's identifier; a reference always sits inside an expression or a declaration. */
+const parentOfReference = (identifier) => {
+    const parent = identifier.parent;
+    if (parent === undefined)
+        throw new TypeError("Cannot read properties of undefined (reading 'type')");
+    return parent;
+};
+/** The module of the declaration holding an import binding; an import-equals declaration has none, which stops the run as it always has. */
+const declarationSource = (parent) => {
+    if (parent.type !== "ImportDeclaration")
+        throw new TypeError("Cannot read properties of undefined (reading 'value')");
+    return parent.source.value;
+};
+/** Runtime imports of the request hooks (including aliases) are confined to named SWR wrappers. */
+export const swrOnlyInFamily = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "FE_SWR_OUTSIDE_FAMILY: request hooks belong to fe.hooks.swr." },
+        schema: [],
+        messages: { outside: "FE_SWR_OUTSIDE_FAMILY: SWR request hooks belong in hooks/swr/. Call the operation's wrapper hook here; cache providers and revalidation remain available to consumers." },
+    },
+    create(context) {
+        if (!isProductSource(context) || isSwrHook(context))
+            return {};
+        const namespaces = new Set();
+        const report = (node) => context.report({ node, messageId: "outside" });
+        return {
+            ImportDeclaration(node) {
+                if (node.importKind === "type" || !swrSource(String(node.source.value)))
+                    return;
+                const runtime = node.specifiers.filter((s) => !isTypeSpecifier(s));
+                if (runtime.some((s) => s.type === "ImportDefaultSpecifier" ||
+                    (s.type === "ImportSpecifier" && isRequestHook(exportName(s.imported)))))
+                    report(node);
+                for (const specifier of runtime)
+                    if (specifier.type === "ImportNamespaceSpecifier")
+                        namespaces.add(specifier);
+            },
+            ExportNamedDeclaration(node) {
+                if (!node.source || node.exportKind === "type" || !swrSource(String(node.source.value)))
+                    return;
+                if (node.specifiers.some((s) => s.exportKind !== "type" && isRequestHook(exportName(s.local))))
+                    report(node);
+            },
+            ExportAllDeclaration(node) {
+                if (node.exportKind !== "type" && swrSource(String(node.source.value)))
+                    report(node);
+            },
+            ImportExpression(node) {
+                if (node.source.type === "Literal" && swrSource(String(node.source.value)))
+                    report(node);
+            },
+            CallExpression(node) {
+                const [first] = node.arguments;
+                if (node.callee.type === "Identifier" && node.callee.name === "require" && first?.type === "Literal" &&
+                    swrSource(String(first.value)) && globalReferences(context, new Set(["require"])).includes(node.callee))
+                    report(node);
+            },
+            "Program:exit"() {
+                const source = context.sourceCode ?? context.getSourceCode();
+                for (const specifier of namespaces) {
+                    const variable = source.getDeclaredVariables(specifier.parent).find((v) => v.name === specifier.local.name);
+                    for (const reference of variable?.references ?? []) {
+                        const id = reference.identifier;
+                        const member = parentOfReference(id);
+                        // Passing or destructuring the namespace also makes its request hooks available outside the family.
+                        if (member.type !== "MemberExpression" || member.object !== id || member.computed && member.property.type !== "Literal" ||
+                            isRequestHook(propertyName(member)))
+                            report(id);
+                    }
+                }
+            },
+        };
+    },
+});
+/** The slot of the stream reader: only a stream operation of the API layer imports it, never an SWR hook, even inside a fetcher. */
+const STREAM_READER_SLOT = "fe.transport.stream";
+/** The slots of the result vocabulary: types, never operations. */
+const OUTCOME_SLOTS = ["fe.transport.outcome", "fe.package.api.outcome"];
+/** The slots that hold API operations. */
+const OPERATION_SLOTS = ["fe.modules.api", "fe.package.api", "fe.transport.client", "fe.transport.stream", "fe.package.api.client"];
+/** The `name` of a parsed package.json; reading it from `null` throws, as it always has. */
+const manifestName = (manifest) => {
+    if (manifest === null || manifest === undefined)
+        throw new TypeError("Cannot read properties of null (reading 'name')");
+    return typeof manifest === "object" && "name" in manifest ? manifest.name : undefined;
+};
+/** Type imports stay available; the API layer may compose its own operations and helpers. */
+const isOperationSource = (context, value, only) => {
+    if (typeof value !== "string")
+        return false;
+    const hfs = hfsOf(context);
+    let target = resolveImport(context, value);
+    if (target === null) {
+        // Workspace package names are read from their actual manifests, never inferred from a suffix.
+        let folders;
+        try {
+            folders = readdirSync(join(hfs.repoRoot, "packages"), { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const folder of folders) {
+            if (!folder.isDirectory())
+                continue;
+            const root = join(hfs.repoRoot, "packages", folder.name);
+            if (hfs.slotOf(join(root, "src", "index.ts")) !== "fe.package.api")
+                continue;
+            let name;
+            try {
+                name = manifestName(JSON.parse(readFileSync(join(root, "package.json"), "utf8")));
+            }
+            catch {
+                continue;
+            }
+            if (typeof name !== "string" || !(value === name || value.startsWith(`${name}/`)))
+                continue;
+            target = value === name ? join(root, "src", "index.ts") : join(root, "src", value.slice(name.length + 1));
+            break;
+        }
+        if (target === null)
+            return false;
+    }
+    // Prefer the actual file before a hypothetical barrel: outcome types have a more specific slot.
+    const candidates = /\.[cm]?[jt]sx?$/.test(target) ? [target] : [`${target}.ts`, `${target}.tsx`, `${target}/index.ts`, `${target}/index.tsx`, target];
+    const found = candidates.map((file) => hfs.classify(file)).filter((entry) => entry.status === "owned");
+    if (found.some((entry) => OUTCOME_SLOTS.includes(entry.slot)))
+        return false;
+    if (only !== undefined)
+        return found.some((entry) => entry.slot === only);
+    return found.some((entry) => OPERATION_SLOTS.includes(entry.slot));
+};
+/** The generated input-bounds module holds constants and a pure reader derived from the contract, never an operation. */
+const BOUNDS_MODULE = /(?:^|\/)__generated__\/input-bounds\.ts$/;
+const RE_EXPORT = /export\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g;
+const ENTRY = /^\s*(type\s+)?([\w$]+)(?:\s+as\s+([\w$]+))?\s*$/;
+/** True when the named export of `target` is, through a chain of relative named re-exports, defined by a generated input-bounds module. */
+const isBoundsExport = (target, name, depth = 0) => {
+    if (depth > 4)
+        return false;
+    for (const file of [`${target}.ts`, `${target}/index.ts`, target]) {
+        if (BOUNDS_MODULE.test(file.replaceAll("\\", "/")))
+            return true;
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const [, list, source] of text.matchAll(RE_EXPORT)) {
+            if (list === undefined || source === undefined || !source.startsWith("."))
+                continue;
+            for (const entry of list.split(",")) {
+                const [, kind, origin, exported] = ENTRY.exec(entry) ?? [];
+                if (origin !== undefined && kind === undefined && (exported ?? origin) === name && isBoundsExport(resolve(dirname(file), source), origin, depth + 1))
+                    return true;
+            }
+        }
+    }
+    return false;
+};
+/** The specifiers of an import or a re-export; the other inspected nodes have none. */
+const specifiersOf = (node) => node.type === "ImportDeclaration" || node.type === "ExportNamedDeclaration" ? node.specifiers : undefined;
+/** An import of named values that all come from a generated input-bounds module is data, not an operation. */
+const importsOnlyBounds = (context, node, value) => {
+    const specifiers = specifiersOf(node)?.filter((s) => !isTypeSpecifier(s)) ?? [];
+    if (!specifiers.length || typeof value !== "string")
+        return false;
+    const target = resolveImport(context, value);
+    if (target === null)
+        return false;
+    return specifiers.every((s) => {
+        const name = s.type === "ImportSpecifier" ? exportName(s.imported) : s.type === "ExportSpecifier" ? exportName(s.local) : undefined;
+        return name !== undefined && isBoundsExport(target, name);
+    });
+};
+const unwrap = (start) => {
+    let node = start;
+    while (node && (node.type === "ChainExpression" || node.type === "TSAsExpression" || node.type === "TSNonNullExpression" || node.type === "TSInstantiationExpression"))
+        node = node.expression;
+    return node;
+};
+/** Resolve lexical bindings so renamed imports and constant aliases keep their provenance. */
+const bindingOf = (source, node) => {
+    for (let scope = source.getScope(node); scope; scope = scope.upper) {
+        const variable = scope.set.get(node.name);
+        if (variable !== undefined)
+            return variable;
+    }
+    return null;
+};
+const requestOrigin = (source, input, seen = new Set()) => {
+    const node = unwrap(input);
+    if (node?.type === "MemberExpression")
+        return isRequestHook(propertyName(node)) && requestOrigin(source, node.object, seen) === "namespace" ? "request" : null;
+    if (node?.type !== "Identifier")
+        return null;
+    const variable = bindingOf(source, node);
+    if (!variable || seen.has(variable) || variable.defs.length !== 1)
+        return null;
+    const [definition] = variable.defs;
+    if (definition === undefined)
+        return null;
+    if (definition.type === "ImportBinding" && definition.parent.importKind !== "type" && swrSource(String(declarationSource(definition.parent)))) {
+        const specifier = definition.node;
+        if ((specifier.type === "ImportSpecifier" || specifier.type === "TSImportEqualsDeclaration") && specifier.importKind === "type")
+            return null;
+        if (specifier.type === "ImportNamespaceSpecifier")
+            return "namespace";
+        return specifier.type === "ImportDefaultSpecifier" || isRequestHook(specifier.type === "ImportSpecifier" ? exportName(specifier.imported) : "") ? "request" : null;
+    }
+    if (definition.type !== "Variable" || definition.parent.kind !== "const")
+        return null;
+    return requestOrigin(source, definition.node.init, new Set([...seen, variable]));
+};
+/** Every value reference to the operation must belong to an SWR fetcher, including a named local fetcher. */
+const wrappedOperations = (context, program, imports) => {
+    const source = context.sourceCode ?? context.getSourceCode();
+    const fetchers = [];
+    walk(source, program, (node) => {
+        if (node.type !== "CallExpression" || requestOrigin(source, node.callee) !== "request")
+            return;
+        const argument = node.arguments[1];
+        if (!argument)
+            return;
+        let fetcher = unwrap(argument) ?? argument;
+        if (fetcher.type === "Identifier") {
+            const definition = bindingOf(source, fetcher)?.defs[0];
+            if (definition?.type === "Variable" && definition.parent.kind === "const")
+                fetcher = unwrap(definition.node.init) ?? fetcher;
+            else if (definition?.node.type === "FunctionDeclaration")
+                fetcher = definition.node;
+        }
+        fetchers.push(fetcher);
+    });
+    const inFetcher = (node) => fetchers.some((fetcher) => fetcher.range[0] <= node.range[0] && fetcher.range[1] >= node.range[1]);
+    return new Set(imports.filter(({ node }) => {
+        if (node.type !== "ImportDeclaration")
+            return inFetcher(node);
+        const runtimeNames = new Set(node.specifiers.filter((s) => !isTypeSpecifier(s)).map((s) => s.local.name));
+        const references = source.getDeclaredVariables(node).filter((v) => runtimeNames.has(v.name))
+            .flatMap((v) => v.references.filter((r) => r.isValueReference !== false).map((r) => r.identifier));
+        return references.length > 0 && references.every(inFetcher);
+    }).map(({ node }) => node));
+};
+/** Direct operation access from domain hooks, features and components skips the request lifecycle. */
+export const operationsOnlyInSwrHooks = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "FE_OP_OUTSIDE_SWR_HOOK: runtime API operations are consumed only by SWR wrappers." },
+        schema: [],
+        messages: { outside: "FE_OP_OUTSIDE_SWR_HOOK: `{{source}}` exposes API operations outside an SWR wrapper. Wrap the operation in hooks/swr/ and call that hook; type-only imports remain available." },
+    },
+    create(context) {
+        if (!isProductSource(context) || isApiLayer(context))
+            return {};
+        const imports = [];
+        const inspect = (node, value) => {
+            if (isOperationSource(context, value) && !importsOnlyBounds(context, node, value))
+                imports.push({ node, value, reader: isOperationSource(context, value, STREAM_READER_SLOT) });
+        };
+        return {
+            ImportDeclaration(node) {
+                if (node.importKind !== "type" && (!node.specifiers.length || node.specifiers.some((s) => !isTypeSpecifier(s))))
+                    inspect(node, node.source.value);
+            },
+            ExportNamedDeclaration(node) {
+                if (node.source && node.exportKind !== "type" && node.specifiers.some((s) => s.exportKind !== "type"))
+                    inspect(node, node.source.value);
+            },
+            ExportAllDeclaration(node) { if (node.exportKind !== "type")
+                inspect(node, node.source.value); },
+            ImportExpression(node) { inspect(node, stringOf(node.source)); },
+            CallExpression(node) {
+                const [first] = node.arguments;
+                if (node.callee.type === "Identifier" && node.callee.name === "require" && first?.type === "Literal" &&
+                    globalReferences(context, new Set(["require"])).includes(node.callee))
+                    inspect(node, first.value);
+            },
+            "Program:exit"(program) {
+                if (!imports.length)
+                    return;
+                const wrapped = isSwrHook(context) ? wrappedOperations(context, program, imports) : new Set();
+                for (const { node, value, reader } of imports)
+                    if (reader || !wrapped.has(node))
+                        context.report({ node, messageId: "outside", data: { source: value } });
+            },
+        };
+    },
+});
+/** A stream operation: `modules/api/sse/<area>/stream-<channel>` or `modules/api/graphql/subscriptions/subscription-<name>`. */
+const STREAM_OPERATION = /modules\/api\/(?:sse\/[^/]+\/stream-[^/]+|graphql\/subscriptions\/subscription-[^/]+)(?:\.tsx?)?$/;
+/** A subscription hook file of the SWR family: `useSubscribe<X>Swr.ts`. */
+const isSubscriptionHook = (context) => isSwrHook(context) && /^useSubscribe[A-Z0-9]\w*Swr\.ts$/.test(fileOf(context).replaceAll("\\", "/").split("/").at(-1) ?? "");
+/** The `onOpen` property of an object literal, else undefined. */
+const onOpenOf = (options) => options?.type === "ObjectExpression"
+    ? options.properties.find((property) => property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "onOpen")
+    : undefined;
+/** True when a function calls `mutate` (the bound mutate of a hook or the one of `useSWRConfig`): the revalidation of the snapshot query. */
+const callsMutate = (source, handler) => {
+    let found = false;
+    walk(source, handler.body, (node) => {
+        if (found)
+            return false;
+        if (node.type !== "CallExpression")
+            return undefined;
+        const callee = unwrap(node.callee);
+        if ((callee?.type === "Identifier" && callee.name === "mutate") || (callee?.type === "MemberExpression" && propertyName(callee) === "mutate"))
+            found = true;
+        return undefined;
+    });
+    return found;
+};
+/** True when a callee is a stream operation: a named import, a member of a namespace import, or a const alias of either. */
+const isStreamCallee = (source, input, locals, seen = new Set()) => {
+    const node = unwrap(input);
+    if (node?.type === "MemberExpression") {
+        const object = unwrap(node.object);
+        return object?.type === "Identifier" && locals.get(object.name) === "namespace" && bindingOf(source, object)?.defs[0]?.type === "ImportBinding";
+    }
+    if (node?.type !== "Identifier")
+        return false;
+    const variable = bindingOf(source, node);
+    if (!variable || seen.has(variable) || variable.defs.length !== 1)
+        return false;
+    const [definition] = variable.defs;
+    if (definition === undefined)
+        return false;
+    if (definition.type === "ImportBinding")
+        return locals.get(variable.name) === "named";
+    if (definition.type !== "Variable" || definition.parent.kind !== "const")
+        return false;
+    return isStreamCallee(source, definition.node.init, locals, new Set([...seen, variable]));
+};
+/**
+ * A stream or subscription has no replay of what it missed (graphql-ws has none, an SSE reconnect replays a bounded buffer), so the
+ * subscription hook revalidates the snapshot query each time the stream opens: its call of the stream operation (named, through a
+ * namespace or an alias) passes an `onOpen` handler that calls `mutate`, and a subscription hook that calls no stream operation at
+ * all is not one (FE-REALTIME-2).
+ */
+export const subscriptionRefetchesSnapshot = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "FE_SUBSCRIPTION_NO_SNAPSHOT: a subscription hook passes the stream operation an onOpen handler that revalidates the snapshot query." },
+        schema: [],
+        messages: {
+            missing: "FE_SUBSCRIPTION_NO_SNAPSHOT: this call of a stream operation has no `onOpen` handler that calls `mutate`. A stream carries changes, not the state: pass `onOpen: () => void mutate(<snapshot query key>)` so the screen reads its snapshot with the query each time the stream (re)opens.",
+            noStream: "FE_SUBSCRIPTION_NO_SNAPSHOT: a `useSubscribe<X>Swr` hook calls one stream operation (`modules/api/sse/<area>/stream-*.ts` or `modules/api/graphql/subscriptions/subscription-*.ts`) and revalidates its snapshot query in `onOpen`; this file calls none.",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context) || !isSubscriptionHook(context))
+            return {};
+        const source = context.sourceCode ?? context.getSourceCode();
+        const locals = new Map();
+        let calls = 0;
+        return {
+            ImportDeclaration(node) {
+                if (node.importKind === "type" || typeof node.source.value !== "string")
+                    return;
+                const target = resolveImport(context, node.source.value);
+                if (target === null || !STREAM_OPERATION.test(target.replaceAll("\\", "/")))
+                    return;
+                for (const specifier of node.specifiers) {
+                    if (isTypeSpecifier(specifier))
+                        continue;
+                    if (specifier.type === "ImportSpecifier")
+                        locals.set(specifier.local.name, "named");
+                    if (specifier.type === "ImportNamespaceSpecifier")
+                        locals.set(specifier.local.name, "namespace");
+                }
+            },
+            CallExpression(node) {
+                if (!isStreamCallee(source, node.callee, locals))
+                    return;
+                calls += 1;
+                const handler = functionOf(context, onOpenOf(node.arguments[0])?.value);
+                if (!handler || !callsMutate(source, handler))
+                    context.report({ node, messageId: "missing" });
+            },
+            "Program:exit"(program) {
+                if (calls === 0)
+                    context.report({ node: program, messageId: "noStream" });
+            },
+        };
+    },
+});
+/** Code metadata is registered on the shared object without changing the shared catalog module. */
+Object.assign(why, {
+    "swr-only-in-family": { code: "FE_SWR_OUTSIDE_FAMILY", en: "A request hook is used outside the SWR family.", fix: "Call the operation's SWR wrapper hook." },
+    "operations-only-in-swr-hooks": { code: "FE_OP_OUTSIDE_SWR_HOOK", en: "An API operation is consumed outside an SWR wrapper.", fix: "Wrap the operation in hooks/swr/." },
+    "subscription-refetches-snapshot": { code: "FE_SUBSCRIPTION_NO_SNAPSHOT", en: "A subscription hook does not revalidate its snapshot query when the stream opens.", fix: "Pass the stream operation an onOpen handler that revalidates the snapshot query key." },
+});
+/** R285's published lint enforcers. */
+export const rules = { "swr-only-in-family": swrOnlyInFamily, "operations-only-in-swr-hooks": operationsOnlyInSwrHooks, "subscription-refetches-snapshot": subscriptionRefetchesSnapshot };
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]));

package/dist/the-split.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The rule that holds `the-split.md`.
+ *
+ * ONE RULE, AND IT WATCHES ONE HALF. The drawing half's purity is checkable: a file that fetches,
+ * reads a store or resolves a word is visible in what it calls. The connected half's discipline is
+ * not - a file that draws badly, or settles the wrong situation, looks exactly like one that does
+ * neither. So this rule guards the boundary from the side where a machine can see it, and the other
+ * side stays a matter for review.
+ *
+ * The scope is the slot. The role `drawing` of a component owner is the drawing half in every tier
+ * that splits, so the slot does the scoping and the rule needs no configuration.
+ */
+import { type Rules, type Recommended } from "./lib/rule.js";
+/** The drawing half receives everything and asks for nothing. */
+export declare const presentationalPurity: import("./lib/rule.js").Rule<"reaches" | "hookType", []>;
+/** A connected block delegates every render path to its exact pure twin. */
+export declare const connectedBlockHasPresentationalTwin: import("./lib/rule.js").Rule<"missing" | "bypass" | "unused" | "called", []>;
+/** The rules this law contributes to the plugin. */
+export declare const rules: Rules;
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * Exact: it fires on a call by name, in one file by name. A repository adopting it with history
+ * should expect each report to be a real move rather than a deletion - the call has to go
+ * somewhere, and where it goes is the other half.
+ */
+export declare const recommended: Recommended;

package/dist/the-split.js

@@ -0,0 +1,157 @@
+/**
+ * The rule that holds `the-split.md`.
+ *
+ * ONE RULE, AND IT WATCHES ONE HALF. The drawing half's purity is checkable: a file that fetches,
+ * reads a store or resolves a word is visible in what it calls. The connected half's discipline is
+ * not - a file that draws badly, or settles the wrong situation, looks exactly like one that does
+ * neither. So this rule guards the boundary from the side where a machine can see it, and the other
+ * side stays a matter for review.
+ *
+ * The scope is the slot. The role `drawing` of a component owner is the drawing half in every tier
+ * that splits, so the slot does the scoping and the rule needs no configuration.
+ */
+import { defineRule } from "./lib/rule.js";
+import { hfsOf } from "./lib/hfs.js";
+import { fileOf, inSlot, kindOfFile, roleOfFile } from "./lib/scope.js";
+/** The drawing half: the file the slot gives the role `drawing` (`component.tsx` of a component, feature or shared-package owner). */
+const isDrawingHalf = (context) => roleOfFile(context) === "drawing";
+/** A connected block entrypoint (the `entry` of a block owner) and the public name its folder fixes. */
+const connectedBlock = (context) => {
+    if (!inSlot(context, "fe.components") || kindOfFile(context) !== "blocks" || roleOfFile(context) !== "entry")
+        return null;
+    const name = hfsOf(context).relative(fileOf(context)).split("/").slice(-2)[0];
+    return name !== undefined && /^[A-Z][A-Za-z0-9]*$/.test(name) ? name : null;
+};
+/**
+ * Calls that reach for the world instead of receiving it.
+ *
+ * Six families of the front-end stack: a request (SWR, `useQuery<X>Swr` / `useMutate<X>Swr` and the REST
+ * `use{Get,Post,Put,Patch,Delete}<X>Swr` of `hooks/swr`, the Apollo hooks, an operation of `modules/api` called directly), a
+ * form (react-hook-form and the `use<X>Form` hooks of `hooks/rhf`), a store (redux, the zustand `use<X>Store`), a socket
+ * (`use<X>SocketIo` of `hooks/socketio`), a toast (`use<X>WithToast` of `modules/toast`) and the translation runtime. Each is a
+ * dependency the drawing half cannot be rendered from a fixture without.
+ */
+const REACHES_FOR_THE_WORLD = /^(?:useSWR|useSWRMutation|useSWRConfig|use[A-Za-z0-9]*Swr|useQuery|useLazyQuery|useMutation|useSubscription|useApolloClient|useForm|useFormContext|useController|useWatch|use[A-Za-z0-9]*Form|useAppSelector|useAppDispatch|useSelector|useDispatch|use[A-Za-z0-9]*Store|use[A-Za-z0-9]*SocketIo|use[A-Za-z0-9]*WithToast|useTranslations|useLocale|useFormatter|query[A-Z][A-Za-z0-9]*|mutation[A-Z][A-Za-z0-9]*)$/;
+// -- SPLIT-1 ---------------------------------------------------------------------------------------
+/** The drawing half receives everything and asks for nothing. */
+export const presentationalPurity = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "The drawing half takes resolved props: no request, no store, no translation, no import (type or value) from `@/hooks`." },
+        schema: [],
+        messages: {
+            reaches: "`{{name}}(...)` reaches for the world from the drawing half. This file must be renderable from a fixture - that is what makes it testable without standing the world up first, and it is the whole reason the split exists. Move the call to `index.tsx` and pass the result down as a settled situation.",
+            hookType: "`{{source}}` lends the drawing half a type derived from a hook. The pure half declares its own atom view types (strings, numbers, booleans, plain objects, a DataSlot per read); a hook-derived type ties it to the world it must be renderable without.",
+        },
+    },
+    create(context) {
+        if (!isDrawingHalf(context))
+            return {};
+        return {
+            ImportDeclaration(node) {
+                const source = node.source.value;
+                if (source === "@/hooks" || source.startsWith("@/hooks/"))
+                    context.report({ node, messageId: "hookType", data: { source } });
+            },
+            CallExpression(node) {
+                const callee = node.callee;
+                if (!callee || callee.type !== "Identifier")
+                    return;
+                if (!REACHES_FOR_THE_WORLD.test(callee.name))
+                    return;
+                context.report({ node, messageId: "reaches", data: { name: callee.name } });
+            },
+        };
+    },
+});
+// -- SPLIT-5 ---------------------------------------------------------------------------------------
+/** A connected block delegates every render path to its exact pure twin. */
+export const connectedBlockHasPresentationalTwin = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "A connected block index renders only its exact `XBase` twin from component.tsx." },
+        schema: [],
+        messages: {
+            missing: "`{{block}}` reads the world, so it must import exact `{{twin}}` from `./component`. A single leaf, one tree, or no local state is not an exception.",
+            bypass: "Connected `{{block}}` renders `<{{rendered}}>` directly. Resolve the world here, then render only `<{{twin}}>`; component.tsx owns the complete presentation.",
+            unused: "Connected `{{block}}` imports `{{twin}}` but never renders it. Every connected render path must cross the pure twin.",
+            called: "Connected `{{block}}` calls `{{twin}}(...)` as an ordinary function. Render `<{{twin}} />` so React owns the twin's hook lifecycle and every render keeps one stable component boundary.",
+        },
+    },
+    create(context) {
+        const block = connectedBlock(context);
+        if (!block)
+            return {};
+        const twin = `${block}Base`;
+        const worldBindings = new Set();
+        const rendered = [];
+        const calledTwin = [];
+        let importsTwin = false;
+        let readsWorld = false;
+        let rendersTwin = false;
+        return {
+            ImportDeclaration(node) {
+                const source = typeof node.source?.value === "string" ? node.source.value : "";
+                for (const specifier of node.specifiers || []) {
+                    const imported = specifier.type === "ImportSpecifier" && specifier.imported.type === "Identifier" ? specifier.imported.name : undefined;
+                    const local = specifier.local.name;
+                    if (source === "./component" && imported === twin && local === twin)
+                        importsTwin = true;
+                    if (imported && local && REACHES_FOR_THE_WORLD.test(imported))
+                        worldBindings.add(local);
+                }
+            },
+            CallExpression(node) {
+                if (node.callee?.type !== "Identifier")
+                    return;
+                if (node.callee.name === twin)
+                    calledTwin.push(node);
+                if (worldBindings.has(node.callee.name) || REACHES_FOR_THE_WORLD.test(node.callee.name)) {
+                    readsWorld = true;
+                }
+            },
+            JSXOpeningElement(node) {
+                if (node.name?.type !== "JSXIdentifier")
+                    return;
+                rendered.push({ name: node.name.name, node });
+                if (node.name.name === twin)
+                    rendersTwin = true;
+            },
+            "Program:exit"(node) {
+                if (!readsWorld)
+                    return;
+                if (!importsTwin) {
+                    context.report({ node, messageId: "missing", data: { block, twin } });
+                    return;
+                }
+                for (const entry of rendered) {
+                    if (entry.name !== twin) {
+                        context.report({
+                            node: entry.node,
+                            messageId: "bypass",
+                            data: { block, rendered: entry.name, twin },
+                        });
+                    }
+                }
+                for (const call of calledTwin) {
+                    context.report({ node: call, messageId: "called", data: { block, twin } });
+                }
+                if (!rendersTwin)
+                    context.report({ node, messageId: "unused", data: { block, twin } });
+            },
+        };
+    },
+});
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "presentational-purity": presentationalPurity,
+    "connected-block-has-presentational-twin": connectedBlockHasPresentationalTwin,
+};
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * Exact: it fires on a call by name, in one file by name. A repository adopting it with history
+ * should expect each report to be a real move rather than a deletion - the call has to go
+ * somewhere, and where it goes is the other half.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]));

package/dist/tokens.d.ts

@@ -0,0 +1,9 @@
+import { type Recommended } from "./lib/rule.js";
+/** An arbitrary value escapes the system, whatever it happens to evaluate to. */
+export declare const noArbitraryValue: import("./lib/rule.js").Rule<"length" | "colour", []>;
+/** Rules of universal token discipline. */
+export declare const rules: {
+    "no-arbitrary-value": import("./lib/rule.js").Rule<"length" | "colour", []>;
+};
+/** Every token-discipline rule is mandatory. */
+export declare const recommended: Recommended;

package/dist/tokens.js

@@ -0,0 +1,35 @@
+/** Universal closed-token discipline, independent of a Grammar scale. */
+import { classTextVisitors } from "./lib/class-text.js";
+import { defineRule } from "./lib/rule.js";
+/** A bracketed length: a value chosen once, for one screen, findable by nobody. */
+const ARBITRARY_LENGTH = /\b(?:gap|gap-x|gap-y|p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|space-x|space-y|size|w|h|min-w|min-h|max-w|max-h)-\[[^\]]+\]/;
+/** A raw colour, which escapes the semantic palette even when it matches it today. */
+const RAW_COLOUR = /\b(?:text|bg|border|ring|from|to|via|fill|stroke|shadow|decoration)-\[#[0-9a-fA-F]/;
+/** An arbitrary value escapes the system, whatever it happens to evaluate to. */
+export const noArbitraryValue = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "Bracketed lengths and raw colours escape the closed vocabulary." },
+        schema: [],
+        messages: {
+            length: "`{{cls}}` is a value chosen once, for one screen. Even where it happens to equal a rung, nobody searching the scale can find it and it does not move when the scale moves. Use a member of the vocabulary, or add one deliberately.",
+            colour: "`{{cls}}` is a raw colour, outside the semantic palette. A colour named for what it MEANS follows the theme; one named for what it is stays the same in a theme where it is wrong.",
+        },
+    },
+    create(context) {
+        return classTextVisitors(context, (node, text) => {
+            if (!text)
+                return;
+            const length = text.match(ARBITRARY_LENGTH);
+            if (length)
+                context.report({ node, messageId: "length", data: { cls: length[0] } });
+            const colour = text.match(RAW_COLOUR);
+            if (colour)
+                context.report({ node, messageId: "colour", data: { cls: colour[0] } });
+        });
+    },
+});
+/** Rules of universal token discipline. */
+export const rules = { "no-arbitrary-value": noArbitraryValue };
+/** Every token-discipline rule is mandatory. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]));