@md-code/react-component-uniqueness 0.1.0

package/resolve.js

@@ -0,0 +1,374 @@
+"use strict";
+
+/**
+ * resolve.js
+ *
+ * String-literal resolution machinery shared by the rule (ESTree AST) and the
+ * catalog scanner (TypeScript AST).
+ *
+ *   - ESTree (rule): stringLiteralsOf, resolveExportedFromFile,
+ *     resolveStringCandidates — resolve className/style expressions to
+ *     candidate string literals, following local constants, cn()/clsx()
+ *     calls, ternaries, and imported helpers (read from disk).
+ *   - TS AST (scanner): tsStringLiteralsOf — the same job over a TypeScript
+ *     AST node (used by the catalog generator).
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const ts = require("typescript");
+
+/**
+ * Collect string literals from an ESTree expression (shallow, capped).
+ */
+function stringLiteralsOf(expr, out, depth) {
+	if (!expr || depth > 4 || out.length >= 24) return;
+	switch (expr.type) {
+		case "Literal":
+			if (typeof expr.value === "string") out.push(expr.value);
+			break;
+		case "TemplateLiteral":
+			for (const q of expr.quasis) {
+				if (q.value && q.value.cooked) out.push(q.value.cooked);
+			}
+			break;
+		case "ObjectExpression":
+			for (const p of expr.properties) {
+				if (p.type === "Property") stringLiteralsOf(p.value, out, depth + 1);
+			}
+			break;
+		case "ArrayExpression":
+			for (const el of expr.elements) {
+				if (el) stringLiteralsOf(el, out, depth + 1);
+			}
+			break;
+		case "CallExpression":
+			for (const arg of expr.arguments) stringLiteralsOf(arg, out, depth + 1);
+			break;
+		case "ConditionalExpression":
+			stringLiteralsOf(expr.consequent, out, depth + 1);
+			stringLiteralsOf(expr.alternate, out, depth + 1);
+			break;
+		case "LogicalExpression":
+			stringLiteralsOf(expr.left, out, depth + 1);
+			stringLiteralsOf(expr.right, out, depth + 1);
+			break;
+		case "BinaryExpression":
+			if (expr.operator === "+") {
+				stringLiteralsOf(expr.left, out, depth + 1);
+				stringLiteralsOf(expr.right, out, depth + 1);
+			}
+			break;
+		default:
+			break;
+	}
+}
+
+/** Collect string literals from a TypeScript AST node (shallow, capped). */
+function tsStringLiteralsOf(node, out, depth, root) {
+	if (!node || depth > 4 || out.length >= 24) return;
+	if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+		out.push(node.text);
+		return;
+	}
+	if (ts.isTemplateExpression(node)) {
+		for (const s of node.head && node.head.text ? [node.head.text] : []) out.push(s);
+		for (const span of node.templateSpans) {
+			if (span.literal && span.literal.text) out.push(span.literal.text);
+			tsStringLiteralsOf(span.expression, out, depth + 1, root);
+		}
+		return;
+	}
+	if (ts.isObjectLiteralExpression(node)) {
+		for (const p of node.properties) tsStringLiteralsOf(p.initializer, out, depth + 1, root);
+		return;
+	}
+	if (ts.isArrayLiteralExpression(node)) {
+		for (const el of node.elements) tsStringLiteralsOf(el, out, depth + 1, root);
+		return;
+	}
+	if (ts.isCallExpression(node)) {
+		for (const arg of node.arguments) tsStringLiteralsOf(arg, out, depth + 1, root);
+		return;
+	}
+	if (ts.isConditionalExpression(node)) {
+		tsStringLiteralsOf(node.whenTrue, out, depth + 1, root);
+		tsStringLiteralsOf(node.whenFalse, out, depth + 1, root);
+		return;
+	}
+	if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.Plus) {
+		tsStringLiteralsOf(node.left, out, depth + 1, root);
+		tsStringLiteralsOf(node.right, out, depth + 1, root);
+		return;
+	}
+	if (ts.isBlock(node)) {
+		ts.forEachChild(node, (n) => tsStringLiteralsOf(n, out, depth + 1, root));
+		return;
+	}
+	if (ts.isReturnStatement(node) && node.expression) {
+		tsStringLiteralsOf(node.expression, out, depth + 1, root);
+		return;
+	}
+	if (ts.isIdentifier(node) && root) {
+		// A bare identifier in the initializer (e.g. const cls = baseCls) —
+		// resolve it within the same file.
+		const findDecl = (n) => {
+			if (out.length >= 24) return;
+			if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.name.text === node.text && n.initializer) {
+				tsStringLiteralsOf(n.initializer, out, depth + 1, root);
+				return;
+			}
+			ts.forEachChild(n, findDecl);
+		};
+		findDecl(root);
+	}
+}
+
+// Cache of imported-value lookups: absPath -> { name: result }.
+const importedCache = new Map();
+
+/**
+ * Read a sibling file from disk and resolve one of its exported constants to
+ * string literals. Handles: const X = "...", template literals, cn()/clsx()
+ * calls, object literals, ternaries, and re-exports (export { Y as X }).
+ * Cached per file. Returns null when the file cannot be read or the export is
+ * not a static string.
+ */
+function resolveExportedFromFile(fileAbs, exportName) {
+	let byFile = importedCache.get(fileAbs);
+	if (!byFile) {
+		byFile = {};
+		importedCache.set(fileAbs, byFile);
+	}
+	if (Object.prototype.hasOwnProperty.call(byFile, exportName)) return byFile[exportName];
+	let result = null;
+	try {
+		const source = fs.readFileSync(fileAbs, "utf8");
+		const sf = ts.createSourceFile(fileAbs, source, ts.ScriptTarget.ES2020, true, fileAbs.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+		const visit = (node) => {
+			if (result) return;
+			// export function NAME(...) { ... }
+			if (ts.isFunctionDeclaration(node) && node.name && node.name.text === exportName && ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export) {
+				const out = [];
+				if (node.body) tsStringLiteralsOf(node.body, out, 0, sf);
+				result = out.length > 0 ? out : null;
+				return;
+			}
+			// export const NAME = ... / export let / export var
+			if (ts.isVariableStatement(node) && ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export) {
+				for (const d of node.declarationList.declarations) {
+					if (ts.isIdentifier(d.name) && d.name.text === exportName && d.initializer) {
+						const out = [];
+						tsStringLiteralsOf(d.initializer, out, 0, sf);
+						// Arrow/function initializer: also collect the body
+						// (const rowCls = (w) => w ? "a" : "b").
+						if (out.length === 0 && (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))) {
+							if (d.initializer.body) tsStringLiteralsOf(d.initializer.body, out, 0, sf);
+						}
+						result = out.length > 0 ? out : null;
+						return;
+					}
+				}
+			}
+			// export { Y as NAME } / export { Y as NAME } from "./other"
+			if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) {
+				for (const el of node.exportClause.elements) {
+					const exported = el.name && el.name.text;
+					if (exported === exportName) {
+						if (node.moduleSpecifier) {
+							// Re-export from another file — resolve there.
+							const localName = el.propertyName ? el.propertyName.text : exportName;
+							const target = path.resolve(path.dirname(fileAbs), node.moduleSpecifier.text);
+							const exts = ["", ".ts", ".tsx", ".js", ".jsx", "/index.ts", "/index.tsx", "/index.js"];
+							for (const ext of exts) {
+								const candidate = target + ext;
+								try {
+									if (fs.statSync(candidate).isFile()) {
+										result = resolveExportedFromFile(candidate, localName);
+										return;
+									}
+								} catch {
+									// try next extension
+								}
+							}
+						} else {
+							// Local re-export: find the local declaration.
+							const localName = el.propertyName ? el.propertyName.text : exportName;
+							const findLocal = (n) => {
+								if (result) return;
+								if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.name.text === localName && n.initializer) {
+									const out = [];
+									tsStringLiteralsOf(n.initializer, out, 0, sf);
+									result = out.length > 0 ? out : null;
+								}
+								ts.forEachChild(n, findLocal);
+							};
+							findLocal(sf);
+							return;
+						}
+					}
+				}
+			}
+			ts.forEachChild(node, visit);
+		};
+		visit(sf);
+	} catch {
+		result = null;
+	}
+	byFile[exportName] = result;
+	return result;
+}
+
+/**
+ * Resolve an expression to candidate string values (dynamic values: local
+ * variables, ternaries, cn()/clsx() calls, template literals, imported
+ * constants). Returns null when the expression is not a statically known
+ * string.
+ */
+function resolveStringCandidates(expr, scope, depth, fileDir) {
+	if (!expr || depth > 3) return null;
+	switch (expr.type) {
+		case "Literal":
+			// Strings and numbers: inline style values are often numeric
+			// (padding: 16, borderRadius: 8). The catalog scanner
+			// (scanner/extract.js) records numeric literals the same way, so
+			// the runtime candidate must too — otherwise a numeric-styled
+			// element loses those style keys and falls below the shared-key
+			// threshold.
+			return typeof expr.value === "string" || typeof expr.value === "number" ? [String(expr.value)] : null;
+		case "TemplateLiteral": {
+			if (expr.expressions.length === 0) {
+				const cooked = expr.quasis.map((q) => q.value.cooked).join("");
+				return [cooked];
+			}
+			const out = [];
+			for (const q of expr.quasis) {
+				if (q.value.cooked) out.push(q.value.cooked);
+			}
+			for (const e of expr.expressions) {
+				const c = resolveStringCandidates(e, scope, depth + 1, fileDir);
+				if (c) out.push(...c);
+			}
+			return out.length ? out : null;
+		}
+		case "ConditionalExpression": {
+			const a = resolveStringCandidates(expr.consequent, scope, depth + 1, fileDir);
+			const b = resolveStringCandidates(expr.alternate, scope, depth + 1, fileDir);
+			const out = [];
+			if (a) out.push(...a);
+			if (b) out.push(...b);
+			return out.length ? out : null;
+		}
+		case "LogicalExpression": {
+			const a = resolveStringCandidates(expr.left, scope, depth + 1, fileDir);
+			const b = resolveStringCandidates(expr.right, scope, depth + 1, fileDir);
+			const out = [];
+			if (a) out.push(...a);
+			if (b) out.push(...b);
+			return out.length ? out : null;
+		}
+		case "BinaryExpression": {
+			if (expr.operator !== "+") return null;
+			const a = resolveStringCandidates(expr.left, scope, depth + 1, fileDir);
+			const b = resolveStringCandidates(expr.right, scope, depth + 1, fileDir);
+			if (a && b) return [...a, ...b];
+			return a || b;
+		}
+		case "CallExpression": {
+			const callee = expr.callee;
+			const isJoiner =
+				(callee.type === "Identifier" && /^(cn|clsx|cx|classNames|classnames|joinClasses|mergeClasses)$/.test(callee.name)) ||
+				(callee.type === "MemberExpression" && callee.object && callee.object.name === "classNames");
+			if (isJoiner) {
+				const out = [];
+				for (const arg of expr.arguments) {
+					const c = resolveStringCandidates(arg, scope, depth + 1, fileDir);
+					if (c) out.push(...c);
+				}
+				return out.length ? out : null;
+			}
+			// Call of an imported function (e.g. rowCls(wide)) — resolve the
+			// exported function body in the sibling file.
+			if (callee.type === "Identifier" && fileDir) {
+				let imp = null;
+				for (let s = scope; s; s = s.upper) {
+					imp = (s.variables || []).find((v) => v.name === callee.name && v.defs && v.defs.some((d) => d.type === "ImportBinding"));
+					if (imp) break;
+				}
+				if (imp) {
+					const binding = (imp.defs.find((d) => d.type === "ImportBinding") || imp.defs[0] || {}).node;
+					const source = binding.parent && binding.parent.source && binding.parent.source.value;
+					if (source && source.startsWith(".")) {
+						const target = path.resolve(fileDir, source);
+						const exts = ["", ".ts", ".tsx", ".js", ".jsx", "/index.ts", "/index.tsx", "/index.js"];
+						for (const ext of exts) {
+							const candidate = target + ext;
+							try {
+								if (fs.statSync(candidate).isFile()) {
+									const c = resolveExportedFromFile(candidate, imp.name);
+									if (c) return c;
+									break;
+								}
+							} catch {
+								// try next extension
+							}
+						}
+					}
+				}
+			}
+			return null;
+		}
+		case "Identifier": {
+			// Local declaration in an enclosing scope (const cls = ...).
+			for (let s = scope; s; s = s.upper) {
+				const v = s.variables.find((x) => x.name === expr.name);
+				if (!v) continue;
+				for (const def of v.defs || []) {
+					const node = def && def.node;
+					if (node && node.type === "VariableDeclarator" && node.init) {
+						const c = resolveStringCandidates(node.init, scope, depth + 1, fileDir);
+						if (c) return c;
+					}
+				}
+			}
+			// Imported from a sibling file — read the file, find the exported
+			// constant, collect its string literals. The import binding lives
+			// in the module scope, so walk up.
+			let imp = null;
+			for (let s = scope; s; s = s.upper) {
+				imp = (s.variables || []).find((v) => v.name === expr.name && v.defs && v.defs.some((d) => d.type === "ImportBinding"));
+				if (imp) break;
+			}
+			if (imp && fileDir) {
+				const binding = (imp.defs.find((d) => d.type === "ImportBinding") || imp.defs[0] || {}).node;
+				const source = binding.parent && binding.parent.source && binding.parent.source.value;
+				if (source && source.startsWith(".")) {
+					const target = path.resolve(fileDir, source);
+					const exts = ["", ".ts", ".tsx", ".js", ".jsx", "/index.ts", "/index.tsx", "/index.js"];
+					for (const ext of exts) {
+						const candidate = target + ext;
+						try {
+							if (fs.statSync(candidate).isFile()) {
+								const c = resolveExportedFromFile(candidate, imp.name);
+								if (c) return c;
+								break;
+							}
+						} catch {
+							// try next extension
+						}
+					}
+				}
+			}
+			return null;
+		}
+		default:
+			return null;
+	}
+}
+
+module.exports = {
+	stringLiteralsOf,
+	tsStringLiteralsOf,
+	resolveExportedFromFile,
+	resolveStringCandidates,
+};

package/scanner/attribute.js

@@ -0,0 +1,79 @@
+"use strict";
+
+/**
+ * scanner/attribute.js
+ *
+ * Component attribution: map a source file to the canonical component it
+ * belongs to.
+ *
+ * The component is the nearest PascalCase directory at or above the file's
+ * directory (e.g. packages/components/default/forms/Button/index.tsx ->
+ * Button). When the component registry is available, the registry's public
+ * name for that directory wins (the registry is the source of truth for
+ * public names).
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+/** Build the dir -> public component name map from the registry (if present). */
+function buildDirNameMap(repoRoot, registryPath) {
+	const map = new Map();
+	const regPath = registryPath || path.join(repoRoot, "reports", "component-registry.json");
+	if (!fs.existsSync(regPath)) return map;
+	try {
+		const reg = JSON.parse(fs.readFileSync(regPath, "utf8"));
+		for (const [name, dirs] of Object.entries((reg && reg.names) || {})) {
+			for (const d of dirs) {
+				if (!map.has(d)) map.set(d, name);
+			}
+		}
+	} catch {
+		// registry unreadable — fall back to directory basenames
+	}
+	return map;
+}
+
+/**
+ * Attribute a file to a component name.
+ *
+ * @param {string} fileAbs absolute path to the source file
+ * @param {string} repoRoot absolute repo root
+ * @param {Map<string,string>} dirNameMap registry dir -> public name
+ * @returns {string} component name
+ */
+function componentNameFor(fileAbs, repoRoot, dirNameMap) {
+	let dir = path.dirname(fileAbs);
+	// Fallback: the file's own basename (e.g. useCampaignRun.tsx -> useCampaignRun).
+	// The old fallback was the directory basename, which produced garbage names
+	// like "hooks" or "components" for files sitting in generic folders.
+	let name = path.basename(fileAbs).replace(/\.[^.]+$/, "");
+	// index.tsx / styles.tsx inside a PascalCase dir belong to that dir's component
+	// (e.g. Pagination/index.tsx -> Pagination, Button/styles.ts -> Button).
+	const isFileScoped = /^(index|styles|types|constants|utils|hooks|test|stories)$/i.test(name);
+	// The file's OWN dir is the most likely component dir (Pagination/index.tsx).
+	let up = dir;
+	if (/^[A-Z][A-Za-z0-9]*$/.test(path.basename(dir)) && isFileScoped) {
+		name = path.basename(dir);
+	} else {
+		for (let i = 0; i < 4; i += 1) {
+			const parent = path.dirname(up);
+			if (parent === up) break;
+			const bn = path.basename(parent);
+			if (/^[A-Z][A-Za-z0-9]*$/.test(bn)) {
+				up = parent;
+				if (isFileScoped) name = bn; // index/styles/etc. -> dir component name
+				break;
+			}
+			up = parent;
+		}
+	}
+	// Prefer the registry's public name for this directory.
+	const relDir = path.relative(repoRoot, dir).split(path.sep).join("/");
+	const relUp = path.relative(repoRoot, up).split(path.sep).join("/");
+	const regName = dirNameMap.get(relDir) || dirNameMap.get(relUp);
+	if (regName) name = regName;
+	return name;
+}
+
+module.exports = { buildDirNameMap, componentNameFor };

package/scanner/clusters.js

@@ -0,0 +1,96 @@
+"use strict";
+
+const { computeGenericTokens, distinctiveTokens } = require("./matching");
+const { resolveThresholds } = require("../thresholds");
+
+const JACCARD_MIN = 0.3;
+const FAMILY_MATCH_MIN = resolveThresholds({}).familyMatchMin;
+const MIN_FAMILY_TOKENS = 3;
+
+const componentTokenSet = (c, generic) => {
+	const s = new Set();
+	for (const e of c.elementProps || []) for (const t of e.tokens || []) s.add(t);
+	return distinctiveTokens([...s], generic);
+};
+
+const jaccard = (a, b) => {
+	if (a.size === 0 || b.size === 0) return 0;
+	let inter = 0;
+	for (const t of a) if (b.has(t)) inter += 1;
+	const union = a.size + b.size - inter;
+	return union === 0 ? 0 : inter / union;
+};
+
+function clusterComponents(canonComponents) {
+	const generic = computeGenericTokens(canonComponents);
+	const sets = canonComponents.map((c) => componentTokenSet(c, generic));
+	const clusters = [];
+	for (let i = 0; i < canonComponents.length; i += 1) {
+		const s = sets[i];
+		if (s.size < MIN_FAMILY_TOKENS) continue;
+		let best = null;
+		for (const cl of clusters) {
+			const j = jaccard(s, cl.tokenSet);
+			if (j >= JACCARD_MIN && (!best || j > best.j)) best = { cl, j };
+		}
+		if (best) best.cl.members.push(i);
+		else clusters.push({ members: [i], tokenSet: new Set(s) });
+	}
+	const families = [];
+	for (const cl of clusters) {
+		if (cl.members.length < 2) continue;
+		const count = new Map();
+		for (const i of cl.members) for (const t of sets[i]) count.set(t, (count.get(t) || 0) + 1);
+		const half = cl.members.length / 2;
+		const tokenSet = new Set();
+		for (const [t, n] of count) if (n >= half) tokenSet.add(t);
+		if (tokenSet.size < MIN_FAMILY_TOKENS) continue;
+		families.push({ members: cl.members, tokenSet, sets });
+	}
+	return { families, sets, generic };
+}
+
+function nearestMember(family, appTokens) {
+	let best = null;
+	for (const i of family.members) {
+		const j = jaccard(appTokens, family.sets[i]);
+		if (!best || j > best.j) best = { idx: i, j };
+	}
+	return best;
+}
+
+function matchFamilies(appComponents, canonComponents, cluster, opts) {
+	const { families, sets, generic } = cluster;
+	const th = resolveThresholds(opts);
+	const matches = [];
+	const seen = new Set();
+	for (const app of appComponents) {
+		const appTokens = componentTokenSet(app, generic);
+		if (appTokens.size < MIN_FAMILY_TOKENS) continue;
+		let best = null;
+		for (const family of families) {
+			const j = jaccard(appTokens, family.tokenSet);
+			if (j < th.familyMatchMin) continue;
+			const near = nearestMember(family, appTokens);
+			if (!near || near.j < th.familyMatchMin) continue;
+			const member = canonComponents[near.idx];
+			if ((app.usesCanonical || []).includes(member.name)) continue;
+			if ((app.elementProps || []).length > 3 * (member.elementProps || []).length) continue;
+			if (!best || near.j > best.j) best = { canon: member, j: near.j, familyJ: j };
+		}
+		if (best) {
+			const key = `${app.path}:${app.line}->${best.canon.path}:${best.canon.name}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			matches.push({
+				app,
+				canon: best.canon,
+				tier: "family",
+				reason: `token profile matches the ${best.canon.name} family (${(best.j * 100).toFixed(0)}% overlap)`,
+			});
+		}
+	}
+	return matches;
+}
+
+module.exports = { clusterComponents, matchFamilies, componentTokenSet, jaccard, JACCARD_MIN, FAMILY_MATCH_MIN, MIN_FAMILY_TOKENS };