@md-code/react-component-uniqueness 0.1.0

package/errorTypes/duplicate-component.js

@@ -0,0 +1,105 @@
+"use strict";
+
+/**
+ * errorTypes/duplicate-component.js
+ *
+ * Error type 1 — DUPLICATE DECLARATION (messageId: duplicateComponent).
+ *
+ * The component registry (reports/component-registry.json) maps every
+ * canonical component name to the list of directories where that name is
+ * allowed to be declared. Declaring a registry name outside its canonical
+ * directories — const Button = ..., function Form() {...}, class Card,
+ * export default function Badge — is a duplicate.
+ *
+ * Only EXPORTED component bindings count: a private styled sub-part
+ * (const Title = styled.h3 inside Card) that happens to share a name with a
+ * canonical component is an internal detail, not a duplicate — private
+ * bindings cannot be imported elsewhere.
+ */
+
+const { inCanonicalDir } = require("../config");
+
+/** Is this identifier a component binding (not a type)? */
+function isComponentBinding(node) {
+	if (!node || node.type !== "Identifier") return false;
+	if (!/^[A-Z]/.test(node.name)) return false;
+	// Skip type-only declarations: export type Foo / interface Foo are
+	// not components.
+	let parent = node.parent;
+	while (parent) {
+		if (parent.type === "TSInterfaceDeclaration") return false;
+		if (parent.type === "TSTypeAliasDeclaration") return false;
+		if (parent.type === "TSModuleDeclaration") return false;
+		if (parent.type === "ExportNamedDeclaration" || parent.type === "ExportDefaultDeclaration") break;
+		parent = parent.parent;
+	}
+	return true;
+}
+
+/**
+ * Is this VariableDeclarator part of an exported declaration?
+ *
+ * Only exported components are "the component" — a private styled sub-part
+ * (const Title = styled.h3 inside Card, const Overlay inside HamburgerMenu)
+ * that happens to share a name with a canonical component is an internal
+ * detail, not a duplicate. Private bindings cannot be imported elsewhere,
+ * so they are never the thing the user is trying to prevent.
+ */
+function isExportedDeclarator(node) {
+	let p = node.parent;
+	while (p && p.type === "VariableDeclaration") p = p.parent;
+	return p != null && p.type === "ExportNamedDeclaration";
+}
+
+/**
+ * Create the error type-1 visitors.
+ *
+ * @param {object} env { context, names, relPath }
+ * @returns {object} visitors: VariableDeclarator, ExportNamedDeclaration,
+ *   ExportDefaultDeclaration
+ */
+function createHandler(env) {
+	const { context, names, relPath } = env;
+
+	/** Report a duplicate declaration of a registry name. */
+	function checkName(name, node) {
+		const dirs = names[name];
+		if (!dirs || dirs.length === 0) return;
+		if (inCanonicalDir(relPath, dirs)) return;
+		context.report({
+			node,
+			messageId: "duplicateComponent",
+			data: { name, dirs: dirs.join(" or ") },
+		});
+	}
+
+	return {
+		VariableDeclarator(node) {
+			if (isComponentBinding(node.id) && isExportedDeclarator(node)) checkName(node.id.name, node.id);
+		},
+		ExportNamedDeclaration(node) {
+			const decl = node.declaration;
+			if (!decl) return;
+			// VariableDeclaration is handled by the VariableDeclarator
+			// visitor (avoids double-reporting).
+			if (decl.type === "FunctionDeclaration" || decl.type === "ClassDeclaration") {
+				if (isComponentBinding(decl.id)) checkName(decl.id.name, decl.id);
+			}
+		},
+		ExportDefaultDeclaration(node) {
+			const decl = node.declaration;
+			if (!decl) return;
+			// export default function Foo / class Foo
+			if ((decl.type === "FunctionDeclaration" || decl.type === "ClassDeclaration") && decl.id) {
+				if (isComponentBinding(decl.id)) checkName(decl.id.name, decl.id);
+			} else if (decl.type === "Identifier") {
+				// export default SomeBinding — the binding must be declared
+				// in this file; its name is the folder name only, so we
+				// cannot attribute a registry name to it reliably. Skip.
+				return;
+			}
+		},
+	};
+}
+
+module.exports = { createHandler, isComponentBinding, isExportedDeclarator };

package/errorTypes/layout-primitive.js

@@ -0,0 +1,212 @@
+"use strict";
+
+/**
+ * errorTypes/layout-primitive.js
+ *
+ * Error type 3 — HAND-ROLLED COMPONENTS BY BEHAVIOR (messageId: layoutPrimitive)
+ * and Error type 3b — CATALOG MATCH (messageId: catalogDuplicate,
+ * similarComponent).
+ *
+ * A plain div is building material and is NOT flagged on its own. But an
+ * element that BEHAVES like a canonical component — a div with
+ * flex/grid/col/row/justify/gap classes (a hand-rolled container), a span
+ * with onClick (a hand-rolled button), role=dialog / aria-modal (a
+ * hand-rolled modal), role=menu (a hand-rolled dropdown), input type=range
+ * (a hand-rolled slider), role=tooltip (a hand-rolled tooltip), a box with
+ * rounded corners + shadow (a hand-rolled Card / Paper), a spinner, tabs,
+ * accordion, progress, alert, avatar, badge — is a duplicate of a canonical
+ * component and is reported EVERYWHERE, including inside the component
+ * folders. That is what makes the rule total: a container hand-rolled in
+ * packages/components is still a duplicate of Container.
+ *
+ * The taxonomy mirrors the component categories of shadcn / MUI / antd.
+ * Values are resolved dynamically: className from a local variable,
+ * ternaries, cn()/clsx() calls, template literals, and identifiers imported
+ * from a sibling file (the imported file is read from disk and the exported
+ * constant's string literals are collected).
+ *
+ * Error type 3b matches the element's Signature against the component catalog
+ * (reports/component-catalog.json) using the decision matrix
+ * (signature.js). An error-tier verdict supersedes the other error types; a
+ * warning-tier verdict is a report-only hint (never fails the gate).
+ */
+
+const sig = require("../signature");
+const {
+	SPINNER_CLASS_RE,
+	MODAL_CLASS_RE,
+	CARD_CLASS_RE,
+	CARD_SECOND_RE,
+	CONTAINER_CLASS_RE,
+	ROLE_WHAT,
+} = require("../config");
+const { attrOf, attrValueOf, classNameCandidates, stylePropsOf, buildSignature } = require("../dom");
+const { forBehavior } = require("../suggestions");
+
+/**
+ * Library style props that signal "this wrapper applies its OWN styling to a
+ * library primitive" — the static equivalent of a style={} object. MUI `sx`,
+ * antd `style`/`css`, styled-components `className` overrides, etc. A bare
+ * <MuiButton> has none of these (plain import); <MuiPaper sx={{...}}> does
+ * (a hand-rolled card). buildSignature() does not read these, so includeDynamic
+ * needs an explicit check to tell the two apart.
+ */
+const LIBRARY_STYLE_PROPS = new Set(["sx", "css", "styleObject", "stl"]);
+function hasLibraryStyleProp(opening) {
+	return (opening.attributes || []).some(
+		(a) => a.type === "JSXAttribute" && a.name && LIBRARY_STYLE_PROPS.has(a.name.name)
+	);
+}
+
+/**
+ * Error type 3: an element that behaves like a canonical component.
+ * Returns a human "what" string, or null if the element is an ordinary
+ * building block.
+ */
+function behaviorOf(tag, opening, scope, fileDir) {
+	const role = attrValueOf(opening, "role");
+	if (typeof role === "string" && ROLE_WHAT[role]) return ROLE_WHAT[role];
+	if (attrValueOf(opening, "aria-modal") === "true") return "modal / dialog";
+	const hasPopup = attrValueOf(opening, "aria-haspopup");
+	if (typeof hasPopup === "string" && hasPopup !== "false") return "dropdown / menu trigger";
+	if (attrValueOf(opening, "contentEditable") != null) return "contentEditable element (a hand-rolled control)";
+	if (attrValueOf(opening, "onClick") != null) return "clickable element (a hand-rolled button)";
+	if (attrOf(opening, "aria-expanded")) return "accordion / collapsible";
+
+	const cls = classNameCandidates(opening, scope, fileDir).join(" ");
+	// Merged styles: tailwind className (incl. arbitrary values like z-[1000])
+	// + inline style={}. The modal check below runs on this merged map, so a
+	// "fixed inset-0 z-[1000]" Tailwind overlay is a modal, not only an inline
+	// style={{position:"fixed",zIndex:9999}} one.
+	const style = {};
+	for (const c of classNameCandidates(opening, scope, fileDir)) {
+		Object.assign(style, sig.twToStyles(c));
+	}
+	for (const [prop, values] of Object.entries(stylePropsOf(opening, scope, fileDir))) {
+		const key = sig.camelToKebab(prop);
+		style[key] = (style[key] || []).concat(values);
+	}
+	const styleHas = (prop) => Object.prototype.hasOwnProperty.call(style, prop);
+	const styleAny = (prop, re) => (style[prop] || []).some((v) => re.test(String(v)));
+
+	if (SPINNER_CLASS_RE.test(cls) || styleAny("animation", /spin|rotate/i)) return "spinner / skeleton";
+	if (MODAL_CLASS_RE.test(cls)) return "modal / dialog";
+	if (
+		styleHas("position") &&
+		(style.position || []).some((v) => /fixed/.test(String(v))) &&
+		(style["z-index"] || []).some((v) => Number(String(v).replace(/[^0-9-]/g, "")) >= 1000)
+	) {
+		return "modal / dialog";
+	}
+	if (CARD_CLASS_RE.test(cls) && (CARD_SECOND_RE.test(cls) || cls.split(/\s+/).filter(Boolean).length >= 3)) {
+		return "card / paper";
+	}
+	// Kebab-case keys: the merged map normalizes inline camelCase to kebab.
+	if (styleHas("border-radius") && (styleHas("box-shadow") || styleHas("border"))) return "card / paper";
+	// NOTE: there is deliberately NO "layout container" branch. A div with
+	// display:flex/grid is the normal way to build a layout — it is not a
+	// duplicate of any canonical component, and the canonical Container is a
+	// CSS-GRID component, so suggesting it for a flexbox div is actively
+	// wrong. Only strong behavior signals (button/modal/card/spinner/...) are
+	// reported here.
+	return null;
+}
+
+/**
+ * Create the error type-3 handler.
+ *
+ * @param {object} env { context, behaviorTags, catalogComponents, relPath, fileDir }
+ * @returns {object} { matchCatalog, handleElement }
+ */
+function createHandler(env) {
+	const { context, behaviorTags, catalogComponents, relPath, fileDir, registry, inComponentsFolder, componentsFolder } = env;
+
+	/**
+	 * Error type 3b: match the element signature against the component catalog
+	 * (decision matrix). Returns {name, path, level, reason, sim} or null.
+	 * Skips the entry whose own file is the current file.
+	 *
+	 * @param {string} tag the (possibly resolved) element tag
+	 * @param {object} opening the JSXOpeningElement node
+	 * @param {object} scope the eslint-scope scope
+	 * @param {object|null} dynEntry optional rendered-DOM signature (includeDynamic):
+	 *   when present, the candidate is re-tagged to the rendered DOM tag and
+	 *   enriched with the styles/actions/a11y that the library applies at
+	 *   runtime (MUI emotion/sx, antd cssinjs) — invisible to static analysis.
+	 */
+	function matchCatalog(tag, opening, scope, dynEntry) {
+		if (!catalogComponents.length) return null;
+		const candidate = buildSignature(tag, opening, scope, fileDir);
+		if (dynEntry) {
+			if (dynEntry.tag) candidate.tag = dynEntry.tag;
+			// A plain library use (<MuiButton> with no style/onClick/a11y of its
+			// own) is an IMPORT, not a duplicate: the rendered DOM is the
+			// library's, so we must not merge its rendered styles into the
+			// candidate — that would let a bare <MuiButton> "look like" a
+			// hand-rolled Card/Container and produce a false similarComponent.
+			// Only a WRAPPER that carries its own static signal (its own styles
+			// or an onClick / a11y marker) is a candidate for a duplicate, and
+			// for it we merge the rendered styles the library applies.
+			const hasOwnSignal =
+				Object.keys(candidate.styles).length > 0 ||
+				candidate.actions.length > 0 ||
+				candidate.a11y.length > 0 ||
+				hasLibraryStyleProp(opening);
+			if (hasOwnSignal && dynEntry.styles && Object.keys(dynEntry.styles).length && Object.keys(candidate.styles).length < sig.MIN_SHARED_STYLE_KEYS) {
+				candidate.styles = sig.mergeStyles(candidate.styles, dynEntry.styles);
+			}
+			// NOTE: actions/a11y are deliberately NOT merged from the dynamic
+			// entry. Behavior (onClick, type, role) is a per-USE static signal:
+			// a plain <MuiButton> without onClick must stay a plain import, not
+			// become a "duplicate" just because MUI renders <button type=button>.
+			// The dynamic catalog contributes only what static analysis cannot
+			// see: the real DOM tag + runtime styles.
+		}
+		// Exclude the current file's OWN catalog entries from the pool BEFORE
+		// best-selection. includeDynamic adds the file's own rendered wrappers
+		// (e.g. <MuiButton> in _keystone.tsx) to the catalog; a candidate that
+		// merges its own rendered styles would match its own entry at sim 1.0,
+		// and a post-hoc "own file" drop would then discard the real match
+		// against the canonical component. Filtering first lets the canonical
+		// entry win the best-selection.
+		// When the CURRENT file is a canonical component (inside the component
+		// folders), also drop the dynamic app-wrapper entries: a canonical
+		// component is the source of truth and must not be reported as a
+		// "duplicate" of a hand-rolled app wrapper (e.g. forms Button must not
+		// match an app's <MuiButton> plain import).
+		const pool = catalogComponents.filter((c) => c.path !== relPath && !(inComponentsFolder && c.__dyn));
+		const res = sig.matchSignature(candidate, { components: pool });
+		return res;
+	}
+
+	/**
+	 * Handle a non-raw element (div, span, ul, a, ...).
+	 * Returns true when a finding was reported.
+	 *
+	 * @param {string} tag
+	 * @param {object} opening the JSXOpeningElement node
+	 * @param {object} scope the eslint-scope scope of the element
+	 * @returns {boolean}
+	 */
+	function handleElement(tag, opening, scope) {
+		if (!behaviorTags.has(tag)) return false;
+		// Error type 3: behavior — reported EVERYWHERE, including inside the
+		// component folders. A container hand-rolled in packages/components is
+		// still a duplicate of Container: that is what makes the rule total.
+		const what = behaviorOf(tag, opening, scope, fileDir);
+		if (what) {
+				const sug = forBehavior(what, registry, catalogComponents, componentsFolder);
+			context.report({
+				node: opening,
+				messageId: "layoutPrimitive",
+				data: { tag, what, component: sug.component, path: sug.path },
+			});
+			return true;
+		}
+		return false;
+	}
+
+	return { matchCatalog, handleElement };
+}
+
+module.exports = { createHandler, behaviorOf };

package/errorTypes/raw-html.js

@@ -0,0 +1,97 @@
+"use strict";
+
+/**
+ * errorTypes/raw-html.js
+ *
+ * Error type 2 — RAW HTML (messageId: rawHtml).
+ *
+ * Raw interactive / form elements (button, label, select, textarea, input,
+ * form, table, dialog) are only legal inside the canonical packages
+ * (@md/components / @md/sections) — that is where the canonical components
+ * are built from them. Outside those packages every raw element is a
+ * report: use the canonical component instead.
+ *
+ * Error type 3 also applies to raw elements: a raw input type=range / select /
+ * dialog is a hand-rolled slider / select / modal, and that behavior check
+ * runs EVERYWHERE — including inside the component folders. The rawHtml
+ * report (error type 2) stays silent there, because the raw element is the
+ * building material the canonical component is made of.
+ */
+
+const { ROLE_WHAT, RAW_BEHAVIOR_TAGS } = require("../config");
+const { attrValueOf } = require("../dom");
+const { forBehavior, forRaw } = require("../suggestions");
+
+/**
+ * Behavior of a raw element (input type=range, select, dialog,
+ * button with onClick, role=...). Returns a "what" string or null.
+ */
+function behaviorForRaw(tag, opening) {
+	const role = attrValueOf(opening, "role");
+	if (typeof role === "string" && ROLE_WHAT[role]) return ROLE_WHAT[role];
+	if (tag === "input") {
+		const type = attrValueOf(opening, "type");
+		if (type === "range") return "slider";
+		if (type === "checkbox") return "checkbox (a hand-rolled control)";
+		if (type === "radio") return "radio (a hand-rolled control)";
+	}
+	if (tag === "dialog") return "modal / dialog";
+	if (tag === "select") return "select (a hand-rolled control)";
+	if (tag === "button" && attrValueOf(opening, "onClick") != null) return "clickable element (a hand-rolled button)";
+	return null;
+}
+
+/**
+ * Create the error type-2 handler.
+ *
+ * @param {object} env { context, rawElements, inComponentsFolder }
+ * @returns {function} handleRaw(tag, opening) -> boolean (was a finding reported?)
+ */
+function createHandler(env) {
+	const { context, rawElements, inComponentsFolder, registry, catalogComponents, componentsFolder } = env;
+
+	/**
+	 * Handle a raw element (button, input, select, ...).
+	 * Returns true when a finding was reported.
+	 *
+	 * @param {string} tag
+	 * @param {object} opening the JSXOpeningElement node
+	 * @returns {boolean}
+	 */
+	function handleRaw(tag, opening) {
+		if (!rawElements.has(tag)) return false;
+		let reported = false;
+		// Error type 2: raw HTML is only legal inside the component folders
+		// (it is the building material the canonical components are made of).
+		if (!inComponentsFolder) {
+			const sug = forRaw(tag, attrValueOf(opening, "type"), registry, catalogComponents, componentsFolder);
+			context.report({
+				node: opening,
+				messageId: "rawHtml",
+				data: { tag, component: sug.component, path: sug.path },
+			});
+			reported = true;
+		}
+		// Error type 3 also applies to raw elements: a raw input type=range /
+		// select / dialog is a hand-rolled slider / select / modal. Runs
+		// EVERYWHERE — a hand-rolled slider in packages/components is still a
+		// duplicate of Slider.
+		if (RAW_BEHAVIOR_TAGS.has(tag)) {
+			const what = behaviorForRaw(tag, opening);
+			if (what) {
+				const sug = forBehavior(what, registry, catalogComponents, componentsFolder);
+				context.report({
+					node: opening,
+					messageId: "layoutPrimitive",
+					data: { tag, what, component: sug.component, path: sug.path },
+				});
+				reported = true;
+			}
+		}
+		return reported;
+	}
+
+	return { handleRaw };
+}
+
+module.exports = { createHandler, behaviorForRaw };

package/errorTypes/styled-in-app.js

@@ -0,0 +1,93 @@
+"use strict";
+
+/**
+ * errorTypes/styled-in-app.js
+ *
+ * Error type 4 — STYLED IN APP (messageId: styledInApp).
+ *
+ * styled.div / styled.button / ... created outside the component folders is
+ * UI built in the app — reported, whatever the tag. Inside the component
+ * folders styled.* is the building material the canonical components are
+ * made of and is legal.
+ */
+
+/**
+ * Create the error type-4 visitors.
+ *
+ * @param {object} env { context, inComponentsFolder }
+ * @returns {object} visitors: VariableDeclarator
+ */
+const sig = require("../signature");
+
+function createHandler(env) {
+	const { context, inComponentsFolder, catalogComponents, componentsFolder } = env;
+
+	/** Fallback path: the first canonical folder, or the generic phrase. */
+	const defaultPath = componentsFolder && componentsFolder.length ? componentsFolder[0] : "the canonical component packages";
+
+	/**
+	 * Collect the CSS text of a styled template (no-substitution literal, or a
+	 * template expression with interpolations — only the literal parts).
+	 */
+	function cssTextOf(tpl) {
+		if (!tpl) return "";
+		if (tpl.type === "NoSubstitutionTemplate") return tpl.value.cooked || tpl.value.raw || "";
+		if (tpl.type === "TemplateLiteral") {
+			return (tpl.quasis || []).map((q) => q.value.cooked || q.value.raw || "").join("");
+		}
+		return "";
+	}
+
+	/**
+	 * Error type 4: styled.<htmlTag> created outside the component folders is
+	 * UI built in the app — reported, whatever the tag. The suggestion is the
+	 * catalog component whose signature matches the styled template, if any.
+	 */
+	function checkStyledInApp(node) {
+		if (inComponentsFolder) return;
+		const init = node.init;
+		if (!init || init.type !== "TaggedTemplateExpression") return;
+		const tagExpr = init.tag;
+		// styled.div`...` (MemberExpression) and styled(MuiButton)`...`
+		// (CallExpression with an identifier argument — a wrapper built on a
+		// LIBRARY component, e.g. MUI/antd). Both are app-built UI outside the
+		// component folders.
+		let tag = null;
+		if (tagExpr.type === "MemberExpression" && tagExpr.property && tagExpr.property.name) {
+			tag = tagExpr.property.name;
+		} else if (tagExpr.type === "CallExpression" && tagExpr.arguments.length) {
+			const arg0 = tagExpr.arguments[0];
+			if (arg0.type === "Identifier") tag = arg0.name;
+			else if (arg0.type === "Literal" && typeof arg0.value === "string") tag = arg0.value;
+		}
+		if (!tag) return;
+
+		let component = "CanonicalComponent";
+		let path = defaultPath;
+		const cssText = cssTextOf(init.template);
+		const styles = sig.cssTextToStyles(cssText);
+		if (Object.keys(styles).length && catalogComponents.length) {
+			const hit = sig.matchSignature(
+				{ tag, styles, actions: [], a11y: [], data: [] },
+				{ components: catalogComponents },
+			);
+			if (hit) {
+				component = hit.name;
+				path = hit.path;
+			}
+		}
+		context.report({
+			node: node.id,
+			messageId: "styledInApp",
+			data: { tag, component, path },
+		});
+	}
+
+	return {
+		VariableDeclarator(node) {
+			checkStyledInApp(node);
+		},
+	};
+}
+
+module.exports = { createHandler };