tempest-react-sdk 0.25.0 → 0.26.1

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/doctor/lucide.mjs

@@ -0,0 +1,74 @@
+// The `lucide-react` single-instance check for `tempest doctor`.
+//
+// Kept out of the generic stateful-deps check on purpose: two copies of React or
+// of react-query break hooks and context, which is a different failure from what
+// two copies of lucide cause. Lucide is stateless, so nothing "breaks" at
+// runtime — instead the bytes are duplicated and, far worse, the generated slug
+// tables behind `tempest-react-sdk/icons` can reference exports the second copy
+// does not have.
+
+/** Major version number from a semver string or range, or null. */
+function major(spec) {
+    if (!spec) return null;
+    const match = /(\d+)\./.exec(String(spec).replace(/^[^\d]*/, ""));
+    return match ? Number(match[1]) : null;
+}
+
+/**
+ * Audit how many copies of `lucide-react` a project will end up with.
+ *
+ * @param {object} params
+ * @param {string | null} params.appSpec - Range the app declares, or `null`.
+ * @param {string | null} params.sdkSpec - Range the installed SDK declares, or `null`.
+ * @param {string | null} params.installedVersion - Version resolved at the app root, or `null`.
+ * @param {boolean} params.nestedCopy - Whether a copy exists under the SDK's own `node_modules`.
+ * @returns {Array<[status: string, label: string, detail?: string]>} Check rows.
+ */
+export function checkLucide({ appSpec, sdkSpec, installedVersion, nestedCopy }) {
+    const rows = [];
+
+    // The SDK not declaring it means this project does not use the icons surface
+    // at all (or the SDK is not installed) — there is nothing to audit.
+    if (!sdkSpec) return rows;
+
+    if (nestedCopy) {
+        rows.push([
+            "warn",
+            "two copies of lucide-react",
+            "nested copy under tempest-react-sdk — duplicated bytes, and the generated " +
+                "icon slug tables may not match it; run `npm dedupe` or drop lucide-react " +
+                "from your package.json (the SDK ships it)",
+        ]);
+    }
+
+    if (appSpec) {
+        const sameRange = appSpec === sdkSpec;
+        rows.push([
+            sameRange ? "info" : "warn",
+            "lucide-react declared by the app",
+            sameRange
+                ? `matches the SDK's ${sdkSpec} so a single copy installs — the declaration is ` +
+                  "redundant, but harmless (npm/yarn resolve it from the SDK without it)"
+                : `you declare ${appSpec}, the SDK declares ${sdkSpec} — two copies install. ` +
+                  "Run `npm uninstall lucide-react`; only declare it under pnpm, and then " +
+                  `use ${sdkSpec}`,
+        ]);
+    }
+
+    const installedMajor = major(installedVersion);
+    const requiredMajor = major(sdkSpec);
+    if (installedMajor !== null && requiredMajor !== null && installedMajor < requiredMajor) {
+        rows.push([
+            "fail",
+            `lucide-react v${installedVersion} is older than the SDK needs`,
+            `the icon slug tables are generated against ${sdkSpec}, so exports they ` +
+                "reference can be missing — the build fails with `… is not exported by " +
+                "lucide-react` pointing inside the SDK",
+        ]);
+    }
+
+    if (rows.length === 0) {
+        rows.push(["ok", "single lucide-react instance", `from the SDK — ${sdkSpec}`]);
+    }
+    return rows;
+}

package/bin/lib/doctor/lucide.test.mjs

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+
+import { checkLucide } from "./lucide.mjs";
+
+/** The healthy shape: the SDK brings lucide, the app declares nothing. */
+const CLEAN = {
+    appSpec: null,
+    sdkSpec: "^1.26.0",
+    installedVersion: "1.26.0",
+    nestedCopy: false,
+};
+
+/** Statuses of the returned rows, in order. */
+const statuses = (rows) => rows.map(([status]) => status);
+
+/** All detail text joined, for asserting the advice is actually present. */
+const details = (rows) => rows.map(([, , detail]) => detail ?? "").join(" ");
+
+describe("checkLucide — nothing to audit", () => {
+    it("returns no rows when the SDK does not declare lucide", () => {
+        expect(checkLucide({ ...CLEAN, sdkSpec: null })).toEqual([]);
+    });
+
+    it("stays silent even if the app declares it, with no SDK to compare against", () => {
+        expect(checkLucide({ ...CLEAN, sdkSpec: null, appSpec: "^1.0.0" })).toEqual([]);
+    });
+});
+
+describe("checkLucide — healthy", () => {
+    it("reports a single instance and names where it came from", () => {
+        const rows = checkLucide(CLEAN);
+        expect(statuses(rows)).toEqual(["ok"]);
+        expect(rows[0][1]).toBe("single lucide-react instance");
+        expect(rows[0][2]).toContain("^1.26.0");
+    });
+
+    it("stays ok when the installed version is newer than required", () => {
+        expect(statuses(checkLucide({ ...CLEAN, installedVersion: "2.4.0" }))).toEqual(["ok"]);
+    });
+
+    it("stays ok when the version cannot be resolved at all", () => {
+        expect(statuses(checkLucide({ ...CLEAN, installedVersion: null }))).toEqual(["ok"]);
+    });
+});
+
+describe("checkLucide — the app declares it too", () => {
+    it("warns and says to uninstall when the range differs from the SDK's", () => {
+        const rows = checkLucide({ ...CLEAN, appSpec: "^0.575.0" });
+        expect(statuses(rows)).toEqual(["warn"]);
+        expect(details(rows)).toContain("npm uninstall lucide-react");
+        expect(details(rows)).toContain("^0.575.0");
+        expect(details(rows)).toContain("^1.26.0");
+    });
+
+    it("mentions pnpm, the one case where declaring it is correct", () => {
+        expect(details(checkLucide({ ...CLEAN, appSpec: "^0.575.0" }))).toContain("pnpm");
+    });
+
+    it("downgrades to info when the range matches — redundant, not broken", () => {
+        const rows = checkLucide({ ...CLEAN, appSpec: "^1.26.0" });
+        expect(statuses(rows)).toEqual(["info"]);
+        expect(details(rows)).toContain("redundant");
+    });
+});
+
+describe("checkLucide — a second physical copy", () => {
+    it("warns about the nested copy and points at both remedies", () => {
+        const rows = checkLucide({ ...CLEAN, nestedCopy: true });
+        expect(statuses(rows)).toEqual(["warn"]);
+        expect(rows[0][1]).toBe("two copies of lucide-react");
+        expect(details(rows)).toContain("npm dedupe");
+        expect(details(rows)).toContain("the SDK ships it");
+    });
+
+    it("reports the nested copy and the declaration as separate rows", () => {
+        const rows = checkLucide({ ...CLEAN, nestedCopy: true, appSpec: "^0.575.0" });
+        expect(statuses(rows)).toEqual(["warn", "warn"]);
+    });
+});
+
+describe("checkLucide — version older than the generated tables need", () => {
+    it("fails, because this one breaks the build rather than wasting bytes", () => {
+        const rows = checkLucide({ ...CLEAN, installedVersion: "0.575.0" });
+        expect(statuses(rows)).toEqual(["fail"]);
+        expect(rows[0][1]).toContain("0.575.0");
+        expect(details(rows)).toContain("is not exported by");
+    });
+
+    it("explains that the error surfaces inside the SDK, not in app code", () => {
+        expect(details(checkLucide({ ...CLEAN, installedVersion: "0.575.0" }))).toContain(
+            "inside the SDK",
+        );
+    });
+
+    it("reports the skew alongside the declaration that caused it", () => {
+        const rows = checkLucide({
+            ...CLEAN,
+            appSpec: "^0.575.0",
+            installedVersion: "0.575.0",
+        });
+        expect(statuses(rows)).toEqual(["warn", "fail"]);
+    });
+
+    it("does not fail on a malformed version string", () => {
+        expect(statuses(checkLucide({ ...CLEAN, installedVersion: "latest" }))).toEqual(["ok"]);
+    });
+});

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 };
+}