@md-code/react-component-uniqueness 0.1.0

package/scanner/component.js

@@ -0,0 +1,346 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const ts = require("typescript");
+const { stringLiterals, resolveLocalIdentifier } = require("./extract");
+
+const HTML_TAGS = new Set([
+	"html",
+	"head",
+	"body",
+	"div",
+	"span",
+	"a",
+	"p",
+	"main",
+	"section",
+	"header",
+	"footer",
+	"nav",
+	"aside",
+	"article",
+	"ul",
+	"ol",
+	"li",
+	"table",
+	"thead",
+	"tbody",
+	"tr",
+	"td",
+	"th",
+	"form",
+	"label",
+	"input",
+	"button",
+	"select",
+	"textarea",
+	"img",
+	"figure",
+	"figcaption",
+	"svg",
+	"path",
+	"circle",
+	"rect",
+	"g",
+	"pre",
+	"code",
+	"strong",
+	"em",
+	"small",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"hr",
+	"br",
+	"i",
+	"b",
+	"u",
+	"s",
+	"sub",
+	"sup",
+	"blockquote",
+	"details",
+	"summary",
+	"dialog",
+	"canvas",
+	"video",
+	"audio",
+	"source",
+	"track",
+	"map",
+	"area",
+	"dl",
+	"dt",
+	"dd",
+	"fieldset",
+	"legend",
+	"data",
+	"output",
+	"progress",
+	"meter",
+	"time",
+	"mark",
+	"abbr",
+	"ruby",
+	"rt",
+	"rp",
+	"wbr",
+	"bdi",
+	"bdo",
+	"template",
+	"slot",
+	"picture",
+]);
+
+const isPascalCase = (name) => /^[A-Z][A-Za-z0-9]*$/.test(name);
+
+const dottedName = (name) => {
+	if (ts.isIdentifier(name)) return name.text;
+	if (name && name.kind === ts.SyntaxKind.QualifiedName) return `${dottedName(name.left)}.${name.right.text}`;
+	if (name && name.kind === ts.SyntaxKind.PropertyAccessExpression) return `${dottedName(name.expression)}.${name.name.text}`;
+	return null;
+};
+
+const tagOf = (name) => dottedName(name);
+
+function hasJsx(node) {
+	let found = false;
+	const visit = (n) => {
+		if (found) return;
+		if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n)) {
+			found = true;
+			return;
+		}
+		ts.forEachChild(n, visit);
+	};
+	visit(node);
+	return found;
+}
+
+function isExported(node, sf) {
+	const mods = ts.getModifiers(node) || [];
+	if (mods.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) return true;
+	const parent = node.parent;
+	if (parent && (ts.isExportDeclaration(parent) || ts.isExportAssignment(parent))) return true;
+	return false;
+}
+
+function collectTokens(expr, sf, out) {
+	if (!expr) return;
+	if (ts.isJsxExpression(expr)) expr = expr.expression;
+	const strs = [];
+	stringLiterals(expr, strs);
+	const idents = new Set();
+	const visitIds = (n) => {
+		if (ts.isIdentifier(n) && n.text.length > 0) idents.add(n.text);
+		ts.forEachChild(n, visitIds);
+	};
+	visitIds(expr);
+	for (const id of idents) {
+		const r = resolveLocalIdentifier(id, sf, "str");
+		for (const s of r.str) strs.push(s);
+	}
+	for (const s of strs) {
+		for (const tok of s.split(/\s+/)) {
+			if (tok && !out.has(tok)) out.add(tok);
+		}
+	}
+}
+
+function openingOf(node) {
+	return ts.isJsxElement(node) ? node.openingElement : node;
+}
+
+function classNameTokens(opening, sf, out) {
+	for (const attr of opening.attributes.properties) {
+		if (ts.isJsxAttribute(attr) && attr.name) {
+			const aname = attr.name.getText(sf);
+			if (aname === "className" || aname === "class") collectTokens(attr.initializer, sf, out);
+		}
+	}
+}
+
+function gatherElements(node, sf, out) {
+	const visit = (n) => {
+		if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n)) {
+			const opening = openingOf(n);
+			const tag = tagOf(opening.tagName);
+			const tokens = new Set();
+			classNameTokens(opening, sf, tokens);
+			out.push({ tag, tokens });
+		}
+		ts.forEachChild(n, visit);
+	};
+	visit(node);
+}
+
+function gatherSubtrees(node, sf) {
+	const out = [];
+	const visit = (n) => {
+		if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n)) {
+			out.push(n);
+		}
+		ts.forEachChild(n, visit);
+	};
+	visit(node);
+	return out;
+}
+
+const MAX_SUBTREE_TAGS = 80;
+
+function subtreeInfo(node, sf) {
+	const seq = [];
+	const tokens = new Set();
+	const visit = (n) => {
+		if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n)) {
+			const opening = openingOf(n);
+			const tag = tagOf(opening.tagName);
+			if (tag) seq.push(tag);
+			classNameTokens(opening, sf, tokens);
+		}
+		ts.forEachChild(n, visit);
+	};
+	visit(node);
+	return { seq, tokens };
+}
+
+function subtreesOf(node, sf) {
+	const out = [];
+	for (const el of gatherSubtrees(node, sf, [])) {
+		const info = subtreeInfo(el, sf);
+		if (info.seq.length > 0 && info.seq.length <= MAX_SUBTREE_TAGS) {
+			out.push({ tag: info.seq[0], seq: info.seq, tokens: [...info.tokens].sort() });
+		}
+	}
+	return out;
+}
+
+function rootTagsOf(node, sf) {
+	const out = new Set();
+	const visit = (n, parent) => {
+		if (n !== node && (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n))) {
+			const isRoot = !parent || !(ts.isJsxElement(parent) || ts.isJsxSelfClosingElement(parent) || ts.isJsxFragment(parent));
+			if (isRoot) {
+				const tag = tagOf(openingOf(n).tagName);
+				if (tag) out.add(tag);
+			}
+		}
+		ts.forEachChild(n, (c) => visit(c, n));
+	};
+	visit(node, null);
+	return out;
+}
+
+function gatherA11y(node, sf, out) {
+	const visit = (n) => {
+		if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n)) {
+			const opening = openingOf(n);
+			for (const attr of opening.attributes.properties) {
+				if (ts.isJsxAttribute(attr) && attr.name) {
+					const aname = attr.name.getText(sf);
+					if (aname === "role" || aname.startsWith("aria-")) {
+						const strs = [];
+						if (attr.initializer) stringLiterals(attr.initializer, strs);
+						const v = strs[0] ?? "true";
+						const key = `${aname}:${v}`;
+						if (!out.has(key)) out.add(key);
+					}
+				}
+			}
+		}
+		ts.forEachChild(n, visit);
+	};
+	visit(node);
+}
+
+function canonicalImportNames(sf) {
+	const names = new Set();
+	const visit = (n) => {
+		if (ts.isImportDeclaration(n) && n.moduleSpecifier && ts.isStringLiteral(n.moduleSpecifier)) {
+			if (n.importClause) {
+				if (n.importClause.name) names.add(n.importClause.name.text);
+				const clause = n.importClause.namedBindings;
+				if (clause && ts.isNamedImports(clause)) {
+					for (const el of clause.elements) {
+						names.add(el.name.text);
+					}
+				}
+			}
+		}
+		ts.forEachChild(n, visit);
+	};
+	visit(sf);
+	return names;
+}
+
+function canonicalTagsUsed(node, names) {
+	const found = new Set();
+	const visit = (n) => {
+		if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n)) {
+			const opening = openingOf(n);
+			if (ts.isIdentifier(opening.tagName) && names.has(opening.tagName.text)) found.add(opening.tagName.text);
+		}
+		ts.forEachChild(n, visit);
+	};
+	visit(node);
+	return found;
+}
+
+function* iterateDeclarations(sf) {
+	const found = [];
+	const visit = (n) => {
+		if (ts.isFunctionDeclaration(n) && n.name && isPascalCase(n.name.text) && n.body) {
+			found.push({ name: n.name.text, body: n.body, node: n });
+		}
+		if (ts.isVariableStatement(n)) {
+			for (const d of n.declarationList.declarations) {
+				if (ts.isIdentifier(d.name) && isPascalCase(d.name.text) && d.initializer && (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))) {
+					found.push({ name: d.name.text, body: d.initializer.body, node: n });
+				}
+			}
+		}
+		ts.forEachChild(n, visit);
+	};
+	visit(sf);
+	for (const d of found) yield d;
+}
+
+function componentsFromFile(fileAbs, canonicalNames) {
+	const source = fs.readFileSync(fileAbs, "utf8");
+	const kind = fileAbs.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+	const sf = ts.createSourceFile(fileAbs, source, ts.ScriptTarget.ES2020, true, kind);
+	const canonNameSet = canonicalNames || new Set();
+	const out = [];
+	const decls = [...iterateDeclarations(sf)];
+	if (decls.length === 0 && hasJsx(sf)) {
+		const base = path.basename(fileAbs, path.extname(fileAbs));
+		const name = base.split(/[-_ ]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+		decls.push({ name, body: sf, node: sf });
+	}
+	for (const d of decls) {
+		if (!hasJsx(d.body)) continue;
+		const elements = [];
+		gatherElements(d.body, sf, elements);
+		const elementProps = elements.map((e) => ({ tag: e.tag, tokens: [...e.tokens].sort() }));
+		const rootTags = [...rootTagsOf(d.body, sf)].sort();
+		const a11y = new Set();
+		gatherA11y(d.body, sf, a11y);
+		out.push({
+			name: d.name,
+			line: sf.getLineAndCharacterOfPosition(d.node.getStart(sf)).line + 1,
+			isExported: isExported(d.node, sf),
+			rootTags,
+			elementProps,
+			subtrees: subtreesOf(d.body, sf),
+			a11y: [...a11y].sort(),
+			usesCanonical: canonNameSet.size > 0 ? [...canonicalTagsUsed(d.body, canonNameSet)].sort() : [],
+		});
+	}
+	return out;
+}
+
+module.exports = { componentsFromFile, gatherSubtrees, openingOf, tagOf, classNameTokens, HTML_TAGS, isPascalCase, isHtmlTag: (t) => HTML_TAGS.has(t) };

package/scanner/extract.js

@@ -0,0 +1,256 @@
+"use strict";
+
+/**
+ * scanner/extract.js
+ *
+ * Signature extraction from one source file (TypeScript AST). For every
+ * JSX element and every styled.* template, a normalized Signature is
+ * recorded:
+ *
+ *   { tag, styles, actions, a11y, data }
+ *
+ * Only elements with at least one style / action / a11y marker are kept —
+ * a bare <div> is building material, not a component signature.
+ */
+
+const fs = require("node:fs");
+const ts = require("typescript");
+const sig = require("../signature");
+const { ACTION_ATTR_NAMES } = require("../config");
+
+/** Collect string literals from a TS expression (shallow, capped). */
+function stringLiterals(node, out, depth = 0) {
+	if (!node || depth > 4 || out.length >= 24) return;
+	if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+		out.push(node.text);
+		return;
+	}
+	if (ts.isTemplateExpression(node)) {
+		if (node.head.text) out.push(node.head.text);
+		for (const span of node.templateSpans) {
+			if (span.literal.text) out.push(span.literal.text);
+			stringLiterals(span.expression, out, depth + 1);
+		}
+		return;
+	}
+	if (ts.isObjectLiteralExpression(node)) {
+		for (const p of node.properties) stringLiterals(p.initializer, out, depth + 1);
+		return;
+	}
+	if (ts.isArrayLiteralExpression(node)) {
+		for (const el of node.elements) stringLiterals(el, out, depth + 1);
+		return;
+	}
+	if (ts.isCallExpression(node)) {
+		for (const arg of node.arguments) stringLiterals(arg, out, depth + 1);
+		return;
+	}
+	if (ts.isConditionalExpression(node)) {
+		stringLiterals(node.whenTrue, out, depth + 1);
+		stringLiterals(node.whenFalse, out, depth + 1);
+		return;
+	}
+	if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.Plus) {
+		stringLiterals(node.left, out, depth + 1);
+		stringLiterals(node.right, out, depth + 1);
+		return;
+	}
+}
+
+/**
+ * Resolve an identifier to a string-literal initializer or object literal
+ * declared somewhere in the same file (const cls = "..."; const st = {...}).
+ */
+function resolveLocalIdentifier(name, fileSf, kind) {
+	const found = { str: [], obj: null };
+	const walk = (n) => {
+		if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.name.text === name && n.initializer) {
+			if (kind === "str") {
+				const strs = [];
+				stringLiterals(n.initializer, strs);
+				found.str.push(...strs);
+			} else if (kind === "obj" && ts.isObjectLiteralExpression(n.initializer)) {
+				found.obj = n.initializer;
+			}
+			return;
+		}
+		ts.forEachChild(n, walk);
+	};
+	walk(fileSf);
+	return found;
+}
+
+/**
+ * Extract component signatures from one source file.
+ *
+ * @param {string} fileAbs absolute path to a .ts/.tsx/.jsx file
+ * @returns {Array<{tag: string, styles: object, actions: string[], a11y: string[], data: string[]}>}
+ */
+function signaturesFromFile(fileAbs) {
+	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 out = [];
+
+	/** Resolve a className-ish expression to a styles map. */
+	const classNameStyles = (expr) => {
+		const merged = {};
+		const addStyles = (s) => {
+			const tw = sig.twToStyles(s);
+			for (const [p, v] of Object.entries(tw)) {
+				if (!merged[p]) merged[p] = [];
+				for (const x of v) if (!merged[p].includes(x)) merged[p].push(x);
+			}
+		};
+		if (!expr) return merged;
+		if (ts.isIdentifier(expr)) {
+			const r = resolveLocalIdentifier(expr.text, sf, "str");
+			for (const s of r.str) addStyles(s);
+			return merged;
+		}
+		const strs = [];
+		stringLiterals(expr, strs);
+		for (const s of strs) addStyles(s);
+		return merged;
+	};
+
+	/** Resolve a style={{...}} expression to { prop: [values] }. */
+	const styleObjectStyles = (expr) => {
+		// The attr initializer is a JSXExpressionContainer wrapping the real expression.
+		if (expr && expr.kind === ts.SyntaxKind.JsxExpression) expr = expr.expression;
+		const styles = {};
+		const add = (prop, value) => {
+			if (!Object.prototype.hasOwnProperty.call(styles, prop)) styles[prop] = [];
+			if (!styles[prop].includes(value)) styles[prop].push(value);
+		};
+		const visitObj = (n) => {
+			if (!n) return;
+			if (ts.isObjectLiteralExpression(n)) {
+				for (const p of n.properties) {
+					if (!ts.isPropertyAssignment(p) || !p.name) continue;
+					const key = ts.isIdentifier(p.name) ? p.name.text : ts.isStringLiteral(p.name) ? p.name.text : null;
+					if (!key) continue;
+					const prop = sig.camelToKebab(key);
+					if (ts.isStringLiteral(p.initializer)) {
+						add(prop, p.initializer.text);
+					} else if (ts.isNumericLiteral(p.initializer)) {
+						add(prop, p.initializer.text);
+					} else if (ts.isPrefixUnaryExpression(p.initializer) && ts.isNumericLiteral(p.initializer.operand)) {
+						add(prop, `${p.operator === ts.SyntaxKind.MinusToken ? "-" : ""}${p.initializer.operand.text}`);
+					} else {
+						const strs = [];
+						stringLiterals(p.initializer, strs);
+						for (const s of strs) add(prop, s);
+					}
+				}
+				return;
+			}
+			if (ts.isConditionalExpression(n)) {
+				visitObj(n.whenTrue);
+				visitObj(n.whenFalse);
+				return;
+			}
+			if (ts.isIdentifier(n)) {
+				const r = resolveLocalIdentifier(n.text, sf, "obj");
+				if (r.obj) visitObj(r.obj);
+			}
+		};
+		visitObj(expr);
+		return styles;
+	};
+
+	const tagOf = (name) => (ts.isIdentifier(name) ? name.text : ts.isNamespacedName(name) ? `${name.name.text}:${name.namespace.text}` : null);
+
+	const visit = (node) => {
+		// JSX elements: <div className="..." role="dialog" onClick={...} data-testid="x" />
+		if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+			// JsxElement carries the tag in node.openingElement; a JsxSelfClosingElement
+			// IS the opening tag (it has tagName + attributes directly, no openingElement).
+			const opening = ts.isJsxElement(node) ? node.openingElement : node;
+			const tag = tagOf(opening.tagName);
+			if (!tag) return;
+			const sigObj = { tag, styles: {}, actions: [], a11y: [], data: [] };
+			for (const attr of opening.attributes.properties) {
+				if (!ts.isJsxAttribute(attr) || !attr.name) continue;
+				const aname = attr.name.getText(sf);
+				const value = attr.initializer;
+				if (aname === "className" || aname === "class") {
+					sigObj.styles = sig.mergeStyles(sigObj.styles, classNameStyles(value));
+				} else if (aname === "style") {
+					sigObj.styles = sig.mergeStyles(sigObj.styles, styleObjectStyles(value));
+				} else if (ACTION_ATTR_NAMES.has(aname)) {
+					const action = aname.slice(2).toLowerCase();
+					if (!sigObj.actions.includes(action)) sigObj.actions.push(action);
+				} else if (aname === "role" || aname.startsWith("aria-")) {
+					const strs = [];
+					if (value) stringLiterals(value, strs);
+					const v = strs[0] ?? "true";
+					const key = `${aname}:${v}`;
+					if (!sigObj.a11y.includes(key)) sigObj.a11y.push(key);
+				} else if (aname.startsWith("data-")) {
+					const strs = [];
+					if (value) stringLiterals(value, strs);
+					const v = strs[0] ?? "";
+					const key = `${aname}:${v}`;
+					if (!sigObj.data.includes(key)) sigObj.data.push(key);
+				} else if (aname === "type" && (tag === "input" || tag === "button")) {
+					const strs = [];
+					if (value) stringLiterals(value, strs);
+					const v = strs[0];
+					if (v) {
+						const key = `type:${v}`;
+						if (!sigObj.a11y.includes(key)) sigObj.a11y.push(key);
+					}
+				} else if (aname === "contentEditable") {
+					if (!sigObj.a11y.includes("contenteditable")) sigObj.a11y.push("contenteditable");
+				}
+			}
+			if (Object.keys(sigObj.styles).length > 0 || sigObj.actions.length > 0 || sigObj.a11y.length > 0) {
+				out.push(sigObj);
+			}
+			if (ts.isJsxElement(node)) ts.forEachChild(node, visit);
+			return;
+		}
+
+		// styled.div`css` / styled("div")`css`
+		if (ts.isVariableDeclaration(node) && node.initializer && ts.isTaggedTemplateExpression(node.initializer)) {
+			// styled.div`...` → tag is the PropertyAccessExpression itself (styled.div).
+			// styled("div")`...` → tag is a CallExpression. styled.div<Props>`...` → wrapped in a TypeAssertion.
+			const tagExpr = node.initializer.tag;
+			const tpl = node.initializer.template;
+			// No interpolation → NoSubstitutionTemplateLiteral (.text). With ${} → TemplateExpression (.head + .templateSpans).
+			const cssText = ts.isTemplateExpression(tpl)
+				? tpl.head.text + tpl.templateSpans.map((s) => s.literal.text).join("")
+				: ts.isNoSubstitutionTemplateLiteral(tpl)
+					? tpl.text
+					: "";
+			let tag = null;
+			// styled.div<Props>`...` wraps the member access in a TypeAssertion.
+			let real = tagExpr;
+			while (real && (ts.isTypeAssertionExpression(real) || ts.isAsExpression(real))) real = real.expression;
+			if (real && ts.isPropertyAccessExpression(real)) {
+				const base = real.expression;
+				if (ts.isIdentifier(base) && base.text === "styled") tag = real.name.text;
+			} else if (tagExpr && ts.isCallExpression(tagExpr)) {
+				const arg0 = tagExpr.arguments[0];
+				// styled("div")`...` — string literal.
+				if (arg0 && ts.isStringLiteral(arg0)) tag = arg0.text;
+				// styled(MuiButton)`...` — identifier: a wrapper built on a
+				// LIBRARY component. The tag is the component name (the rendered
+				// DOM tag is unknown statically — that is what the dynamic
+				// snapshot catalog is for), so the signature is matched by the
+				// CSS the wrapper adds on top of the library styles.
+				else if (arg0 && ts.isIdentifier(arg0)) tag = arg0.text;
+			}
+			if (tag) {
+				const sigObj = { tag, styles: sig.cssTextToStyles(cssText), actions: [], a11y: [], data: [] };
+				if (Object.keys(sigObj.styles).length > 0) out.push(sigObj);
+			}
+		}
+
+		ts.forEachChild(node, visit);
+	};
+	visit(sf);
+	return out;
+}
+
+module.exports = { signaturesFromFile, stringLiterals, resolveLocalIdentifier };

package/scanner/filters/drop-child-element-matches.js

@@ -0,0 +1,16 @@
+"use strict";
+
+const { registerFilter } = require("./registry");
+
+registerFilter({
+	name: "drop-child-element-matches",
+	test(match) {
+		if (match.tier === "name" || match.tier === "name-fuzzy" || match.tier === "jsx-block") return null;
+		const appEls = (match.app.elementProps || []).length;
+		const canonEls = (match.canon.elementProps || []).length;
+		if (canonEls > 0 && appEls > 3 * canonEls) {
+			return `app has ${appEls} elements vs canonical's ${canonEls} — match is on a child element, not the component itself`;
+		}
+		return null;
+	},
+});

package/scanner/filters/drop-usages.js

@@ -0,0 +1,14 @@
+"use strict";
+
+const { registerFilter } = require("./registry");
+
+registerFilter({
+	name: "drop-usages",
+	test(match) {
+		const used = match.app.usesCanonical || [];
+		if (used.includes(match.canon.name)) {
+			return `renders canonical ${match.canon.name} (usage, not a duplicate)`;
+		}
+		return null;
+	},
+});

package/scanner/filters/index.js

@@ -0,0 +1,8 @@
+"use strict";
+
+const { FILTERS, registerFilter, applyFilters } = require("./registry");
+
+require("./drop-usages");
+require("./drop-child-element-matches");
+
+module.exports = { FILTERS, registerFilter, applyFilters };

package/scanner/filters/registry.js

@@ -0,0 +1,30 @@
+"use strict";
+
+const FILTERS = [];
+
+function registerFilter(filter) {
+	if (!filter || typeof filter.name !== "string") throw new Error("filter must have a string `name`");
+	if (typeof filter.test !== "function") throw new Error(`filter "${filter && filter.name}" must have a test(match) function`);
+	FILTERS.push(filter);
+	return filter;
+}
+
+function applyFilters(matches) {
+	const kept = [];
+	const dropped = [];
+	for (const m of matches) {
+		let drop = null;
+		for (const f of FILTERS) {
+			const reason = f.test(m);
+			if (reason) {
+				drop = { filter: f.name, reason };
+				break;
+			}
+		}
+		if (drop) dropped.push({ match: m, ...drop });
+		else kept.push(m);
+	}
+	return { kept, dropped };
+}
+
+module.exports = { FILTERS, registerFilter, applyFilters };