@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/src/analyse/pureModule.ts

@@ -0,0 +1,88 @@
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+
+/**
+ * Is this LOCAL module a pure calculation — same inputs, same output, no
+ * world it can touch?
+ *
+ * The spec's mock loop replaces whole modules a server component reads data
+ * from, and a formatter like `splitCode` gets swept up with them: from one
+ * imported call site it looks exactly like a query. The pure-binding
+ * exemption rescued only names it had heard of (`cn`), so when the mock loop
+ * widened to a render tree's data modules, `drop-format` was mocked and
+ * `splitCode` came back as `{}` — `segments.map is not a function`.
+ *
+ * So ask the module itself. Pure here means: no async, no await, no yield;
+ * nothing imported except types (so it reaches no database through a helper
+ * of its own); no top-level call (nothing runs, or fetches, at import). A
+ * module that passes is not mocked at all — its real code renders.
+ */
+export function isPureLocalModule(absPath: string): boolean {
+  let text: string;
+  try {
+    text = readFileSync(absPath, "utf8");
+  } catch {
+    return false;
+  }
+  if (/^\s*['"]use server['"]/.test(text)) return false;
+  const kind = absPath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  let sf: ts.SourceFile;
+  try {
+    sf = ts.createSourceFile(absPath, text, ts.ScriptTarget.Latest, true, kind);
+  } catch {
+    return false;
+  }
+
+  let impure = false;
+  const walk = (n: ts.Node, fnDepth: number): void => {
+    if (impure) return;
+    if (ts.isAwaitExpression(n) || ts.isYieldExpression(n)) {
+      impure = true;
+      return;
+    }
+    if (fnDepth === 0 && ts.isCallExpression(n)) {
+      impure = true; // something RUNS at import
+      return;
+    }
+    const isFn =
+      ts.isFunctionDeclaration(n) ||
+      ts.isFunctionExpression(n) ||
+      ts.isArrowFunction(n) ||
+      ts.isMethodDeclaration(n);
+    if (isFn) {
+      if ((n.modifiers ?? []).some((m) => m.kind === ts.SyntaxKind.AsyncKeyword)) {
+        impure = true;
+        return;
+      }
+      fnDepth += 1;
+    }
+    ts.forEachChild(n, (c) => walk(c, fnDepth));
+  };
+  walk(sf, 0);
+  if (impure) return false;
+
+  for (const st of sf.statements) {
+    if (ts.isImportDeclaration(st)) {
+      const clause = st.importClause;
+      const named =
+        clause !== undefined && clause.namedBindings !== undefined
+          ? clause.namedBindings
+          : undefined;
+      const typeOnly =
+        clause?.isTypeOnly === true ||
+        // `import { type A, type B } from …` marks each SPECIFIER type-only.
+        // `NamedImports` has no `isTypeOnly` of its own, so reading it off the
+        // list returned undefined and every such module counted as live.
+        (named !== undefined &&
+          ts.isNamedImports(named) &&
+          named.elements.length > 0 &&
+          named.elements.every((e) => e.isTypeOnly));
+      if (!typeOnly) return false; // imports something LIVE
+    } else if (ts.isExportDeclaration(st) && !st.isTypeOnly) {
+      return false; // `export { x } from "./live"`
+    } else if (ts.isExpressionStatement(st) || ts.isIfStatement(st) || ts.isForStatement(st)) {
+      return false; // a side effect at import time
+    }
+  }
+  return true;
+}

package/src/analyse/reexportTable.ts

@@ -0,0 +1,148 @@
+import ts from "typescript";
+
+/**
+ * What a file hands to another module instead of declaring: the re-export
+ * table. Feature-Sliced apps are built out of these — a slice's `index.ts` is
+ * `export * from './model'`, and the model index is
+ * `export { useRateQuery } from './queries'` — so the name a component imports
+ * is usually not one the imported file declares.
+ */
+export interface ReexportTable {
+  /** `export { useX, useY as useZ } from './m'`: the EXPORTED name → the module
+   *  it came from and the name that module uses (`useY` for `useZ`). The same
+   *  entry is recorded for a name the file imported and handed back out with a
+   *  module-less `export { … }`. */
+  named: Map<string, { specifier: string; imported: string }[]>;
+  /** The bare `export * from './m'` specifiers, which carry every name. */
+  stars: string[];
+}
+
+const EMPTY: ReexportTable = { named: new Map(), stars: [] };
+
+/**
+ * Read a source file's hand-offs. Forms that are NOT a hand-off of one of the
+ * target's names: `export * as ns from './m'`, which exposes the namespace
+ * rather than a member, `export type { T } from './m'`, which is erased, and
+ * `export { useLocal }` of a name the file declares, which is its own.
+ * The bare star is the clauseless form in this parser (typescript 5.9.3,
+ * probed); a NamespaceExport with an empty name is the same thing written the
+ * other way, so both are read as a star.
+ */
+export function reexportTableOf(sourceFile: ts.SourceFile): ReexportTable {
+  const named = new Map<string, { specifier: string; imported: string }[]>();
+  const stars: string[] = [];
+  const add = (exported: string, hop: { specifier: string; imported: string }) => {
+    const arr = named.get(exported);
+    if (arr) arr.push(hop);
+    else named.set(exported, [hop]);
+  };
+  // The local name → where it came from, read only if the file has a
+  // module-less `export { … }` clause to answer for.
+  let imported: Map<string, { specifier: string; imported: string }> | undefined;
+  const importedBindings = () => {
+    if (!imported) {
+      imported = new Map();
+      for (const stmt of sourceFile.statements) {
+        if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+        const bindings = stmt.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings)) continue;
+        for (const el of bindings.elements) {
+          imported.set(el.name.text, {
+            specifier: stmt.moduleSpecifier.text,
+            imported: (el.propertyName ?? el.name).text,
+          });
+        }
+      }
+    }
+    return imported;
+  };
+  for (const stmt of sourceFile.statements) {
+    if (!ts.isExportDeclaration(stmt) || stmt.isTypeOnly) continue;
+    const ref = stmt.moduleSpecifier;
+    const clause = stmt.exportClause;
+    if (!ref) {
+      // `import { Card } from './card'; export { Card }` — ESM counts that as an
+      // export of this module, and it is how a package republishes a component
+      // it does not own. Only a name the file IMPORTED is a hand-off.
+      if (!clause || !ts.isNamedExports(clause)) continue;
+      const byLocal = importedBindings();
+      for (const spec of clause.elements) {
+        const hop = byLocal.get((spec.propertyName ?? spec.name).text);
+        if (hop) add(spec.name.text, hop);
+      }
+      continue;
+    }
+    if (!ts.isStringLiteral(ref)) continue;
+    if (!clause || (ts.isNamespaceExport(clause) && !clause.name.text)) {
+      if (!stars.includes(ref.text)) stars.push(ref.text);
+      continue;
+    }
+    if (!ts.isNamedExports(clause)) continue;
+    for (const spec of clause.elements) {
+      add(spec.name.text, {
+        specifier: ref.text,
+        imported: spec.propertyName?.text ?? spec.name.text,
+      });
+    }
+  }
+  // A file with no hand-offs — which is most files — shares one empty table
+  // instead of allocating a map per parse.
+  return named.size === 0 && stars.length === 0 ? EMPTY : { named, stars };
+}
+
+/** What `followHandoff` needs from its caller: read a file's syntax tree,
+ *  resolve a specifier the way the importer would, and say whether a file
+ *  declares a name. A component and a hook are found by different lookups, so
+ *  the caller decides. */
+export interface HandoffReader {
+  read: (file: string) => Promise<ts.SourceFile | undefined> | ts.SourceFile | undefined;
+  resolve: (specifier: string, fromFile: string) => string | undefined;
+  declares: (file: string, name: string) => Promise<boolean> | boolean;
+}
+
+/**
+ * Follow `name` from `file` through its hand-offs to the module that DECLARES
+ * it — the caller checks its own file first, this answers only for the hop.
+ *
+ * Named hand-offs are exact, so they go first and a star is consulted only when
+ * no named hop carries the name. A hop whose module does not resolve, or whose
+ * target does not answer for the name, ends that hop rather than the search:
+ * `export * from './ui'` pointing at nothing must not lose the sibling that
+ * does hold it. The seen-set makes a barrel cycle cost one visit.
+ */
+export async function followHandoff(
+  file: string,
+  name: string,
+  reader: HandoffReader,
+): Promise<{ file: string; name: string } | undefined> {
+  const seen = new Set<string>();
+  const search = async (
+    file: string,
+    name: string,
+  ): Promise<{ file: string; name: string } | undefined> => {
+    const key = `${file}::${name}`;
+    if (seen.has(key)) return undefined;
+    seen.add(key);
+    const source = await reader.read(file);
+    if (!source) return undefined;
+    const table = reexportTableOf(source);
+    const hops = table.named.get(name) ?? [];
+    for (const hop of hops) {
+      const target = reader.resolve(hop.specifier, file);
+      if (!target) continue;
+      if (await reader.declares(target, hop.imported)) return { file: target, name: hop.imported };
+      const deeper = await search(target, hop.imported);
+      if (deeper) return deeper;
+    }
+    if (hops.length > 0) return undefined;
+    for (const spec of table.stars) {
+      const target = reader.resolve(spec, file);
+      if (!target) continue;
+      if (await reader.declares(target, name)) return { file: target, name };
+      const deeper = await search(target, name);
+      if (deeper) return deeper;
+    }
+    return undefined;
+  };
+  return search(file, name);
+}

package/src/analyse/refs.ts

@@ -0,0 +1,195 @@
+import ts from "typescript";
+import type { StateInfo } from "../types.ts";
+import type { ExtractedProps } from "./extractProps.ts";
+import type { ParsedComponentUnit } from "./parseFile.ts";
+
+/**
+ * Shared identifier-reference machinery for the usage/state/hook extractors.
+ * Purely syntactic: no symbol table, no type checker. Known accepted limit:
+ * shadowing inside nested closures is not tracked (declaration names are
+ * excluded, but later reads of a shadow are misattributed to the outer name).
+ */
+
+export interface ComponentScope {
+  /** Prop names as declared on the props type (shape keys ∪ unresolved). */
+  propNames: Set<string>;
+  /** local name → original prop name (destructuring aliases, body `const {a} = props`). */
+  propAliases: Map<string, string>;
+  /** First param identifier when the component takes a bare props object. */
+  paramName: string | undefined;
+  stateVars: Set<string>;
+  setterNames: Set<string>;
+  refNames: Set<string>;
+  /** `const x = useMemo(...)` / `useCallback(...)` result names. */
+  memoResultNames: Set<string>;
+  /** Other top-level body bindings: name → whether the value is function-like. */
+  derivedNames: Map<string, { isFunctionValued: boolean }>;
+}
+
+export function buildComponentScope(
+  unit: ParsedComponentUnit,
+  props: ExtractedProps,
+  state: StateInfo[],
+  bodyNode: ts.Node,
+): ComponentScope {
+  const propNames = new Set<string>([...Object.keys(props.propsShape), ...props.unresolvedProps]);
+  const propAliases = new Map<string, string>(unit.destructuredAliases);
+
+  const stateVars = new Set<string>();
+  const setterNames = new Set<string>();
+  const refNames = new Set<string>();
+  for (const s of state) {
+    if (s.kind === "useRef") refNames.add(s.varName);
+    else stateVars.add(s.varName);
+    if (s.setterName) setterNames.add(s.setterName);
+  }
+
+  const memoResultNames = new Set<string>();
+  const derivedNames = new Map<string, { isFunctionValued: boolean }>();
+  const claimed = (name: string): boolean =>
+    propNames.has(name) ||
+    propAliases.has(name) ||
+    stateVars.has(name) ||
+    setterNames.has(name) ||
+    refNames.has(name);
+
+  for (const stmt of bodyStatements(bodyNode)) {
+    if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+      if (!claimed(stmt.name.text)) derivedNames.set(stmt.name.text, { isFunctionValued: true });
+      continue;
+    }
+    if (!ts.isVariableStatement(stmt)) continue;
+    for (const decl of stmt.declarationList.declarations) {
+      // `const { a, b: c } = props` → aliases onto the props object.
+      if (
+        ts.isObjectBindingPattern(decl.name) &&
+        decl.initializer &&
+        ts.isIdentifier(decl.initializer) &&
+        unit.paramName !== undefined &&
+        decl.initializer.text === unit.paramName
+      ) {
+        for (const el of decl.name.elements) {
+          if (!ts.isBindingElement(el) || !ts.isIdentifier(el.name)) continue;
+          const original =
+            el.propertyName && ts.isIdentifier(el.propertyName)
+              ? el.propertyName.text
+              : el.name.text;
+          propAliases.set(el.name.text, original);
+        }
+        continue;
+      }
+      if (!ts.isIdentifier(decl.name)) continue;
+      const name = decl.name.text;
+      if (claimed(name)) continue;
+      const init = decl.initializer;
+      if (init && ts.isCallExpression(init)) {
+        const callee = hookCalleeName(init.expression);
+        if (callee === "useMemo" || callee === "useCallback") {
+          memoResultNames.add(name);
+          continue;
+        }
+      }
+      const isFunctionValued =
+        init !== undefined && (ts.isArrowFunction(init) || ts.isFunctionExpression(init));
+      derivedNames.set(name, { isFunctionValued });
+    }
+  }
+
+  return {
+    propNames,
+    propAliases,
+    paramName: unit.paramName,
+    stateVars,
+    setterNames,
+    refNames,
+    memoResultNames,
+    derivedNames,
+  };
+}
+
+/** Statements of the component's function body (block or none for concise arrows). */
+export function bodyStatements(bodyNode: ts.Node): readonly ts.Statement[] {
+  const fn = bodyNode as ts.FunctionLikeDeclaration;
+  if (fn.body && ts.isBlock(fn.body)) return fn.body.statements;
+  return [];
+}
+
+export interface CollectedRef {
+  /** Canonical name from the requested set. */
+  name: string;
+  node: ts.Identifier;
+  /** Reference reached through `props.x` rather than a bare identifier. */
+  viaParam: boolean;
+}
+
+/**
+ * All identifier references to `names` inside `root`, excluding non-reference
+ * positions (declaration names, property keys, JSX attribute names, member
+ * names, import/export specifiers, signature names). When `paramName` is set,
+ * `props.x` property accesses count as references to `x` if `x` ∈ names.
+ */
+export function collectRefs(
+  root: ts.Node,
+  _sf: ts.SourceFile,
+  names: Set<string>,
+  paramName: string | undefined,
+): CollectedRef[] {
+  const out: CollectedRef[] = [];
+
+  const visit = (n: ts.Node): void => {
+    if (ts.isIdentifier(n) && names.has(n.text) && isReferencePosition(n)) {
+      out.push({ name: n.text, node: n, viaParam: false });
+    }
+    if (
+      paramName !== undefined &&
+      ts.isPropertyAccessExpression(n) &&
+      ts.isIdentifier(n.expression) &&
+      n.expression.text === paramName &&
+      ts.isIdentifier(n.name) &&
+      names.has(n.name.text)
+    ) {
+      out.push({ name: n.name.text, node: n.name, viaParam: true });
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(root);
+  return out;
+}
+
+function isReferencePosition(id: ts.Identifier): boolean {
+  const parent = id.parent;
+  if (!parent) return true;
+
+  // x.title — `title` is a member name, not a reference (the receiver is visited separately).
+  if (ts.isPropertyAccessExpression(parent) && parent.name === id) return false;
+  // { title: value } — non-shorthand property key.
+  if (ts.isPropertyAssignment(parent) && parent.name === id) return false;
+  // Declaration names of any kind.
+  if (
+    (ts.isVariableDeclaration(parent) ||
+      ts.isParameter(parent) ||
+      ts.isBindingElement(parent) ||
+      ts.isFunctionDeclaration(parent) ||
+      ts.isFunctionExpression(parent) ||
+      ts.isClassDeclaration(parent)) &&
+    parent.name === id
+  ) {
+    return false;
+  }
+  // JSX attribute names.
+  if (ts.isJsxAttribute(parent) && parent.name === id) return false;
+  // Import / export specifiers.
+  if (ts.isImportSpecifier(parent) || ts.isExportSpecifier(parent)) return false;
+  if (ts.isImportClause(parent) || ts.isNamespaceImport(parent)) return false;
+  // Type-position property/method signature names.
+  if ((ts.isPropertySignature(parent) || ts.isMethodSignature(parent)) && parent.name === id) {
+    return false;
+  }
+  return true;
+}
+
+export function hookCalleeName(expr: ts.Expression): string | undefined {
+  if (ts.isIdentifier(expr)) return expr.text;
+  if (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.name)) return expr.name.text;
+  return undefined;
+}