@starci/eslint-canon-fe 9.2.0 → 9.4.0

package/dist/lib/react.d.ts

@@ -0,0 +1,16 @@
+/**
+ * React hooks of the front-end canon, decided by the import: a call is `useEffect` when its callee is the `useEffect`
+ * export of `react` (named import, alias, default or namespace member), not when something is spelled that way.
+ */
+import type { TSESTree } from "@typescript-eslint/utils";
+import type { AnyContext } from "./rule.js";
+/** The hooks that run work after render and may return its cleanup. */
+export declare const EFFECT_HOOKS: Set<string>;
+/**
+ * The React export a call invokes, or null when the callee is not an export of `react`.
+ *
+ * @param context - The ESLint rule context.
+ * @param call - An ESTree call expression.
+ * @returns The export name (`useEffect`, `useSyncExternalStore`, ...).
+ */
+export declare const reactHookOf: (context: AnyContext, call: TSESTree.CallExpression) => string | null;

package/dist/lib/react.js

@@ -0,0 +1,22 @@
+import { importOf, unwrap } from "./bindings.js";
+/** The hooks that run work after render and may return its cleanup. */
+export const EFFECT_HOOKS = new Set(["useEffect", "useLayoutEffect"]);
+/**
+ * The React export a call invokes, or null when the callee is not an export of `react`.
+ *
+ * @param context - The ESLint rule context.
+ * @param call - An ESTree call expression.
+ * @returns The export name (`useEffect`, `useSyncExternalStore`, ...).
+ */
+export const reactHookOf = (context, call) => {
+    const callee = unwrap(call.callee);
+    if (callee.type === "Identifier") {
+        const from = importOf(context, callee);
+        return from && from.source === "react" && from.imported ? from.imported : null;
+    }
+    if (callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && callee.property.type === "Identifier") {
+        const from = importOf(context, callee.object);
+        return from && from.source === "react" && from.imported === null ? callee.property.name : null;
+    }
+    return null;
+};

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

@@ -0,0 +1,4 @@
+import type { ImportBindingDefinition } from "./own-hook-origin.js";
+import type { AnyContext } from "./rule.js";
+/** A relative/barrel import must resolve to a const initialized by a real Redux hook's withTypes(). */
+export declare function importedReduxHook(context: AnyContext, definition: ImportBindingDefinition): boolean;

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

@@ -0,0 +1,50 @@
+/** Resolve typed Redux hook factories by their import provenance, never by a local use* name. */
+import ts from "typescript";
+import { programFor } from "./program-for.js";
+const REDUX_HOOKS = new Set(["useSelector", "useDispatch", "useStore"]);
+function reduxImport(declaration) {
+    if (!ts.isImportSpecifier(declaration) || declaration.isTypeOnly)
+        return false;
+    const clause = declaration.parent.parent;
+    const specifier = clause.parent.moduleSpecifier;
+    return !clause.isTypeOnly && ts.isStringLiteral(specifier) && specifier.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) === 0)
+        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;
+    const parent = definition.parent;
+    if (specifier.type !== "ImportSpecifier" || parent.importKind === "type" || specifier.importKind === "type")
+        return false;
+    // an import specifier always sits in an import declaration
+    if (parent.type !== "ImportDeclaration")
+        return false;
+    const source = String(parent.source.value);
+    const name = specifier.imported.type === "Identifier" ? 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) : undefined;
+    if (!exported)
+        return false;
+    const symbol = (exported.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(exported) : exported;
+    return (symbol.declarations ?? []).some(declaration => typedFactory(checker, declaration));
+}

package/dist/lib/rule.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The types every law of the canon is written in: the typescript-eslint AST (JSX and TypeScript nodes included, which
+ * ESLint's own ESTree types lack), its rule module, context and listener, and the shape a law module exports.
+ */
+import type { TSESLint, TSESTree } from "@typescript-eslint/utils";
+/** Any node the parser produces. */
+export type Node = TSESTree.Node;
+/** A rule module with message ids `M` and options `O`. */
+export type Rule<M extends string = string, O extends readonly unknown[] = readonly unknown[]> = TSESLint.RuleModule<M, O>;
+/** The context a rule's `create` receives. */
+export type Context<M extends string = string, O extends readonly unknown[] = readonly unknown[]> = Readonly<TSESLint.RuleContext<M, O>>;
+/** The context of any rule, whatever its messages: what the shared readers take. */
+export type AnyContext = Readonly<TSESLint.RuleContext<string, readonly unknown[]>>;
+/** The source code a context reads. */
+export type SourceCode = Readonly<TSESLint.SourceCode>;
+/** The visitor a rule returns. */
+export type Listener = TSESLint.RuleListener;
+/** A comment of the source. */
+export type Comment = TSESTree.Comment;
+/** The rules a law publishes, by name. */
+export type Rules = Readonly<Record<string, Rule<string, readonly unknown[]>>>;
+/** The level a law asks for each of its rules, by `starci-fe/<name>`. */
+export type Recommended = Readonly<Record<string, "error">>;
+/**
+ * A rule with its message ids and options inferred from the literal: `defineRule({ meta: { messages: { a: "..." } }, ... })`
+ * types `context.report({ messageId })` against `a`. It returns the object it is given.
+ */
+export declare const defineRule: <M extends string, O extends readonly unknown[] = []>(rule: Rule<M, O>) => Rule<M, O>;

package/dist/lib/rule.js

@@ -0,0 +1,5 @@
+/**
+ * A rule with its message ids and options inferred from the literal: `defineRule({ meta: { messages: { a: "..." } }, ... })`
+ * types `context.report({ messageId })` against `a`. It returns the object it is given.
+ */
+export const defineRule = (rule) => rule;

package/dist/lib/scope.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Path predicates shared by the laws that scope themselves by where a file sits.
+ *
+ * ONE PLACE, because a scope written twice drifts: a rule that thinks `modules/config` is one
+ * spelling and a sibling that thinks it is another disagree about which file may read the
+ * environment, and the disagreement shows up as a finding nobody can satisfy.
+ */
+import type { TSESTree } from "@typescript-eslint/utils";
+import type { HfsClassification } from "./hfs-view.js";
+import type { AnyContext } from "./rule.js";
+/**
+ * The HFS slot id of the file being linted, read from the slot view (`settings.starci.hfs`).
+ *
+ * @param {object} context - The ESLint rule context.
+ * @returns {string | null} The slot id, or null when no slot owns the file.
+ */
+export declare const slotOfFile: (context: AnyContext) => string | null;
+/**
+ * True when the file being linted sits in one of the given slots.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {...string} ids - Slot ids.
+ * @returns {boolean} Whether the file's slot is one of them.
+ */
+export declare const inSlot: (context: AnyContext, ...ids: readonly string[]) => boolean;
+/** The filename a rule is linting. */
+export declare const fileOf: (context: AnyContext) => string;
+/** The classification of the linted file from the slot view: `{ slot, root, bindings, kind?, role? }` or a no-slot status. */
+export declare const classOf: (context: AnyContext) => HfsClassification;
+/** The tier of the linted file in the import direction matrix (`route`, `feature`, `components`, `hooks`, `foundation`, `modules`, `transport`, `package`, `none`), or null when no slot owns it. */
+export declare const tierOfFile: (context: AnyContext) => string | null;
+/** The folder kind the slot reports for the linted file (a component layer, a feature kind), or null. */
+export declare const kindOfFile: (context: AnyContext) => string | null;
+/** The role the slot reports for the linted file (`entry`, `drawing`, `styles`, `shared`, `page`, `layout`, ...), or null. */
+export declare const roleOfFile: (context: AnyContext) => string | null;
+/** Product source: a file of a product tier. */
+export declare const isProductSource: (context: AnyContext) => boolean;
+/** A file of a component tier: slot `fe.components` or `fe.package.ui`, inside one of its layer folders (blocks, composites, branches, leaves). */
+export declare const isComponentFile: (context: AnyContext) => boolean;
+/** True when the given file (an absolute or repo-relative name, e.g. where an import resolves to) sits in a component layer of slot `fe.components` or `fe.package.ui`. */
+export declare const isComponentPath: (context: AnyContext, file: string) => boolean;
+/** The one place that may read the environment: slot `fe.modules.config`. */
+export declare const isConfigModule: (context: AnyContext) => boolean;
+/**
+ * The transport owner: the folder of the auth and no-auth Apollo clients and their link chain, slot `fe.transport.client`
+ * (`modules/api/graphql/clients/`, one-app repository) or `fe.package.api.client` (`src/graphql/clients/` of the shared api package).
+ */
+export declare const isApiClient: (context: AnyContext) => boolean;
+/** True when the linted file sits in the API layer: the only place that talks to the back end (Apollo, axios, `fetch`). */
+export declare const isApiLayer: (context: AnyContext) => boolean;
+/**
+ * True when the linted file is a REST call of the API layer: `modules/api/rest/**` of an app (slot `fe.modules.api`) or
+ * `src/rest/**` of the shared api package (slot `fe.package.api`), the one home of axios.
+ */
+export declare const isApiRest: (context: AnyContext) => boolean;
+/** The file that may declare the one result vocabulary (`GraphQLResponse`): the file of the slot the manifest marks `outcomeHome`. */
+export declare const isOutcomeModule: (context: AnyContext) => boolean;
+/** The basename of a path without directories. */
+export declare const baseName: (filename: string) => string;
+/** The file name with its extension removed. */
+export declare const stem: (filename: string) => string;
+/**
+ * The references in the file that resolve to no declaration of the file, i.e. to a global (`fetch`, `Request`, `window`).
+ * An import, a parameter, a local `const fetch` binds the name and is not one; a type-position use is not a value reference.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {Set<string>} names - The global names to look for.
+ * @returns {Array<object>} The ESTree identifiers that reference such a global as a value.
+ */
+export declare const globalReferences: (context: AnyContext, names: ReadonlySet<string>) => (TSESTree.Identifier | TSESTree.JSXIdentifier)[];
+/**
+ * Where an import specifier of the linted file points, as an absolute path without an extension: a relative specifier, or `@/`
+ * from the owning app's `src/` (the app directory is the directory part of slot `fe.app.next`). Null for a package or a file no app owns.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {string} specifier - The module specifier.
+ * @returns {string | null} The absolute path, or null.
+ */
+export declare const resolveImport: (context: AnyContext, specifier: string) => string | null;
+/**
+ * The classification of an existing module file, resolving explicit files before extension and directory-index candidates.
+ * Virtual rule inputs with no existing candidate retain the path-only slot classification.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {string} specifier - The module specifier.
+ * @returns {object | null} The resolved file's owned slot classification, or the virtual-input classification when no file exists.
+ */
+export declare const classifyImport: (context: AnyContext, specifier: string) => HfsClassification | null;

package/{lib/scope.mjs → dist/lib/scope.js}

@@ -5,20 +5,17 @@
  * spelling and a sibling that thinks it is another disagree about which file may read the
  * environment, and the disagreement shows up as a finding nobody can satisfy.
  */
-
-import { dirname, join, resolve } from "node:path"
-import ts from "typescript"
-import { hfsOf } from "./hfs.mjs"
-import { normalizePath } from "./path.mjs"
-
+import { dirname, join, resolve } from "node:path";
+import ts from "typescript";
+import { hfsOf, requiredRoot, requiredSlot } from "./hfs.js";
+import { normalizePath } from "./path.js";
 /**
  * The HFS slot id of the file being linted, read from the slot view (`settings.starci.hfs`).
  *
  * @param {object} context - The ESLint rule context.
  * @returns {string | null} The slot id, or null when no slot owns the file.
  */
-export const slotOfFile = (context) => hfsOf(context).slotOf(context.filename || context.getFilename())
-
+export const slotOfFile = (context) => hfsOf(context).slotOf(context.filename || context.getFilename());
 /**
  * True when the file being linted sits in one of the given slots.
  *
@@ -26,78 +23,64 @@ export const slotOfFile = (context) => hfsOf(context).slotOf(context.filename ||
  * @param {...string} ids - Slot ids.
  * @returns {boolean} Whether the file's slot is one of them.
  */
-export const inSlot = (context, ...ids) => ids.includes(slotOfFile(context))
-
+export const inSlot = (context, ...ids) => {
+    const slot = slotOfFile(context);
+    return slot !== null && ids.includes(slot);
+};
 /** The filename a rule is linting. */
-export const fileOf = (context) => context.filename || context.getFilename()
-
+export const fileOf = (context) => context.filename || context.getFilename();
 /** The classification of the linted file from the slot view: `{ slot, root, bindings, kind?, role? }` or a no-slot status. */
-export const classOf = (context) => hfsOf(context).classify(fileOf(context))
-
+export const classOf = (context) => hfsOf(context).classify(fileOf(context));
 /** The tier of the linted file in the import direction matrix (`route`, `feature`, `components`, `hooks`, `foundation`, `modules`, `transport`, `package`, `none`), or null when no slot owns it. */
-export const tierOfFile = (context) => hfsOf(context).tierOf(fileOf(context))
-
+export const tierOfFile = (context) => hfsOf(context).tierOf(fileOf(context));
 /** The folder kind the slot reports for the linted file (a component layer, a feature kind), or null. */
-export const kindOfFile = (context) => classOf(context).kind ?? null
-
+export const kindOfFile = (context) => classOf(context).kind ?? null;
 /** The role the slot reports for the linted file (`entry`, `drawing`, `styles`, `shared`, `page`, `layout`, ...), or null. */
-export const roleOfFile = (context) => classOf(context).role ?? null
-
+export const roleOfFile = (context) => classOf(context).role ?? null;
 /** The tiers of product source: everything a slot places in an app's route, feature, component, hook or module tiers and in a shared package. */
-const PRODUCT_TIERS = new Set(["route", "feature", "components", "hooks", "foundation", "modules", "transport", "package"])
-
+const PRODUCT_TIERS = new Set(["route", "feature", "components", "hooks", "foundation", "modules", "transport", "package"]);
 /** Product source: a file of a product tier. */
-export const isProductSource = (context) => PRODUCT_TIERS.has(tierOfFile(context))
-
+export const isProductSource = (context) => PRODUCT_TIERS.has(tierOfFile(context));
 /** A file of a component tier: slot `fe.components` or `fe.package.ui`, inside one of its layer folders (blocks, composites, branches, leaves). */
-export const isComponentFile = (context) => inSlot(context, "fe.components", "fe.package.ui") && kindOfFile(context) !== null
-
+export const isComponentFile = (context) => inSlot(context, "fe.components", "fe.package.ui") && kindOfFile(context) !== null;
 /** True when the given file (an absolute or repo-relative name, e.g. where an import resolves to) sits in a component layer of slot `fe.components` or `fe.package.ui`. */
 export const isComponentPath = (context, file) => {
-  const found = hfsOf(context).classify(file)
-  return (found.slot === "fe.components" || found.slot === "fe.package.ui") && found.kind !== undefined
-}
-
+    const found = hfsOf(context).classify(file);
+    return (found.slot === "fe.components" || found.slot === "fe.package.ui") && found.kind !== undefined;
+};
 /** The one place that may read the environment: slot `fe.modules.config`. */
-export const isConfigModule = (context) => inSlot(context, "fe.modules.config")
-
+export const isConfigModule = (context) => inSlot(context, "fe.modules.config");
 /**
  * The transport owner: the folder of the auth and no-auth Apollo clients and their link chain, slot `fe.transport.client`
  * (`modules/api/graphql/clients/`, one-app repository) or `fe.package.api.client` (`src/graphql/clients/` of the shared api package).
  */
-export const isApiClient = (context) => inSlot(context, "fe.transport.client", "fe.package.api.client")
-
+export const isApiClient = (context) => inSlot(context, "fe.transport.client", "fe.package.api.client");
 /** The slots of the API layer: the app's `modules/api` (with its clients folder, its stream reader and its GraphQLResponse file) and the shared api package. */
-const API_LAYER_SLOTS = Object.freeze(["fe.modules.api", "fe.transport.client", "fe.transport.stream", "fe.transport.outcome", "fe.package.api", "fe.package.api.client", "fe.package.api.outcome"])
-
+const API_LAYER_SLOTS = Object.freeze(["fe.modules.api", "fe.transport.client", "fe.transport.stream", "fe.transport.outcome", "fe.package.api", "fe.package.api.client", "fe.package.api.outcome"]);
 /** True when the linted file sits in the API layer: the only place that talks to the back end (Apollo, axios, `fetch`). */
-export const isApiLayer = (context) => inSlot(context, ...API_LAYER_SLOTS)
-
+export const isApiLayer = (context) => inSlot(context, ...API_LAYER_SLOTS);
 /**
  * True when the linted file is a REST call of the API layer: `modules/api/rest/**` of an app (slot `fe.modules.api`) or
  * `src/rest/**` of the shared api package (slot `fe.package.api`), the one home of axios.
  */
 export const isApiRest = (context) => {
-  if (!inSlot(context, "fe.modules.api", "fe.package.api")) return false
-  const hfs = hfsOf(context)
-  const file = fileOf(context)
-  const below = hfs.relative(file).slice(hfs.classify(file).root.length + 1).split("/")
-  return (below[0] === "src" ? below[1] : below[0]) === "rest"
-}
-
+    if (!inSlot(context, "fe.modules.api", "fe.package.api"))
+        return false;
+    const hfs = hfsOf(context);
+    const file = fileOf(context);
+    const below = hfs.relative(file).slice(requiredRoot(hfs.classify(file)).length + 1).split("/");
+    return (below[0] === "src" ? below[1] : below[0]) === "rest";
+};
 /** The file that may declare the one result vocabulary (`GraphQLResponse`): the file of the slot the manifest marks `outcomeHome`. */
 export const isOutcomeModule = (context) => {
-  const hfs = hfsOf(context)
-  const slot = slotOfFile(context)
-  return slot !== null && hfs.slot(slot)?.outcomeHome === true
-}
-
+    const hfs = hfsOf(context);
+    const slot = slotOfFile(context);
+    return slot !== null && hfs.slot(slot)?.outcomeHome === true;
+};
 /** The basename of a path without directories. */
-export const baseName = (filename) => normalizePath(filename).split("/").pop() ?? ""
-
+export const baseName = (filename) => normalizePath(filename).split("/").pop() ?? "";
 /** The file name with its extension removed. */
-export const stem = (filename) => baseName(filename).replace(/\.[cm]?[jt]sx?$/, "")
-
+export const stem = (filename) => baseName(filename).replace(/\.[cm]?[jt]sx?$/, "");
 /**
  * The references in the file that resolve to no declaration of the file, i.e. to a global (`fetch`, `Request`, `window`).
  * An import, a parameter, a local `const fetch` binds the name and is not one; a type-position use is not a value reference.
@@ -107,19 +90,23 @@ export const stem = (filename) => baseName(filename).replace(/\.[cm]?[jt]sx?$/,
  * @returns {Array<object>} The ESTree identifiers that reference such a global as a value.
  */
 export const globalReferences = (context, names) => {
-  const sourceCode = context.sourceCode ?? context.getSourceCode()
-  const found = []
-  const visit = (scope) => {
-    for (const reference of scope.references) {
-      if (!names.has(reference.identifier.name) || reference.isValueReference === false) continue
-      if (!reference.resolved || reference.resolved.defs.length === 0) found.push(reference.identifier)
-    }
-    scope.childScopes.forEach(visit)
-  }
-  visit(sourceCode.scopeManager.globalScope)
-  return found
-}
-
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const found = [];
+    const visit = (scope) => {
+        for (const reference of scope.references) {
+            if (!names.has(reference.identifier.name) || reference.isValueReference === false)
+                continue;
+            if ((!reference.resolved || reference.resolved.defs.length === 0))
+                found.push(reference.identifier);
+        }
+        scope.childScopes.forEach(visit);
+    };
+    const globalScope = sourceCode.scopeManager?.globalScope;
+    if (!globalScope)
+        throw new TypeError("the parser gave no scope manager");
+    visit(globalScope);
+    return found;
+};
 /**
  * Where an import specifier of the linted file points, as an absolute path without an extension: a relative specifier, or `@/`
  * from the owning app's `src/` (the app directory is the directory part of slot `fe.app.next`). Null for a package or a file no app owns.
@@ -129,16 +116,18 @@ export const globalReferences = (context, names) => {
  * @returns {string | null} The absolute path, or null.
  */
 export const resolveImport = (context, specifier) => {
-  const hfs = hfsOf(context)
-  const file = fileOf(context)
-  if (specifier.startsWith(".")) return resolve(dirname(file), specifier)
-  if (!specifier.startsWith("@/")) return null
-  const app = hfs.classify(file).bindings?.app
-  if (app === undefined) return null
-  const appDirectory = hfs.slot("fe.app.next").path.split("/{")[0].replace("<app>", app)
-  return join(hfs.repoRoot, appDirectory, "src", specifier.slice(2))
-}
-
+    const hfs = hfsOf(context);
+    const file = fileOf(context);
+    if (specifier.startsWith("."))
+        return resolve(dirname(file), specifier);
+    if (!specifier.startsWith("@/"))
+        return null;
+    const app = hfs.classify(file).bindings?.app;
+    if (app === undefined)
+        return null;
+    const appDirectory = requiredSlot(hfs.slot("fe.app.next"), "fe.app.next").path.split("/{")[0]?.replace("<app>", app) ?? "";
+    return join(hfs.repoRoot, appDirectory, "src", specifier.slice(2));
+};
 /**
  * The classification of an existing module file, resolving explicit files before extension and directory-index candidates.
  * Virtual rule inputs with no existing candidate retain the path-only slot classification.
@@ -148,19 +137,20 @@ export const resolveImport = (context, specifier) => {
  * @returns {object | null} The resolved file's owned slot classification, or the virtual-input classification when no file exists.
  */
 export const classifyImport = (context, specifier) => {
-  const target = resolveImport(context, specifier)
-  if (target === null) return null
-  const hfs = hfsOf(context)
-  const candidates = [`${target}.ts`, `${target}.tsx`, `${target}/index.ts`, `${target}/index.tsx`, target]
-  // Match the owner helper's on-disk module order; a nonexistent auth.ts must not shadow auth/index.ts.
-  const existing = [target, ...candidates].find((candidate) => ts.sys.fileExists(candidate))
-  if (existing !== undefined) {
-    const found = hfs.classify(existing)
-    return found.slot && found.status === "owned" ? found : null
-  }
-  // RuleTester deliberately accepts virtual source paths; preserve its existing slot/role inference only without a real target.
-  const owned = candidates
-    .map((candidate) => hfs.classify(candidate))
-    .filter((found) => found.slot && found.status === "owned")
-  return owned.find((found) => found.role) ?? owned[0] ?? null
-}
+    const target = resolveImport(context, specifier);
+    if (target === null)
+        return null;
+    const hfs = hfsOf(context);
+    const candidates = [`${target}.ts`, `${target}.tsx`, `${target}/index.ts`, `${target}/index.tsx`, target];
+    // Match the owner helper's on-disk module order; a nonexistent auth.ts must not shadow auth/index.ts.
+    const existing = [target, ...candidates].find((candidate) => ts.sys.fileExists(candidate));
+    if (existing !== undefined) {
+        const found = hfs.classify(existing);
+        return found.slot && found.status === "owned" ? found : null;
+    }
+    // RuleTester deliberately accepts virtual source paths; preserve its existing slot/role inference only without a real target.
+    const owned = candidates
+        .map((candidate) => hfs.classify(candidate))
+        .filter((found) => found.slot && found.status === "owned");
+    return owned.find((found) => found.role) ?? owned[0] ?? null;
+};

package/dist/lib/typed-class-values.d.ts

@@ -0,0 +1,13 @@
+import type { AnyContext, Node } from "./rule.js";
+/** One text found for a node of the linted file. */
+export interface TypedString {
+    readonly node: Node;
+    readonly text: string;
+}
+/**
+ * Imported class values are reported at their use in the linted file, while their text comes from the typed declaration.
+ * Syntax-only rule consumers have no imported-file program and retain same-file inspection.
+ */
+export declare const typedClassStrings: (context: AnyContext, node: Node, mode: string) => TypedString[];
+/** Known imported props spreads expose the same static property values as named JSX attributes. */
+export declare const typedPropertyStrings: (context: AnyContext, node: Node, key: string, mode: string) => TypedString[];

package/dist/lib/typed-class-values.js

@@ -0,0 +1,92 @@
+/** Static class declarations in imported colocated modules, resolved by the consuming TypeScript program. */
+import ts from "typescript";
+/** True for a TypeScript node (a declaration's `initializer`, when it has one). */
+const isTsNode = (value) => typeof value === "object" && value !== null && "kind" in value && typeof value.kind === "number";
+/** The expression's literal fragments, following imported const/property declarations without executing code. */
+const fragments = (checker, node, seen, mode) => {
+    if (!node || seen.has(node))
+        return [];
+    seen.add(node);
+    if (ts.isStringLiteralLike(node) || ts.isTemplateHead(node) || ts.isTemplateMiddle(node) || ts.isTemplateTail(node))
+        return mode === "style-keys" ? [] : [node.text];
+    if (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isSatisfiesExpression(node) || ts.isParenthesizedExpression(node) || ts.isNonNullExpression(node))
+        return fragments(checker, node.expression, seen, mode);
+    if (ts.isIdentifier(node) || ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+        const symbol = ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)
+            ? checker.getTypeAtLocation(node.expression).getProperty(node.argumentExpression.text)
+            : checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node);
+        return symbolFragments(checker, symbol, seen, mode);
+    }
+    if (mode === "style-keys" && ts.isObjectLiteralExpression(node)) {
+        return node.properties.flatMap((property) => {
+            if (ts.isSpreadAssignment(property))
+                return fragments(checker, property.expression, seen, mode);
+            if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property))
+                return [];
+            return ts.isComputedPropertyName(property.name)
+                ? fragments(checker, property.name.expression, seen, "variant")
+                : [property.name.text];
+        });
+    }
+    return fragmentChildren(node, mode).flatMap((child) => fragments(checker, child, seen, mode));
+};
+/** An object binding reads only its selected property's symbol, including aliases and nested patterns. */
+const bindingProperty = (checker, declaration) => {
+    const source = declaration.parent.parent;
+    const owner = ts.isBindingElement(source) ? bindingProperty(checker, source) : null;
+    const initializer = "initializer" in source ? source.initializer : undefined;
+    const type = owner ? checker.getTypeOfSymbolAtLocation(owner, source) : initializer ? checker.getTypeAtLocation(initializer) : null;
+    const name = declaration.propertyName ?? declaration.name;
+    return ts.isIdentifier(name) || ts.isStringLiteralLike(name) ? type?.getProperty(name.text) : null;
+};
+/** Alias and destructuring symbols retain their declaration values without reading sibling properties. */
+const symbolFragments = (checker, input, seen, mode) => {
+    let symbol = input;
+    if (symbol && (symbol.flags & ts.SymbolFlags.Alias) !== 0)
+        symbol = checker.getAliasedSymbol(symbol);
+    return (symbol?.declarations ?? []).flatMap((declaration) => {
+        const selected = ts.isBindingElement(declaration) ? bindingProperty(checker, declaration) : null;
+        return selected ? symbolFragments(checker, selected, seen, mode) : fragments(checker, "initializer" in declaration && isTsNode(declaration.initializer) ? declaration.initializer : undefined, seen, mode);
+    });
+};
+/** Class-producing positions inside a declaration, including cn dictionaries and conditional recipes. */
+const fragmentChildren = (node, mode) => {
+    if (ts.isCallExpression(node))
+        return mode === "classes" ? node.arguments : [];
+    if (ts.isArrayLiteralExpression(node))
+        return node.elements;
+    if (ts.isConditionalExpression(node))
+        return [node.whenTrue, node.whenFalse];
+    if (ts.isBinaryExpression(node)) {
+        if (node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken)
+            return [node.right];
+        return [ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].some((kind) => kind === node.operatorToken.kind) ? [node.left, node.right] : [];
+    }
+    if (ts.isObjectLiteralExpression(node))
+        return node.properties.flatMap((property) => ts.isPropertyAssignment(property) ? [property.name, property.initializer] : []);
+    if (ts.isTemplateExpression(node) && mode === "classes")
+        return [node.head, ...node.templateSpans.flatMap((span) => [span.expression, span.literal])];
+    return [];
+};
+/**
+ * Imported class values are reported at their use in the linted file, while their text comes from the typed declaration.
+ * Syntax-only rule consumers have no imported-file program and retain same-file inspection.
+ */
+export const typedClassStrings = (context, node, mode) => {
+    const services = context.sourceCode.parserServices;
+    if (!services?.program || !services.esTreeNodeToTSNodeMap)
+        return [];
+    const source = services.esTreeNodeToTSNodeMap.get(node);
+    const checker = services.program.getTypeChecker();
+    return fragments(checker, source, new Set(), mode).map((text) => ({ node, text }));
+};
+/** Known imported props spreads expose the same static property values as named JSX attributes. */
+export const typedPropertyStrings = (context, node, key, mode) => {
+    const services = context.sourceCode.parserServices;
+    if (!services?.program || !services.esTreeNodeToTSNodeMap)
+        return [];
+    const source = services.esTreeNodeToTSNodeMap.get(node);
+    const checker = services.program.getTypeChecker();
+    const symbol = checker.getTypeAtLocation(source).getProperty(key);
+    return symbolFragments(checker, symbol, new Set(), mode).map((text) => ({ node, text }));
+};

package/dist/lib/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Type-aware helpers of the front-end canon: a rule asks what a node IS (its TypeScript type, the symbol an identifier
+ * resolves to, the module a declaration comes from), never what it is called. `starciFeConfig` turns typed linting on for
+ * the source tree (`parserOptions.projectService`), so these helpers refuse to run without the program instead of falling
+ * back to a name match.
+ */
+import ts from "typescript";
+import type { AnyContext, Node } from "./rule.js";
+/** The TypeScript services of a linted file: its program, the checker and the ESTree to TS node map. */
+export interface Typed {
+    readonly program: ts.Program;
+    readonly checker: ts.TypeChecker;
+    readonly toTs: (node: Node) => ts.Node | undefined;
+}
+/**
+ * The TypeScript services of the file being linted.
+ *
+ * @param context - The ESLint rule context.
+ * @returns The program, its checker and the ESTree to TS node map.
+ */
+export declare const typed: (context: AnyContext) => Typed;
+/**
+ * True when the type of an expression is a promise (a thenable carrying a `then` method), after union members are read.
+ *
+ * @param context - The ESLint rule context.
+ * @param node - An ESTree expression.
+ * @returns Whether evaluating the node yields a promise.
+ */
+export declare const isPromiseValued: (context: AnyContext, node: Node) => boolean;
+/**
+ * The declarations the symbol of an identifier resolves to, after import aliases are followed.
+ *
+ * @param context - The ESLint rule context.
+ * @param identifier - An ESTree identifier (or any node with a symbol).
+ * @returns The TypeScript declarations (empty when the checker has no symbol).
+ */
+export declare const declarationsOf: (context: AnyContext, identifier: Node) => ts.Declaration[];
+/**
+ * The forward-slash file name a declaration lives in.
+ *
+ * @param declaration - A TypeScript declaration.
+ * @returns Its source file name.
+ */
+export declare const fileOf: (declaration: ts.Node) => string;