@md-code/react-component-uniqueness 0.1.0

package/snapshots/README.md

@@ -0,0 +1,69 @@
+# snapshots/ — dynamic component catalog (headless-browser pipeline)
+
+Static AST scanning cannot see styles/actions of **library wrappers**
+(`<MuiButton>`, `<AntButton>`, `styled.button`, tailwind classes inside a
+wrapper). This pipeline renders every component once in a headless browser
+and captures what the DOM actually shows:
+
+- rendered DOM tag (`MuiButton` → `button`, `Bn` → `button`, `MuiPaper` → `div`)
+- computed styles (normalized: padding/margin shorthand, defaults filtered)
+- click behavior (fiber `__reactProps$` walk — React delegates listeners to
+  the root, so `getEventListeners` is unusable)
+- a11y attributes (`type`, `role`, `aria-label`, `data-testid`, `tabindex`)
+
+## Usage
+
+```sh
+node <pkg>/snapshots/run.mjs --root <repoRoot> --manifest <repo>/playground/manifest.js
+```
+
+1. `build-playground.mjs` — esbuild bundle of the manifest → `dist/playground.html` + `dist/playground.js` (one page, every component rendered exactly once, `data-slot` per component, `data-snapshot-ready` flag after click-marker instrumentation).
+2. `snapshot.mjs` — puppeteer-core + chromium opens the page via **file:// (no HTTP server)**, waits for `data-snapshot-ready="1"`, captures per slot, writes `reports/component-catalog-dynamic.json`.
+
+Confined browsers (snap chromium) cannot read `/tmp` or hidden dirs — the page
+is copied to `~/rqu-snapshot-dist/` automatically (override with `SNAPSHOT_URL`
+by passing a `--url` that the browser can already read).
+
+## Manifest format
+
+CommonJS module exporting an array:
+
+```js
+module.exports = [
+  { id: "can-button", label: "Button (canonical)",
+    import: ["/abs/path/Button.tsx", "Button"],
+    jsxTag: "Button",        // the JSX tag the consumer writes (dynTagMap key)
+    props: { onClick: () => {}, children: "press" } },
+];
+```
+
+`jsxTag` matters for renamed imports: `import { Button as Bn }` →
+`jsxTag: "Bn"`. The rule resolves `Bn` → rendered `button` at lint time.
+
+## Rule side
+
+```js
+rules: { "md/component-uniqueness": ["error", { includeDynamic: true }] }
+```
+
+`includeDynamic` (default `false`) merges the dynamic catalog into the static
+one:
+
+- entries are deduped by `path` — a file already in the static catalog keeps
+  its static entry; dynamic only ADDS files the static pass could not fully see
+- the rule resolves capitalized JSX tags (import aliases) to real DOM tags via
+  the `comp` field
+- **only tag + styles are merged** (and styles only into thin candidates,
+  <3 style keys); actions/a11y are deliberately NOT merged — a plain
+  `<MuiButton>` without onClick must stay a plain import, not a "duplicate"
+- without the dynamic catalog file the flag is a no-op (static behavior)
+
+## Env
+
+| Var | Default |
+| --- | --- |
+| `SNAPSHOT_CHROME` | `/snap/bin/chromium` → `/usr/bin/chromium` → `google-chrome` |
+| `SNAPSHOT_PUPPETEER` | consumer `node_modules/puppeteer-core`, else known hoisted paths |
+| `ESBUILD_PATH` | consumer `node_modules/esbuild` |
+
+`puppeteer-core` is an **optional** dependency — the static rule works without it.

package/snapshots/build-playground.mjs

@@ -0,0 +1,132 @@
+import { createRequire } from "node:module";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/**
+ * build-playground.mjs
+ *
+ * Builds the one-and-only playground page from a manifest:
+ *   - every component is rendered exactly ONCE per run
+ *   - the page is static (dist/playground.html + playground.js) — it can be
+ *     snapshotted later by headless chromium with file://, no server needed
+ *
+ * Usage (from the consumer repo, e.g. /tmp/strict-test):
+ *   node <pkg>/snapshots/build-playground.mjs --root <repoRoot> --manifest <path/to/manifest.js>
+ *
+ * The manifest is a CommonJS module exporting an array of:
+ *   { id, label, import: [absModulePath, exportName], jsxTag?, props }
+ *
+ * Output: <root>/dist/playground.html + <root>/dist/playground.js
+ * (plus <root>/dist/tw.css if the manifest file lives next to an input.css —
+ * the consumer generates tw.css itself with @tailwindcss/cli when needed).
+ */
+
+const here = dirname(fileURLToPath(import.meta.url));
+const req = createRequire(join(here, "noop.js"));
+
+function arg(name, dflt) {
+	const i = process.argv.indexOf(`--${name}`);
+	return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : dflt;
+}
+const root = arg("root", process.cwd());
+const manifestPath = arg("manifest", join(root, "playground/manifest.js"));
+
+// esbuild: consumer's node_modules first, then this package's, then env override.
+const importFile = (p) => import(pathToFileURL(p).href);
+let esbuild;
+try {
+	esbuild = await importFile(req.resolve("esbuild"));
+} catch {
+	try {
+		esbuild = await importFile(req.resolve(join(here, "..", "node_modules/esbuild/lib/main.js")));
+	} catch {
+		if (!process.env.ESBUILD_PATH) throw new Error("esbuild not found: install it or set ESBUILD_PATH");
+		const ep = process.env.ESBUILD_PATH;
+		esbuild = ep.startsWith("file:") || ep.startsWith("node:") ? await import(ep) : await importFile(ep);
+	}
+}
+
+const manifestUrl = manifestPath.startsWith("file:") ? manifestPath : pathToFileURL(manifestPath).href;
+const manifest = (await import(manifestUrl)).default;
+if (!Array.isArray(manifest) || !manifest.length) throw new Error(`manifest at ${manifestPath} must export a non-empty array`);
+
+const dist = join(root, "dist");
+mkdirSync(dist, { recursive: true });
+
+function serProps(p) {
+	const parts = [];
+	for (const [k, v] of Object.entries(p || {})) {
+		if (typeof v === "function") parts.push(`${k}: () => {}`);
+		else parts.push(`${k}: ${JSON.stringify(v)}`);
+	}
+	return `{ ${parts.join(", ")} }`;
+}
+
+const imports = manifest.map((m, i) => `import { ${m.import[1]} as Comp${i} } from ${JSON.stringify(m.import[0])};`);
+const slots = manifest.map((m, i) => `  { id: ${JSON.stringify(m.id)}, name: ${JSON.stringify(m.import[1])}, jsxTag: ${JSON.stringify(m.jsxTag || m.import[1])}, comp: Comp${i}, props: ${serProps(m.props)} },`).join("\n");
+
+const entry = `import * as React from "react";
+import { createRoot } from "react-dom/client";
+${imports.join("\n")}
+const SLOTS = [
+${slots}
+];
+function App() {
+  return React.createElement("div", { style: { fontFamily: "sans-serif", padding: 16 } },
+    SLOTS.map((s) =>
+      React.createElement("div", { key: s.id, "data-slot": s.id, "data-comp": s.name, "data-jsxtag": s.jsxTag, style: { margin: 12, padding: 8, border: "1px solid #ccc", borderRadius: 6 } },
+        [React.createElement("div", { style: { fontSize: 11, color: "#888", marginBottom: 6 } }, s.name + "  [" + s.id + "]"),
+         React.createElement(s.comp, s.props)]
+      )
+    )
+  );
+}
+const root = document.getElementById("root");
+createRoot(root).render(React.createElement(App));
+// Click-marker instrumentation: React delegates listeners to its root
+// container, so per-element getEventListeners is unavailable from page
+// context. Read the onClick prop from the fiber props map (React 18: key
+// starts with "__reactProps$") and mark the element with data-clickevent.
+window.addEventListener("load", () => {
+  setTimeout(() => {
+    const app = document.querySelector("[data-slot]");
+    if (!app) return;
+    let key = null;
+    for (const k of Object.keys(app)) if (k.startsWith("__reactProps$")) { key = k; break; }
+    if (!key) return;
+    const marked = new WeakSet();
+    const mark = (el) => {
+      if (marked.has(el)) return;
+      marked.add(el);
+      const p = el[key];
+      if (p && typeof p.onClick === "function") el.setAttribute("data-clickevent", "1");
+      for (let c = el.firstElementChild; c; c = c.nextElementSibling) mark(c);
+    };
+    mark(root.firstElementChild);
+    document.body.setAttribute("data-snapshot-ready", "1");
+  }, 400);
+});
+`;
+
+const entryPath = join(root, "playground/entry.generated.tsx");
+writeFileSync(entryPath, entry);
+
+const html = `<!doctype html>
+<html><head><meta charset="utf-8"><link rel="stylesheet" href="tw.css"></head>
+<body><div id="root"></div><script src="playground.js"></script>
+<script>document.body.setAttribute("data-snapshot-ready","0");</script>
+</body></html>`;
+writeFileSync(join(dist, "playground.html"), html);
+
+await esbuild.build({
+	entryPoints: [entryPath],
+	bundle: true,
+	format: "iife",
+	outfile: join(dist, "playground.js"),
+	jsx: "automatic",
+	define: { "process.env.NODE_ENV": '"production"' },
+	logLevel: "warning",
+	platform: "browser",
+});
+console.log(`PLAYGROUND BUNDLE OK -> ${join(dist, "playground.js")} (${manifest.length} slots)`);

package/snapshots/run.mjs

@@ -0,0 +1,43 @@
+import { execFileSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+
+/**
+ * run.mjs — one command for the whole dynamic-catalog pipeline.
+ *
+ *   node <pkg>/snapshots/run.mjs --root <repoRoot> [--manifest <path>] [--url <file://...>]
+ *
+ * Steps:
+ *   1. build-playground.mjs — bundle the manifest into dist/playground.html + playground.js
+ *   2. snapshot.mjs         — headless chromium (file://, no server) renders the page,
+ *                             captures computed styles + click markers per slot and
+ *                             writes reports/component-catalog-dynamic.json
+ *
+ * The consumer is responsible for dist/tw.css (e.g. @tailwindcss/cli) — the
+ * generated page links it, but the snapshot works without it (components
+ * that rely on tailwind classes will just capture fewer styles).
+ */
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+function arg(name, dflt) {
+	const i = process.argv.indexOf(`--${name}`);
+	return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : dflt;
+}
+const root = arg("root", process.cwd());
+const manifest = arg("manifest", join(root, "playground/manifest.js"));
+const url = arg("url", pathToFileURL(join(root, "dist", "playground.html")).href);
+
+const node = process.execPath;
+const env = { ...process.env };
+
+console.log(`[run] 1/2 build playground (root=${root})`);
+execFileSync(node, [join(here, "build-playground.mjs"), "--root", root, "--manifest", manifest], { stdio: "inherit", env });
+
+console.log(`[run] 2/2 snapshot (url=${url})`);
+execFileSync(node, [join(here, "snapshot.mjs"), "--root", root, "--url", url, "--manifest", manifest], { stdio: "inherit", env });
+
+const out = join(root, "reports/component-catalog-dynamic.json");
+if (!existsSync(out)) throw new Error(`expected output not found: ${out}`);
+console.log(`[run] DONE -> ${out}`);

package/snapshots/snapshot.mjs

@@ -0,0 +1,204 @@
+import { createRequire } from "node:module";
+import { writeFileSync, mkdirSync, cpSync, existsSync } from "node:fs";
+import { join, dirname, resolve, relative, basename } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/**
+ * snapshot.mjs
+ *
+ * Headless-chromium snapshot of the built playground page ->
+ * reports/component-catalog-dynamic.json
+ *
+ * No HTTP server: the page is opened via file://. Confined browsers (e.g. the
+ * snap chromium) cannot read /tmp, so if --url points under /tmp the page is
+ * copied to a home-dir temp location first.
+ *
+ * The page must contain a <div id="root"> with [data-slot] children (see
+ * build-playground.mjs) and must set data-snapshot-ready="1" on <body> once
+ * React has rendered (the generated entry does this after click-marker
+ * instrumentation).
+ *
+ * Usage:
+ *   node <pkg>/snapshots/snapshot.mjs --root <repoRoot> --url file:///abs/dist/playground.html \
+ *        --manifest <path/to/manifest.js> [--out reports/component-catalog-dynamic.json]
+ *
+ * Env: SNAPSHOT_CHROME (default: /snap/bin/chromium, then /usr/bin/chromium,
+ *      then /usr/bin/google-chrome), SNAPSHOT_PUPPETEER (path to puppeteer-core).
+ *
+ * Manifest entries may carry `jsxTag` — the JSX tag the consumer actually
+ * writes (e.g. "Bn" for `import { Button as Bn }`). The dynamic catalog keys
+ * on it (field `comp`), so the rule can resolve the tag at lint time.
+ */
+
+const here = dirname(fileURLToPath(import.meta.url));
+const req = createRequire(join(here, "noop.js"));
+
+function arg(name, dflt) {
+	const i = process.argv.indexOf(`--${name}`);
+	return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : dflt;
+}
+const root = arg("root", process.cwd());
+const url = arg("url", null);
+const manifestPath = arg("manifest", join(root, "playground/manifest.js"));
+const outRel = arg("out", "reports/component-catalog-dynamic.json");
+if (!url) throw new Error("--url is required (file:// URL of the built playground.html)");
+
+// puppeteer-core: consumer first, then env override, then known hoisted locations.
+const importFile = (p) => import(pathToFileURL(p).href);
+let puppeteer;
+try {
+	puppeteer = await importFile(req.resolve("puppeteer-core"));
+} catch {
+	const candidates = [
+		process.env.SNAPSHOT_PUPPETEER,
+		"/home/llm/Documents/Work/fun/Jabberwock/node_modules/.pnpm/puppeteer-core@24.10.2/node_modules/puppeteer-core/lib/cjs/puppeteer/puppeteer-core.js",
+	].filter(Boolean);
+	let lastErr;
+	for (const c of candidates) {
+		try {
+			puppeteer = await importFile(resolve(c));
+			break;
+		} catch (e) {
+			lastErr = e;
+		}
+	}
+	if (!puppeteer) throw new Error(`puppeteer-core not found (tried: ${candidates.join(", ")}): ${lastErr?.message}`);
+}
+
+const chrome =
+	process.env.SNAPSHOT_CHROME ||
+	[
+		"/snap/bin/chromium",
+		"/usr/bin/chromium",
+		"/usr/bin/chromium-browser",
+		"/usr/bin/google-chrome",
+		"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+		"C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+	].find((p) => existsSync(p));
+if (!chrome) throw new Error("No chromium found. Set SNAPSHOT_CHROME.");
+
+const manifestUrl = manifestPath.startsWith("file:") ? manifestPath : pathToFileURL(manifestPath).href;
+const manifest = (await import(manifestUrl)).default;
+
+// Confinement: snap chromium cannot read /tmp. Copy the page to a home-dir temp.
+let pageUrl = url;
+const urlPath = decodeURIComponent(new URL(url).pathname);
+if (urlPath.startsWith("/tmp/")) {
+	// NOTE: snap chromium also refuses HIDDEN dirs — keep the name unhidden.
+	const dest = join(process.env.HOME, "rqu-snapshot-dist");
+	mkdirSync(dest, { recursive: true });
+	cpSync(dirname(urlPath), dest, { recursive: true });
+	// cpSync(distDir, existingDestDir) copies dist contents flat into dest
+	pageUrl = `file://${dest}/${basename(urlPath)}`;
+	console.log(`[snapshot] confined browser: page at ${pageUrl}`);
+}
+
+const browser = await puppeteer.default.launch({
+	headless: "new",
+	executablePath: chrome,
+	args: ["--no-sandbox", "--disable-gpu", "--window-size=1440,900"],
+});
+try {
+	const page = await browser.newPage();
+	await page.setViewport({ width: 1440, height: 900 });
+	const errors = [];
+	page.on("pageerror", (e) => errors.push(`pageerror: ${e.message}`));
+	page.on("console", (m) => m.type() === "error" && errors.push(`console: ${m.text()}`));
+	await page.goto(pageUrl, { waitUntil: "load", timeout: 30000 });
+	await page.waitForFunction("document.body.getAttribute('data-snapshot-ready') === '1'", { timeout: 20000 });
+
+	const raw = await page.evaluate(() => {
+		const props = [
+			"display", "flex-direction", "align-items", "justify-content", "gap",
+			"padding", "padding-top", "padding-right", "padding-bottom", "padding-left",
+			"margin", "margin-top", "margin-right", "margin-bottom", "margin-left",
+			"border", "border-radius", "box-shadow", "background-color", "color",
+			"font-size", "font-weight", "text-align", "text-transform", "letter-spacing",
+			"line-height", "width", "max-width", "height", "list-style",
+		];
+		const slots = [...document.querySelectorAll("[data-slot][data-comp]")];
+		return slots.map((slot) => {
+			const el = slot.children[1] || slot.firstElementChild;
+			if (!el) return null;
+			const cs = getComputedStyle(el);
+			const styles = {};
+			for (const p of props) {
+				const v = cs.getPropertyValue(p);
+				if (v && v !== "none" && v !== "normal" && v !== "auto" && v !== "0px" && v !== "transparent") styles[p] = v;
+			}
+			const attrs = {};
+			for (const a of ["type", "role", "aria-label", "data-testid", "tabindex"]) {
+				const v = el.getAttribute(a);
+				if (v != null) attrs[a] = v;
+			}
+			const hasClick = !!el.closest("[data-clickevent]");
+			return {
+				id: slot.getAttribute("data-slot"),
+				comp: slot.getAttribute("data-comp"),
+				jsxTag: slot.getAttribute("data-jsxtag"),
+				tag: el.tagName.toLowerCase(),
+				styles,
+				attrs,
+				hasClick,
+			};
+		});
+	});
+
+	if (errors.length) console.error(`[snapshot] PAGE ERRORS:\n${errors.join("\n")}`);
+
+	// --- noise filter: computed-style defaults that carry no design signal ---
+	const NOISE = {
+		"flex-direction": (v) => v === "row",
+		"border": (v) => v.startsWith("0px solid") && /rgb\(0, 0, 0\)|transparent/.test(v),
+		"list-style": () => true, // default "outside none disc"
+		"width": () => true, // px layout noise
+		"height": () => true,
+		"max-width": (v) => v === "100%",
+		"display": (v) => v === "block", // default for div
+	};
+	const normalize = (s) => {
+		const out = {};
+		for (const [k, v] of Object.entries(s)) {
+			if (NOISE[k] && NOISE[k](v)) continue;
+			if (k === "padding" || k === "margin") {
+				const [t, r, b, l] = v.split(" ");
+				if (t === r && r === b && b === l) { out[k] = t; continue; }
+				if (l !== r) out[`margin` === k ? "margin-left" : "padding-left"] = l;
+				if (r !== l) out[`margin` === k ? "margin-right" : "padding-right"] = r;
+				if (t !== b) out[`margin` === k ? "margin-top" : "padding-top"] = t;
+				if (b !== t) out[`margin` === k ? "margin-bottom" : "padding-bottom"] = b;
+				continue;
+			}
+			out[k] = v;
+		}
+		return out;
+	};
+
+	const byId = new Map(raw.filter(Boolean).map((r) => [r.id, r]));
+	const components = manifest.map((m) => {
+		const r = byId.get(m.id);
+		if (!r) throw new Error(`snapshot missing slot ${m.id}`);
+		const styles = normalize(r.styles);
+		// a11y must be an ARRAY of "key:value" tokens to match the static
+		// catalog format (signature.js runs `new Set(entry.a11y)`).
+		const a11y = Object.entries(r.attrs).map(([k, v]) => `${k}:${v}`);
+		return {
+			name: m.label,
+			path: m.fileRel || relative(root, m.import[0]),
+			comp: m.jsxTag || r.jsxTag, // JSX tag the consumer writes (dynTagMap key)
+			origTag: r.comp, // export name (context)
+			tag: r.tag, // rendered DOM tag
+			styles,
+			actions: r.hasClick ? ["click"] : [],
+			a11y,
+			data: {},
+		};
+	});
+
+	const outPath = join(root, outRel);
+	mkdirSync(dirname(outPath), { recursive: true });
+	writeFileSync(outPath, JSON.stringify({ generatedAt: new Date().toISOString(), components }, null, 2));
+	console.log(`[snapshot] wrote ${outPath} (${components.length} components)`);
+} finally {
+	await browser.close();
+}

package/thresholds.js

@@ -0,0 +1,35 @@
+"use strict";
+
+const DEFAULTS = {
+	minShared: 2,
+	minRatioSameTag: 0.4,
+	minRatioAnyTag: 0.5,
+	exactRatio: 0.8,
+	familyMatchMin: 0.35,
+};
+
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+
+function resolveThresholds(opts) {
+	const o = opts && typeof opts === "object" ? opts : {};
+	const t = (o.thresholds && typeof o.thresholds === "object") ? o.thresholds : {};
+	const num = (key) => (typeof t[key] === "number" && Number.isFinite(t[key]) ? t[key] : DEFAULTS[key]);
+
+	return {
+		minShared: Math.max(1, Math.floor(num("minShared"))),
+		minRatioSameTag: clamp01(num("minRatioSameTag")),
+		minRatioAnyTag: clamp01(num("minRatioAnyTag")),
+		exactRatio: clamp01(num("exactRatio")),
+		familyMatchMin: clamp01(num("familyMatchMin")),
+	};
+}
+
+const CANON_DUP_STRICT = {
+	minShared: 3,
+	minRatioSameTag: 0.6,
+	minRatioAnyTag: 0.7,
+	exactRatio: 0.8,
+	familyMatchMin: 0.35,
+};
+
+module.exports = { resolveThresholds, DEFAULT_THRESHOLDS: DEFAULTS, CANON_DUP_STRICT };