tempest-react-sdk 0.25.0 → 0.26.1

package/bin/lib/alias/index.test.mjs

@@ -0,0 +1,138 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { aliasImports } from "./index.mjs";
+
+let root;
+
+/**
+ * Build a project fixture whose `typescript` resolves to this repo's copy.
+ *
+ * The symlinked `node_modules` is what makes `loadTypeScript` succeed from a
+ * directory outside the repo — the codemod deliberately refuses to fall back to
+ * a compiler the project does not have, so a fixture without it can only ever
+ * exercise the `no-typescript` branch.
+ */
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "tempest-alias-run-"));
+    symlinkSync(join(process.cwd(), "node_modules"), join(root, "node_modules"), "dir");
+    mkdirSync(join(root, "src"), { recursive: true });
+    writeFileSync(
+        join(root, "tsconfig.json"),
+        JSON.stringify({ compilerOptions: { paths: { "@/*": ["./src/*"] } } }),
+    );
+});
+
+afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+
+/** Write a fixture file, creating parent directories. */
+function write(rel, contents) {
+    const path = join(root, rel);
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, contents);
+}
+
+/** Read a fixture file back. */
+function read(rel) {
+    return readFileSync(join(root, rel), "utf8");
+}
+
+const run = (targets = ["."], dryRun = false) => aliasImports({ root, targets, dryRun });
+
+describe("aliasImports — writing", () => {
+    it("rewrites source and style files and reports the totals", () => {
+        write(
+            "src/pages/admin/Login.tsx",
+            `import { api } from "../../lib/api";\nimport "../x.css";\n`,
+        );
+        write("src/pages/admin/Login.module.css", `@import "../../styles/tokens.css";\n`);
+
+        const result = run();
+
+        expect(result.status).toBe("ok");
+        expect(result.prefix).toBe("@");
+        expect(result.total).toBe(3);
+        expect(result.files.map((f) => f.path.split("\\").join("/")).sort()).toEqual([
+            "src/pages/admin/Login.module.css",
+            "src/pages/admin/Login.tsx",
+        ]);
+        expect(read("src/pages/admin/Login.tsx")).toBe(
+            `import { api } from "@/lib/api";\nimport "@/pages/x.css";\n`,
+        );
+        expect(read("src/pages/admin/Login.module.css")).toBe(`@import "@/styles/tokens.css";\n`);
+    });
+
+    it("leaves files it must not touch alone", () => {
+        write("src/pages/admin/Login.tsx", `import { Row } from "./Row";\n`);
+        write("src/pages/admin/Deep.tsx", `import cfg from "../../../vite.config";\n`);
+        write("vite.config.ts", `import x from "./src/lib/api";\n`);
+        write("e2e/spec.ts", `import { api } from "../src/lib/api";\n`);
+
+        const result = run();
+
+        expect(result.total).toBe(0);
+        expect(result.files).toEqual([]);
+        expect(read("src/pages/admin/Deep.tsx")).toBe(`import cfg from "../../../vite.config";\n`);
+        expect(read("vite.config.ts")).toBe(`import x from "./src/lib/api";\n`);
+        expect(read("e2e/spec.ts")).toBe(`import { api } from "../src/lib/api";\n`);
+    });
+
+    it("is idempotent across two runs", () => {
+        write("src/pages/admin/Login.tsx", `import { api } from "../../lib/api";\n`);
+        expect(run().total).toBe(1);
+        const after = read("src/pages/admin/Login.tsx");
+        expect(run().total).toBe(0);
+        expect(read("src/pages/admin/Login.tsx")).toBe(after);
+    });
+
+    it("restricts the rewrite to a positional path", () => {
+        write("src/pages/admin/Login.tsx", `import { api } from "../../lib/api";\n`);
+        write("src/widgets/nested/Card.tsx", `import { api } from "../../lib/api";\n`);
+
+        expect(run(["src/pages"]).total).toBe(1);
+        expect(read("src/widgets/nested/Card.tsx")).toBe(`import { api } from "../../lib/api";\n`);
+    });
+});
+
+describe("aliasImports — dry run", () => {
+    it("reports the changes without writing", () => {
+        const before = `import { api } from "../../lib/api";\n`;
+        write("src/pages/admin/Login.tsx", before);
+
+        const result = run(["."], true);
+
+        expect(result.total).toBe(1);
+        expect(result.files[0].changes).toEqual([
+            { from: "../../lib/api", to: "@/lib/api", line: 1 },
+        ]);
+        expect(read("src/pages/admin/Login.tsx")).toBe(before);
+    });
+});
+
+describe("aliasImports — degraded projects", () => {
+    it("reports no-typescript when the project has no compiler", () => {
+        const bare = mkdtempSync(join(tmpdir(), "tempest-alias-bare-"));
+        try {
+            expect(aliasImports({ root: bare, targets: ["."] })).toMatchObject({
+                status: "no-typescript",
+                total: 0,
+                files: [],
+            });
+        } finally {
+            rmSync(bare, { recursive: true, force: true });
+        }
+    });
+
+    it("reports no-alias and writes nothing when no tsconfig declares one", () => {
+        rmSync(join(root, "tsconfig.json"));
+        const before = `import { api } from "../../lib/api";\n`;
+        write("src/pages/admin/Login.tsx", before);
+
+        expect(run()).toMatchObject({ status: "no-alias", total: 0, files: [] });
+        expect(read("src/pages/admin/Login.tsx")).toBe(before);
+    });
+});

package/bin/lib/alias/rewrite-css.mjs

@@ -0,0 +1,76 @@
+// Rewrite relative paths inside CSS to the project alias. Vite resolves aliases
+// in stylesheets too, but the TypeScript AST pass cannot see `.css` files.
+import { isInsideBase, toAlias } from "./specifier.mjs";
+
+/**
+ * `url(...)` in any position — `@import url("x")`, `background: url(x)`.
+ * Group 1 is everything before the value, group 2 the optional quote, group 3 the
+ * value, so the value's offset is derivable without searching inside the match.
+ */
+const URL_PATTERN = /(url\(\s*)(["']?)([^"')]+)\2(\s*\))/g;
+
+/**
+ * Quoted `@import` without `url()`. The quote must follow the whitespace
+ * directly, which is what keeps this from also matching the `url()` form above
+ * and rewriting the same span twice.
+ */
+const IMPORT_PATTERN = /(@import\s+)(["'])([^"']+)\2/g;
+
+/**
+ * Collect the rewritable value spans of a stylesheet.
+ *
+ * @param {string} text - Stylesheet contents.
+ * @returns {Array<{ start: number, end: number, value: string }>}
+ */
+function collectSpans(text) {
+    const spans = [];
+    for (const pattern of [URL_PATTERN, IMPORT_PATTERN]) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            const start = match.index + match[1].length + match[2].length;
+            spans.push({ start, end: start + match[3].length, value: match[3] });
+        }
+    }
+    return spans.sort((a, b) => a.start - b.start);
+}
+
+/**
+ * Rewrite the relative paths of one stylesheet to the alias form.
+ *
+ * Only values that climb out of the file's directory *and* land inside the alias
+ * base are converted, so `data:`, `http:` and fragment URLs need no special
+ * casing — none of them starts with `../`.
+ *
+ * Pure, and back-to-front like the TypeScript pass, for the same reason: earlier
+ * offsets must stay valid while later edits are applied.
+ *
+ * @param {object} params
+ * @param {string} params.text - Stylesheet contents.
+ * @param {string} params.filePath - Absolute path of the file.
+ * @param {string} params.prefix - Alias prefix, e.g. `"@"`.
+ * @param {string} params.baseDir - Absolute alias base directory.
+ * @returns {{ text: string, changes: Array<{ from: string, to: string, line: number }> }}
+ */
+export function rewriteCss({ text, filePath, prefix, baseDir }) {
+    if (!isInsideBase(filePath, baseDir)) return { text, changes: [] };
+
+    const edits = [];
+    const changes = [];
+    for (const { start, end, value } of collectSpans(text)) {
+        const to = toAlias({ spec: value, filePath, prefix, baseDir });
+        if (!to) continue;
+        edits.push({ start, end, to });
+        changes.push({
+            from: value,
+            to,
+            line: text.slice(0, start).split("\n").length,
+        });
+    }
+
+    let out = text;
+    for (const { start, end, to } of edits.reverse()) {
+        out = `${out.slice(0, start)}${to}${out.slice(end)}`;
+    }
+    return { text: out, changes };
+}

package/bin/lib/alias/rewrite-css.test.mjs

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+
+import { rewriteCss } from "./rewrite-css.mjs";
+
+const BASE = "/proj/src";
+const FILE = "/proj/src/components/Card/Card.module.css";
+
+const rewrite = (text, filePath = FILE) =>
+    rewriteCss({ text, filePath, prefix: "@", baseDir: BASE });
+
+describe("rewriteCss — @import", () => {
+    it("converts a quoted @import", () => {
+        const { text, changes } = rewrite(`@import "../../styles/tokens.css";\n`);
+        expect(text).toBe(`@import "@/styles/tokens.css";\n`);
+        expect(changes).toEqual([
+            { from: "../../styles/tokens.css", to: "@/styles/tokens.css", line: 1 },
+        ]);
+    });
+    it("converts @import url(...) exactly once", () => {
+        const { text, changes } = rewrite(`@import url("../../styles/tokens.css");\n`);
+        expect(text).toBe(`@import url("@/styles/tokens.css");\n`);
+        expect(changes).toHaveLength(1);
+    });
+    it("preserves single quotes", () => {
+        const { text } = rewrite(`@import '../../styles/tokens.css';\n`);
+        expect(text).toBe(`@import '@/styles/tokens.css';\n`);
+    });
+});
+
+describe("rewriteCss — url()", () => {
+    it("converts an unquoted url()", () => {
+        const { text } = rewrite(`.a { background: url(../../assets/bg.png); }\n`);
+        expect(text).toBe(`.a { background: url(@/assets/bg.png); }\n`);
+    });
+    it("converts a quoted url()", () => {
+        const { text } = rewrite(`.a { background: url("../../assets/bg.png"); }\n`);
+        expect(text).toBe(`.a { background: url("@/assets/bg.png"); }\n`);
+    });
+    it("converts several url() on one line without sliding offsets", () => {
+        const { text } = rewrite(
+            `.a { background: url(../../a.png); border-image: url(../../b.png); }\n`,
+        );
+        expect(text).toBe(`.a { background: url(@/a.png); border-image: url(@/b.png); }\n`);
+    });
+});
+
+describe("rewriteCss — what stays", () => {
+    it("leaves data:, http: and fragment URLs alone", () => {
+        const src = `.a { background: url(data:image/png;base64,AAA); }\n.b { background: url("https://x/y.png"); }\n.c { fill: url(#grad); }\n`;
+        expect(rewrite(src).text).toBe(src);
+    });
+    it("leaves a sibling path alone", () => {
+        const src = `@import "./tokens.css";\n.a { background: url(./bg.png); }\n`;
+        expect(rewrite(src).text).toBe(src);
+    });
+    it("leaves a root-absolute path alone", () => {
+        const src = `.a { background: url(/icon.svg); }\n`;
+        expect(rewrite(src).text).toBe(src);
+    });
+    it("leaves a target outside the alias base alone", () => {
+        const src = `.a { background: url(../../../public/bg.png); }\n`;
+        expect(rewrite(src).text).toBe(src);
+    });
+    it("leaves a file outside the alias base untouched", () => {
+        const src = `@import "../src/styles/tokens.css";\n`;
+        const { text, changes } = rewrite(src, "/proj/e2e/fixture.css");
+        expect(text).toBe(src);
+        expect(changes).toEqual([]);
+    });
+});
+
+describe("rewriteCss — mechanics", () => {
+    it("reports the line of each change", () => {
+        const { changes } = rewrite(
+            `@import "../../styles/a.css";\n\n.x { background: url(../../assets/b.png); }\n`,
+        );
+        expect(changes.map((ch) => ch.line)).toEqual([1, 3]);
+    });
+    it("is idempotent", () => {
+        const first = rewrite(`@import "../../styles/tokens.css";\n`);
+        const second = rewrite(first.text);
+        expect(second.text).toBe(first.text);
+        expect(second.changes).toEqual([]);
+    });
+});

package/bin/lib/alias/rewrite.mjs

@@ -0,0 +1,141 @@
+// Rewrite relative module specifiers to the project alias, driven by the
+// TypeScript AST so only real specifier positions are touched.
+import { extname } from "node:path";
+
+import { isInsideBase, toAlias } from "./specifier.mjs";
+
+const SCRIPT_KIND_BY_EXT = {
+    ".ts": "TS",
+    ".mts": "TS",
+    ".cts": "TS",
+    ".tsx": "TSX",
+    ".js": "JS",
+    ".mjs": "JS",
+    ".cjs": "JS",
+    ".jsx": "JSX",
+};
+
+const MOCK_METHODS = new Set(["mock", "doMock", "unmock", "doUnmock"]);
+
+/**
+ * Pick the `ts.ScriptKind` for a file so JSX parses as JSX.
+ *
+ * Getting this wrong is silent: parsed with `ScriptKind.TS`, a `.tsx` file's
+ * `<Foo />` becomes a type assertion and the specifiers after it are never
+ * visited.
+ *
+ * @param {string} filePath
+ * @param {object} ts - The `typescript` module.
+ * @returns {number} A `ts.ScriptKind` value.
+ */
+function scriptKindFor(filePath, ts) {
+    return ts.ScriptKind[SCRIPT_KIND_BY_EXT[extname(filePath)] ?? "TSX"];
+}
+
+/**
+ * True for a `vi.mock(...)`-family call expression.
+ *
+ * The mock path has to travel with the import it shadows: Vitest matches mocks
+ * by resolved id, so converting the import while leaving the mock relative keeps
+ * working, but a half-converted *pair* in a file someone later moves is exactly
+ * the silent-mock failure this avoids.
+ *
+ * @param {object} node - A `ts.CallExpression`.
+ * @param {object} ts - The `typescript` module.
+ * @returns {boolean}
+ */
+function isViMockCall(node, ts) {
+    const target = node.expression;
+    return (
+        ts.isPropertyAccessExpression(target) &&
+        ts.isIdentifier(target.expression) &&
+        target.expression.text === "vi" &&
+        ts.isIdentifier(target.name) &&
+        MOCK_METHODS.has(target.name.text)
+    );
+}
+
+/**
+ * Collect every string literal that sits in a module-specifier position.
+ *
+ * This is the whole reason the codemod parses instead of running a regex: a path
+ * inside a comment, a template literal, a plain variable or a `vi.mock` call with
+ * a computed argument never reaches this list.
+ *
+ * @param {object} sourceFile - A `ts.SourceFile`.
+ * @param {object} ts - The `typescript` module.
+ * @returns {object[]} The `ts.StringLiteral` nodes, in source order.
+ */
+function collectSpecifiers(sourceFile, ts) {
+    const found = [];
+    const push = (node) => {
+        if (node && ts.isStringLiteral(node)) found.push(node);
+    };
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+            push(node.moduleSpecifier);
+        } else if (ts.isImportTypeNode(node)) {
+            if (ts.isLiteralTypeNode(node.argument)) push(node.argument.literal);
+        } else if (ts.isCallExpression(node)) {
+            const isDynamicImport = node.expression.kind === ts.SyntaxKind.ImportKeyword;
+            if (isDynamicImport || isViMockCall(node, ts)) push(node.arguments[0]);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return found;
+}
+
+/**
+ * Rewrite the relative specifiers of one source file to the alias form.
+ *
+ * Pure: takes text, returns text. Nothing is read from or written to disk, which
+ * is what makes the rule itself testable without a fixture tree.
+ *
+ * Edits are applied back-to-front so that earlier offsets stay valid, and the
+ * original quote character is reused so the pass never fights Prettier over
+ * quote style. Formatting and import order are deliberately left alone — the
+ * `eslint --fix` and Prettier passes that follow own those.
+ *
+ * Files outside `baseDir` are returned untouched: see `isInsideBase`.
+ *
+ * @param {object} params
+ * @param {string} params.text - File contents.
+ * @param {string} params.filePath - Absolute path of the file.
+ * @param {string} params.prefix - Alias prefix, e.g. `"@"`.
+ * @param {string} params.baseDir - Absolute alias base directory.
+ * @param {object} params.ts - The `typescript` module.
+ * @returns {{ text: string, changes: Array<{ from: string, to: string, line: number }> }}
+ */
+export function rewriteSource({ text, filePath, prefix, baseDir, ts }) {
+    if (!isInsideBase(filePath, baseDir)) return { text, changes: [] };
+
+    const sourceFile = ts.createSourceFile(
+        filePath,
+        text,
+        ts.ScriptTarget.Latest,
+        true,
+        scriptKindFor(filePath, ts),
+    );
+
+    const edits = [];
+    const changes = [];
+    for (const literal of collectSpecifiers(sourceFile, ts)) {
+        const to = toAlias({ spec: literal.text, filePath, prefix, baseDir });
+        if (!to) continue;
+        const start = literal.getStart(sourceFile);
+        const end = literal.getEnd();
+        edits.push({ start, end, quote: text[start], to });
+        changes.push({
+            from: literal.text,
+            to,
+            line: sourceFile.getLineAndCharacterOfPosition(start).line + 1,
+        });
+    }
+
+    let out = text;
+    for (const { start, end, quote, to } of edits.reverse()) {
+        out = `${out.slice(0, start)}${quote}${to}${quote}${out.slice(end)}`;
+    }
+    return { text: out, changes };
+}

package/bin/lib/alias/rewrite.test.mjs

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+
+import { rewriteSource } from "./rewrite.mjs";
+import { loadTypeScript } from "./typescript.mjs";
+
+const ts = loadTypeScript(process.cwd());
+const BASE = "/proj/src";
+const FILE = "/proj/src/pages/admin/Users.tsx";
+
+const rewrite = (text, filePath = FILE) =>
+    rewriteSource({ text, filePath, prefix: "@", baseDir: BASE, ts });
+
+describe("rewriteSource — import / export positions", () => {
+    it("converts a value import", () => {
+        const { text, changes } = rewrite(`import { api } from "../../lib/api";\n`);
+        expect(text).toBe(`import { api } from "@/lib/api";\n`);
+        expect(changes).toEqual([{ from: "../../lib/api", to: "@/lib/api", line: 1 }]);
+    });
+    it("converts a type-only import", () => {
+        const { text } = rewrite(`import type { User } from "../../types/user";\n`);
+        expect(text).toBe(`import type { User } from "@/types/user";\n`);
+    });
+    it("converts a side-effect import", () => {
+        const { text } = rewrite(`import "../../styles/global.css";\n`);
+        expect(text).toBe(`import "@/styles/global.css";\n`);
+    });
+    it("converts a re-export", () => {
+        const { text } = rewrite(`export { api } from "../../lib/api";\nexport * from "../x";\n`);
+        expect(text).toBe(`export { api } from "@/lib/api";\nexport * from "@/pages/x";\n`);
+    });
+    it("converts an inline import type node", () => {
+        const { text } = rewrite(`type A = import("../../types/user").User;\n`);
+        expect(text).toBe(`type A = import("@/types/user").User;\n`);
+    });
+    it("converts a dynamic import", () => {
+        const { text } = rewrite(`const m = await import("../../pages/Dashboard");\n`);
+        expect(text).toBe(`const m = await import("@/pages/Dashboard");\n`);
+    });
+    it("converts vi.mock and its paired import together", () => {
+        const { text, changes } = rewrite(
+            `import { api } from "../../lib/api";\nvi.mock("../../lib/api");\n`,
+        );
+        expect(text).toBe(`import { api } from "@/lib/api";\nvi.mock("@/lib/api");\n`);
+        expect(changes.map((ch) => ch.line)).toEqual([1, 2]);
+    });
+    it("converts vi.doMock", () => {
+        const { text } = rewrite(`vi.doMock("../../lib/api", () => ({}));\n`);
+        expect(text).toBe(`vi.doMock("@/lib/api", () => ({}));\n`);
+    });
+});
+
+describe("rewriteSource — positions it must not touch", () => {
+    it("ignores a path in a plain variable", () => {
+        const src = `const p = "../../lib/api";\n`;
+        expect(rewrite(src).text).toBe(src);
+    });
+    it("ignores a path in a line comment", () => {
+        const src = `// see "../../lib/api"\nconst a = 1;\n`;
+        expect(rewrite(src).text).toBe(src);
+    });
+    it("ignores a path in a block comment above an import", () => {
+        const src = `/* was "../../lib/old" */\nimport { api } from "../../lib/api";\n`;
+        expect(rewrite(src).text).toBe(
+            `/* was "../../lib/old" */\nimport { api } from "@/lib/api";\n`,
+        );
+    });
+    it("ignores a template literal", () => {
+        const src = "const p = `../../lib/api`;\n";
+        expect(rewrite(src).text).toBe(src);
+    });
+    it("ignores a dynamic import with an interpolated specifier", () => {
+        const src = "const m = await import(`../../pages/${name}`);\n";
+        expect(rewrite(src).text).toBe(src);
+    });
+    it("ignores a dynamic import with a computed specifier", () => {
+        const src = `const m = await import(path);\n`;
+        expect(rewrite(src).text).toBe(src);
+    });
+    it("ignores require()", () => {
+        const src = `const api = require("../../lib/api");\n`;
+        expect(rewrite(src).text).toBe(src);
+    });
+    it("ignores a mock-looking call on another object", () => {
+        const src = `jest.mock("../../lib/api");\n`;
+        expect(rewrite(src).text).toBe(src);
+    });
+    it("ignores a sibling import", () => {
+        const src = `import { Row } from "./Row";\nimport css from "./Users.module.css";\n`;
+        expect(rewrite(src).text).toBe(src);
+    });
+    it("ignores a target outside the alias base", () => {
+        const src = `import cfg from "../../../vite.config";\n`;
+        expect(rewrite(src).text).toBe(src);
+    });
+});
+
+describe("rewriteSource — file scope", () => {
+    it("leaves a file outside the alias base untouched", () => {
+        const src = `import { x } from "../src/lib/api";\n`;
+        const { text, changes } = rewrite(src, "/proj/e2e/spec.ts");
+        expect(text).toBe(src);
+        expect(changes).toEqual([]);
+    });
+});
+
+describe("rewriteSource — mechanics", () => {
+    it("preserves single quotes", () => {
+        const { text } = rewrite(`import { api } from '../../lib/api';\n`);
+        expect(text).toBe(`import { api } from '@/lib/api';\n`);
+    });
+    it("rewrites several specifiers on one line without sliding offsets", () => {
+        const { text } = rewrite(
+            `import { a } from "../../lib/a";import { b } from "../../lib/b";\n`,
+        );
+        expect(text).toBe(`import { a } from "@/lib/a";import { b } from "@/lib/b";\n`);
+    });
+    it("reports the line of each change", () => {
+        const { changes } = rewrite(
+            `import { a } from "../../lib/a";\n\n\nimport { b } from "../../lib/b";\n`,
+        );
+        expect(changes.map((ch) => ch.line)).toEqual([1, 4]);
+    });
+    it("does not reorder or reformat anything", () => {
+        const { text } = rewrite(
+            `import {z} from "../../lib/z";\nimport {a} from "../../lib/a";\n`,
+        );
+        expect(text).toBe(`import {z} from "@/lib/z";\nimport {a} from "@/lib/a";\n`);
+    });
+    it("is idempotent", () => {
+        const first = rewrite(`import { api } from "../../lib/api";\n`);
+        const second = rewrite(first.text);
+        expect(second.text).toBe(first.text);
+        expect(second.changes).toEqual([]);
+    });
+    it("parses JSX without losing the specifiers after it", () => {
+        const { text } = rewrite(
+            `const el = <div className="x" />;\nimport { api } from "../../lib/api";\n`,
+        );
+        expect(text).toContain(`"@/lib/api"`);
+    });
+    it("parses a .ts file where < is a comparison", () => {
+        const { text } = rewrite(
+            `const ok = a < b;\nimport { api } from "../../lib/api";\n`,
+            "/proj/src/pages/admin/users.ts",
+        );
+        expect(text).toContain(`"@/lib/api"`);
+    });
+});

package/bin/lib/alias/specifier.mjs

@@ -0,0 +1,49 @@
+// The single rule both rewriters share: when does a relative specifier become an
+// alias specifier, and what does it become.
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+
+/**
+ * True when `filePath` sits inside `baseDir`.
+ *
+ * The gate exists because `@/` only resolves for files the bundler and the
+ * type-checker process through the alias. A file outside the base — a
+ * `vite.config.ts`, a script under `scripts/` — would get a specifier that
+ * resolves nowhere, and `vite.config.ts` in particular is loaded *without* the
+ * aliases it declares.
+ *
+ * @param {string} filePath - Absolute file path.
+ * @param {string} baseDir - Absolute alias base directory.
+ * @returns {boolean}
+ */
+export function isInsideBase(filePath, baseDir) {
+    const rel = relative(baseDir, filePath);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/**
+ * Convert one relative specifier to its alias form, or report that it stays.
+ *
+ * Only specifiers that climb out of their own directory are converted: a sibling
+ * `./x` already reads as "next to this file", which is information the alias
+ * form throws away. A specifier that resolves *outside* the alias base is left
+ * alone — that is what keeps `../../vite.config` and `../../../scripts/x`
+ * intact.
+ *
+ * The extension is never touched: whatever the specifier carried (`.module.css`,
+ * `.svg`, nothing at all) survives, because resolution of extensionless imports
+ * is the bundler's business, not this codemod's.
+ *
+ * @param {object} params
+ * @param {string} params.spec - The original specifier text.
+ * @param {string} params.filePath - Absolute path of the importing file.
+ * @param {string} params.prefix - Alias prefix, e.g. `"@"`.
+ * @param {string} params.baseDir - Absolute alias base directory.
+ * @returns {string | null} The alias specifier, or `null` to leave it as is.
+ */
+export function toAlias({ spec, filePath, prefix, baseDir }) {
+    if (!spec.startsWith("../")) return null;
+    const target = resolve(dirname(filePath), spec);
+    const rel = relative(baseDir, target);
+    if (!rel || rel.startsWith("..") || isAbsolute(rel)) return null;
+    return `${prefix}/${rel.split(sep).join("/")}`;
+}