@starci/eslint-canon-fe 8.3.0 → 8.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+- Changed (R287 `FE_CALLBACK_SHAPE`, a18.1 NIVO request F2, owner ruling `auth-callback-pure-helpers`): the auth callback may call pure text helpers of the app's `modules/routes` or `modules/auth` (`requestOrigin`, `safeNextPath`; resolved by TypeScript symbol: synchronous, no await, no I/O global, only owner helpers and `modules/config` readers), use static route tables (`AUTH_ROUTES`), and read the exchange outcome's `success` or `ok` flag. An impure, async or non-text helper, a helper outside those owners and a credential passed to a helper are still refused.
+- Changed (R287 `FE_CALLBACK_SHAPE`, a18.1 NIVO request F, owner ruling `auth-callback-email-link`): the auth callback may await one `verifyOtp({ token_hash, type })` of the auth owner (`auth.verifyOtp` or `verifyOtp` from `modules/auth/server`), built from exactly the query values `token_hash` and `type`, beside the one `exchangeAuthCode(code)`; the token hash never reaches a redirect.
+- Fixed (R55 `FE_CLIENT_BOUNDARY`, a18.1 NIVO request I): the finding on a page or layout owner now says the owner stays a server component that renders the client block or overlay carrying the directive. The rule is unchanged.
+
 ## 8.3.0 - 2026-10-15
 - Changed: layouts may import overlays beside pages (tier edge `feature -> feature` from pages and layouts to overlays); a layout hosts the route-selected overlay through `components/branches/OverlayHost` while pages stay server components (pattern FE-BOUNDARY-5). Carries the runtime mirror of the manifest and pins, rebased onto alpha.13 (eslint-canon-fe 8.2.18).
 

package/callback-shape.mjs

@@ -0,0 +1,344 @@
+/**
+ * R287 FE_CALLBACK_SHAPE: the Supabase callback only reads the PKCE code (or the email-link `token_hash` and `type`), exchanges it
+ * through the auth owner with exactly one `exchangeAuthCode(code)` or one `verifyOtp({ token_hash, type })`, and redirects. It may read
+ * the exchange result's `success` or `ok` flag and call PURE text helpers of `modules/routes` or `modules/auth` (`requestOrigin`,
+ * `safeNextPath`), found by symbol resolution in lib/pure-owner-helper.mjs, so open-redirect protection stays in the app's owner modules.
+ * Cookie configuration and writes belong in the Supabase helper in fe.modules.auth; application data belongs in the back end.
+ * This syntax check follows lexical bindings and local aliases rather than trusting a method's spelling.
+ */
+import { stringOf, walk } from "./lib/ast.mjs"
+import { normalizePath } from "./lib/path.mjs"
+import { ownerExportKind } from "./lib/pure-owner-helper.mjs"
+import { classifyImport, inSlot, resolveImport } from "./lib/scope.mjs"
+
+/** Runtime expression wrappers that preserve the value's source. */
+const unwrap = (node) => {
+  while (node && ["AwaitExpression", "ChainExpression", "TSAsExpression", "TSTypeAssertion", "TSNonNullExpression", "TSInstantiationExpression"].includes(node.type)) node = node.expression ?? node.argument
+  return node
+}
+
+/** A member's static key, including a bracketed string spelling. */
+const memberName = (node) => node.computed ? stringOf(node.property) : node.property.name
+
+/** The lexical binding of an identifier, including shadowing inside the handler. */
+const bindingOf = (sourceCode, node) => {
+  for (let scope = sourceCode.getScope(node); scope; scope = scope.upper) {
+    const variable = scope.set.get(node.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)
+
+/** The property path that a destructured binding selects from its initializer. */
+const patternPath = (pattern, name) => {
+  if (pattern.type === "Identifier") return pattern.name === name ? [] : null
+  if (pattern.type === "AssignmentPattern") return patternPath(pattern.left, name)
+  if (pattern.type !== "ObjectPattern") return null
+  for (const property of pattern.properties) {
+    if (property.type !== "Property") continue
+    const nested = patternPath(property.value, name)
+    if (nested !== null) return [property.computed ? stringOf(property.key) : property.key.name ?? property.key.value, ...nested]
+  }
+  return null
+}
+
+/** 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"]])],
+])
+
+/** 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"]])
+
+/** 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 runtime names introduced by one local named export. */
+const namedExports = (statement, sourceCode) => {
+  const declaration = statement.declaration
+  if (declaration?.type === "FunctionDeclaration") return [{ name: declaration.id.name, value: declaration }]
+  if (declaration?.type === "VariableDeclaration") {
+    if (declaration.declarations.some((entry) => entry.id.type !== "Identifier")) return null
+    return declaration.declarations.map((entry) => ({ name: entry.id.name, value: unwrap(entry.init) }))
+  }
+  if (declaration) return []
+  return statement.specifiers.filter((entry) => entry.exportKind !== "type")
+    .map((entry) => ({ name: entry.exported.name ?? entry.exported.value, 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 = handlers[0].value
+  if (!handler || !FUNCTIONS.has(handler.type) || !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"
+
+/** 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 (["supabase", "supabaseClient", "authClient"].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
+  return ownerExportKind(context, source, name)
+}
+
+/** 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.importKind === "type") continue
+    const name = specifier.imported?.name ?? specifier.imported?.value
+    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" && !["__proto__", "constructor", "prototype"].includes(key)) return "text"
+  if (TEXT.has(kind) && ["startsWith", "endsWith", "includes"].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)
+  if (!variable || seen.has(variable) || variable.defs.length !== 1) return null
+  const definition = variable.defs[0]
+  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
+}
+
+/** 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 (property.key.name ?? property.key.value) === "status" && property.value.type === "Literal" && [301, 302, 303, 307, 308].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 keyOf = (property) => property.type === "Property" && !property.computed && !property.method && property.kind === "init" ? property.key.name ?? property.key.value : null
+  const expected = new Map([["token_hash", "token-hash"], ["type", "otp-type"]])
+  return node.properties.length === expected.size && node.properties.every((property) => expected.get(keyOf(property)) === origin(property.value))
+    && new Set(node.properties.map(keyOf)).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 && node.body.type !== "BlockStatement") return origin(node.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 && ["text", "url"].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
+}
+
+/** 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 = {
+  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/client-boundary.mjs

@@ -75,7 +75,7 @@ export const useClientOnlyAtBoundary = {
     schema: [],
     messages: {
       slot:
-        "`\"use client\"` on a {{slot}}. Routes, pages and layouts are server components: making one a client component ships its whole subtree, including the message catalog, to every reader and stops it reading data on the server. Move the interaction into a block below it and put the directive on that block's `index.tsx`; context providers go in the route tree's `providers.tsx`.",
+        "`\"use client\"` on a {{slot}}. Routes, pages and layouts are server components: making one a client component ships its whole subtree, including the message catalog, to every reader and stops it reading data on the server. Keep the {{slot}} a server component that renders a client component: move the interaction into a block (or overlay) below it, put the directive on that block's `index.tsx`, and import that entry from the {{slot}}; context providers go in the route tree's `providers.tsx`.",
       elsewhere:
         "`\"use client\"` here is not at an interaction boundary. The directive belongs on the `index.tsx` of the interactive block (or overlay), on a leaf whose interaction is intrinsic, on `error.tsx`/`global-error.tsx`, on the route tree's `providers.tsx` (the context providers a layout renders around its children), or on the client state of the stack (`components/providers/<name>/index.tsx`, `hooks/`, `redux/`, `modules/toast/`). Below a client block the file is already client; above one it must stay a server component.",
     },

package/docs/hooks-folder.md

@@ -8,7 +8,7 @@ Every rule below is an error in `starciFeConfig`; none can be switched off or su
 
 ## `starci-fe/hooks-folder-holds-hooks-only`
 
-`hooks/` holds `use*.ts` hooks under the names their family slot gives and, per domain, one `<domain>.shared.ts`; nothing else. A hook file exports one hook; `server-only` and `next/headers` are never imported there.
+`hooks/` holds `use*.ts` hooks under the names their family slot gives and, per domain, one `<domain>.shared.ts`; nothing else. A hook file exports one hook; `server-only` and `next/headers` are never imported there. A hook is a function that calls a hook: a React, SWR or Redux hook, a `use*` imported from the app's own `hooks/` folders (a `hooks/swr` wrapper or a sibling domain hook, resolved by TypeScript symbol resolution through barrels; that hook's own file is judged when it is linted), or a library hook from an explicit list (`next-intl` `useTranslations`/`useLocale`/`useFormatter`/`useNow`/`useTimeZone`/`useMessages`, `next/navigation`, `react-hook-form`, `zustand`). A `use*` from outside every `hooks/` folder or an unlisted library is not a hook by its spelling, and a file that exports a helper, a constant or a component still fails (owner ruling 2026-10-16).
 
 **Invalid** (`src/hooks/course/readCourse.ts`)
 

package/env-owner.mjs

@@ -52,6 +52,101 @@ const URL_TEXT = /^(?:https?:)?\/\/\S+/i
 /** Variable names whose value is a secret or an address: a default for one is a hole in a deployment. */
 const SENSITIVE_NAME = /(?:SECRET|TOKEN|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY|URL|URI|HOST|ENDPOINT|ORIGIN)$/i
 
+/** Type assertions and optional chains preserve the identity of the wrapped value. */
+const unwrapped = (node) => {
+  while (node && ["TSAsExpression", "TSTypeAssertion", "TSNonNullExpression", "TSSatisfiesExpression", "ChainExpression"].includes(node.type)) node = node.expression
+  return node
+}
+
+/** The binding of this identifier, rather than every variable with the same spelling. */
+const bindingOf = (sourceCode, identifier) => {
+  for (let scope = sourceCode.getScope(identifier); scope; scope = scope.upper) {
+    const variable = scope.set.get(identifier.name)
+    if (variable) return variable
+  }
+  return null
+}
+
+/** Prior writes in the use's execution scope or its parents; a closure can capture a later initializer. */
+const writeBefore = (sourceCode, variable, node) => {
+  const scopes = new Set()
+  for (let scope = sourceCode.getScope(node); scope; scope = scope.upper) scopes.add(scope.variableScope)
+  const writes = variable.references.filter((reference) => reference.isWrite()
+    && scopes.has(reference.from.variableScope)
+    && !(reference.writeExpr && reference.writeExpr.range[0] <= node.range[0] && node.range[1] <= reference.writeExpr.range[1]))
+  return writes
+    .filter((reference) => reference.identifier.range[0] < node.range[0])
+    .sort((left, right) => right.identifier.range[0] - left.identifier.range[0])[0]
+    ?? writes.find((reference) => reference.init)
+}
+
+/** Property extraction between a write's source and its destructured binding. */
+const propertyPath = (identifier) => {
+  const properties = []
+  for (let node = identifier; node.parent; node = node.parent) {
+    const parent = node.parent
+    if (parent.type === "Property" && parent.value === node) properties.unshift(parent)
+    else if (parent.type !== "ObjectPattern" && !(parent.type === "AssignmentPattern" && parent.left === node)) break
+  }
+  return properties
+}
+
+/** Known environment containers and constant computed keys, followed through local aliases. */
+const environmentIdentity = (sourceCode) => {
+  const textOf = (node, seen = new Set()) => {
+    node = unwrapped(node)
+    if (!node || seen.has(node)) return null
+    if (node.type === "Literal" && typeof node.value === "string") return node.value
+    if (node.type === "TemplateLiteral" && node.expressions.length === 0) return node.quasis[0].value.cooked
+    if (node.type !== "Identifier") return null
+    const variable = bindingOf(sourceCode, node)
+    if (!variable) return null
+    const write = writeBefore(sourceCode, variable, node)
+    if (!write?.writeExpr || propertyPath(write.identifier).length > 0) return null
+    return textOf(write.writeExpr, new Set([...seen, node]))
+  }
+  const keyOf = (node) => node.computed ? textOf(node.key ?? node.property) : (node.key ?? node.property).name ?? (node.key ?? node.property).value
+  const propertyKind = (kind, key) => {
+    if (kind === "global" && key === "process") return "process"
+    if ((kind === "process" || kind === "meta") && key === "env") return "env"
+    return null
+  }
+  const kindOf = (node, seen = new Set()) => {
+    node = unwrapped(node)
+    if (!node || seen.has(node)) return null
+    if (node.type === "MetaProperty" && node.meta.name === "import" && node.property.name === "meta") return "meta"
+    if (node.type === "MemberExpression") return propertyKind(kindOf(node.object, new Set([...seen, node])), keyOf(node))
+    if (node.type !== "Identifier") return null
+    const variable = bindingOf(sourceCode, node)
+    if (!variable || variable.defs.length === 0) {
+      if (node.name === "process") return "process"
+      return ["globalThis", "global"].includes(node.name) ? "global" : null
+    }
+    const imported = variable.defs.find((definition) => definition.type === "ImportBinding" && ["process", "node:process"].includes(definition.parent.source.value))
+    if (imported) {
+      if (imported.parent.importKind === "type" || imported.node.importKind === "type") return null
+      if (imported.node.type !== "ImportSpecifier") return "process"
+      const name = imported.node.imported.name ?? imported.node.imported.value
+      return name === "default" ? "process" : name === "env" ? "env" : null
+    }
+    const write = writeBefore(sourceCode, variable, node)
+    if (!write?.writeExpr) return null
+    let kind = kindOf(write.writeExpr, new Set([...seen, node]))
+    for (const property of propertyPath(write.identifier)) kind = propertyKind(kind, keyOf(property))
+    return kind
+  }
+  const readsEnv = (pattern, kind) => {
+    if (pattern.type === "AssignmentPattern") return readsEnv(pattern.left, kind)
+    if (pattern.type !== "ObjectPattern") return false
+    return pattern.properties.some((property) => {
+      if (property.type !== "Property") return false
+      const valueKind = propertyKind(kind, keyOf(property))
+      return valueKind === "env" || readsEnv(property.value, valueKind)
+    })
+  }
+  return { kindOf, readsEnv }
+}
+
 // -- FE-ENV-1 --------------------------------------------------------------------------------------
 
 /** Only `modules/config` reads the environment. */
@@ -66,20 +161,36 @@ export const noEnvOutsideConfig = {
     },
   },
   create(context) {
-    const filename = context.filename || context.getFilename()
     if (isConfigModule(context)) return {}
+    const members = []
+    const destructures = []
     return {
+      ImportDeclaration(node) {
+        if (node.importKind === "type" || !["process", "node:process"].includes(node.source.value)) return
+        for (const specifier of node.specifiers) {
+          if (specifier.type === "ImportSpecifier" && specifier.importKind !== "type" && (specifier.imported.name ?? specifier.imported.value) === "env") context.report({ node: specifier, messageId: "env" })
+        }
+      },
       MemberExpression(node) {
-        if (isEnvObject(node)) context.report({ node, messageId: "env" })
+        members.push(node)
       },
       VariableDeclarator(node) {
-        // `const { env } = process` reads the environment without the member expression.
-        if (node.id.type !== "ObjectPattern" || !node.init) return
-        if (node.init.type !== "Identifier" || node.init.name !== "process") return
-        const reads = node.id.properties.some(
-          (property) => property.type === "Property" && property.key.type === "Identifier" && property.key.name === "env",
-        )
-        if (reads) context.report({ node, messageId: "env" })
+        if (node.id.type === "ObjectPattern" && node.init) destructures.push({ node, pattern: node.id, value: node.init })
+      },
+      AssignmentExpression(node) {
+        if (node.operator === "=" && node.left.type === "ObjectPattern") destructures.push({ node, pattern: node.left, value: node.right })
+      },
+      AssignmentPattern(node) {
+        if (node.left.type === "ObjectPattern") destructures.push({ node, pattern: node.left, value: node.right })
+      },
+      "Program:exit"() {
+        const { kindOf, readsEnv } = environmentIdentity(context.sourceCode ?? context.getSourceCode())
+        for (const node of members) {
+          if (kindOf(node) === "env") context.report({ node, messageId: "env" })
+        }
+        for (const { node, pattern, value } of destructures) {
+          if (readsEnv(pattern, kindOf(value))) context.report({ node, messageId: "env" })
+        }
       },
     }
   },

package/function-budget.mjs

@@ -0,0 +1,49 @@
+/**
+ * R291 HFS_FUNCTION_BUDGET: every function body stays within the common line budget.
+ *
+ * Count the physical span of the body, including braces, comments, blank lines and nested functions.
+ * Signatures and parameters are outside the body. An expression arrow has an expression body and
+ * counts the expression and its wrapping parentheses, including comments and blanks inside them.
+ */
+import { hfsOf } from "./lib/hfs.mjs"
+
+/** Functions, methods, constructors, accessors and callbacks all receive the same body budget. */
+export const functionLineBudget = {
+  meta: {
+    type: "problem",
+    docs: { description: "A function body stays within ruleParams.functionLines, counting comments and blank lines." },
+    schema: [],
+    messages: {
+      lines: "HFS_FUNCTION_BUDGET: this function body has {{lines}} lines; the budget is {{max}}. Split the work into functions with one responsibility each.",
+    },
+  },
+  create(context) {
+    // C08 adds this common parameter to the shipped manifest; keep the owner-decided cap while it lands.
+    const max = hfsOf(context).ruleParams.functionLines ?? 80
+    if (!Number.isInteger(max) || max < 1) throw new RangeError("ruleParams.functionLines must be a positive integer")
+    const source = context.sourceCode || context.getSourceCode()
+    const check = (node) => {
+      if (!node.body) return
+      let start = node.body.loc.start.line
+      let end = node.body.loc.end.line
+      if (node.type === "ArrowFunctionExpression" && node.body.type !== "BlockStatement") {
+        const arrow = source.getTokenBefore(node.body, { filter: (token) => token.value === "=>" })
+        start = source.getTokenAfter(arrow, { includeComments: true }).loc.start.line
+        end = node.loc.end.line
+      }
+      const lines = end - start + 1
+      if (lines > max) context.report({ node: node.body, messageId: "lines", data: { lines, max } })
+    }
+    return {
+      FunctionDeclaration: check,
+      FunctionExpression: check,
+      ArrowFunctionExpression: check,
+    }
+  },
+}
+
+/** The rule this law contributes to the plugin. */
+export const rules = { "function-line-budget": functionLineBudget }
+
+/** The function budget is an error in both editions. */
+export const recommended = { "starci-fe/function-line-budget": "error" }