tempest-react-sdk 0.24.0 → 0.26.0

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

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+
+import { isInsideBase, toAlias } from "./specifier.mjs";
+
+const BASE = "/proj/src";
+const FILE = "/proj/src/components/Card/Card.tsx";
+
+const alias = (spec, filePath = FILE) => toAlias({ spec, filePath, prefix: "@", baseDir: BASE });
+
+describe("isInsideBase", () => {
+    it("accepts a file under the base", () => {
+        expect(isInsideBase(FILE, BASE)).toBe(true);
+    });
+    it("rejects a file outside the base", () => {
+        expect(isInsideBase("/proj/vite.config.ts", BASE)).toBe(false);
+        expect(isInsideBase("/proj/e2e/spec.ts", BASE)).toBe(false);
+    });
+    it("rejects the base itself", () => {
+        expect(isInsideBase(BASE, BASE)).toBe(false);
+    });
+});
+
+describe("toAlias — what converts", () => {
+    it("converts a specifier climbing two levels", () => {
+        expect(alias("../../services/api")).toBe("@/services/api");
+    });
+    it("converts a specifier climbing one level", () => {
+        expect(alias("../Button")).toBe("@/components/Button");
+    });
+    it("converts up to the base root", () => {
+        expect(alias("../../routes")).toBe("@/routes");
+    });
+});
+
+describe("toAlias — what stays", () => {
+    it("leaves a sibling alone", () => {
+        expect(alias("./Card.module.css")).toBeNull();
+        expect(alias("./nested/deep")).toBeNull();
+    });
+    it("leaves a bare package alone", () => {
+        expect(alias("react")).toBeNull();
+        expect(alias("tempest-react-sdk/charts")).toBeNull();
+    });
+    it("leaves an already-aliased specifier alone", () => {
+        expect(alias("@/services/api")).toBeNull();
+    });
+    it("leaves a target outside the base alone", () => {
+        expect(alias("../../../vite.config")).toBeNull();
+        expect(alias("../../../../elsewhere/x")).toBeNull();
+    });
+    it("leaves a climb that lands exactly on the base alone", () => {
+        expect(alias("../..")).toBeNull();
+        expect(alias("../../")).toBeNull();
+    });
+});
+
+describe("toAlias — extensions", () => {
+    it("preserves whatever extension the specifier carried", () => {
+        expect(alias("../../styles/tokens.css")).toBe("@/styles/tokens.css");
+        expect(alias("../Card.module.css")).toBe("@/components/Card.module.css");
+        expect(alias("../../assets/logo.svg")).toBe("@/assets/logo.svg");
+        expect(alias("../../data/seed.json")).toBe("@/data/seed.json");
+    });
+    it("does not add an extension to an extensionless specifier", () => {
+        expect(alias("../../lib/api")).toBe("@/lib/api");
+    });
+});
+
+describe("toAlias — prefix and base come from the caller", () => {
+    it("honours a non-@ prefix", () => {
+        expect(toAlias({ spec: "../../lib/api", filePath: FILE, prefix: "~", baseDir: BASE })).toBe(
+            "~/lib/api",
+        );
+    });
+    it("honours an app/ base", () => {
+        expect(
+            toAlias({
+                spec: "../../lib/api",
+                filePath: "/proj/app/components/Card/Card.tsx",
+                prefix: "@",
+                baseDir: "/proj/app",
+            }),
+        ).toBe("@/lib/api");
+    });
+});

package/bin/lib/alias/tsconfig.mjs

@@ -0,0 +1,116 @@
+// Read a project's tsconfig.json the way `tsc` does: JSONC comments allowed and
+// the `extends` chain merged — without normalizing option values.
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+const MAX_EXTENDS_DEPTH = 16;
+
+/**
+ * Parse one tsconfig file into its raw JSON object.
+ *
+ * Prefers `ts.readConfigFile`, which accepts the JSONC dialect `tsc` accepts
+ * (comments, trailing commas). Falls back to `JSON.parse` so a project without
+ * TypeScript installed still gets the previous behavior instead of nothing.
+ *
+ * @param {string} path - Absolute path to a tsconfig file.
+ * @param {object | null} ts - The `typescript` module, or `null`.
+ * @returns {object | null} The raw config object, or `null` when unreadable.
+ */
+function parseConfigFile(path, ts) {
+    if (ts) {
+        const { config, error } = ts.readConfigFile(path, (p) => {
+            try {
+                return readFileSync(p, "utf8");
+            } catch {
+                return undefined;
+            }
+        });
+        return error || !config ? null : config;
+    }
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Resolve an `extends` entry to an absolute file path.
+ *
+ * Handles the two forms `tsc` supports: a relative/absolute path (with the
+ * `.json` extension optional) and a bare package specifier such as
+ * `@tsconfig/vite-react/tsconfig.json`, resolved from the extending file's
+ * directory.
+ *
+ * @param {string} spec - The `extends` value.
+ * @param {string} fromDir - Directory of the config that declares it.
+ * @returns {string | null} Absolute path, or `null` when it cannot be resolved.
+ */
+function resolveExtends(spec, fromDir) {
+    if (spec.startsWith(".") || isAbsolute(spec)) {
+        const base = resolve(fromDir, spec);
+        for (const candidate of [base, `${base}.json`, join(base, "tsconfig.json")]) {
+            if (existsSync(candidate)) return candidate;
+        }
+        return null;
+    }
+    try {
+        return createRequire(join(fromDir, "package.json")).resolve(spec);
+    } catch {
+        try {
+            return createRequire(join(fromDir, "package.json")).resolve(
+                join(spec, "tsconfig.json"),
+            );
+        } catch {
+            return null;
+        }
+    }
+}
+
+/**
+ * Read a project's tsconfig with its `extends` chain merged.
+ *
+ * `compilerOptions` are merged shallowly with the extending file winning, which
+ * matches `tsc` for the scalar options this CLI reads. Path-valued options
+ * (`baseUrl`, `paths`) are kept together with the directory of the file that
+ * declared them, because `tsc` resolves them relative to *that* file — not to
+ * the leaf config.
+ *
+ * Values are returned raw (`"bundler"`, `"react-jsx"`), never the numeric enums
+ * `ts.parseJsonConfigFileContent` would produce, so callers can compare strings.
+ *
+ * @param {object} params
+ * @param {string} params.root - Project root.
+ * @param {object | null} params.ts - The `typescript` module, or `null`.
+ * @param {string} [params.fileName] - Config file name. Default `"tsconfig.json"`.
+ * @returns {{ path: string, dir: string, compilerOptions: object, pathsBaseDir: string } | null}
+ *   `null` when the file is absent or unparseable.
+ */
+export function readTsconfig({ root, ts, fileName = "tsconfig.json" }) {
+    const path = resolve(root, fileName);
+    if (!existsSync(path)) return null;
+
+    const chain = [];
+    let current = path;
+    let depth = 0;
+    while (current && depth++ < MAX_EXTENDS_DEPTH) {
+        const config = parseConfigFile(current, ts);
+        if (!config) break;
+        chain.push({ dir: dirname(current), config });
+        const next = config.extends;
+        if (typeof next !== "string") break;
+        current = resolveExtends(next, dirname(current));
+    }
+    if (!chain.length) return null;
+
+    const compilerOptions = {};
+    let pathsBaseDir = dirname(path);
+    for (const { dir, config } of chain.reverse()) {
+        const co = config.compilerOptions;
+        if (!co || typeof co !== "object") continue;
+        if (co.paths || co.baseUrl) pathsBaseDir = dir;
+        Object.assign(compilerOptions, co);
+    }
+    return { path, dir: dirname(path), compilerOptions, pathsBaseDir };
+}

package/bin/lib/alias/typescript.mjs

@@ -0,0 +1,23 @@
+// Resolve the *project's own* TypeScript install — the alias codemod parses app
+// source, so it must agree with the compiler that type-checks it.
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+/**
+ * Load `typescript` from the project's `node_modules`.
+ *
+ * Resolution is anchored at `root` (not at this file) so the CLI never falls
+ * back to a copy bundled with the SDK: parsing app source with a different
+ * compiler version than the one that type-checks it would let syntax the app
+ * accepts fail here.
+ *
+ * @param {string} root - Project root, the directory holding `node_modules`.
+ * @returns {object | null} The `typescript` module, or `null` when not installed.
+ */
+export function loadTypeScript(root) {
+    try {
+        return createRequire(join(root, "package.json"))("typescript");
+    } catch {
+        return null;
+    }
+}

package/bin/lib/icons/generate.mjs

@@ -0,0 +1,156 @@
+// `tempest gen icons` — write a static icon registry from the slugs an app's
+// source mentions, for projects that want a versioned file instead of the
+// `virtual:tempest-icons` module the Vite plugin generates.
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const NAME_PATTERNS = [
+    /\bname\s*=\s*["']([a-z0-9-]+)["']/g,
+    /\bname\s*=\s*\{\s*["']([a-z0-9-]+)["']\s*\}/g,
+    /\bname\s*:\s*["']([a-z0-9-]+)["']/g,
+];
+
+const SOURCE_FILE = /\.[cm]?[jt]sx?$/;
+const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage"]);
+
+/**
+ * Read the slug tables out of the installed SDK build.
+ *
+ * Deliberately reads `dist/` rather than embedding a copy: the CLI must agree with
+ * the `<Icon>` the app actually renders, and both come from the same install.
+ *
+ * @param {string} selfDir - Directory holding this CLI (`bin/`).
+ * @returns {Promise<{ known: Set<string>, aliases: Record<string, string> }>}
+ */
+export async function loadIconTables(selfDir) {
+    const dist = join(selfDir, "..", "dist", "icons.js");
+    const mod = await import(pathToFileURL(dist).href);
+    return { known: new Set(mod.iconNames), aliases: mod.iconAliases };
+}
+
+/**
+ * Collect the icon slugs referenced literally in a source string.
+ *
+ * @param {string} code - File contents.
+ * @param {Set<string>} known - Real lucide slugs, aliases included.
+ * @returns {string[]} Validated slugs.
+ */
+export function scanIconSlugs(code, known) {
+    const found = new Set();
+    for (const pattern of NAME_PATTERNS) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(code)) !== null) {
+            if (known.has(match[1])) found.add(match[1]);
+        }
+    }
+    return [...found];
+}
+
+/**
+ * Walk a directory for source files, skipping build output and dot directories.
+ *
+ * @param {string} dir - Absolute directory.
+ * @returns {Promise<string[]>} Absolute file paths.
+ */
+export async function collectSourceFiles(dir) {
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+            out.push(...(await collectSourceFiles(join(dir, entry.name))));
+        } else if (entry.isFile() && SOURCE_FILE.test(entry.name)) {
+            out.push(join(dir, entry.name));
+        }
+    }
+    return out;
+}
+
+/** `circle-alert` → `CircleAlert`; `a-arrow-down` → `AArrowDown`. */
+function pascalCase(slug) {
+    return slug
+        .split("-")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
+}
+
+/**
+ * Export names that would shadow a restricted global if bound directly.
+ *
+ * Lucide ships an icon literally called `infinity`, whose export is `Infinity`.
+ * Binding that at module scope shadows the global, so the import is aliased.
+ */
+const RESERVED_NAMES = new Set(["Infinity", "NaN", "undefined", "eval", "arguments"]);
+
+/** The local binding to use for a lucide export name. */
+function localName(name) {
+    return RESERVED_NAMES.has(name) ? `${name}Icon` : name;
+}
+
+/**
+ * Render the registry module.
+ *
+ * An alias slug imports its canonical component but keeps its own key, so a name
+ * persisted before a lucide rename still resolves with no extra request.
+ *
+ * @param {readonly string[]} slugs - Validated slugs.
+ * @param {Record<string, string>} aliases - Alias slug → canonical slug.
+ * @returns {string} TypeScript module source.
+ */
+export function renderRegistry(slugs, aliases) {
+    const sorted = [...new Set(slugs)].sort();
+    const header = `// GENERATED by \`tempest gen icons\` — re-run after adding icons.
+import { createIconRegistry } from "tempest-react-sdk/icons";
+`;
+    if (!sorted.length) {
+        return `${header}
+export const icons = createIconRegistry({});
+`;
+    }
+    const componentOf = new Map(sorted.map((slug) => [slug, pascalCase(aliases[slug] ?? slug)]));
+    const named = [...new Set(componentOf.values())]
+        .sort()
+        .map((name) => (localName(name) === name ? name : `${name} as ${localName(name)}`))
+        .join(", ");
+    const entries = sorted
+        .map((slug) => `    "${slug}": ${localName(componentOf.get(slug))},`)
+        .join("\n");
+    return `${header}import { ${named} } from "lucide-react";
+
+export const icons = createIconRegistry({
+${entries}
+});
+`;
+}
+
+/**
+ * Scan a directory tree and render the registry module for it.
+ *
+ * @param {object} params
+ * @param {string} params.dir - Absolute directory to scan.
+ * @param {Set<string>} params.known - Real lucide slugs.
+ * @param {Record<string, string>} params.aliases - Alias slug → canonical slug.
+ * @param {readonly string[]} [params.include] - Extra slugs the scan cannot see.
+ * @returns {Promise<{ source: string, slugs: string[], files: number }>}
+ */
+export async function generateRegistry({ dir, known, aliases, include = [] }) {
+    const files = await collectSourceFiles(dir);
+    const slugs = new Set(include.filter((slug) => known.has(slug)));
+    for (const file of files) {
+        try {
+            const code = await readFile(file, "utf8");
+            for (const slug of scanIconSlugs(code, known)) slugs.add(slug);
+        } catch {
+            /* an unreadable file just contributes nothing */
+        }
+    }
+    const sorted = [...slugs].sort();
+    return { source: renderRegistry(sorted, aliases), slugs: sorted, files: files.length };
+}

package/bin/lib/icons/generate.test.mjs

@@ -0,0 +1,125 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { iconAliases, iconNames } from "@/icons";
+
+import { generateRegistry, renderRegistry, scanIconSlugs } from "./generate.mjs";
+
+const known = new Set(iconNames);
+
+describe("scanIconSlugs", () => {
+    it("finds literal name props, braced or not", () => {
+        expect(
+            scanIconSlugs(`<Icon name="save" /><Icon name={"trash-2"} />`, known).sort(),
+        ).toEqual(["save", "trash-2"]);
+    });
+    it("finds an object field", () => {
+        expect(scanIconSlugs(`{ name: "house" }`, known)).toEqual(["house"]);
+    });
+    it("ignores a name that is not a lucide slug", () => {
+        expect(scanIconSlugs(`<Field name="email" />`, known)).toEqual([]);
+    });
+    it("ignores a dynamic name", () => {
+        expect(scanIconSlugs(`<Icon name={row.icon} />`, known)).toEqual([]);
+    });
+});
+
+describe("renderRegistry", () => {
+    it("emits a createIconRegistry call with static imports", () => {
+        const out = renderRegistry(["save", "trash-2"], iconAliases);
+        expect(out).toContain(`import { createIconRegistry } from "tempest-react-sdk/icons";`);
+        expect(out).toContain(`import { Save, Trash2 } from "lucide-react";`);
+        expect(out).toContain(`    "save": Save,`);
+    });
+    it("imports the canonical component for an alias but keeps the alias key", () => {
+        const out = renderRegistry(["alert-circle"], iconAliases);
+        expect(out).toContain(`import { CircleAlert } from "lucide-react";`);
+        expect(out).toContain(`    "alert-circle": CircleAlert,`);
+    });
+    it("emits an empty registry rather than an empty import", () => {
+        expect(renderRegistry([], iconAliases)).toContain("createIconRegistry({})");
+    });
+    it("is deterministic regardless of input order", () => {
+        expect(renderRegistry(["trash-2", "save"], iconAliases)).toBe(
+            renderRegistry(["save", "trash-2"], iconAliases),
+        );
+    });
+});
+
+describe("generateRegistry", () => {
+    let root;
+
+    beforeEach(() => {
+        root = mkdtempSync(join(tmpdir(), "tempest-gen-icons-"));
+    });
+
+    afterEach(() => {
+        rmSync(root, { recursive: true, force: true });
+    });
+
+    /** Write a source file under the fixture root. */
+    function write(rel, contents) {
+        const path = join(root, rel);
+        mkdirSync(join(path, ".."), { recursive: true });
+        writeFileSync(path, contents);
+    }
+
+    it("collects slugs across a nested tree", async () => {
+        write("pages/Home.tsx", `<Icon name="house" />`);
+        write("pages/admin/Users.tsx", `<Icon name="users" />`);
+        const { slugs, files } = await generateRegistry({ dir: root, known, aliases: iconAliases });
+        expect(slugs).toEqual(["house", "users"]);
+        expect(files).toBe(2);
+    });
+
+    it("skips node_modules, dist and dot directories", async () => {
+        write("node_modules/dep/index.ts", `<Icon name="bug" />`);
+        write("dist/out.js", `<Icon name="bomb" />`);
+        write(".cache/x.ts", `<Icon name="box" />`);
+        write("App.tsx", `<Icon name="house" />`);
+        const { slugs } = await generateRegistry({ dir: root, known, aliases: iconAliases });
+        expect(slugs).toEqual(["house"]);
+    });
+
+    it("adds include slugs and drops invalid ones", async () => {
+        write("App.tsx", "");
+        const { slugs } = await generateRegistry({
+            dir: root,
+            known,
+            aliases: iconAliases,
+            include: ["rocket", "not-an-icon"],
+        });
+        expect(slugs).toEqual(["rocket"]);
+    });
+
+    it("yields an empty registry for a tree with no icons", async () => {
+        write("App.tsx", `export const App = () => null;`);
+        const { slugs, source } = await generateRegistry({
+            dir: root,
+            known,
+            aliases: iconAliases,
+        });
+        expect(slugs).toEqual([]);
+        expect(source).toContain("createIconRegistry({})");
+    });
+
+    it("returns zero files for a directory that does not exist", async () => {
+        const { files, slugs } = await generateRegistry({
+            dir: join(root, "nope"),
+            known,
+            aliases: iconAliases,
+        });
+        expect(files).toBe(0);
+        expect(slugs).toEqual([]);
+    });
+});
+
+describe("renderRegistry — reserved names", () => {
+    it("aliases an export name that would shadow a restricted global", () => {
+        const out = renderRegistry(["infinity"], iconAliases);
+        expect(out).toContain(`import { Infinity as InfinityIcon } from "lucide-react";`);
+        expect(out).toContain(`"infinity": InfinityIcon,`);
+    });
+});