@starci/eslint-canon-fe 9.3.0 → 9.4.1

package/dist/callback-shape.js

@@ -0,0 +1,396 @@
+import { stringOf, walk } from "./lib/ast.js";
+import { patternPath } from "./lib/bindings.js";
+import { normalizePath } from "./lib/path.js";
+import { ownerExportKind } from "./lib/pure-owner-helper.js";
+import { defineRule } from "./lib/rule.js";
+import { classifyImport, inSlot, resolveImport } from "./lib/scope.js";
+/** A value a well-formed tree always has; its absence stops the run as reading it always has. */
+const must = (value, what) => {
+    if (value === null || value === undefined)
+        throw new TypeError(`missing ${what}`);
+    return value;
+};
+/** The node a runtime wrapper wraps, or undefined when the node wraps nothing. */
+const wrapped = (node) => {
+    if (node.type === "AwaitExpression")
+        return node.argument;
+    if (node.type === "ChainExpression" || node.type === "TSAsExpression" || node.type === "TSTypeAssertion" || node.type === "TSNonNullExpression" || node.type === "TSInstantiationExpression")
+        return node.expression;
+    return undefined;
+};
+const WRAPPERS = new Set(["AwaitExpression", "ChainExpression", "TSAsExpression", "TSTypeAssertion", "TSNonNullExpression", "TSInstantiationExpression"]);
+/** Runtime expression wrappers that preserve the value's source. */
+const unwrap = (input) => {
+    let node = input;
+    while (node && WRAPPERS.has(node.type))
+        node = wrapped(node);
+    return node;
+};
+/** A member's static key, including a bracketed string spelling. */
+const memberName = (node) => node.computed ? stringOf(node.property) : node.property.name;
+/** The name an identifier-like node spells, or undefined. */
+const nameOf = (node) => ("name" in node && typeof node.name === "string" ? node.name : undefined);
+/** The lexical binding of an identifier, including shadowing inside the handler. */
+const bindingOf = (sourceCode, node) => {
+    const name = nameOf(node);
+    for (let scope = sourceCode.getScope(node); scope; scope = scope.upper) {
+        const variable = name === undefined ? undefined : scope.set.get(name);
+        if (variable)
+            return variable;
+    }
+    return null;
+};
+/** Whether an identifier refers to the actual unshadowed platform global. */
+const isGlobal = (sourceCode, node, name) => node?.type === "Identifier" && node.name === name && !(bindingOf(sourceCode, node)?.defs.length);
+/** Route configuration is inert; a second HTTP door or an exported helper is not. */
+const CONFIG_EXPORTS = new Set(["runtime", "dynamic", "revalidate", "fetchCache", "preferredRegion", "maxDuration"]);
+const FUNCTIONS = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
+const FORBIDDEN = new Set(["AssignmentExpression", "UpdateExpression", "ImportExpression", "TaggedTemplateExpression", "ClassDeclaration", "ClassExpression", "ForStatement", "ForInStatement", "ForOfStatement", "WhileStatement", "DoWhileStatement", "ThrowStatement", "YieldExpression", "SpreadElement", "ArrayPattern", "JSXElement", "JSXFragment"]);
+const TEXT = new Set(["text", "code", "otp-type"]);
+const CALLS = new Set(["factory", "exchange", "verify-otp", "pure", "redirect", "params-get", "params-has", "text-guard"]);
+/** What a pure owner helper may be given: query text, the page URL or request, and plain values; never the credential itself. */
+const PURE_ARGUMENTS = new Set(["text", "otp-type", "scalar", "url", "request"]);
+const URL_TEXT = new Set(["origin", "href", "pathname", "search", "hash", "host", "hostname", "protocol"]);
+const CALL_RESULTS = new Map([["factory", "client"], ["exchange", "exchange-result"], ["verify-otp", "exchange-result"], ["pure", "text"], ["redirect", "redirect-result"], ["params-has", "scalar"], ["text-guard", "scalar"]]);
+const MEMBERS = new Map([
+    ["request", new Map([["nextUrl", "url"], ["url", "text"]])],
+    ["url", new Map([["searchParams", "params"], ...[...URL_TEXT].map((key) => [key, "text"])])],
+    ["params", new Map([["get", "params-get"], ["has", "params-has"]])],
+    ["client", new Map([["auth", "auth"]])],
+    ["auth", new Map([["exchangeCodeForSession", "exchange"], ["verifyOtp", "verify-otp"]])],
+    ["next-response", new Map([["redirect", "redirect"]])],
+    ["exchange-result", new Map([["error", "exchange-error"], ["success", "scalar"], ["ok", "scalar"]])],
+]);
+const TEXT_GUARDS = ["startsWith", "endsWith", "includes"];
+const UNSAFE_KEYS = ["__proto__", "constructor", "prototype"];
+const REDIRECT_TARGETS = ["text", "url"];
+const REDIRECT_STATUSES = [301, 302, 303, 307, 308];
+/** The query parameters whose provenance an exchange requires: the PKCE code, and the email link's token hash and type. */
+const PARAM_ORIGINS = new Map([["code", "code"], ["token_hash", "token-hash"], ["type", "otp-type"]]);
+/** True for a function node. */
+const isFunctionNode = (node) => FUNCTIONS.has(node.type);
+/** A locally exported binding's implementation. */
+const exportValue = (sourceCode, entry) => {
+    const definition = bindingOf(sourceCode, entry.local)?.defs[0]?.node;
+    return unwrap(definition?.type === "VariableDeclarator" ? definition.init : definition);
+};
+/** The spelling of an export or import name: an identifier's name or a string literal's value. */
+const moduleExportName = (node) => node.type === "Identifier" ? node.name : node.value;
+/** The runtime names introduced by one local named export. */
+const namedExports = (statement, sourceCode) => {
+    const declaration = statement.declaration;
+    if (declaration?.type === "FunctionDeclaration")
+        return [{ name: must(declaration.id, "function name").name, value: declaration }];
+    if (declaration?.type === "VariableDeclaration") {
+        if (declaration.declarations.some((entry) => entry.id.type !== "Identifier"))
+            return null;
+        return declaration.declarations.map((entry) => ({ name: must(nameOf(entry.id), "variable name"), value: unwrap(entry.init) }));
+    }
+    if (declaration)
+        return [];
+    return statement.specifiers.filter((entry) => entry.exportKind !== "type")
+        .map((entry) => ({ name: moduleExportName(entry.exported), value: exportValue(sourceCode, entry) }));
+};
+/** Collect runtime exports, refusing reexports and default exports. */
+const exportsOf = (program, sourceCode) => {
+    const exported = [];
+    for (const statement of program.body) {
+        if (statement.type === "ExportDefaultDeclaration" || statement.type === "ExportAllDeclaration")
+            return null;
+        if (statement.type !== "ExportNamedDeclaration" || statement.exportKind === "type")
+            continue;
+        if (statement.source)
+            return null;
+        const entries = namedExports(statement, sourceCode);
+        if (!entries)
+            return null;
+        exported.push(...entries);
+    }
+    return exported;
+};
+/** Find the one locally implemented GET export and its single request parameter. */
+const handlerOf = (program, sourceCode) => {
+    const exported = exportsOf(program, sourceCode);
+    if (!exported || exported.some((entry) => entry.name !== "GET" && !CONFIG_EXPORTS.has(entry.name)))
+        return null;
+    const handlers = exported.filter((entry) => entry.name === "GET");
+    if (handlers.length !== 1)
+        return null;
+    const handler = must(handlers[0], "GET export").value;
+    if (!handler || !isFunctionNode(handler) || !handler.async || handler.generator)
+        return null;
+    return handler.params.length === 1 && handler.params[0]?.type === "Identifier" ? handler : null;
+};
+/** Framework imports retain their actual owner even under a local alias. */
+const frameworkImportKind = (source, name) => {
+    if (source === "next/server" && name === "NextResponse")
+        return "next-response";
+    if (source === "next/server" && name === "NextRequest")
+        return "request-type";
+    if (source === "next/navigation" && name === "redirect")
+        return "redirect";
+    return null;
+};
+/** Only the server auth entry exposes the cookie-owning exchangeAuthCode helper. */
+const isServerAuthImport = (context, source) => {
+    const target = normalizePath(resolveImport(context, source));
+    return target.endsWith("/modules/auth/server") || target.endsWith("/modules/auth/server.ts");
+};
+/** A directory import resolves to its index, before the generic modules slot's hypothetical routes.ts. */
+const isRoutesImport = (context, source, slot) => slot === "fe.modules.routes" || classifyImport(context, `${source}/index`)?.slot === "fe.modules.routes";
+const CLIENT_NAMES = ["supabase", "supabaseClient", "authClient"];
+/** The exchange, client and factory names of the auth owner. */
+const authImportKind = (context, source, name) => {
+    if (name === "exchangeAuthCode" && isServerAuthImport(context, source))
+        return "exchange";
+    if (name === "verifyOtp" && isServerAuthImport(context, source))
+        return "verify-otp";
+    if (name === "exchangeCodeForSession")
+        return "exchange";
+    if (/^(?:create|get)\w*Client$/.test(name ?? ""))
+        return "factory";
+    if (CLIENT_NAMES.includes(name))
+        return "client";
+    return null;
+};
+/** Auth helpers and static route values must come from their declared HFS owners; any other export of `modules/routes` or `modules/auth` counts only as a pure helper or a static table. */
+const ownerImportKind = (context, source, name) => {
+    const slot = classifyImport(context, source)?.slot;
+    if (name === "APP_ROUTES" && isRoutesImport(context, source, slot))
+        return "routes";
+    const authKind = slot === "fe.modules.auth" ? authImportKind(context, source, name) : null;
+    if (authKind || !(slot === "fe.modules.auth" || isRoutesImport(context, source, slot)))
+        return authKind;
+    // A default or namespace import names no export, so no export of the owner can match it.
+    return name === undefined ? null : ownerExportKind(context, source, name);
+};
+/** The imported name of a specifier; undefined for a default or namespace import. */
+const importedName = (specifier) => specifier.type === "ImportSpecifier" ? moduleExportName(specifier.imported) : undefined;
+/** Register the allowed bindings in a single import statement. */
+const addImportBindings = (context, sourceCode, statement, imports) => {
+    const source = String(statement.source.value);
+    if (source === "server-only" && statement.specifiers.length === 0)
+        return true;
+    if (statement.specifiers.length === 0)
+        return false;
+    const variables = sourceCode.getDeclaredVariables(statement);
+    for (const specifier of statement.specifiers) {
+        if (specifier.type === "ImportSpecifier" && specifier.importKind === "type")
+            continue;
+        const name = importedName(specifier);
+        const kind = frameworkImportKind(source, name) ?? ownerImportKind(context, source, name);
+        if (!kind)
+            return false;
+        imports.set(variables.find((entry) => entry.name === specifier.local.name), kind);
+    }
+    return true;
+};
+/** Every runtime import is restricted, even if it is unused in the handler. */
+const importsOf = (context, program, sourceCode) => {
+    const imports = new Map();
+    for (const statement of program.body) {
+        if (statement.type !== "ImportDeclaration" || statement.importKind === "type")
+            continue;
+        if (!addImportBindings(context, sourceCode, statement, imports))
+            return null;
+    }
+    return imports;
+};
+/** Select a known property without granting arbitrary methods on the selected value. */
+const memberKind = (kind, key) => {
+    if (kind === "routes" && typeof key === "string" && !UNSAFE_KEYS.includes(key))
+        return "text";
+    if (TEXT.has(kind) && TEXT_GUARDS.includes(key))
+        return "text-guard";
+    return MEMBERS.get(kind)?.get(key) ?? null;
+};
+/** An identifier keeps the provenance of its one initializer or the GET request parameter. */
+const identifierOrigin = (node, seen, env, origin) => {
+    const variable = bindingOf(env.sourceCode, node);
+    if (env.imports.has(variable))
+        return env.imports.get(variable) ?? null;
+    if (!variable || seen.has(variable) || variable.defs.length !== 1)
+        return null;
+    const definition = must(variable.defs[0], "definition");
+    if (definition.type === "Parameter" && definition.node === env.handler)
+        return "request";
+    if (definition.node.type !== "VariableDeclarator")
+        return null;
+    const path = patternPath(definition.node.id, node.name);
+    const nextSeen = new Set([...seen, variable]);
+    return path?.reduce((kind, key) => memberKind(kind, key), origin(definition.node.init, nextSeen)) ?? null;
+};
+/** Combining known primitive values cannot introduce user-defined coercion. */
+const combinedOrigin = (kinds, conditional = false) => {
+    if (conditional && kinds[0] === kinds[1])
+        return kinds[0];
+    if (kinds.every((kind) => TEXT.has(kind)))
+        return "text";
+    if (!conditional && kinds.every((kind) => TEXT.has(kind) || kind === "scalar"))
+        return "scalar";
+    return null;
+};
+/** The source of a call's return value, independent of argument validation. */
+const callOrigin = (node, seen, origin) => {
+    const kind = origin(node.callee, seen);
+    if (kind === "params-get")
+        return PARAM_ORIGINS.get(stringOf(node.arguments[0])) ?? "text";
+    return CALL_RESULTS.get(kind) ?? null;
+};
+/** Composite expressions retain provenance only for supported primitive operations. */
+const expressionOrigin = (node, seen, env, origin) => {
+    if (node.type === "TemplateLiteral")
+        return node.expressions.every((expression) => TEXT.has(origin(expression, seen)) || origin(expression, seen) === "scalar") ? "text" : null;
+    if (node.type === "MemberExpression")
+        return memberKind(origin(node.object, seen), memberName(node));
+    if (node.type === "NewExpression" && isGlobal(env.sourceCode, node.callee, "URL"))
+        return "url";
+    if (node.type === "LogicalExpression" || node.type === "BinaryExpression")
+        return combinedOrigin([origin(node.left, seen), origin(node.right, seen)]);
+    if (node.type === "ConditionalExpression")
+        return combinedOrigin([origin(node.consequent, seen), origin(node.alternate, seen)], true);
+    if (node.type === "CallExpression")
+        return callOrigin(node, seen, origin);
+    return null;
+};
+/** Follow lexical aliases rather than trusting the spelling of an identifier. */
+const originOf = (env) => {
+    const origin = (input, seen = new Set()) => {
+        const node = unwrap(input);
+        if (!node)
+            return null;
+        if (node.type === "Identifier")
+            return identifierOrigin(node, seen, env, origin);
+        if (node.type === "Literal")
+            return typeof node.value === "string" || node.value === null ? "text" : "scalar";
+        return expressionOrigin(node, seen, env, origin);
+    };
+    return origin;
+};
+/** The closest enclosing function must be the GET handler. */
+const insideHandler = (node, handler) => {
+    for (let parent = node.parent; parent; parent = parent.parent)
+        if (FUNCTIONS.has(parent.type))
+            return parent === handler;
+    return false;
+};
+/** Await must wrap the actual exchange call before its enclosing statement ends. */
+const isAwaited = (node, handler) => {
+    for (let parent = node.parent; parent && parent !== handler; parent = parent.parent) {
+        if (parent.type === "AwaitExpression")
+            return true;
+        if (parent.type.endsWith("Statement"))
+            return false;
+    }
+    return false;
+};
+/** The static key of a plain `init` property, or null for a computed, method or accessor property and for a spread. */
+const plainKey = (property) => {
+    if (property.type !== "Property" || property.computed || property.method || property.kind !== "init")
+        return null;
+    const key = property.key;
+    return key.type === "Identifier" ? key.name : key.value;
+};
+/** Only a literal redirect status is allowed in an options object. */
+const isRedirectStatus = (property) => {
+    if (property.type !== "Property" || property.computed || property.method || property.kind !== "init")
+        return false;
+    return plainKey(property) === "status" && property.value.type === "Literal" && REDIRECT_STATUSES.includes(property.value.value);
+};
+/** Arbitrary objects can invoke getters or toString during coercion; only redirect options belong here. */
+const isRedirectOptions = (node, origin) => node.parent.type === "CallExpression" && origin(node.parent.callee) === "redirect" && node.parent.arguments[1] === node && node.properties.every(isRedirectStatus);
+/** The one object `verifyOtp` takes: exactly `token_hash` read from the query `token_hash` and `type` read from the query `type`. */
+const isOtpArguments = (node, origin) => {
+    if (node.parent.type !== "CallExpression" || origin(node.parent.callee) !== "verify-otp" || node.parent.arguments[0] !== node)
+        return false;
+    const expected = new Map([["token_hash", "token-hash"], ["type", "otp-type"]]);
+    return node.properties.length === expected.size && node.properties.every((property) => property.type === "Property" && expected.get(plainKey(property)) === origin(property.value))
+        && new Set(node.properties.map(plainKey)).size === expected.size;
+};
+/** Non-call expressions must preserve the callback's narrow set of values and effects. */
+const validExpression = (node, env, origin) => {
+    if (node.type === "MemberExpression")
+        return Boolean(origin(node));
+    if (node.type === "ObjectExpression")
+        return isRedirectOptions(node, origin) || isOtpArguments(node, origin);
+    if (node.type === "VariableDeclarator" && node.id.type === "ObjectPattern")
+        return env.sourceCode.getDeclaredVariables(node).every((variable) => origin(variable.identifiers[0]));
+    if (node.type === "NewExpression")
+        return isGlobal(env.sourceCode, node.callee, "URL") && node.arguments.length >= 1 && node.arguments.length <= 2 && node.arguments.every((argument) => TEXT.has(origin(argument)));
+    if (node.type === "ReturnStatement")
+        return insideHandler(node, env.handler) && origin(node.argument) === "redirect-result";
+    if (node === env.handler && env.handler.body.type !== "BlockStatement")
+        return origin(env.handler.body) === "redirect-result";
+    return true;
+};
+/** Validate arguments to each permitted operation. */
+const validCall = (node, kind, env, origin) => {
+    if (!insideHandler(node, env.handler) || !CALLS.has(kind) || node.arguments.some((argument) => argument.type === "SpreadElement"))
+        return false;
+    if (kind === "exchange")
+        return isAwaited(node, env.handler) && node.arguments.length === 1 && origin(node.arguments[0]) === "code";
+    if (kind === "verify-otp")
+        return isAwaited(node, env.handler) && node.arguments.length === 1 && node.arguments[0]?.type === "ObjectExpression";
+    if (kind === "pure")
+        return node.arguments.length <= 4 && node.arguments.every((argument) => PURE_ARGUMENTS.has(origin(argument)));
+    if (kind === "redirect")
+        return node.arguments.length >= 1 && node.arguments.length <= 2 && REDIRECT_TARGETS.includes(origin(node.arguments[0]));
+    if (kind === "factory")
+        return node.arguments.length <= 1 && node.arguments.every((argument) => origin(argument) === "request");
+    return node.arguments.length === 1 && TEXT.has(origin(node.arguments[0]));
+};
+/** Syntactic forms that add work beyond the one handler are refused outright. */
+const forbiddenNode = (node, handler) => FORBIDDEN.has(node.type) || (FUNCTIONS.has(node.type) && node !== handler) || (node.type === "UnaryExpression" && node.operator === "delete");
+/** Walk all runtime syntax, counting the single exchange and permitted redirects. */
+const validOperations = (program, env) => {
+    const origin = originOf(env);
+    const counts = new Map();
+    let valid = true;
+    walk(env.sourceCode, program, (node) => {
+        if (!valid)
+            return false;
+        valid = !forbiddenNode(node, env.handler) && validExpression(node, env, origin);
+        if (!valid || node.type !== "CallExpression")
+            return undefined;
+        const kind = origin(node.callee);
+        valid = validCall(node, kind, env, origin);
+        counts.set(kind, (counts.get(kind) ?? 0) + 1);
+        return undefined;
+    });
+    const exchanges = (counts.get("exchange") ?? 0) + (counts.get("verify-otp") ?? 0);
+    return valid && exchanges >= 1 && (counts.get("exchange") ?? 0) <= 1 && (counts.get("verify-otp") ?? 0) <= 1 && (counts.get("factory") ?? 0) <= 1 && (counts.get("redirect") ?? 0) > 0;
+};
+/** The callback's request, imports and operations must all have known owners. */
+const callbackVerdict = (context, program) => {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const handler = handlerOf(program, sourceCode);
+    if (!handler)
+        return false;
+    const imports = importsOf(context, program, sourceCode);
+    return imports !== null && validOperations(program, { sourceCode, handler, imports });
+};
+/** A callback stays a PKCE exchange and redirect, with every side effect owned by the auth helper. */
+export const callbackShape = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "R287 FE_CALLBACK_SHAPE: the Supabase callback reads the PKCE code or the email-link token_hash and type, exchanges it through modules/auth (exchangeAuthCode or verifyOtp), and redirects only." },
+        schema: [],
+        messages: {
+            shape: "FE_CALLBACK_SHAPE: the auth callback must export an async GET that reads the query code (or the email-link token_hash and type), awaits one exchangeAuthCode(code) from modules/auth/server or auth.exchangeCodeForSession(code) and, for an email link, one verifyOtp({ token_hash, type }) built from exactly those two query values, may call pure text helpers of modules/routes or modules/auth (no I/O, no await) to compute the target and validate next, and redirects with NextResponse.redirect or next/navigation redirect. Create the client in modules/auth; keep data access, cookie writes, other calls and additional HTTP handlers outside the callback.",
+        },
+    },
+    create(context) {
+        if (!inSlot(context, "fe.route.callback"))
+            return {};
+        return {
+            "Program:exit"(program) {
+                if (!callbackVerdict(context, program))
+                    context.report({ node: program, messageId: "shape" });
+            },
+        };
+    },
+});
+/** The rule R287 contributes to the front-end plugin. */
+export const rules = { "callback-shape": callbackShape };
+/** Every callback shape violation is an error. */
+export const recommended = { "starci-fe/callback-shape": "error" };

package/dist/class-names.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The classNames law: component markup consumes named styling declarations, while colocated
+ * classNames files own the utility-token composition.
+ */
+import { type Recommended } from "./lib/rule.js";
+/** Report className values written directly in component JSX. */
+export declare const noInlineClassName: import("./lib/rule.js").Rule<"inline", []>;
+/** Require every classNames declaration to use the colocated classNames.ts convention. */
+export declare const classNamesInColocatedFile: import("./lib/rule.js").Rule<"misplaced", []>;
+/** Require variadic cn utility tokens: no arrays, whitespace-packed values, or fractional commas. */
+export declare const cnArgumentsAreSingleTokens: import("./lib/rule.js").Rule<"array" | "token" | "unexported", []>;
+/** Every rule this law publishes. */
+export declare const rules: {
+    "no-inline-class-name": import("./lib/rule.js").Rule<"inline", []>;
+    "class-names-in-colocated-file": import("./lib/rule.js").Rule<"misplaced", []>;
+    "cn-arguments-are-single-tokens": import("./lib/rule.js").Rule<"array" | "token" | "unexported", []>;
+};
+/** Recommended severity for the classNames law. */
+export declare const recommended: Recommended;

package/dist/class-names.js

@@ -0,0 +1,170 @@
+/**
+ * The classNames law: component markup consumes named styling declarations, while colocated
+ * classNames files own the utility-token composition.
+ */
+import { defineRule } from "./lib/rule.js";
+import { isComponentFile, roleOfFile } from "./lib/scope.js";
+/** The owner a cn call may sit in, and the exports that publish one. */
+const FUNCTION_OWNERS = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
+const EXPORTS = new Set(["ExportNamedDeclaration", "ExportDefaultDeclaration"]);
+/** The styling declarations of a component owner: the file its slot gives the role `styles`. */
+const isClassNamesFile = (context) => isComponentFile(context) && roleOfFile(context) === "styles";
+const isClassAttribute = (node) => {
+    const name = node.name.name;
+    return typeof name === "string" && ["className", "class"].includes(name);
+};
+const isCn = (node) => node?.type === "Identifier" && node.name === "cn";
+const importedClassNames = (context) => {
+    const imports = new Set();
+    const sourceCode = context.sourceCode || context.getSourceCode();
+    for (const statement of sourceCode.ast.body) {
+        if (statement.type !== "ImportDeclaration" || statement.source.value !== "./classNames")
+            continue;
+        for (const specifier of statement.specifiers)
+            imports.add(specifier.local.name);
+    }
+    return imports;
+};
+const isExportedOwner = (node) => {
+    let current = node;
+    while (current) {
+        if (FUNCTION_OWNERS.has(current.type)) {
+            current = current.parent;
+            if (current?.type === "VariableDeclarator")
+                current = current.parent;
+            if (current?.type === "VariableDeclaration")
+                current = current.parent;
+            return EXPORTS.has(current?.type);
+        }
+        if (current.type === "VariableDeclarator") {
+            current = current.parent?.parent;
+            return EXPORTS.has(current?.type);
+        }
+        current = current.parent;
+    }
+    return false;
+};
+const visitTokenLeaves = (node, report) => {
+    if (!node)
+        return;
+    if (node.type === "ArrayExpression") {
+        report(node, "array");
+        return;
+    }
+    if (node.type === "Literal" && typeof node.value === "string") {
+        if (/\s/.test(node.value) || /\d+,\d+/.test(node.value))
+            report(node, "token");
+        return;
+    }
+    if (node.type === "ConditionalExpression") {
+        visitTokenLeaves(node.consequent, report);
+        visitTokenLeaves(node.alternate, report);
+    }
+    else if (node.type === "LogicalExpression") {
+        visitTokenLeaves(node.left, report);
+        visitTokenLeaves(node.right, report);
+    }
+};
+const isEmptyClassName = (node) => node?.type === "Literal" && node.value === null || node?.type === "Identifier" && node.name === "undefined";
+const usesImportedClassName = (node, imported) => {
+    if (!node)
+        return false;
+    if (node.type === "Identifier")
+        return imported.has(node.name) || node.name === "undefined";
+    if (isEmptyClassName(node))
+        return true;
+    if (node.type === "CallExpression") {
+        if (node.callee.type === "Identifier")
+            return imported.has(node.callee.name);
+        return node.callee.type === "MemberExpression" && node.callee.object.type === "Identifier" && imported.has(node.callee.object.name);
+    }
+    if (node.type === "MemberExpression")
+        return node.object.type === "Identifier" && imported.has(node.object.name);
+    if (node.type === "ConditionalExpression")
+        return usesImportedClassName(node.consequent, imported) && usesImportedClassName(node.alternate, imported);
+    if (node.type === "LogicalExpression") {
+        if (node.operator === "&&")
+            return usesImportedClassName(node.right, imported);
+        return usesImportedClassName(node.left, imported) && usesImportedClassName(node.right, imported);
+    }
+    return false;
+};
+/** Report className values written directly in component JSX. */
+export const noInlineClassName = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "Component JSX must import a named className declaration." },
+        schema: [],
+        messages: { inline: "Move this className value to an imported colocated classNames.ts export." },
+    },
+    create(context) {
+        if (!isComponentFile(context))
+            return {};
+        const imported = importedClassNames(context);
+        return {
+            JSXAttribute(node) {
+                if (!isClassAttribute(node) || !node.value)
+                    return;
+                const expression = node.value.type === "JSXExpressionContainer" ? node.value.expression : node.value;
+                if (!usesImportedClassName(expression, imported))
+                    context.report({ node, messageId: "inline" });
+            },
+        };
+    },
+});
+/** Require every classNames declaration to use the colocated classNames.ts convention. */
+export const classNamesInColocatedFile = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "Reusable className declarations belong in colocated classNames.ts files." },
+        schema: [],
+        messages: { misplaced: "Put reusable className declarations in a colocated classNames.ts file." },
+    },
+    create(context) {
+        if (!isComponentFile(context))
+            return {};
+        const styles = isClassNamesFile(context);
+        return {
+            CallExpression(node) {
+                if (!isCn(node.callee) || styles)
+                    return;
+                context.report({ node, messageId: "misplaced" });
+            },
+        };
+    },
+});
+/** Require variadic cn utility tokens: no arrays, whitespace-packed values, or fractional commas. */
+export const cnArgumentsAreSingleTokens = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "Each cn argument is one valid utility token." },
+        schema: [],
+        messages: {
+            array: "Pass utility tokens to cn as variadic arguments, not an array.",
+            token: "Each cn argument must be one utility token without whitespace or malformed fractional commas.",
+            unexported: "Export every className declaration or function that produces a cn value.",
+        },
+    },
+    create(context) {
+        if (!isClassNamesFile(context))
+            return {};
+        return {
+            CallExpression(node) {
+                if (!isCn(node.callee))
+                    return;
+                if (!isExportedOwner(node))
+                    context.report({ node, messageId: "unexported" });
+                for (const argument of node.arguments)
+                    visitTokenLeaves(argument, (reportedNode, messageId) => context.report({ node: reportedNode, messageId }));
+            },
+        };
+    },
+});
+/** Every rule this law publishes. */
+export const rules = {
+    "no-inline-class-name": noInlineClassName,
+    "class-names-in-colocated-file": classNamesInColocatedFile,
+    "cn-arguments-are-single-tokens": cnArgumentsAreSingleTokens,
+};
+/** Recommended severity for the classNames law. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]));

package/dist/client-boundary.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The rule that holds `client-boundary.md` (HFS R55, `FE_CLIENT_BOUNDARY`).
+ *
+ * SERVER FIRST. A route file is a server component; `"use client"` is a cost the app pays where a
+ * reader interacts, and it is paid once, at the top of the interactive subtree, not sprinkled
+ * wherever a hook happened to be needed. The measured alternative: 155 client files in one app,
+ * a client layout that shipped a 132 KB message catalog to every page, against 3 client files in a
+ * sibling app that did the same job server-first.
+ *
+ * The directive is allowed in exactly the places the framework or the interaction requires:
+ *   - the `index.tsx` of an interactive block (or overlay), which is the connected half;
+ *   - a leaf, whose interactivity is intrinsic (a menu, a tooltip trigger);
+ *   - `error.tsx` and `global-error.tsx`, which Next requires to be client components;
+ *   - the client state of the front-end stack, which only ever runs in the browser: a provider of
+ *     `components/providers/<name>/index.tsx`, every file of `hooks/` (the SWR, form, store, socket and effect hooks and the
+ *     side-effect components), the redux store (`redux/`) and the toast module (`modules/toast/`). A directive there states
+ *     what the file already is; it ships nothing a server component would have kept.
+ * Everything below a client block is already on the client and needs no directive; everything
+ * above it is a server component and must not have one.
+ */
+import { type Recommended, type Rules } from "./lib/rule.js";
+/** `"use client"` only at an interaction boundary; pages and layouts stay server components. */
+export declare const useClientOnlyAtBoundary: import("./lib/rule.js").Rule<"slot" | "elsewhere", []>;
+/** A client component imports nothing that only exists on the server. */
+export declare const clientNoServerImport: import("./lib/rule.js").Rule<"server", []>;
+export declare const serverModuleMarksServerOnly: import("./lib/rule.js").Rule<"mark", []>;
+/**
+ * The front end serves no API: no `"use server"` directive, at the top of a module or as the first statement of a function.
+ * Reads and writes reach the back end through the operations of `modules/api` and the SWR hooks; a write that must run on a
+ * server is a GraphQL mutation of the back end.
+ */
+export declare const noServerAction: import("./lib/rule.js").Rule<"action", []>;
+/** Web storage is read and written only inside `modules/`. */
+export declare const webStorageOnlyInModules: import("./lib/rule.js").Rule<"storage", []>;
+/** Raw HTML is set only on a `<script>`, where the framework has no other way to inline JSON-LD or the theme bootstrap. */
+export declare const noDangerousHtml: import("./lib/rule.js").Rule<"html", []>;
+/** A cookie the app writes states its script reach, is sent only over TLS and is kept off cross-site requests. */
+export declare const responseCookieAttributes: import("./lib/rule.js").Rule<"attributes", []>;
+/** The rules this law contributes to the plugin. */
+export declare const rules: Rules;
+/** Every rule is an error. */
+export declare const recommended: Recommended;