@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/src/analyse/resolveModule.ts

@@ -0,0 +1,431 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+
+/**
+ * Project-local module resolution for the analyser: relative specifiers,
+ * tsconfig `paths` aliases (with `extends` chains) and `baseUrl` fallback,
+ * then the monorepo's own workspace packages (`@scope/shared`) resolved to
+ * their SOURCE trees. Bare THIRD-PARTY specifiers (react, next/link, …)
+ * still intentionally resolve to undefined — node_modules is never walked
+ * into; only directories the workspace map enumerates are entered, and all
+ * of those live inside the repo.
+ */
+
+export interface PathPattern {
+  /** Key split on its single `*`; exact keys have no star. */
+  prefix: string;
+  suffix: string;
+  exact: boolean;
+  /** Raw target strings with `*` preserved, in declared order. */
+  targets: string[];
+  /** Directory targets resolve against. */
+  baseDir: string;
+}
+
+interface ResolvedTsconfig {
+  configPath: string;
+  baseUrlDir: string | undefined;
+  patterns: PathPattern[];
+}
+
+const MODULE_SUFFIXES = [".tsx", ".ts", "/index.tsx", "/index.ts"];
+
+/** Try `base` as a module file: as-is, extension-swapped, then index files. */
+export function probeModuleFile(base: string): string | undefined {
+  if (existsSync(base) && !isDirectory(base)) return base;
+  const stripped = base.replace(/\.(jsx?|tsx?)$/, "");
+  for (const ext of MODULE_SUFFIXES) {
+    const candidate = `${stripped}${ext}`;
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function isDirectory(p: string): boolean {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+interface WorkspaceMap {
+  rootDir: string;
+  /** package.json `name` → absolute package dir. */
+  packages: Map<string, string>;
+}
+
+/**
+ * The workspace glob list declared at `dir`, or undefined when `dir` is not
+ * a workspace root. package.json `workspaces` (array or `{ packages: [] }`)
+ * and pnpm-workspace.yaml are unioned when both exist — resolving a true
+ * member is never wrong whichever manager owns the repo.
+ */
+function workspaceGlobs(dir: string): string[] | undefined {
+  const globs: string[] = [];
+  const pkgPath = path.join(dir, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as {
+        workspaces?: string[] | { packages?: string[] };
+      };
+      const ws = Array.isArray(pkg.workspaces) ? pkg.workspaces : pkg.workspaces?.packages;
+      if (ws) globs.push(...ws.filter((g): g is string => typeof g === "string"));
+    } catch {
+      // Unparseable package.json: not a workspace root we can trust.
+    }
+  }
+  const pnpmPath = path.join(dir, "pnpm-workspace.yaml");
+  if (existsSync(pnpmPath)) globs.push(...pnpmWorkspacePackages(pnpmPath));
+  return globs.length > 0 ? globs : undefined;
+}
+
+/**
+ * The top-level `packages:` list of a pnpm-workspace.yaml, without a YAML
+ * dependency: consume `- entry` lines until the first non-list line. Fancy
+ * YAML (anchors, flow lists) yields nothing — the bail-safe direction.
+ */
+function pnpmWorkspacePackages(file: string): string[] {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  const out: string[] = [];
+  let inList = false;
+  for (const line of text.split("\n")) {
+    if (/^packages\s*:\s*(#.*)?$/.test(line)) {
+      inList = true;
+      continue;
+    }
+    if (!inList) continue;
+    // Zero-indent items (`- 'packages/*'` at column 0) are valid YAML and
+    // pnpm accepts them; only a new top-level key ends the list.
+    const m = /^\s*-\s*['"]?([^'"#]+?)['"]?\s*(#.*)?$/.exec(line);
+    if (m?.[1]) out.push(m[1]);
+    else if (/^\S/.test(line)) break;
+  }
+  return out;
+}
+
+/**
+ * The supported glob subset, classified: a literal dir, or a single
+ * TRAILING-star dir glob (`packages/*`, bare `*`). Anything else — `**`,
+ * mid-pattern or multiple stars — is undefined (unsupported).
+ */
+function dirGlobShape(
+  glob: string,
+): { kind: "literal"; dir: string } | { kind: "star"; parent: string } | undefined {
+  const star = glob.indexOf("*");
+  if (star === -1) return { kind: "literal", dir: glob };
+  if (glob !== "*" && !glob.endsWith("/*")) return undefined;
+  if (star !== glob.lastIndexOf("*")) return undefined;
+  return { kind: "star", parent: glob === "*" ? "." : glob.slice(0, -2) };
+}
+
+/**
+ * Enumerate the packages the globs name. The supported subset is literal
+ * dirs and single-star dir globs (`packages/*`) — a fancier POSITIVE glob
+ * (`**`, mid-pattern stars) is silently skipped, because resolution
+ * returning undefined is the bail-safe direction. Negations are APPLIED,
+ * not skipped: ignoring an exclusion would widen the map — the one
+ * direction that is not bail-safe — so an unsupported negation disables
+ * this root entirely. node_modules is refused even when a glob names it:
+ * the never-walk invariant outranks the map.
+ */
+function buildWorkspaceMap(rootDir: string, globs: string[]): WorkspaceMap {
+  const packages = new Map<string, string>();
+
+  const negations: Array<{ kind: "literal"; dir: string } | { kind: "star"; parent: string }> = [];
+  for (const glob of globs) {
+    if (!glob.startsWith("!")) continue;
+    const shape = dirGlobShape(glob.slice(1));
+    if (!shape) return { rootDir, packages };
+    negations.push(shape);
+  }
+  const excluded = (pkgDir: string): boolean =>
+    negations.some((neg) =>
+      neg.kind === "literal"
+        ? path.resolve(rootDir, neg.dir) === pkgDir
+        : path.dirname(pkgDir) === path.resolve(rootDir, neg.parent),
+    );
+
+  const addPackage = (pkgDir: string): void => {
+    if (excluded(pkgDir)) return;
+    const pkgJson = path.join(pkgDir, "package.json");
+    if (!existsSync(pkgJson)) return;
+    try {
+      const pkg = JSON.parse(readFileSync(pkgJson, "utf8")) as { name?: string };
+      if (typeof pkg.name === "string" && pkg.name.length > 0 && !packages.has(pkg.name)) {
+        packages.set(pkg.name, pkgDir);
+      }
+    } catch {
+      // Unreadable member manifest: skip the package, keep the map.
+    }
+  };
+  for (const glob of globs) {
+    if (glob.startsWith("!") || glob.includes("node_modules")) continue;
+    const shape = dirGlobShape(glob);
+    if (!shape) continue;
+    if (shape.kind === "literal") {
+      addPackage(path.resolve(rootDir, shape.dir));
+      continue;
+    }
+    const parent = path.resolve(rootDir, shape.parent);
+    if (path.basename(parent) === "node_modules" || !isDirectory(parent)) continue;
+    let entries: string[];
+    try {
+      entries = readdirSync(parent);
+    } catch {
+      continue;
+    }
+    for (const entry of entries.sort()) {
+      if (entry === "node_modules" || entry.startsWith(".")) continue;
+      const pkgDir = path.join(parent, entry);
+      if (isDirectory(pkgDir)) addPackage(pkgDir);
+    }
+  }
+  return { rootDir, packages };
+}
+
+export class ModuleResolver {
+  /** dir → nearest resolved tsconfig (null = no tsconfig above this dir). */
+  private dirCache = new Map<string, ResolvedTsconfig | null>();
+  /** configPath → parsed chain result. */
+  private configCache = new Map<string, ResolvedTsconfig>();
+  /** dir → nearest workspace map (null = no workspace root above this dir). */
+  private workspaceDirCache = new Map<string, WorkspaceMap | null>();
+  /** workspace root dir → built map. */
+  private workspaceCache = new Map<string, WorkspaceMap>();
+
+  /** The tsconfig path patterns in effect for files under `dir` (for alias re-emission). */
+  aliasPatternsFor(dir: string): PathPattern[] {
+    return this.nearestConfig(dir)?.patterns ?? [];
+  }
+
+  /** Resolve `spec` as imported from `importerAbsPath`. Undefined for bare/unresolvable. */
+  resolve(spec: string, importerAbsPath: string): string | undefined {
+    if (spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/")) {
+      return probeModuleFile(path.resolve(path.dirname(importerAbsPath), spec));
+    }
+    const importerDir = path.dirname(importerAbsPath);
+    const config = this.nearestConfig(importerDir);
+    if (config) {
+      const match = this.matchPattern(config, spec);
+      if (match) return match;
+
+      if (config.baseUrlDir) {
+        const hit = probeModuleFile(path.resolve(config.baseUrlDir, spec));
+        if (hit) return hit;
+      }
+    }
+    // Both non-workspace exits (no tsconfig at all, and a paths/baseUrl
+    // miss) fall through here: a workspace app often has no tsconfig of its
+    // own, and gating the branch on one would silently keep it failing.
+    return this.resolveWorkspace(spec, importerDir);
+  }
+
+  /**
+   * A bare specifier as one of the monorepo's own workspace packages,
+   * resolved to its SOURCE tree — never `exports`/`main`/`types`: dist is
+   * routinely stale or absent, and `.d.ts` files have no function bodies for
+   * the fetch-wrapper path to read. probeModuleFile only knows .ts/.tsx, so
+   * a .js-source or .d.ts-only package misses here exactly like a package
+   * that does not exist — bail-safe, and deliberate.
+   */
+  private resolveWorkspace(spec: string, importerDir: string): string | undefined {
+    const ws = this.nearestWorkspace(importerDir);
+    if (!ws) return undefined;
+    let best: { name: string; dir: string } | undefined;
+    for (const [name, dir] of ws.packages) {
+      if (spec !== name && !spec.startsWith(`${name}/`)) continue;
+      if (!best || name.length > best.name.length) best = { name, dir };
+    }
+    if (!best) return undefined;
+    const subpath = spec === best.name ? undefined : spec.slice(best.name.length + 1);
+    const bases =
+      subpath === undefined
+        ? [path.join(best.dir, "src", "index"), path.join(best.dir, "index")]
+        : [path.join(best.dir, "src", subpath), path.join(best.dir, subpath)];
+    for (const base of bases) {
+      const hit = probeModuleFile(base);
+      if (hit) return hit;
+    }
+    return undefined;
+  }
+
+  private nearestWorkspace(fromDir: string): WorkspaceMap | null {
+    const visited: string[] = [];
+    let dir = path.resolve(fromDir);
+    for (;;) {
+      const cached = this.workspaceDirCache.get(dir);
+      if (cached !== undefined) {
+        for (const v of visited) this.workspaceDirCache.set(v, cached);
+        return cached;
+      }
+      visited.push(dir);
+      const globs = workspaceGlobs(dir);
+      if (globs) {
+        const built = this.workspaceCache.get(dir) ?? buildWorkspaceMap(dir, globs);
+        this.workspaceCache.set(dir, built);
+        for (const v of visited) this.workspaceDirCache.set(v, built);
+        return built;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) {
+        for (const v of visited) this.workspaceDirCache.set(v, null);
+        return null;
+      }
+      dir = parent;
+    }
+  }
+
+  private matchPattern(config: ResolvedTsconfig, spec: string): string | undefined {
+    for (const p of config.patterns) {
+      if (p.exact) {
+        if (spec !== p.prefix) continue;
+        for (const target of p.targets) {
+          const hit = probeModuleFile(path.resolve(p.baseDir, target));
+          if (hit) return hit;
+        }
+        continue;
+      }
+      if (
+        spec.startsWith(p.prefix) &&
+        spec.endsWith(p.suffix) &&
+        spec.length >= p.prefix.length + p.suffix.length
+      ) {
+        const captured = spec.slice(p.prefix.length, spec.length - p.suffix.length);
+        for (const target of p.targets) {
+          const substituted = target.replace("*", captured);
+          const hit = probeModuleFile(path.resolve(p.baseDir, substituted));
+          if (hit) return hit;
+        }
+      }
+    }
+    return undefined;
+  }
+
+  private nearestConfig(fromDir: string): ResolvedTsconfig | null {
+    const visited: string[] = [];
+    let dir = path.resolve(fromDir);
+    for (;;) {
+      const cached = this.dirCache.get(dir);
+      if (cached !== undefined) {
+        for (const v of visited) this.dirCache.set(v, cached);
+        return cached;
+      }
+      visited.push(dir);
+      const candidate = path.join(dir, "tsconfig.json");
+      if (existsSync(candidate)) {
+        const resolved = this.parseConfigChain(candidate);
+        for (const v of visited) this.dirCache.set(v, resolved);
+        return resolved;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) {
+        for (const v of visited) this.dirCache.set(v, null);
+        return null;
+      }
+      dir = parent;
+    }
+  }
+
+  private parseConfigChain(configPath: string): ResolvedTsconfig {
+    const cached = this.configCache.get(configPath);
+    if (cached) return cached;
+
+    // Walk the extends chain collecting raw configs root-first (child last),
+    // so later entries override earlier ones with TS semantics: `paths` and
+    // `baseUrl` are replaced wholesale by whichever config declares them last.
+    const chain: Array<{ dir: string; options: Record<string, unknown> }> = [];
+    const seen = new Set<string>();
+    const load = (p: string): void => {
+      const abs = path.resolve(p);
+      if (seen.has(abs)) return;
+      seen.add(abs);
+      const read = ts.readConfigFile(abs, ts.sys.readFile);
+      const config = (read.config ?? {}) as {
+        extends?: string | string[];
+        compilerOptions?: Record<string, unknown>;
+      };
+      const dir = path.dirname(abs);
+      const bases = config.extends
+        ? Array.isArray(config.extends)
+          ? config.extends
+          : [config.extends]
+        : [];
+      for (const base of bases) {
+        const resolved = this.resolveExtends(base, dir);
+        if (resolved) load(resolved);
+      }
+      chain.push({ dir, options: config.compilerOptions ?? {} });
+    };
+    load(configPath);
+
+    let baseUrlDir: string | undefined;
+    let pathsEntry:
+      | { dir: string; paths: Record<string, unknown>; baseUrlDir?: string }
+      | undefined;
+    for (const { dir, options } of chain) {
+      const baseUrl = typeof options.baseUrl === "string" ? options.baseUrl : undefined;
+      if (baseUrl !== undefined) baseUrlDir = path.resolve(dir, baseUrl);
+      const paths = options.paths;
+      if (paths && typeof paths === "object") {
+        pathsEntry = { dir, paths: paths as Record<string, unknown>, baseUrlDir };
+      }
+    }
+
+    const patterns: PathPattern[] = [];
+    if (pathsEntry) {
+      // Without baseUrl (TS >= 4.1), paths resolve against the declaring config's dir.
+      const baseDir = pathsEntry.baseUrlDir ?? pathsEntry.dir;
+      for (const [key, rawTargets] of Object.entries(pathsEntry.paths)) {
+        if (!Array.isArray(rawTargets)) continue;
+        const targets = rawTargets.filter((t): t is string => typeof t === "string");
+        if (targets.length === 0) continue;
+        const star = key.indexOf("*");
+        if (star === -1) {
+          patterns.push({ prefix: key, suffix: "", exact: true, targets, baseDir });
+        } else {
+          patterns.push({
+            prefix: key.slice(0, star),
+            suffix: key.slice(star + 1),
+            exact: false,
+            targets,
+            baseDir,
+          });
+        }
+      }
+      // Longest prefix wins.
+      patterns.sort((a, b) => b.prefix.length - a.prefix.length);
+    }
+
+    const result: ResolvedTsconfig = { configPath, baseUrlDir, patterns };
+    this.configCache.set(configPath, result);
+    return result;
+  }
+
+  private resolveExtends(spec: string, fromDir: string): string | undefined {
+    if (spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/")) {
+      const base = path.resolve(fromDir, spec);
+      if (existsSync(base) && !isDirectory(base)) return base;
+      if (existsSync(`${base}.json`)) return `${base}.json`;
+      if (existsSync(path.join(base, "tsconfig.json"))) return path.join(base, "tsconfig.json");
+      return undefined;
+    }
+    // Bare specifier (@tsconfig/foo): probe node_modules upward from the config dir.
+    let dir = fromDir;
+    for (;;) {
+      const root = path.join(dir, "node_modules", spec);
+      for (const candidate of [root, `${root}.json`, path.join(root, "tsconfig.json")]) {
+        if (existsSync(candidate) && !isDirectory(candidate)) return candidate;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) return undefined;
+      dir = parent;
+    }
+  }
+}

package/src/analyse/resolveTagRootTags.ts

@@ -0,0 +1,103 @@
+import ts from "typescript";
+import { extractRootTag } from "./extractRootTag.ts";
+import type { ImportBinding } from "./parseFile.ts";
+import { parseFile } from "./parseFile.ts";
+import type { ModuleResolver } from "./resolveModule.ts";
+import type { SourceFileCache } from "./sourceCache.ts";
+
+/**
+ * What host element each component tag in a render actually produces.
+ *
+ * This exists to replace a naming convention. Deciding whether a bare
+ * `page.locator("button")` names one element meant counting how many things in
+ * the render could answer to it, and a `<Button>` obviously can — but "obviously"
+ * was implemented as `tag.toLowerCase().endsWith("button")`, which is a guess in
+ * a codebase whose rule is to bail rather than guess. `<LinkButton>` may well
+ * render an `<a>`.
+ *
+ * The evidence is one hop away: resolve the tag to its module, parse it, and
+ * read the root tag the analyser already computes for every component. Same-file
+ * components resolve without any I/O at all.
+ *
+ * Unresolved tags are simply absent from the map. The caller falls back to the
+ * convention for those, which only ever makes it MORE cautious — a false
+ * positive costs a test, a false negative clicks the wrong element.
+ */
+export async function resolveTagRootTags(
+  bodyNode: ts.Node,
+  sameFile: ts.SourceFile,
+  imports: Map<string, ImportBinding>,
+  fromPath: string,
+  resolver: ModuleResolver,
+  /** Shared parse cache — without it every tag target re-parses once per entry. */
+  cache?: SourceFileCache,
+): Promise<Map<string, string>> {
+  const out = new Map<string, string>();
+  const tags = componentTagsIn(bodyNode);
+  if (tags.size === 0) return out;
+
+  // Same-file first: no resolution, no read.
+  const localBodies = componentBodiesIn(sameFile);
+  for (const tag of tags) {
+    const body = localBodies.get(tag);
+    if (!body) continue;
+    const root = extractRootTag(body);
+    if (root) out.set(tag, root);
+  }
+
+  for (const tag of tags) {
+    if (out.has(tag)) continue;
+    const binding = imports.get(tag);
+    if (!binding || binding.isTypeOnly) continue;
+    const target = resolver.resolve(binding.specifier, fromPath);
+    // Bare THIRD-PARTY specifiers resolve to undefined by design (workspace
+    // packages resolve to their source since B-8) — node_modules is never
+    // walked, so a third-party <Button> stays unknown rather than guessed.
+    if (!target) continue;
+    try {
+      const parsed = await parseFile(target, cache);
+      const wanted = binding.importedName ?? tag;
+      const unit =
+        parsed.components.find((c) => c.componentName === wanted) ??
+        (binding.kind === "default" ? parsed.components[0] : undefined);
+      if (!unit) continue;
+      const root = extractRootTag(unit.bodyNode);
+      if (root) out.set(tag, root);
+    } catch {
+      // Unparseable target: absent from the map, so the caller stays cautious.
+    }
+  }
+  return out;
+}
+
+/** Capitalised JSX tag names used anywhere in this render. */
+function componentTagsIn(root: ts.Node): Set<string> {
+  const tags = new Set<string>();
+  const visit = (n: ts.Node): void => {
+    if (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n)) {
+      if (ts.isIdentifier(n.tagName) && /^[A-Z]/.test(n.tagName.text)) tags.add(n.tagName.text);
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(root);
+  return tags;
+}
+
+/** Component name → body node, for the components declared in this same file. */
+function componentBodiesIn(sourceFile: ts.SourceFile): Map<string, ts.Node> {
+  const out = new Map<string, ts.Node>();
+  const visit = (n: ts.Node): void => {
+    if (ts.isFunctionDeclaration(n) && n.name && n.body && /^[A-Z]/.test(n.name.text)) {
+      out.set(n.name.text, n.body);
+    }
+    if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && /^[A-Z]/.test(n.name.text)) {
+      const init = n.initializer;
+      if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+        out.set(n.name.text, init.body);
+      }
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(sourceFile);
+  return out;
+}