fix(run): bug causing runs to fail if files use alias imports

.changeset/tsconfig-path-aliases.md

@@ -0,0 +1,9 @@
+---
+"@qawolf/cli": patch
+---
+
+`qawolf flows run` now resolves the tsconfig path aliases a flow imports through. A flow that imported `@utilities/gpt-helpers.ts` used to fail with `Cannot find package '@utilities/gpt-helpers.ts'`, because the local run handed the alias straight to Node, which went looking for an npm package by that name. The staged copy of your project is now rewritten so every alias becomes the equivalent relative import, which is what the platform runner does before it runs a flow. The aliases come from `compilerOptions.paths` in your project's `tsconfig.json`, the same table and the same rules the platform reads.
+
+Overlapping alias patterns now pick the target TypeScript picks. An exact pattern beats a wildcard, the longest matching prefix wins among wildcards, and the text after the `*` has to match too, so `@utilities/email/*` no longer loses to `@utilities/*` depending on the order the two are written in.
+
+An alias that still does not resolve now says so. The failure used to tell you to declare `@utilities/gpt-helpers.ts` in `package.json` "dependencies" and run npm install, which could never work. It now points at `compilerOptions.paths` in your tsconfig.

src/commands/flows/runStagedFlows.ts

@@ -86,6 +86,8 @@ export async function runStagedFlows(
     runRoot: runStagingRoot(),
     onInstallStart: (depCount) =>
       ctx.ui.info(runnerMessages.installingProjectDeps(depCount)),
+    onTsconfigUnparsed: (dir) =>
+      ctx.ui.warn(runnerMessages.tsconfigUnparsedNotice(dir)),
   });
 
   if (staged.outerHop.mode === "install") {

src/core/aliasImports/collectAliasSpecifiers.ts

@@ -0,0 +1,70 @@
+import type ts from "typescript";
+
+export type AliasSpecifier = {
+  end: number;
+  specifier: string;
+  start: number;
+};
+
+function isRelativeSpecifier(specifier: string): boolean {
+  return specifier.startsWith("./") || specifier.startsWith("../");
+}
+
+export function collectAliasSpecifiers(options: {
+  sourceFile: ts.SourceFile;
+  typescript: typeof ts;
+}): AliasSpecifier[] {
+  const { sourceFile, typescript: compiler } = options;
+  const specifiers: AliasSpecifier[] = [];
+
+  const addCandidate = (literal: ts.StringLiteralLike): void => {
+    if (isRelativeSpecifier(literal.text)) return;
+    specifiers.push({
+      end: literal.getEnd(),
+      specifier: literal.text,
+      start: literal.getStart(sourceFile),
+    });
+  };
+
+  for (const statement of sourceFile.statements) {
+    if (compiler.isImportDeclaration(statement)) {
+      const phase = statement.importClause?.phaseModifier;
+      if (phase === compiler.SyntaxKind.TypeKeyword) continue;
+      if (compiler.isStringLiteral(statement.moduleSpecifier)) {
+        addCandidate(statement.moduleSpecifier);
+      }
+      continue;
+    }
+
+    if (compiler.isExportDeclaration(statement) && !statement.isTypeOnly) {
+      const { moduleSpecifier } = statement;
+      if (
+        moduleSpecifier !== undefined &&
+        compiler.isStringLiteral(moduleSpecifier)
+      ) {
+        addCandidate(moduleSpecifier);
+      }
+    }
+  }
+
+  const visit = (node: ts.Node): void => {
+    if (
+      compiler.isCallExpression(node) &&
+      node.expression.kind === compiler.SyntaxKind.ImportKeyword
+    ) {
+      const [firstArgument] = node.arguments;
+      if (
+        firstArgument !== undefined &&
+        (compiler.isStringLiteral(firstArgument) ||
+          compiler.isNoSubstitutionTemplateLiteral(firstArgument))
+      ) {
+        addCandidate(firstArgument);
+      }
+      return;
+    }
+    compiler.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+
+  return specifiers;
+}

src/core/aliasImports/filePathVariants.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "bun:test";
+
+import { filePathVariants } from "./filePathVariants.js";
+
+describe("filePathVariants", () => {
+  it("tries the other source extension for a path that names one", () => {
+    expect(filePathVariants("src/utilities/gptHelpers.ts")).toEqual([
+      "src/utilities/gptHelpers.ts",
+      "src/utilities/gptHelpers.js",
+    ]);
+  });
+
+  it("resolves a .js specifier to its TypeScript source", () => {
+    expect(filePathVariants("src/pages/login.js")).toEqual([
+      "src/pages/login.js",
+      "src/pages/login.ts",
+    ]);
+  });
+
+  it("adds index candidates only for an extensionless path", () => {
+    expect(filePathVariants("src/pages/login")).toEqual([
+      "src/pages/login",
+      "src/pages/login.ts",
+      "src/pages/login.js",
+      "src/pages/login/index.ts",
+      "src/pages/login/index.js",
+    ]);
+  });
+  it("prefers TypeScript when a project holds both spellings of a file", () => {
+    const projectFiles = new Set(["src/u/foo.ts", "src/u/foo.js"]);
+    expect(
+      filePathVariants("src/u/foo").find((candidate) =>
+        projectFiles.has(candidate),
+      ),
+    ).toBe("src/u/foo.ts");
+  });
+
+  it("still binds the JavaScript file when the import names it", () => {
+    const projectFiles = new Set(["src/u/foo.ts", "src/u/foo.js"]);
+    expect(
+      filePathVariants("src/u/foo.js").find((candidate) =>
+        projectFiles.has(candidate),
+      ),
+    ).toBe("src/u/foo.js");
+  });
+});

src/core/aliasImports/filePathVariants.ts

@@ -0,0 +1,14 @@
+const sourceExtensionPattern = /\.(js|ts)$/;
+const sourceExtensions = [".ts", ".js"];
+
+export function filePathVariants(importPath: string): string[] {
+  const hasSourceExtension = sourceExtensionPattern.test(importPath);
+  const base = importPath.replace(sourceExtensionPattern, "");
+
+  const siblings = sourceExtensions.map((extension) => base + extension);
+  const indexes = hasSourceExtension
+    ? []
+    : sourceExtensions.map((extension) => `${base}/index${extension}`);
+
+  return [...new Set([importPath, ...siblings, ...indexes])];
+}

src/core/aliasImports/rewriteAliasImports.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from "bun:test";
+import typescript from "typescript";
+
+import { rewriteAliasImports } from "./rewriteAliasImports.js";
+import type { TsconfigPaths } from "./tsconfigPaths.js";
+
+const tsconfigPaths: TsconfigPaths = {
+  "@flows/*": ["src/flows/*"],
+  "@pages/*": ["src/pages/*"],
+  "@utilities/*": ["src/utilities/*"],
+};
+
+const projectFilePaths = new Set([
+  "src/flows/checkout.flow.ts",
+  "src/flows/shared.ts",
+  "src/pages/login/index.ts",
+  "src/utilities/gptHelpers.ts",
+  "src/utilities/legacy.js",
+  "src/utilities/both.ts",
+  "src/utilities/both.js",
+]);
+
+function rewrite(
+  code: string,
+  importingFilePath = "src/flows/checkout.flow.ts",
+): string {
+  return rewriteAliasImports({
+    code,
+    importingFilePath,
+    projectFilePaths,
+    tsconfigPaths,
+    typescript,
+  });
+}
+
+describe("rewriteAliasImports", () => {
+  it("rewrites an alias naming a source file to a relative specifier", () => {
+    expect(rewrite('import { ask } from "@utilities/gptHelpers.ts";')).toBe(
+      'import { ask } from "../utilities/gptHelpers.ts";',
+    );
+  });
+
+  it("rewrites an extensionless alias", () => {
+    expect(rewrite('import { ask } from "@utilities/gptHelpers";')).toBe(
+      'import { ask } from "../utilities/gptHelpers.ts";',
+    );
+  });
+
+  it("prefixes a same-directory target so it stays a relative specifier", () => {
+    expect(rewrite('import { shared } from "@flows/shared.ts";')).toBe(
+      'import { shared } from "./shared.ts";',
+    );
+  });
+
+  it("resolves a directory alias through its index file", () => {
+    expect(rewrite('import { login } from "@pages/login";')).toBe(
+      'import { login } from "../pages/login/index.ts";',
+    );
+  });
+
+  it("resolves a .js specifier to the TypeScript file on disk", () => {
+    expect(rewrite('import { ask } from "@utilities/gptHelpers.js";')).toBe(
+      'import { ask } from "../utilities/gptHelpers.ts";',
+    );
+  });
+
+  it("rewrites a dynamic import and a re-export", () => {
+    expect(rewrite('const m = await import("@utilities/gptHelpers.ts");')).toBe(
+      'const m = await import("../utilities/gptHelpers.ts");',
+    );
+    expect(rewrite('export { ask } from "@utilities/gptHelpers.ts";')).toBe(
+      'export { ask } from "../utilities/gptHelpers.ts";',
+    );
+  });
+
+  it("keeps the quote character the source used", () => {
+    expect(rewrite("import { ask } from '@utilities/gptHelpers.ts';")).toBe(
+      "import { ask } from '../utilities/gptHelpers.ts';",
+    );
+  });
+
+  it("leaves packages, builtins and subpath imports alone", () => {
+    const code = [
+      'import { readFile } from "node:fs/promises";',
+      'import { expect } from "playwright";',
+      'import { chromium } from "#playwright";',
+      'import { page } from "./page.ts";',
+    ].join("\n");
+    expect(rewrite(code)).toBe(code);
+  });
+
+  it("leaves an alias whose target is not in the project alone", () => {
+    const code = 'import { gone } from "@utilities/missing.ts";';
+    expect(rewrite(code)).toBe(code);
+  });
+
+  it("leaves the code alone when the project declares no aliases", () => {
+    const code = 'import { ask } from "@utilities/gptHelpers.ts";';
+    expect(
+      rewriteAliasImports({
+        code,
+        importingFilePath: "src/flows/checkout.flow.ts",
+        projectFilePaths,
+        tsconfigPaths: undefined,
+        typescript,
+      }),
+    ).toBe(code);
+  });
+
+  it("rewrites every alias in a file without moving any other line", () => {
+    const code = [
+      'import { ask } from "@utilities/gptHelpers.ts";',
+      'import { login } from "@pages/login";',
+      'import { shared } from "@flows/shared.ts";',
+      "",
+      "export default async function run() {",
+      "  await login();",
+      "  return ask(shared);",
+      "}",
+      "",
+    ].join("\n");
+    const rewritten = rewrite(code);
+
+    expect(rewritten.split("\n")).toEqual([
+      'import { ask } from "../utilities/gptHelpers.ts";',
+      'import { login } from "../pages/login/index.ts";',
+      'import { shared } from "./shared.ts";',
+      "",
+      "export default async function run() {",
+      "  await login();",
+      "  return ask(shared);",
+      "}",
+      "",
+    ]);
+  });
+
+  it("rewrites relative to the importing file, not the project root", () => {
+    expect(
+      rewrite(
+        'import { ask } from "@utilities/gptHelpers.ts";',
+        "src/pages/login/index.ts",
+      ),
+    ).toBe('import { ask } from "../../utilities/gptHelpers.ts";');
+  });
+  it("leaves a type-only import alone, as the platform runner does", () => {
+    const code = 'import type { Helper } from "@utilities/gptHelpers.ts";';
+    expect(rewrite(code)).toBe(code);
+  });
+
+  it("rewrites from a file sitting at the project root", () => {
+    expect(
+      rewrite(
+        'import { ask } from "@utilities/gptHelpers.ts";',
+        "smoke.flow.ts",
+      ),
+    ).toBe('import { ask } from "./src/utilities/gptHelpers.ts";');
+  });
+  it("binds the TypeScript file when the project holds both spellings", () => {
+    expect(rewrite('import { both } from "@utilities/both";')).toBe(
+      'import { both } from "../utilities/both.ts";',
+    );
+  });
+});