@starci/eslint-canon-fe 8.3.0 → 8.4.1

package/hooks-folder.mjs

@@ -25,8 +25,13 @@
  * architecture machine that sees the whole tree.
  */
 
+import { importedReduxHook } from "./lib/redux-hook-origin.mjs"
+import { importedOwnHook } from "./lib/own-hook-origin.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
+import { walk } from "./lib/ast.mjs"
+import { functionOf, isFn, unwrap, variableOf } from "./lib/bindings.mjs"
 import { baseName, classOf, fileOf, inSlot } from "./lib/scope.mjs"
+import { rules as swrFamilyRules } from "./swr-family.mjs"
 
 /** Names that mark a hook. */
 const isHookName = (name) => /^use[A-Z0-9]/.test(name)
@@ -38,29 +43,153 @@ const isHookName = (name) => /^use[A-Z0-9]/.test(name)
 const isSwrKeyName = (name) => /^[A-Z][A-Z0-9_]*_SWR_KEY$/.test(name)
 
 /** A hook file name: `use<Name>.ts`. */
-const isHookFileName = (name) => /^use[A-Z0-9]\w*\.ts$/.test(name)
+const HOOK_FILE = new RegExp(String.raw`^use[A-Z0-9]\w*\.ts$`)
+const isHookFileName = (name) => HOOK_FILE.test(name)
 
 /** Modules that only run on the server: server code, not a hook. */
-const SERVER_ONLY = /^(?:server-only|next\/headers)$/
+const SERVER_ONLY = new Set(["server-only", "next/headers"])
 
 /** The hooks families of the front-end stack: each slot names its files (`allows`) and its non-hook files (roles). */
 const FAMILY_SLOTS = ["fe.hooks.swr", "fe.hooks.rhf", "fe.hooks.zustand", "fe.hooks.socketio", "fe.hooks.effects", "fe.hooks.reuseables"]
 
-/** The exported names a declaration introduces. */
-const exportedNames = (node) => {
+/** Runtime exports and their local values; type exports do not introduce hooks or helpers. */
+const exportedEntries = (node) => {
   if (node.type === "ExportDefaultDeclaration") {
     const declaration = node.declaration
-    return [declaration && declaration.id ? declaration.id.name : "default"]
+    return [{ node, name: declaration.id?.name ?? "default", local: declaration, default: true }]
   }
+  if (node.exportKind === "type") return []
+  if (node.type === "ExportAllDeclaration") return [{ node, name: "*", local: null }]
   const declaration = node.declaration
-  if (!declaration) return node.specifiers.map((specifier) => specifier.exported.name)
-  if (declaration.type === "FunctionDeclaration" && declaration.id) return [declaration.id.name]
+  if (!declaration) {
+    return node.specifiers.filter((specifier) => specifier.exportKind !== "type").map((specifier) => ({
+      node, name: specifier.exported.name ?? specifier.exported.value, local: node.source ? null : specifier.local,
+      default: (specifier.exported.name ?? specifier.exported.value) === "default",
+    }))
+  }
+  if (declaration.type === "FunctionDeclaration" && declaration.id) return [{ node, name: declaration.id.name, local: declaration }]
   if (declaration.type === "VariableDeclaration") {
-    return declaration.declarations.filter((d) => d.id.type === "Identifier").map((d) => d.id.name)
+    return declaration.declarations.filter((d) => d.id.type === "Identifier").map((d) => ({ node, name: d.id.name, local: d.id }))
   }
   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"])],
+])
+const SWR_DEFAULTS = new Map([["swr", "useSWR"], ["swr/immutable", "useSWRImmutable"], ["swr/infinite", "useSWRInfinite"], ["swr/mutation", "useSWRMutation"]])
+/**
+ * The library hooks a composite hook may stand on (an explicit list, owner ruling 2026-10-16): next-intl, next/navigation,
+ * 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"])],
+  ["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"
+const builtinHook = (origin) => origin?.source === OWN_HOOK || Boolean(LIBRARY_HOOKS.get(origin?.source)?.has(origin.name)) || origin?.source === "react-redux" || (origin?.source === "react" ? REACT_HOOKS.has(origin.name) : Boolean(SWR_HOOKS.get(origin?.source)?.has(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 (LIBRARY_HOOKS.get(source)?.has(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
+  const source = String(definition.parent.source.value)
+  if (definition.parent.importKind === "type" || specifier.importKind === "type") return null
+  if (source !== "react" && !SWR_HOOKS.has(source) && !LIBRARY_HOOKS.has(source)) return null
+  if (specifier.type === "ImportSpecifier") return namedOrigin(source, specifier.imported.name ?? specifier.imported.value)
+  if (specifier.type === "ImportDefaultSpecifier" && SWR_DEFAULTS.has(source)) return { source, name: SWR_DEFAULTS.get(source) }
+  return { source, name: null }
+}
+
+/** Resolve a constant alias, including destructuring a React/SWR namespace. */
+const constantOrigin = (context, definition, variable, seen) => {
+  const declaration = definition.node
+  if (declaration.type !== "VariableDeclarator" || definition.parent.kind !== "const") return null
+  const origin = hookOrigin(context, declaration.init, seen)
+  if (declaration.id.type === "Identifier") return origin
+  if (declaration.id.type !== "ObjectPattern" || !origin || origin.name !== null) return null
+  const property = declaration.id.properties.find((entry) => entry.type === "Property" && entry.value.type === "Identifier" && entry.value.name === variable.name)
+  if (!property) return null
+  const name = property.computed || property.key.type === "Literal" ? property.key.value : property.key.name
+  return namedOrigin(origin.source, name)
+}
+
+/** Follow lexical bindings so shadowed, reassigned and unrelated `use*` values cannot prove a hook. */
+const hookOrigin = (context, input, seen = new Set()) => {
+  const node = unwrap(input)
+  if (node?.type === "MemberExpression") {
+    const origin = hookOrigin(context, node.object, seen)
+    if (origin?.name !== null) return null
+    const name = propertyName(node)
+    return namedOrigin(origin.source, name)
+  }
+  if (node?.type !== "Identifier") return null
+  const variable = variableOf(context, node)
+  if (!variable || seen.has(variable) || variable.defs.length !== 1) return null
+  if (variable.references.some((reference) => reference.isWrite() && !reference.init)) return null
+  const definition = variable.defs[0]
+  if (definition.type === "ImportBinding") {
+    const origin = importOrigin(definition)
+    if (origin) return origin
+    if (importedReduxHook(context, definition)) return { source: "react-redux", name: "hook" }
+    return importedOwnHook(context, definition) ? { source: OWN_HOOK, name: "hook" } : null
+  }
+  return constantOrigin(context, definition, variable, new Set([...seen, variable]))
+}
+
+/** The exported function itself must call the hook; an unused nested callback is not evidence. */
+const callsBuiltinHook = (context, local) => {
+  const hook = functionOf(context, local)
+  if (!hook) return false
+  let found = false
+  walk(context.sourceCode, hook.body, (node) => {
+    if (found || isFn(node)) return false
+    if (node.type === "CallExpression" && builtinHook(hookOrigin(context, node.callee))) found = true
+    return undefined
+  })
+  return found
+}
+
+/** Exactly one named, locally implemented hook; optional SWR key and type exports remain available. */
+const checkHookExports = (context, program, exported) => {
+  const hooks = exported.filter((item) => !item.default && isHookName(item.name))
+  const defaults = exported.filter((item) => item.default)
+  for (const item of defaults) context.report({ node: item.node, messageId: "defaultExport" })
+  for (const item of exported) {
+    if (!item.default && !isHookName(item.name) && !isSwrKeyName(item.name)) {
+      context.report({ node: item.node, messageId: "export", data: { name: item.name } })
+    }
+  }
+  if (hooks.length === 0 && defaults.length === 0) context.report({ node: program, messageId: "missing" })
+  if (hooks.length > 1) context.report({ node: hooks[1].node, messageId: "many", data: { count: hooks.length } })
+  for (const item of hooks) {
+    if (!callsBuiltinHook(context, item.local)) context.report({ node: item.node, messageId: "fake", data: { name: item.name } })
+  }
+}
+
 /**
  * What the linted file is inside `hooks/`, or null when no hooks slot owns it: `stray` is a file its slot does not name
  * (directly in `hooks/`, a non-hook name in a domain, a name outside a family's `allows`); `hookFile` a `use<Name>.ts` hook
@@ -107,6 +236,12 @@ export const hooksFolderHoldsHooksOnly = {
         "`{{name}}` is exported from a hook file but is not a hook. A hook file exports the hook (a function named `use...`) and at most its SWR key (`QUERY_<X>_SWR_KEY`, `MUTATE_<X>_SWR_KEY`); a helper belongs in `<domain>.shared.ts`.",
       many:
         "This file exports {{count}} hooks. One hook per file keeps a hook findable by its name and keeps a change to one from re-running the tests of the others.",
+      missing:
+        "FE_HOOKS_ARE_HOOKS: a hook file exports exactly one named use* function that calls a hook (React, Redux, SWR, a listed library hook or a use* hook of the app's own hooks folders). Non-hook helpers belong in the domain's shared helper file.",
+      defaultExport:
+        "FE_HOOKS_ARE_HOOKS: export the hook as a named use* function. A default export does not identify the hook this file owns.",
+      fake:
+        "FE_HOOKS_ARE_HOOKS: `{{name}}` must be a function that calls a real hook: a React, Redux or SWR hook, a listed library hook (next-intl, next/navigation, react-hook-form, zustand) or a hook of the app's own `hooks/` folders. A use* name alone does not make a reader or helper a hook.",
       sharedHook:
         "`{{name}}` is a hook exported from the shared helper file. That file holds non-hook helpers; a hook there is a hook nobody will find. Give it its own `use<Name>.ts`.",
       server:
@@ -125,28 +260,22 @@ export const hooksFolderHoldsHooksOnly = {
         else context.report({ node: program, messageId: "notHook", data: { name } })
       },
       ImportDeclaration(node) {
-        if (SERVER_ONLY.test(String(node.source.value))) {
+        if (SERVER_ONLY.has(String(node.source.value))) {
           context.report({ node, messageId: "server", data: { source: node.source.value } })
         }
       },
       "Program:exit"(program) {
         if (judged.directlyInHooks || judged.stray || (!judged.hookFile && !judged.sharedFile)) return
         const exported = program.body
-          .filter((node) => node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration")
-          .flatMap((node) => exportedNames(node).map((exportedName) => ({ node, name: exportedName })))
+          .filter((node) => ["ExportNamedDeclaration", "ExportDefaultDeclaration", "ExportAllDeclaration"].includes(node.type))
+          .flatMap(exportedEntries)
         if (judged.sharedFile) {
           for (const item of exported) {
             if (isHookName(item.name)) context.report({ node: item.node, messageId: "sharedHook", data: { name: item.name } })
           }
           return
         }
-        const hooks = exported.filter((item) => isHookName(item.name))
-        for (const item of exported) {
-          if (!isHookName(item.name) && !isSwrKeyName(item.name) && item.name !== "default") {
-            context.report({ node: item.node, messageId: "export", data: { name: item.name } })
-          }
-        }
-        if (hooks.length > 1) context.report({ node: hooks[1].node, messageId: "many", data: { count: hooks.length } })
+        checkHookExports(context, program, exported)
       },
     }
   },
@@ -155,6 +284,8 @@ export const hooksFolderHoldsHooksOnly = {
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "hooks-folder-holds-hooks-only": hooksFolderHoldsHooksOnly,
+  // Forward the family enforcers for the catalog's source-only CONTRIBUTIONS discovery.
+  ...swrFamilyRules,
 }
 
 /** Every rule is an error. */

package/icon.mjs

@@ -16,6 +16,7 @@ import { isClassAttribute, staticText } from "./lib/ast.mjs"
 import { canonicalPackages } from "./lib/fe-stack.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
 import { fileOf, inSlot, isComponentFile, isProductSource, kindOfFile, roleOfFile } from "./lib/scope.mjs"
+import { why } from "./lib/why.mjs"
 
 /** The one module allowed to name a glyph from a library: the entry of the leaf owner named `Icon`. */
 const ICON_LEAF = { kind: "leaves", owner: "Icon" }
@@ -195,12 +196,78 @@ export const noDecorativeIconInMetricCell = {
   },
 }
 
+/** The immediately preceding JSDoc declares this exported component as a brand mark. */
+const declaresBrandMark = (sourceCode, node) => {
+  const comment = sourceCode.getCommentsBefore(node).at(-1)
+  return comment?.type === "Block" && comment.value.startsWith("*") &&
+    /(?:^|\n)\s*\*?\s*@brand-mark(?:\s|$)/.test(comment.value) &&
+    sourceCode.text.slice(comment.range[1], node.range[0]).trim() === ""
+}
+
+/** A marker belongs to the exported component itself, never to a sibling or an enclosing file. */
+const isDeclaredBrandMarkFunction = (sourceCode, node) => {
+  let declaration = node
+  if (node.parent?.type === "VariableDeclarator") {
+    if (node.parent.init !== node || node.parent.id.type !== "Identifier") return false
+    declaration = node.parent.parent
+    if (declaration.type !== "VariableDeclaration" || declaration.declarations.length !== 1) return false
+  }
+  const exported = declaration.parent
+  if (!["ExportNamedDeclaration", "ExportDefaultDeclaration"].includes(exported?.type)) return false
+  return declaresBrandMark(sourceCode, exported) || declaresBrandMark(sourceCode, declaration)
+}
+
+/** An SVG belongs to its nearest function; marking another component cannot license it. */
+const inDeclaredBrandMark = (sourceCode, node) => {
+  for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
+    if (["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"].includes(ancestor.type)) {
+      return isDeclaredBrandMarkFunction(sourceCode, ancestor)
+    }
+  }
+  return false
+}
+
+/** Inline SVG belongs only to an explicitly declared brand mark in a leaf entry. */
+export const noInlineSvgOutsideBrandMarkLeaf = {
+  meta: {
+    type: "problem",
+    docs: { description: "FE_ICON_INLINE_SVG: inline SVG is drawn only by an exported leaf entry component with a @brand-mark JSDoc declaration." },
+    schema: [],
+    messages: {
+      inlineSvg:
+        "FE_ICON_INLINE_SVG: inline `<svg>` draws a second glyph vocabulary. Use the Icon leaf for product glyphs. A brand mark may draw its own SVG only in a leaf entry whose exported component is immediately documented with `@brand-mark` in JSDoc.",
+    },
+  },
+  create(context) {
+    if (!isProductSource(context)) return {}
+    const sourceCode = context.sourceCode ?? context.getSourceCode()
+    const isLeafEntry = isComponentFile(context) && kindOfFile(context) === "leaves" && roleOfFile(context) === "entry"
+    return {
+      JSXOpeningElement(node) {
+        if (node.name?.type !== "JSXIdentifier" || node.name.name !== "svg") return
+        if (isLeafEntry && inDeclaredBrandMark(sourceCode, node)) return
+        context.report({ node, messageId: "inlineSvg" })
+      },
+    }
+  },
+}
+
+/** The finding code for the copy-and-glyph law's inline SVG enforcer. */
+Object.assign(why, {
+  "no-inline-svg-outside-brand-mark-leaf": {
+    code: "FE_ICON_INLINE_SVG",
+    en: "`<file>` draws an inline SVG outside an exported leaf entry component declared as a brand mark.",
+    fix: "Use the Icon leaf for product glyphs; declare an original brand mark with @brand-mark JSDoc on its exported leaf entry component.",
+  },
+})
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "no-vendor-icon-outside-icon-leaf": noVendorIconOutsideIconLeaf,
   "heroicons-is-the-glyph-vendor": heroiconsIsTheGlyphVendor,
   "no-off-scale-glyph-size": noOffScaleGlyphSize,
   "no-decorative-icon-in-metric-cell": noDecorativeIconInMetricCell,
+  "no-inline-svg-outside-brand-mark-leaf": noInlineSvgOutsideBrandMarkLeaf,
 }
 
 /**

package/index.mjs

@@ -237,3 +237,50 @@ export const starciFeConfig = ({ hfs } = {}) => {
     source: { ...recommended, ...reactHooksRules(reactHooks) },
   })
 }
+
+// A21 append-only registration: keep the already exported plugin and recommendation live.
+import { recommended as functionBudgetRecommended, rules as functionBudgetRules } from "./function-budget.mjs"
+CONTRIBUTIONS.push({ law: "function-budget", rules: functionBudgetRules, recommended: functionBudgetRecommended })
+lawOwners.push("function-budget")
+ruleDeclarations.push(...Object.keys(functionBudgetRules).map((name) => ({ law: "function-budget", name })))
+Object.assign(ruleOwners, Object.fromEntries(Object.keys(functionBudgetRules).map((name) => [name, "function-budget"])))
+Object.assign(rules, functionBudgetRules)
+Object.assign(recommended, functionBudgetRecommended)
+// A14 modules are also forwarded by the existing hooks-folder and transport contributions so
+// source-only catalog discovery can find them. The appended registration gives each module
+// ownership of those same rule instances without declaring either rule twice.
+import { recommended as swrFamilyRecommended, rules as swrFamilyRules } from "./swr-family.mjs"
+import { recommended as callbackShapeRecommended, rules as callbackShapeRules } from "./callback-shape.mjs"
+
+const A14_CONTRIBUTIONS = [
+  { law: "swr-family", rules: swrFamilyRules, recommended: swrFamilyRecommended },
+  { law: "callback-shape", rules: callbackShapeRules, recommended: callbackShapeRecommended },
+]
+
+for (const addition of A14_CONTRIBUTIONS) {
+  const names = new Set(Object.keys(addition.rules))
+  for (const contribution of CONTRIBUTIONS) {
+    for (const name of names) {
+      if (name in contribution.rules && contribution.rules[name] !== addition.rules[name]) {
+        throw new Error("A14 registration: two laws publish different rules named " + name)
+      }
+    }
+    // Replace contribution views only; the law module's exported maps retain their forwarding
+    // entries for the source-only catalog reader.
+    contribution.rules = Object.fromEntries(Object.entries(contribution.rules).filter(([name]) => !names.has(name)))
+    contribution.recommended = Object.fromEntries(
+      Object.entries(contribution.recommended).filter(([name]) => !names.has(name.replace(/^starci-fe\//, ""))),
+    )
+  }
+  CONTRIBUTIONS.push(addition)
+  lawOwners.push(addition.law)
+  for (const name of names) {
+    const declarations = ruleDeclarations.filter((entry) => entry.name === name)
+    if (declarations.length > 1) throw new Error("A14 registration: duplicate declarations for " + name)
+    if (declarations.length === 1) declarations[0].law = addition.law
+    else ruleDeclarations.push({ law: addition.law, name })
+    ruleOwners[name] = addition.law
+  }
+  Object.assign(rules, addition.rules)
+  Object.assign(recommended, addition.recommended)
+}

package/lib/own-hook-origin.mjs

@@ -0,0 +1,53 @@
+/**
+ * Resolve a `use*` import that comes from the app's own hooks folders (`hooks/swr`, `hooks/<domain>`, `hooks/zustand/<store>`...) by
+ * TypeScript symbol resolution, never by the spelling of the name (R56 `FE_HOOKS_ARE_HOOKS`, owner ruling 2026-10-16 "Theo y tro").
+ *
+ * A composite product hook is built from the hooks beneath it: `hooks/<domain>/use<Name>.ts` composes the `use{Query,Mutate}<X>Swr`
+ * wrappers of `hooks/swr`. The import is followed through barrels and re-exports to the declaration, and counts only when that declaration
+ * is a `use*` value that lives in a `hooks/` folder of the app (never in `node_modules`). The hook's own file is judged by this same
+ * rule when it is linted, so a fake one is refused where it is written.
+ */
+import ts from "typescript"
+import { programFor } from "./program-for.mjs"
+
+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. */
+const widened = new WeakMap()
+export function reaching(program, filename, targetFile) {
+  if (program.getSourceFile(targetFile)) return program
+  const key = `${filename}\0${targetFile}`
+  const cache = widened.get(program) ?? new Map()
+  widened.set(program, cache)
+  if (!cache.has(key)) cache.set(key, ts.createProgram([filename, targetFile], program.getCompilerOptions()))
+  return cache.get(key)
+}
+
+/** A declaration of a hook value: a function or a variable, not a type, interface, class or enum. */
+const hookValue = (declaration) => ts.isFunctionDeclaration(declaration) || ts.isVariableDeclaration(declaration)
+
+const inAppHooksFolder = (file) => {
+  const fileName = file.fileName.replaceAll("\\", "/")
+  return !fileName.includes("/node_modules/") && !file.isDeclarationFile && HOOKS_FOLDER.test(fileName)
+}
+
+/** 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
+  if (specifier.type !== "ImportSpecifier" || definition.parent.importKind === "type" || specifier.importKind === "type") return false
+  const name = specifier.imported.name ?? specifier.imported.value
+  if (!isHookName(name)) return false
+  const source = String(definition.parent.source.value)
+  const base = programFor(context)
+  const target = ts.resolveModuleName(source, context.filename, base.getCompilerOptions(), ts.sys).resolvedModule
+  if (!target || target.isExternalLibraryImport) return false
+  const program = reaching(base, context.filename, target.resolvedFileName)
+  const file = program.getSourceFile(target.resolvedFileName)
+  const checker = program.getTypeChecker()
+  const moduleSymbol = file && checker.getSymbolAtLocation(file)
+  const exported = moduleSymbol && checker.getExportsOfModule(moduleSymbol).find((symbol) => symbol.name === name)
+  if (!exported) return false
+  const symbol = exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported
+  return (symbol.declarations ?? []).some((declaration) => hookValue(declaration) && inAppHooksFolder(declaration.getSourceFile()))
+}

package/lib/program-for.mjs

@@ -0,0 +1,22 @@
+/** The TypeScript program a rule resolves symbols through: the lint run's own when typed linting is on, else one rooted at the linted file. */
+import ts from "typescript"
+import path from "node:path"
+
+const programs = new WeakMap()
+
+/** The program for a rule context; a program built here is remembered per context. */
+export function programFor(context) {
+  if (programs.has(context)) return programs.get(context)
+  const services = context.sourceCode?.parserServices
+  if (services?.program) return services.program
+  const filename = context.filename
+  const configPath = ts.findConfigFile(path.dirname(filename), ts.sys.fileExists)
+  let options = { moduleResolution: ts.ModuleResolutionKind.Bundler, module: ts.ModuleKind.ESNext }
+  if (configPath) {
+    const config = ts.readConfigFile(configPath, ts.sys.readFile)
+    options = { ...options, ...ts.parseJsonConfigFileContent(config.config, ts.sys, path.dirname(configPath)).options }
+  }
+  const program = ts.createProgram([filename], options)
+  programs.set(context, program)
+  return program
+}

package/lib/pure-owner-helper.mjs

@@ -0,0 +1,148 @@
+/**
+ * The owner exports an auth callback may use besides the exchange (R287 `FE_CALLBACK_SHAPE`, owner ruling `auth-callback-pure-helpers`,
+ * 2026-10-17 "Theo y tro"): a PURE helper of the app's `modules/routes` or `modules/auth` that computes the redirect target or validates
+ * `next`, and a static route table. Both are found by TypeScript symbol resolution to the declaration, never by the spelling of the name.
+ *
+ * A pure helper is a synchronous function that returns text (or null), holds no `await` or `yield`, reaches no I/O global (network, storage,
+ * DOM, `process`, `require`, `console`) and calls only locals, language built-ins and other pure helpers of `modules/routes` or
+ * `modules/auth` (followed through barrels). `modules/config` is the environment owner: a call to its readers is a configuration read, not I/O.
+ * Anything else it imports, a library value included, makes it impure.
+ */
+import ts from "typescript"
+import { reaching } from "./own-hook-origin.mjs"
+import { programFor } from "./program-for.mjs"
+import { resolveImport } from "./scope.mjs"
+
+/** Globals that reach the network, storage, the page, the process or the console. */
+const IO_GLOBALS = new Set(["fetch", "XMLHttpRequest", "WebSocket", "EventSource", "Request", "navigator", "localStorage", "sessionStorage", "indexedDB", "document", "window", "self", "globalThis", "process", "require", "console", "setTimeout", "setInterval", "queueMicrotask", "Worker", "BroadcastChannel"])
+
+const OWNER_FILE = /\/modules\/(?:routes|auth)(?:\/|\.tsx?$)/
+const CONFIG_FILE = /\/modules\/config(?:\/|\.tsx?$)/
+const EXTENSIONS = ["", ".ts", ".tsx", "/index.ts", "/index.tsx"]
+
+const normal = (file) => file.fileName.replaceAll("\\", "/")
+
+/** The module file an import specifier names, or null when none exists on disk. */
+const moduleFile = (context, source) => {
+  const target = resolveImport(context, source)
+  if (target === null) return null
+  return EXTENSIONS.map((extension) => `${target}${extension}`).find((candidate) => ts.sys.fileExists(candidate)) ?? null
+}
+
+/** The declaration an export of the module resolves to, after barrels and re-exports. */
+const exportedDeclaration = (context, source, name) => {
+  const file = moduleFile(context, source)
+  if (file === null) return null
+  const program = reaching(programFor(context), context.filename, file)
+  const checker = program.getTypeChecker()
+  const sourceFile = program.getSourceFile(file)
+  const moduleSymbol = sourceFile && checker.getSymbolAtLocation(sourceFile)
+  const exported = moduleSymbol && checker.getExportsOfModule(moduleSymbol).find((symbol) => symbol.name === name)
+  if (!exported) return null
+  const symbol = exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported
+  return { checker, declaration: symbol.declarations?.[0] ?? null }
+}
+
+/** Strip `as`, `satisfies` and parentheses. */
+const bare = (node) => {
+  let current = node
+  while (current && (ts.isAsExpression(current) || ts.isSatisfiesExpression(current) || ts.isParenthesizedExpression(current))) current = current.expression
+  return current
+}
+
+/** The function-like node of a function declaration or of a variable initialised with an arrow or function expression. */
+const functionOf = (declaration) => {
+  if (ts.isFunctionDeclaration(declaration)) return declaration
+  const init = ts.isVariableDeclaration(declaration) ? bare(declaration.initializer) : null
+  return init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) ? init : null
+}
+
+const isInside = (node, root) => node.getSourceFile() === root.getSourceFile() && node.pos >= root.pos && node.end <= root.end
+
+/** Whether an identifier names a declaration, a property or a member rather than referring to a binding. */
+const isNameOnly = (node) => {
+  const parent = node.parent
+  if (ts.isPropertyAccessExpression(parent)) return parent.name === node
+  if (ts.isPropertyAssignment(parent) || ts.isMethodDeclaration(parent) || ts.isPropertySignature(parent)) return parent.name === node
+  return (ts.isParameter(parent) || ts.isVariableDeclaration(parent) || ts.isFunctionDeclaration(parent) || ts.isBindingElement(parent)) && parent.name === node
+}
+
+/** A declaration of another file: an owner helper is followed, the environment owner is a leaf, everything else is impure. */
+const foreignPure = (env, declaration, root) => {
+  const file = normal(declaration.getSourceFile())
+  if (CONFIG_FILE.test(file)) return true
+  if (!OWNER_FILE.test(file) || declaration.getSourceFile().isDeclarationFile) return false
+  return declarationPure(env, declaration, root)
+}
+
+/** A global of the language or of the lib files is pure unless it reaches I/O. */
+const globalPure = (symbol) => !IO_GLOBALS.has(symbol.getName())
+
+/** Whether one identifier reference stays inside the pure surface. */
+const referencePure = (env, node, root) => {
+  const symbol = env.checker.getSymbolAtLocation(node)
+  if (!symbol) return node.text === "undefined"
+  const target = symbol.flags & ts.SymbolFlags.Alias ? env.checker.getAliasedSymbol(symbol) : symbol
+  const declarations = target.declarations ?? []
+  if (declarations.length === 0) return node.text === "undefined"
+  return declarations.every((declaration) => {
+    const file = declaration.getSourceFile()
+    if (isInside(declaration, root)) return true
+    if (!ts.isExternalModule(file)) return globalPure(target)
+    return foreignPure(env, declaration, root)
+  })
+}
+
+/** Walk a node: no await or yield, no impure reference; type positions are not behaviour. */
+const nodePure = (env, node, root) => {
+  if (ts.isAwaitExpression(node) || ts.isYieldExpression(node)) return false
+  if (ts.isTypeNode(node) && !ts.isExpressionWithTypeArguments(node)) return true
+  if (ts.isIdentifier(node) && !isNameOnly(node) && !referencePure(env, node, root)) return false
+  return ts.forEachChild(node, (child) => (nodePure(env, child, root) ? undefined : true)) !== true
+}
+
+/** A declaration is pure when its function (or its constant initialiser) is. */
+function declarationPure(env, declaration, root) {
+  if (env.seen.has(declaration)) return true
+  env.seen.add(declaration)
+  const fn = functionOf(declaration)
+  if (fn) return !fn.asteriskToken && !fn.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword) && (fn.body ? nodePure(env, fn.body, fn) : false)
+  if (ts.isVariableDeclaration(declaration) && declaration.initializer) return nodePure(env, declaration.initializer, declaration.initializer)
+  return false
+}
+
+/** Whether a function's declared or inferred return type is text, null or undefined. */
+const returnsText = (checker, declaration) => {
+  const signature = checker.getSignaturesOfType(checker.getTypeAtLocation(declaration), ts.SignatureKind.Call)[0]
+  if (!signature) return false
+  const type = checker.getReturnTypeOfSignature(signature)
+  const parts = type.isUnion() ? type.types : [type]
+  return parts.every((part) => part.flags & (ts.TypeFlags.StringLike | ts.TypeFlags.Null | ts.TypeFlags.Undefined))
+}
+
+/** A static table: a constant object whose leaves are string literals or plain templates. */
+const isStaticTable = (node) => {
+  const value = bare(node)
+  if (!value) return false
+  if (ts.isStringLiteralLike(value)) return true
+  if (ts.isObjectLiteralExpression(value)) return value.properties.every((property) => ts.isPropertyAssignment(property) && isStaticTable(property.initializer))
+  return false
+}
+
+/**
+ * What an import of the callback's owner modules is: `"pure"` (a pure text-returning helper), `"routes"` (a static route table) or null.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {string} source - The import specifier.
+ * @param {string} name - The imported name.
+ * @returns {"pure" | "routes" | null} The kind.
+ */
+export function ownerExportKind(context, source, name) {
+  const found = exportedDeclaration(context, source, name)
+  if (!found?.declaration) return null
+  const { checker, declaration } = found
+  if (ts.isVariableDeclaration(declaration) && !functionOf(declaration)) return declaration.parent.flags & ts.NodeFlags.Const && isStaticTable(declaration.initializer) ? "routes" : null
+  const fn = functionOf(declaration)
+  const env = { checker, seen: new Set() }
+  return fn && returnsText(checker, fn) && declarationPure(env, declaration, fn) ? "pure" : null
+}

package/lib/redux-hook-origin.mjs

@@ -0,0 +1,44 @@
+/** Resolve typed Redux hook factories by their import provenance, never by a local use* name. */
+import ts from "typescript"
+import { programFor } from "./program-for.mjs"
+
+const REDUX_HOOKS = new Set(["useSelector", "useDispatch", "useStore"])
+
+function reduxImport(declaration) {
+  if (!ts.isImportSpecifier(declaration) || declaration.isTypeOnly) return false
+  const clause = declaration.parent.parent
+  return !clause.isTypeOnly && clause.parent.moduleSpecifier.text === "react-redux"
+    && REDUX_HOOKS.has((declaration.propertyName ?? declaration.name).text)
+}
+
+function typedFactory(checker, declaration) {
+  if (!ts.isVariableDeclaration(declaration) || !(declaration.parent.flags & ts.NodeFlags.Const)) return false
+  const call = declaration.initializer
+  if (!call || !ts.isCallExpression(call) || call.arguments.length !== 0) return false
+  const member = call.expression
+  return ts.isPropertyAccessExpression(member) && member.name.text === "withTypes"
+    && reduxBinding(checker, member.expression)
+}
+
+function reduxBinding(checker, node) {
+  const symbol = checker.getSymbolAtLocation(node)
+  return (symbol?.declarations ?? []).some(reduxImport)
+}
+
+/** A relative/barrel import must resolve to a const initialized by a real Redux hook's withTypes(). */
+export function importedReduxHook(context, definition) {
+  const specifier = definition.node
+  if (specifier.type !== "ImportSpecifier" || definition.parent.importKind === "type" || specifier.importKind === "type") return false
+  const source = String(definition.parent.source.value)
+  const name = specifier.imported.name ?? specifier.imported.value
+  if (source === "react-redux") return REDUX_HOOKS.has(name)
+  const program = programFor(context)
+  const target = ts.resolveModuleName(source, context.filename, program.getCompilerOptions(), ts.sys).resolvedModule
+  const file = target && program.getSourceFile(target.resolvedFileName)
+  const checker = program.getTypeChecker()
+  const moduleSymbol = file && checker.getSymbolAtLocation(file)
+  const exported = moduleSymbol && checker.getExportsOfModule(moduleSymbol).find(symbol => symbol.name === name)
+  if (!exported) return false
+  const symbol = exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported
+  return (symbol.declarations ?? []).some(declaration => typedFactory(checker, declaration))
+}