@hazem3500/palette 0.9.106 → 0.9.107

package/README.md

@@ -256,7 +256,8 @@ export default defineConfig({
   plugins: [
     paletteComponents({
       enabled: process.env.PREVIEW_BUILD === "1",
-      // Every component export of these packages that has editable props.
+      // Every component export of these packages that has editable props. "@acme/ui/*" lists
+      // every subpath in the package's exports map (@acme/ui/button, @acme/ui/badge, …).
       packages: ["@acme/ui"],
       // App components, by module and export, relative to the Vite root.
       components: ["src/cards/ProjectCard.tsx#ProjectCard", "src/nav/TopBar.tsx"],
@@ -286,7 +287,7 @@ export default defineConfig({
 - **Finding the instance.** Picking an element reads React's fiber links (`return`, `child`, `memoizedState`) to find the nearest instrumented instance, like the fiber adapter, and never writes them. In Viewport, the framed app's own instances answer.
 - **Cost.** The preview build carries a 2 KB gzip runtime plus each component's prop list. The test fixture measured 2.3 KB for 13 components, and on an Apple M4 Max about 0.6 µs per instance to mount and 0.3 µs per update.
 - **Limits.**
-  - Code that compares element types, such as `child.type === Tab` inside the package, sees the wrapper instead of the original. Exclude such components.
+  - Code that compares element types, such as `child.type === Tab`, would see the wrapper instead of the original. The plugin scans each package's shipped JavaScript for such comparisons and leaves those components uninstrumented, with a warning naming the file. A minified package renames its locals, so the scan can't see them there: exclude such components yourself.
   - A component with several root elements is selected by its first one.
   - Components used only inside the package itself, not imported by the app, aren't instrumented.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hazem3500/palette",
-  "version": "0.9.106",
+  "version": "0.9.107",
   "description": "Point, area, and threaded comments for website branches.",
   "type": "module",
   "license": "MIT",

package/vite/index.d.mts

@@ -4,7 +4,11 @@ export interface PaletteComponentsOptions {
    * `process.env.PREVIEW === "1"`. Off, the plugin has no hooks and the build is unchanged.
    */
   enabled?: boolean;
-  /** Design-system packages (or package subpaths): every eligible component export is instrumented. */
+  /**
+   * Design-system packages or package subpaths: every eligible component export is instrumented.
+   * "@scope/ds/*" expands to every subpath in the package's exports map. Components the package
+   * compares by element type (`child.type === Item`) are left alone, with a warning.
+   */
   packages?: string[];
   /**
    * App components to instrument, relative to the Vite root: "src/cards/Card.tsx" for every

package/vite/index.mjs

@@ -9,6 +9,7 @@
 // from @hazem3500/palette/react-instrument. Node-only.
 import { resolve } from "node:path";
 import { collectComponents, defaultExclude } from "./metadata.mjs";
+import { expandPackages, packageDirectory, packageName, typeComparedNames } from "./packages.mjs";
 
 const PREFIX = "\0palette-components:";
 const RUNTIME = "@hazem3500/palette/react-instrument";
@@ -17,7 +18,10 @@ const RUNTIME = "@hazem3500/palette/react-instrument";
 export function paletteComponents(options = {}) {
   const name = "palette-components";
   if (options.enabled !== true) return { name };
-  const packages = [...new Set(options.packages ?? [])];
+  const listed = [...new Set(options.packages ?? [])];
+  /** Specifiers after expanding `@scope/ds/*` globs. */
+  let packages = listed.filter((entry) => !entry.endsWith("/*"));
+  let expanded;
   const modules = (options.components ?? []).map((entry) => {
     const [file, exported] = String(entry).split("#");
     return { file, exports: exported ? exported.split(",").map((item) => item.trim()).filter(Boolean) : undefined };
@@ -49,8 +53,32 @@ export function paletteComponents(options = {}) {
     return lines.join("\n") + "\n";
   }
 
+  const expand = () => (expanded ??= expandPackages(listed, root).then((result) => {
+    packages = result.specifiers;
+    return result;
+  }));
+
   async function prepare(context) {
+    const { warnings } = await expand();
+    for (const warning of warnings) context.warn(warning);
     const { entries, skipped } = await collectComponents({ root, packages, modules, tsconfig: options.tsconfig, exclude: options.exclude ?? defaultExclude });
+    // A component the package compares by element type (`child.type === Footer`) would stop
+    // matching once the app renders the wrapper: leave it as it is, and say where.
+    const compared = new Map();
+    for (const entry of entries) {
+      if (entry.kind !== "package" || !entry.components.length) continue;
+      const name = packageName(entry.specifier);
+      if (!compared.has(name)) {
+        const dir = packageDirectory(name, root);
+        compared.set(name, dir ? await typeComparedNames(dir) : new Map());
+      }
+      const names = compared.get(name);
+      entry.components = entry.components.filter((component) => {
+        const file = names.get(component.name) ?? names.get(component.export);
+        if (file) skipped.push({ from: entry.specifier, name: component.export, reason: `compared by element type in ${file}` });
+        return !file;
+      });
+    }
     let count = 0;
     for (const [index, entry] of entries.entries()) {
       if (!entry.components.length) continue;
@@ -67,8 +95,13 @@ export function paletteComponents(options = {}) {
   return {
     name,
     enforce: "pre",
-    config: () => ({ optimizeDeps: { include: [RUNTIME, ...packages] } }),
+    async config(config) {
+      root = resolve(config.root ?? process.cwd());
+      const { specifiers } = await expand();
+      return { optimizeDeps: { include: [RUNTIME, ...specifiers] } };
+    },
     configResolved(config) {
+      if (resolve(config.root) !== root) expanded = undefined;
       root = config.root;
     },
     buildStart() {

package/vite/packages.mjs

@@ -0,0 +1,77 @@
+// Package lookups for @hazem3500/palette/vite: subpath globs, and components a package compares
+// by element type. Node-only.
+import { existsSync } from "node:fs";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+
+/** "@scope/ds/button" → "@scope/ds"; "ds/x" → "ds". */
+export const packageName = (specifier) => specifier.split("/").slice(0, specifier.startsWith("@") ? 2 : 1).join("/");
+
+/** The directory of an installed package, looked up from the app root like Node does. */
+export function packageDirectory(name, root) {
+  for (let dir = root; ; dir = dirname(dir)) {
+    const candidate = join(dir, "node_modules", ...name.split("/"));
+    if (existsSync(join(candidate, "package.json"))) return candidate;
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+/**
+ * `@scope/ds/*` becomes every subpath the package's `exports` map lists (`@scope/ds/button`, …),
+ * with the root entry when there is one. Pattern exports (`./*`) can't be listed and are reported.
+ */
+export async function expandPackages(list, root) {
+  const specifiers = [], warnings = [];
+  for (const entry of list) {
+    if (!entry.endsWith("/*")) {
+      specifiers.push(entry);
+      continue;
+    }
+    const name = entry.slice(0, -2), dir = packageDirectory(name, root);
+    if (!dir) {
+      warnings.push(`${entry}: package not found`);
+      continue;
+    }
+    const exports = JSON.parse(await readFile(join(dir, "package.json"), "utf8")).exports;
+    const keys = exports && typeof exports === "object" && Object.keys(exports).some((key) => key.startsWith(".")) ? Object.keys(exports) : ["."];
+    for (const key of keys) {
+      if (key.includes("*")) warnings.push(`${entry}: "${key}" is a pattern export; list its subpaths explicitly`);
+      else if (key === "./package.json" || /\.(css|json)$/.test(key)) continue;
+      else specifiers.push(key === "." ? name : `${name}${key.slice(1)}`);
+    }
+  }
+  return { specifiers: [...new Set(specifiers)], warnings };
+}
+
+const SCRIPT = /\.(m|c)?js$/;
+const LIMIT = 4_000_000;
+// `x.type === Footer`, `Footer !== child.type`, `type === Footer` after destructuring.
+const TYPE_LEFT = /\.type\s*[!=]==?\s*([A-Za-z_$][\w$]*)/g;
+const TYPE_RIGHT = /([A-Za-z_$][\w$]*)\s*[!=]==?\s*[\w$\])?.]*\.type\b/g;
+
+/**
+ * Names a package compares against an element's type in its own runtime code, with the first file
+ * that does. Instrumenting such a component would make the comparison fail for the app's elements.
+ * Minified packages rename their locals, so this finds what the shipped code still spells out.
+ */
+export async function typeComparedNames(dir) {
+  const found = new Map();
+  let read = 0;
+  async function walk(path) {
+    for (const entry of await readdir(path, { withFileTypes: true })) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      const file = join(path, entry.name);
+      if (entry.isDirectory()) await walk(file);
+      else if (SCRIPT.test(entry.name) && !entry.name.endsWith(".map")) {
+        const size = (await stat(file)).size;
+        if ((read += size) > LIMIT) return;
+        const code = await readFile(file, "utf8");
+        for (const pattern of [TYPE_LEFT, TYPE_RIGHT])
+          for (const match of code.matchAll(pattern))
+            if (/^[A-Z]/.test(match[1]) && !found.has(match[1])) found.set(match[1], relative(dir, file).split(sep).join("/"));
+      }
+    }
+  }
+  await walk(dir);
+  return found;
+}