tempest-react-sdk 0.26.0 → 0.26.1

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/tempest.mjs

@@ -14,6 +14,7 @@ import { fileURLToPath } from "node:url";
 import { aliasImports } from "./lib/alias/index.mjs";
 import { loadTypeScript } from "./lib/alias/typescript.mjs";
 import { readTsconfig } from "./lib/alias/tsconfig.mjs";
+import { checkLucide } from "./lib/doctor/lucide.mjs";
 import { generateRegistry, loadIconTables } from "./lib/icons/generate.mjs";
 import { generate } from "./lib/openapi/generate.mjs";
 import { loadSpec } from "./lib/openapi/load.mjs";
@@ -351,6 +352,21 @@ function doctor() {
                       "nested copy under tempest-react-sdk — run `npm dedupe` or align versions; two instances break hooks/context",
                   ],
         );
+
+        // lucide-react gets its own check: two copies of it do not break hooks the
+        // way a second React does, but they duplicate bytes and can leave the
+        // generated icon slug tables pointing at exports the older copy lacks.
+        const sdkPkg = readJSON(join(ROOT, "node_modules", "tempest-react-sdk", "package.json"));
+        checks.push(
+            ...checkLucide({
+                appSpec: deps["lucide-react"] ? String(deps["lucide-react"]) : null,
+                sdkSpec: sdkPkg?.dependencies?.["lucide-react"]
+                    ? String(sdkPkg.dependencies["lucide-react"])
+                    : null,
+                installedVersion: installedVersion("lucide-react"),
+                nestedCopy: nestedDupe("lucide-react"),
+            }),
+        );
     }
 
     // Declared-but-not-installed (package.json ↔ node_modules drift).

package/package.json

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