tempest-react-sdk 0.29.0 → 0.29.1

package/bin/lib/alias/index.mjs

@@ -7,7 +7,7 @@ import { collectFiles } from "./collect.mjs";
 import { discoverAlias } from "./discover.mjs";
 import { rewriteCss } from "./rewrite-css.mjs";
 import { rewriteSource } from "./rewrite.mjs";
-import { loadTypeScript } from "./typescript.mjs";
+import { loadTypeScript, typeScriptUnavailableReason } from "./typescript.mjs";
 
 export { collectFiles } from "./collect.mjs";
 export { discoverAlias } from "./discover.mjs";
@@ -15,7 +15,7 @@ export { rewriteCss } from "./rewrite-css.mjs";
 export { rewriteSource } from "./rewrite.mjs";
 export { isInsideBase, toAlias } from "./specifier.mjs";
 export { readTsconfig } from "./tsconfig.mjs";
-export { loadTypeScript } from "./typescript.mjs";
+export { describeTypeScript, loadTypeScript, typeScriptUnavailableReason } from "./typescript.mjs";
 
 /**
  * Convert relative imports that climb out of their directory into alias imports.
@@ -42,7 +42,13 @@ export function aliasImports({ root, targets, dryRun = false }) {
     const empty = { files: [], total: 0, errors: [] };
 
     const ts = loadTypeScript(root);
-    if (!ts) return { status: "no-typescript", ...empty };
+    if (!ts) {
+        return {
+            status: "no-typescript",
+            reason: typeScriptUnavailableReason(root),
+            ...empty,
+        };
+    }
 
     const alias = discoverAlias({ root, ts });
     if (!alias) return { status: "no-alias", ...empty };

package/bin/lib/alias/tsconfig.mjs

@@ -6,19 +6,62 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
 
 const MAX_EXTENDS_DEPTH = 16;
 
+/**
+ * Strip the JSONC a tsconfig is allowed to contain: `//` and block comments, and
+ * a trailing comma before `}` or `]`.
+ *
+ * Needed because `ts.readConfigFile` is not always available — TypeScript 7 does
+ * not ship the classic API — and a plain `JSON.parse` chokes on the comments
+ * every Vite-generated tsconfig has. Losing the whole config to a comment would
+ * silently drop the `strict`/`jsx`/`paths` checks.
+ *
+ * Comment markers inside a string are left alone, which matters: `"paths"` and
+ * `"extends"` values legitimately hold `//` (a URL, a Windows share).
+ *
+ * @param {string} text
+ * @returns {string} Plain JSON.
+ */
+export function stripJsonc(text) {
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '"') {
+            let j = i + 1;
+            while (j < text.length && text[j] !== '"') j += text[j] === "\\" ? 2 : 1;
+            out += text.slice(i, Math.min(j + 1, text.length));
+            i = j + 1;
+            continue;
+        }
+        if (ch === "/" && text[i + 1] === "/") {
+            const end = text.indexOf("\n", i);
+            i = end < 0 ? text.length : end;
+            continue;
+        }
+        if (ch === "/" && text[i + 1] === "*") {
+            const end = text.indexOf("*/", i + 2);
+            i = end < 0 ? text.length : end + 2;
+            continue;
+        }
+        out += ch;
+        i += 1;
+    }
+    return out.replace(/,(\s*[}\]])/g, "$1");
+}
+
 /**
  * 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.
+ * Prefers `ts.readConfigFile`, which accepts the exact dialect `tsc` accepts.
+ * Falls back to a JSONC-tolerant parse so a project without the classic
+ * TypeScript API still gets its config read 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) {
+    if (ts && typeof ts.readConfigFile === "function") {
         const { config, error } = ts.readConfigFile(path, (p) => {
             try {
                 return readFileSync(p, "utf8");
@@ -29,7 +72,7 @@ function parseConfigFile(path, ts) {
         return error || !config ? null : config;
     }
     try {
-        return JSON.parse(readFileSync(path, "utf8"));
+        return JSON.parse(stripJsonc(readFileSync(path, "utf8")));
     } catch {
         return null;
     }

package/bin/lib/alias/typescript.mjs

@@ -3,6 +3,23 @@
 import { createRequire } from "node:module";
 import { join } from "node:path";
 
+/**
+ * The classic-API members every codemod in this CLI needs.
+ *
+ * TypeScript 7 is the native port: its package still installs under the name
+ * `typescript`, but the `.` export is a version stub — the JS API moved behind
+ * `typescript/unstable/*` with a different shape. So "the module resolved" no
+ * longer implies "the API is there", and calling into it blew up with
+ * `ts.readConfigFile is not a function` — a stack trace out of `tempest doctor`,
+ * which is the command people run first.
+ */
+const REQUIRED_API = ["readConfigFile", "createSourceFile", "forEachChild"];
+
+/** True when the resolved module exposes the classic compiler API. */
+function hasClassicApi(module) {
+    return Boolean(module) && REQUIRED_API.every((name) => typeof module[name] === "function");
+}
+
 /**
  * Load `typescript` from the project's `node_modules`.
  *
@@ -11,13 +28,66 @@ import { join } from "node:path";
  * compiler version than the one that type-checks it would let syntax the app
  * accepts fail here.
  *
+ * Returns `null` both when TypeScript is absent and when the install does not
+ * expose the classic API, because callers treat the two the same way — report it
+ * and leave the source untouched. Use {@link describeTypeScript} to say which of
+ * the two happened.
+ *
  * @param {string} root - Project root, the directory holding `node_modules`.
- * @returns {object | null} The `typescript` module, or `null` when not installed.
+ * @returns {object | null} The `typescript` module, or `null`.
  */
 export function loadTypeScript(root) {
     try {
-        return createRequire(join(root, "package.json"))("typescript");
+        const module = createRequire(join(root, "package.json"))("typescript");
+        return hasClassicApi(module) ? module : null;
     } catch {
         return null;
     }
 }
+
+/**
+ * What the project's TypeScript install is, so a message can say the truth
+ * instead of "not installed" about a package that is right there.
+ *
+ * @param {string} root - Project root.
+ * @returns {{ status: "ok" | "missing" | "api-unavailable", version: string | null }}
+ */
+export function describeTypeScript(root) {
+    let resolve_;
+    try {
+        resolve_ = createRequire(join(root, "package.json"));
+    } catch {
+        return { status: "missing", version: null };
+    }
+    let version = null;
+    try {
+        version = resolve_("typescript/package.json")?.version ?? null;
+    } catch {
+        return { status: "missing", version: null };
+    }
+    try {
+        return {
+            status: hasClassicApi(resolve_("typescript")) ? "ok" : "api-unavailable",
+            version,
+        };
+    } catch {
+        return { status: "api-unavailable", version };
+    }
+}
+
+/**
+ * One line explaining why a codemod cannot run, or `null` when it can.
+ *
+ * @param {string} root - Project root.
+ * @returns {string | null}
+ */
+export function typeScriptUnavailableReason(root) {
+    const { status, version } = describeTypeScript(root);
+    if (status === "ok") return null;
+    if (status === "missing") return "typescript não instalado (npm i -D typescript)";
+    return (
+        `typescript ${version ?? "?"} não expõe a API clássica do compilador — o 7 publica só ` +
+        "`typescript/unstable/*`, com outra forma. Pra usar os codemods, tenha o TypeScript 6 " +
+        "instalado; o resto do comando segue normal"
+    );
+}

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

@@ -0,0 +1,120 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { readTsconfig, stripJsonc } from "./tsconfig.mjs";
+import { describeTypeScript, loadTypeScript, typeScriptUnavailableReason } from "./typescript.mjs";
+
+let root;
+
+/** Write a file under the fixture, creating parent directories. */
+function write(rel, text) {
+    const full = join(root, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, text);
+}
+
+/**
+ * Fake an installed `typescript` whose main module exports `exports`.
+ *
+ * TypeScript 7 is exactly this shape: the package resolves, the version is there,
+ * and the classic API is not — it moved to `typescript/unstable/*`.
+ */
+function fakeTypeScript(version, exports) {
+    write(
+        "node_modules/typescript/package.json",
+        JSON.stringify({ name: "typescript", version, main: "index.js" }),
+    );
+    write("node_modules/typescript/index.js", `module.exports = ${exports};`);
+}
+
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "tempest-ts-"));
+    write("package.json", JSON.stringify({ name: "fixture" }));
+});
+
+afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+
+describe("loadTypeScript", () => {
+    it("returns null when typescript is not installed", () => {
+        expect(loadTypeScript(root)).toBeNull();
+        expect(describeTypeScript(root)).toEqual({ status: "missing", version: null });
+        expect(typeScriptUnavailableReason(root)).toContain("não instalado");
+    });
+
+    it("returns null for an install without the classic compiler API", () => {
+        fakeTypeScript("7.0.2", '{ version: "7.0.2", versionMajorMinor: "7.0" }');
+        expect(loadTypeScript(root)).toBeNull();
+        expect(describeTypeScript(root)).toEqual({ status: "api-unavailable", version: "7.0.2" });
+        const reason = typeScriptUnavailableReason(root);
+        expect(reason).toContain("7.0.2");
+        expect(reason).toContain("unstable");
+    });
+
+    it("returns the module when the classic API is there", () => {
+        fakeTypeScript(
+            "6.0.3",
+            "{ readConfigFile: () => ({}), createSourceFile: () => ({}), forEachChild: () => {} }",
+        );
+        expect(loadTypeScript(root)).not.toBeNull();
+        expect(describeTypeScript(root)).toEqual({ status: "ok", version: "6.0.3" });
+        expect(typeScriptUnavailableReason(root)).toBeNull();
+    });
+
+    it("treats a partial API as unavailable rather than half-usable", () => {
+        fakeTypeScript("7.1.0", "{ createSourceFile: () => ({}) }");
+        expect(loadTypeScript(root)).toBeNull();
+    });
+});
+
+describe("stripJsonc", () => {
+    it("removes line and block comments", () => {
+        expect(stripJsonc('{ // hi\n "a": 1 /* there */ }')).toBe('{ \n "a": 1  }');
+    });
+
+    it("removes a trailing comma before a close", () => {
+        expect(JSON.parse(stripJsonc('{ "a": [1, 2,], }'))).toEqual({ a: [1, 2] });
+    });
+
+    it("leaves comment markers inside strings alone", () => {
+        expect(JSON.parse(stripJsonc('{ "url": "https://x.dev/a", "p": "a/*b" }'))).toEqual({
+            url: "https://x.dev/a",
+            p: "a/*b",
+        });
+    });
+
+    it("survives an unterminated comment instead of throwing", () => {
+        expect(() => stripJsonc('{ "a": 1 } /* forever')).not.toThrow();
+    });
+});
+
+describe("readTsconfig without the compiler API", () => {
+    it("still reads a tsconfig that has comments and a trailing comma", () => {
+        write(
+            "tsconfig.json",
+            '{\n  // the app\n  "compilerOptions": {\n    "strict": true,\n    "paths": { "@/*": ["./src/*"] },\n  },\n}\n',
+        );
+        const config = readTsconfig({ root, ts: null });
+        expect(config.compilerOptions.strict).toBe(true);
+        expect(config.compilerOptions.paths["@/*"]).toEqual(["./src/*"]);
+    });
+
+    it("follows extends with the fallback parser", () => {
+        write("base.json", '{ "compilerOptions": { "jsx": "react-jsx" } } // base\n');
+        write(
+            "tsconfig.json",
+            '{ "extends": "./base.json", "compilerOptions": { "strict": true } }',
+        );
+        const config = readTsconfig({ root, ts: null });
+        expect(config.compilerOptions).toMatchObject({ jsx: "react-jsx", strict: true });
+    });
+
+    it("ignores a `ts` that cannot read a config file", () => {
+        write("tsconfig.json", '{ "compilerOptions": { "strict": true } }');
+        const config = readTsconfig({ root, ts: { version: "7.0.2" } });
+        expect(config.compilerOptions.strict).toBe(true);
+    });
+});

package/bin/lib/css/extract.mjs

@@ -25,7 +25,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 
 import { discoverAlias } from "../alias/discover.mjs";
-import { loadTypeScript } from "../alias/typescript.mjs";
+import { loadTypeScript, typeScriptUnavailableReason } from "../alias/typescript.mjs";
 import { collectSources, indexClassUses, resolveSpecifier } from "./references.mjs";
 import { parseCss } from "./parse.mjs";
 import { declSignature } from "./semantic.mjs";
@@ -192,8 +192,7 @@ export function planExtraction({ analysis, root, target, prefix = "u-" }) {
     if (!ts) {
         return {
             status: "no-typescript",
-            message:
-                "typescript não instalado — a reescrita do TSX precisa do compilador do projeto",
+            message: `a reescrita do TSX precisa do compilador do projeto: ${typeScriptUnavailableReason(root)}`,
             groups: [],
             refusals: [],
         };

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

@@ -155,6 +155,50 @@ describe("tempest doctor — generic findings still surface", () => {
     });
 });
 
+describe("tempest doctor — a project on TypeScript 7", () => {
+    /**
+     * TypeScript 7 is the native port: same package name, and no classic compiler
+     * API — it moved to `typescript/unstable/*`. Before this was detected, `doctor`
+     * died with `ts.readConfigFile is not a function` on any such project, which is
+     * the worst possible failure for the command people run first.
+     */
+    beforeEach(() => {
+        thirdPartyApp();
+        write("node_modules/typescript/package.json", {
+            name: "typescript",
+            version: "7.0.2",
+            main: "index.js",
+        });
+        write(
+            "node_modules/typescript/index.js",
+            'module.exports = { version: "7.0.2", versionMajorMinor: "7.0" };',
+        );
+    });
+
+    it("does not crash, and still reports the tsconfig checks", () => {
+        const { out, code } = doctor();
+        expect(out).not.toContain("is not a function");
+        expect(out).toContain("moduleResolution: bundler");
+        expect(code).toBe(0);
+    });
+
+    it("says the codemods are unavailable, and why", () => {
+        const { out } = doctor();
+        expect(out).toContain("no classic compiler API");
+        expect(out).toContain("every other pass runs");
+    });
+
+    it("reads a tsconfig with comments through the fallback parser", () => {
+        writeFileSync(
+            join(root, "tsconfig.json"),
+            '{\n  // vite default\n  "compilerOptions": { "strict": true, "jsx": "react-jsx", "moduleResolution": "bundler" },\n}\n',
+        );
+        const { out } = doctor();
+        expect(out).toContain("strict mode on");
+        expect(out).not.toContain("strict mode off");
+    });
+});
+
 describe("tempest doctor — stylesheets", () => {
     beforeEach(thirdPartyApp);
 

package/bin/tempest.mjs

@@ -12,7 +12,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { aliasImports } from "./lib/alias/index.mjs";
-import { loadTypeScript } from "./lib/alias/typescript.mjs";
+import { describeTypeScript, loadTypeScript } from "./lib/alias/typescript.mjs";
 import { readTsconfig } from "./lib/alias/tsconfig.mjs";
 import { analyzeCss, applyCssFixes, applyExtraction, planExtraction } from "./lib/css/index.mjs";
 import { checkLucide } from "./lib/doctor/lucide.mjs";
@@ -535,6 +535,21 @@ function doctor() {
     const tsc = readTsconfig({ root: ROOT, ts: loadTypeScript(ROOT) });
     if (tsc) {
         checks.push(["section", "TypeScript"]);
+        /*
+         * TypeScript 7 installs under the same package name and does not ship the
+         * classic compiler API — it lives behind `typescript/unstable/*` with a
+         * different shape. The tsconfig checks below keep working (they fall back to
+         * a JSONC-tolerant parse), but the codemods cannot run, and saying so here is
+         * better than each pass reporting it as if TypeScript were missing.
+         */
+        const tsInstall = describeTypeScript(ROOT);
+        if (tsInstall.status === "api-unavailable") {
+            checks.push([
+                "info",
+                `typescript ${tsInstall.version} has no classic compiler API`,
+                "`tempest fix` skips the alias and --extract-css codemods — they need the TypeScript 6 API; every other pass runs",
+            ]);
+        }
         const co = tsc.compilerOptions;
         // The `@/*` alias is the SDK's convention, not a health property: a project
         // that has not adopted the SDK is not wrong for lacking it.
@@ -855,7 +870,7 @@ function parseFixArgs(args) {
 function reportAlias(result, dryRun) {
     if (result.status === "no-typescript") {
         console.log(
-            `${c.yellow}! typescript not installed — skipping alias pass${c.reset} ${c.dim}(npm i -D typescript)${c.reset}`,
+            `${c.yellow}! alias pass skipped${c.reset} ${c.dim}— ${result.reason ?? "typescript não instalado"}${c.reset}`,
         );
         return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempest-react-sdk",
-  "version": "0.29.0",
+  "version": "0.29.1",
   "description": "SDK público da Tempest com componentes, hooks e integrações para projetos React.",
   "type": "module",
   "license": "MIT",