@starci/eslint-canon-fe 9.9.10 → 9.9.11

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 9.9.11
+
+- Changed: Recognize declared module hook roles through real hook-call provenance.
+
 ## 9.9.10
 
 - Changed: Refresh shared repository identity and release-aligned canon data.

package/dist/hooks-folder.js

@@ -28,6 +28,7 @@
 import { defineRule } from "./lib/rule.js";
 import { importedReduxHook } from "./lib/redux-hook-origin.js";
 import { importedOwnHook } from "./lib/own-hook-origin.js";
+import { builtinHook, isLibrarySource, namedOrigin, OWN_HOOK } from "./lib/hook-library-origin.js";
 import { hfsOf } from "./lib/hfs.js";
 import { walk } from "./lib/ast.js";
 import { functionOf, isFn, unwrap, variableOf } from "./lib/bindings.js";
@@ -75,55 +76,11 @@ const exportedEntries = (node) => {
     }
     return [];
 };
-/** Actual React hook APIs and SWR public entry points, rather than an arbitrary `use*` spelling. */
-const REACT_HOOKS = new Set([
-    "use", "useState", "useReducer", "useEffect", "useLayoutEffect", "useInsertionEffect", "useRef", "useImperativeHandle",
-    "useMemo", "useCallback", "useContext", "useDebugValue", "useDeferredValue", "useTransition", "useId",
-    "useSyncExternalStore", "useActionState", "useOptimistic",
-]);
-const SWR_HOOKS = new Map([
-    ["swr", new Set(["useSWR", "useSWRConfig"])],
-    ["swr/immutable", new Set(["useSWRImmutable"])],
-    ["swr/infinite", new Set(["useSWRInfinite"])],
-    ["swr/mutation", new Set(["useSWRMutation"])],
-    ["swr/subscription", new Set(["useSWRSubscription"])],
-]);
-const SWR_DEFAULTS = new Map([["swr", "useSWR"], ["swr/immutable", "useSWRImmutable"], ["swr/infinite", "useSWRInfinite"], ["swr/mutation", "useSWRMutation"], ["swr/subscription", "useSWRSubscription"]]);
-/**
- * The canonical library hooks a composite hook may call (R56, FE-THEME): next-intl, next/navigation,
- * next-themes, react-hook-form and zustand's React entry points. A name outside the list is not a hook by its spelling.
- */
-const LIBRARY_HOOKS = new Map([
-    ["next-intl", new Set(["useTranslations", "useLocale", "useFormatter", "useNow", "useTimeZone", "useMessages"])],
-    ["next/navigation", new Set(["useRouter", "usePathname", "useSearchParams", "useParams", "useSelectedLayoutSegment", "useSelectedLayoutSegments"])],
-    ["next-themes", new Set(["useTheme"])],
-    ["react-hook-form", new Set(["useForm", "useFormContext", "useWatch", "useController", "useFieldArray", "useFormState"])],
-    ["zustand", new Set(["useStore"])],
-    ["zustand/react/shallow", new Set(["useShallow"])],
-]);
-const OWN_HOOK = "own-hooks";
-/** True when `set` holds `name`. */
-const hasName = (set, name) => set !== undefined && typeof name === "string" && set.has(name);
-const builtinHook = (origin) => {
-    if (origin === null)
-        return false;
-    return origin.source === OWN_HOOK || hasName(LIBRARY_HOOKS.get(origin.source), origin.name) || origin.source === "react-redux" || (origin.source === "react" ? hasName(REACT_HOOKS, origin.name) : hasName(SWR_HOOKS.get(origin.source), origin.name));
-};
 const propertyName = (node) => {
     if (!node.computed && node.property.type === "Identifier")
         return node.property.name;
     return node.property.type === "Literal" ? node.property.value : null;
 };
-/** SWR request hooks are default exports; its root also names useSWRConfig. */
-const namedOrigin = (source, name) => {
-    if (source === "react")
-        return { source, name };
-    if (hasName(LIBRARY_HOOKS.get(source), name))
-        return { source, name };
-    if (name === "default" && SWR_DEFAULTS.has(source))
-        return { source, name: SWR_DEFAULTS.get(source) };
-    return source === "swr" && name === "useSWRConfig" ? { source, name } : null;
-};
 /** A runtime import records whether its value is a hook or its module namespace. */
 const importOrigin = (definition) => {
     const specifier = definition.node;
@@ -132,14 +89,14 @@ const importOrigin = (definition) => {
     const source = String(definition.parent.source.value);
     if (definition.parent.importKind === "type" || ("importKind" in specifier && specifier.importKind === "type"))
         return null;
-    if (source !== "react" && !SWR_HOOKS.has(source) && !LIBRARY_HOOKS.has(source))
+    if (!isLibrarySource(source))
         return null;
     if (source === "next-themes" && specifier.type === "ImportDefaultSpecifier")
         return null;
     if (specifier.type === "ImportSpecifier")
         return namedOrigin(source, spelled(specifier.imported));
-    if (specifier.type === "ImportDefaultSpecifier" && SWR_DEFAULTS.has(source))
-        return { source, name: SWR_DEFAULTS.get(source) };
+    if (specifier.type === "ImportDefaultSpecifier")
+        return source === "react" ? { source, name: null } : namedOrigin(source, "default") ?? { source, name: null };
     return { source, name: null };
 };
 /** Resolve a constant alias, including destructuring a React/SWR namespace. */

package/dist/lib/hook-library-origin.d.ts

@@ -0,0 +1,13 @@
+/** The marker for an app hook proven by symbol provenance. */
+export declare const OWN_HOOK = "own-hooks";
+/** Where a hook comes from: the module and the export it names (null for the module object itself; any key a member reads). */
+export interface HookOrigin {
+    readonly source: string;
+    readonly name: unknown;
+}
+/** Judge an origin against the canonical library hook catalog. */
+export declare const builtinHook: (origin: HookOrigin | null) => boolean;
+/** SWR request hooks are default exports; its root also names useSWRConfig. */
+export declare const namedOrigin: (source: string, name: unknown) => HookOrigin | null;
+/** A library with a known hook entry. */
+export declare const isLibrarySource: (source: string) => boolean;

package/dist/lib/hook-library-origin.js

@@ -0,0 +1,48 @@
+/** Actual React hook APIs and SWR public entry points, rather than an arbitrary `use*` spelling. */
+const REACT_HOOKS = new Set([
+    "use", "useState", "useReducer", "useEffect", "useLayoutEffect", "useInsertionEffect", "useRef", "useImperativeHandle",
+    "useMemo", "useCallback", "useContext", "useDebugValue", "useDeferredValue", "useTransition", "useId",
+    "useSyncExternalStore", "useActionState", "useOptimistic",
+]);
+const SWR_HOOKS = new Map([
+    ["swr", new Set(["useSWR", "useSWRConfig"])],
+    ["swr/immutable", new Set(["useSWRImmutable"])],
+    ["swr/infinite", new Set(["useSWRInfinite"])],
+    ["swr/mutation", new Set(["useSWRMutation"])],
+    ["swr/subscription", new Set(["useSWRSubscription"])],
+]);
+const SWR_DEFAULTS = new Map([["swr", "useSWR"], ["swr/immutable", "useSWRImmutable"], ["swr/infinite", "useSWRInfinite"], ["swr/mutation", "useSWRMutation"], ["swr/subscription", "useSWRSubscription"]]);
+/**
+ * The canonical library hooks a composite hook may call (R56, FE-THEME): next-intl, next/navigation,
+ * next-themes, react-hook-form and zustand's React entry points. A name outside the list is not a hook by its spelling.
+ */
+const LIBRARY_HOOKS = new Map([
+    ["next-intl", new Set(["useTranslations", "useLocale", "useFormatter", "useNow", "useTimeZone", "useMessages"])],
+    ["next/navigation", new Set(["useRouter", "usePathname", "useSearchParams", "useParams", "useSelectedLayoutSegment", "useSelectedLayoutSegments"])],
+    ["next-themes", new Set(["useTheme"])],
+    ["react-hook-form", new Set(["useForm", "useFormContext", "useWatch", "useController", "useFieldArray", "useFormState"])],
+    ["zustand", new Set(["useStore"])],
+    ["zustand/react/shallow", new Set(["useShallow"])],
+]);
+/** The marker for an app hook proven by symbol provenance. */
+export const OWN_HOOK = "own-hooks";
+/** True when `set` holds `name`. */
+const hasName = (set, name) => set !== undefined && typeof name === "string" && set.has(name);
+/** Judge an origin against the canonical library hook catalog. */
+export const builtinHook = (origin) => {
+    if (origin === null)
+        return false;
+    return origin.source === OWN_HOOK || hasName(LIBRARY_HOOKS.get(origin.source), origin.name) || origin.source === "react-redux" || (origin.source === "react" ? hasName(REACT_HOOKS, origin.name) : hasName(SWR_HOOKS.get(origin.source), origin.name));
+};
+/** SWR request hooks are default exports; its root also names useSWRConfig. */
+export const namedOrigin = (source, name) => {
+    if (source === "react")
+        return { source, name };
+    if (hasName(LIBRARY_HOOKS.get(source), name))
+        return { source, name };
+    if (name === "default" && SWR_DEFAULTS.has(source))
+        return { source, name: SWR_DEFAULTS.get(source) };
+    return source === "swr" && name === "useSWRConfig" ? { source, name } : null;
+};
+/** A library with a known hook entry. */
+export const isLibrarySource = (source) => source === "react" || SWR_HOOKS.has(source) || LIBRARY_HOOKS.has(source);

package/dist/lib/own-hook-origin.js

@@ -1,5 +1,7 @@
 import ts from "typescript";
 import { programFor } from "./program-for.js";
+import { hfsOf } from "./hfs.js";
+import { builtinHook, namedOrigin } from "./hook-library-origin.js";
 const HOOKS_FOLDER = /(^|\/)hooks\//;
 const isHookName = (name) => /^use[A-Z0-9]/.test(name);
 /** The program that holds the import target: the project program has it; a program rooted at the linted file alone (its disk text may differ from the linted text) is widened with it. */
@@ -23,6 +25,133 @@ const inAppHooksFolder = (file) => {
     const fileName = file.fileName.replaceAll("\\", "/");
     return !fileName.includes("/node_modules/") && !file.isDeclarationFile && HOOKS_FOLDER.test(fileName);
 };
+/** A type-only alias never supplies a runtime hook. */
+const runtimeAlias = (declaration) => {
+    if (ts.isImportSpecifier(declaration))
+        return !declaration.isTypeOnly && !declaration.parent.parent.isTypeOnly;
+    if (ts.isImportClause(declaration))
+        return !declaration.isTypeOnly;
+    if (ts.isExportSpecifier(declaration))
+        return !declaration.isTypeOnly && !declaration.parent.parent.isTypeOnly;
+    if (ts.isNamespaceExport(declaration))
+        return !declaration.parent.isTypeOnly;
+    return false;
+};
+/** Follow every alias separately, so a type-only link or cycle never becomes a runtime binding. */
+function runtimeSymbol(checker, start) {
+    let symbol = start;
+    const seen = new Set();
+    while ((symbol.flags & ts.SymbolFlags.Alias) !== 0) {
+        if (seen.has(symbol))
+            return null;
+        seen.add(symbol);
+        const declarations = symbol.declarations ?? [];
+        if (declarations.length !== 1 || !declarations.every(runtimeAlias))
+            return null;
+        const next = checker.getImmediateAliasedSymbol(symbol);
+        if (!next)
+            return null;
+        symbol = next;
+    }
+    return symbol;
+}
+/** The module hook role is slot-defined and belongs to the same app as the caller. */
+function moduleHookRole(context, file) {
+    const hfs = hfsOf(context);
+    const found = hfs.classify(file.fileName);
+    const caller = hfs.classify(context.filename);
+    return !file.isDeclarationFile && !file.fileName.replaceAll("\\", "/").includes("/node_modules/") &&
+        found.status === "owned" && found.slot?.startsWith("fe.modules.") === true && found.role === "hooks" &&
+        found.bindings?.app !== undefined && found.bindings.app === caller.bindings?.app && hfs.allows(file.fileName)?.allowed === true;
+}
+/** A known library import is proven by its own runtime import declaration and canonical exported name. */
+function libraryImport(declaration) {
+    if (!runtimeAlias(declaration))
+        return false;
+    if (ts.isImportSpecifier(declaration)) {
+        const module = declaration.parent.parent.parent.moduleSpecifier;
+        return ts.isStringLiteral(module) && builtinHook(namedOrigin(module.text, (declaration.propertyName ?? declaration.name).text));
+    }
+    if (ts.isExportSpecifier(declaration)) {
+        const module = declaration.parent.parent.moduleSpecifier;
+        return module !== undefined && ts.isStringLiteral(module) && builtinHook(namedOrigin(module.text, (declaration.propertyName ?? declaration.name).text));
+    }
+    return false;
+}
+/** Follow runtime re-exports until a known library import itself proves the binding. */
+function librarySymbol(checker, start) {
+    let symbol = start;
+    const visited = new Set();
+    while (!visited.has(symbol)) {
+        visited.add(symbol);
+        const declarations = symbol.declarations ?? [];
+        if (declarations.length !== 1)
+            return false;
+        const declaration = declarations[0];
+        if (!declaration)
+            return false;
+        if (libraryImport(declaration))
+            return true;
+        if ((symbol.flags & ts.SymbolFlags.Alias) === 0 || !runtimeAlias(declaration))
+            return false;
+        const next = checker.getImmediateAliasedSymbol(symbol);
+        if (!next)
+            return false;
+        symbol = next;
+    }
+    return false;
+}
+/** Resolve calls through lexical symbols, constant aliases and runtime import/re-export chains. */
+function moduleHookBody(context, checker, declaration, seen) {
+    if (!moduleHookRole(context, declaration.getSourceFile()))
+        return false;
+    if (ts.isVariableDeclaration(declaration) && (declaration.parent.flags & ts.NodeFlags.Const) === 0)
+        return false;
+    const body = ts.isFunctionDeclaration(declaration) ? declaration.body : ts.isVariableDeclaration(declaration) && declaration.initializer &&
+        (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer)) ? declaration.initializer.body : undefined;
+    if (!body)
+        return false;
+    const proves = (expression, visited) => {
+        if (!ts.isIdentifier(expression))
+            return false;
+        const symbol = checker.getSymbolAtLocation(expression);
+        if (!symbol || visited.has(symbol))
+            return false;
+        const nextSeen = new Set([...visited, symbol]);
+        if (librarySymbol(checker, symbol))
+            return true;
+        const resolved = runtimeSymbol(checker, symbol);
+        if (!resolved || nextSeen.has(resolved) && resolved !== symbol)
+            return false;
+        const actual = resolved.declarations ?? [];
+        if (actual.length !== 1)
+            return false;
+        const target = actual[0];
+        if (!target)
+            return false;
+        if (hookValue(target) && inAppHooksFolder(target.getSourceFile()) && isHookName(resolved.name)) {
+            const hfs = hfsOf(context);
+            const app = hfs.classify(context.filename).bindings?.app;
+            const found = hfs.classify(target.getSourceFile().fileName);
+            return app !== undefined && found.status === "owned" && found.slot?.startsWith("fe.hooks") === true && found.bindings?.app === app;
+        }
+        if (ts.isVariableDeclaration(target) && (target.parent.flags & ts.NodeFlags.Const) !== 0 && target.initializer && ts.isIdentifier(target.initializer))
+            return proves(target.initializer, nextSeen);
+        return moduleHookBody(context, checker, target, nextSeen);
+    };
+    let found = false;
+    const visit = (node) => {
+        if (found || node !== body && ts.isFunctionLike(node))
+            return;
+        if (ts.isCallExpression(node) && proves(node.expression, seen)) {
+            found = true;
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(body);
+    return found;
+}
 /** True when the import binding is a runtime `use*` import that resolves to a hook declared in a `hooks/` folder of the app. */
 export function importedOwnHook(context, definition) {
     const specifier = definition.node;
@@ -47,6 +176,11 @@ export function importedOwnHook(context, definition) {
     const exported = moduleSymbol ? checker.getExportsOfModule(moduleSymbol).find((symbol) => symbol.name === name) : undefined;
     if (!exported)
         return false;
-    const symbol = (exported.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(exported) : exported;
-    return (symbol.declarations ?? []).some((declaration) => hookValue(declaration) && inAppHooksFolder(declaration.getSourceFile()));
+    const original = (exported.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(exported) : exported;
+    if ((original.declarations ?? []).some((declaration) => hookValue(declaration) && inAppHooksFolder(declaration.getSourceFile())))
+        return true;
+    const symbol = runtimeSymbol(checker, exported);
+    if (!symbol)
+        return false;
+    return (symbol.declarations ?? []).some((declaration) => hookValue(declaration) && moduleHookBody(context, checker, declaration, new Set([symbol])));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "9.9.10",
+  "version": "9.9.11",
   "description": "Universal front-end lint laws for TypeScript and Next.js, independent of the selected Grammar family.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,35 +31,35 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.21.10
+    version: 0.21.11
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.11.17
+    version: 3.11.18
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.9.10
+    version: 9.9.11
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.21.10
+    version: 0.21.11
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.21.10
+    version: 0.21.11
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 5.0.6
+    version: 5.0.7
     group: starci
     install: registry
     side: both