@md-code/react-component-uniqueness 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# @md-code/react-component-uniqueness
+
+ESLint rule + CLI scanner that finds **duplicate React components** in your app code by comparing them against your canonical component library.
+
+## How it works
+
+```mermaid
+flowchart TD
+    A["Canonical components<br/>(walk folders, extract signatures)"] --> B[("catalog.json")]
+    A --> CD["canon-dup<br/>canonicals matched against each other (strict thresholds)<br/>duplicates dropped → unique canonical set"]
+    CD --> A
+    C["App code<br/>(every JSX element)"] --> D
+
+    subgraph match["Match (4 matchers in parallel)"]
+        D --> M1["name<br/>same or fuzzy name"]
+        D --> M2["structural<br/>shared class tokens"]
+        D --> M3["family<br/>token-profile cluster"]
+        D --> M4["jsx-block<br/>subtree contains canonical"]
+        B --> M1
+        B --> M2
+        B --> M3
+        B --> M4
+    end
+
+    M1 --> F1
+    M2 --> F1
+    M3 --> F1
+    M4 --> F1
+
+    subgraph filter["Filter"]
+        F1["drop-usages<br/>app already imports the canonical"]
+        F1 --> F2["drop-child-element<br/>match is on a child, not the root"]
+    end
+
+    F2 --> E["report.md<br/>Markdown funnel of duplicates"]
+    CD -. "own section" .-> E
+```
+
+## Quick start
+
+```sh
+bun add -D @md-code/react-component-uniqueness
+```
+
+```js
+// eslint.config.js
+const uniqueness = require("@md-code/react-component-uniqueness/plugin");
+
+module.exports = [
+  {
+    files: ["**/*.tsx"],
+    plugins: { "md-code": uniqueness },
+    rules: {
+      "md-code/react-component-uniqueness": ["error", {
+        componentsFolder: [
+          { path: "core/ui/atoms", rank: 0 },
+          { path: "core/ui/formation", rank: 1 },
+          { path: "core/ui/partials", rank: 2 },
+        ],
+        catalogPath: "reports/component-catalog.json",
+      }],
+    },
+  },
+];
+```
+
+The catalog is generated automatically on the first lint when the file is
+missing (from the `componentsFolder` option) — it is gitignored and never
+committed. You can also generate it explicitly:
+
+```sh
+bunx md-code-react-component-uniqueness
+```
+
+Run the linter as usual:
+
+```sh
+bunx eslint "src/**/*.tsx"
+```
+
+## CLI
+
+```sh
+bunx md-code-react-component-uniqueness [flags]
+```
+
+| Flag | Description |
+| --- | --- |
+| `--roots a:b` | Scan roots (overrides `componentsFolder` from config) |
+| `--out <file>` | Catalog output path (default `reports/component-catalog.json`) |
+| `--check` | CI gate — exit 1 if catalog is stale |
+| `--report [file]` | Write a Markdown duplicate report |
+| `--verbose` | Include the "Filtered out" section in the report |
+| `--app-roots a:b` | App-code roots for the report (default: repo root) |
+| `--repo-root <dir>` | Repo root (default: auto-discovered) |
+
+## What it flags
+
+| Tier | Meaning |
+| --- | --- |
+| `name` | App component has the same name as a canonical one |
+| `name-fuzzy` | Name is a fuzzy match (e.g. `MyButton` vs `Button`) |
+| `structural-exact` | ≥ 80% of the canonical's distinctive class tokens are shared |
+| `structural-similar` | 40–80% shared |
+| `family` | Clusters by token profile (hand-built library pieces) |
+| `jsx-block` | A JSX subtree in app code contains the full tag-sequence of a canonical component |
+
+## Options (rule config)
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `componentsFolder` | `[]` | Canonical dirs. `{ path, rank }` objects or plain strings |
+| `catalogPath` | `reports/component-catalog.json` | Where the catalog lives |
+| `thresholds` | built-in | `minShared`, `minRatioSameTag`, `minRatioAnyTag`, `exactRatio`, `familyMatchMin` |
+| `exclude` | `node_modules, dist, build, .git` | Globs or regexes to skip |
+| `include` | `[]` | If set, only matching files are linted |
+
+## Notes
+
+- The catalog is **generated on demand** by the rule when the file is missing
+  (same code path as the CLI), so it can stay gitignored and CI works out of
+  the box. The CLI is still useful for `--report` and `--check`.
+- The catalog is read once per ESLint process and cached.
+- A missing or stale catalog logs a warning; lint never crashes.
+- Everything is plain Node + `fs`/`path` — works identically on Linux, macOS, Windows.

package/bin/react-component-uniqueness.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * bin/react-component-uniqueness.js
+ *
+ * CLI entry point: runs the catalog scanner (scanner/main.js).
+ */
+
+require("../scanner/main.js");

package/config.js

@@ -0,0 +1,290 @@
+"use strict";
+
+/**
+ * config.js
+ *
+ * The single place that knows the rule's defaults and normalizes the
+ * ESLint options into a runtime config object. Every error type reads from this
+ * object, so changing a default or taxonomy is a one-file edit.
+ *
+ * Paths are GENERIC: the registry and catalog locations are options that
+ * default to the conventional reports/ files under the repository root
+ * (the repo root is discovered by walking up for pnpm-workspace.yaml).
+ */
+
+const path = require("node:path");
+const { minimatch } = require("minimatch");
+const { findRepoRoot } = require("./debt");
+
+/** Raw interactive / form elements that are only legal inside the canonical packages. */
+const DEFAULT_RAW_ELEMENTS = ["button", "label", "select", "textarea", "input", "form", "table", "dialog"];
+
+/** Tags eligible for the behavior error type (plain building blocks + containers). */
+const DEFAULT_BEHAVIOR_TAGS = [
+	"div",
+	"main",
+	"section",
+	"header",
+	"footer",
+	"nav",
+	"aside",
+	"span",
+	"ul",
+	"li",
+	"a",
+	"p",
+	"figure",
+	"img",
+];
+
+/**
+ * Default file exclusions (repo-relative paths): build artifacts and
+ * dependency folders are never linted by the rule.
+ */
+const DEFAULT_EXCLUDE = ["**/node_modules/**", "**/dist/**", "**/build/**", ".git/**"];
+
+/** Class tokens that turn a plain element into a specific hand-rolled component (shadcn / MUI / antd taxonomy). */
+const SPINNER_CLASS_RE = /(^|[\s"'`-])(spin(ning)?|loading|loader|pulse|shimmer|skeleton)([\s"'`-]|$)/i;
+const MODAL_CLASS_RE = /(^|[\s"'`-])(modal|dialog|drawer|overlay|backdrop|popup)([\s"'`-]|$)/i;
+const CARD_CLASS_RE = /(^|[\s"'`-])(card|paper|panel|tile)([\s"'`-]|$)/i;
+const CARD_SECOND_RE = /(^|[\s"'`-])(shadow|rounded|border|elevation)([\s"'`-]|$)/i;
+const CONTAINER_CLASS_RE =
+	/(^|[\s"'`-])(flex|grid|col(umn)?|row|justify-|items-|gap-|space-|stack|container|wrapper|layout)([\s"'`-]|$)/i;
+
+/** role values that turn a plain element into a hand-rolled component. */
+const ROLE_WHAT = {
+	dialog: "modal / dialog",
+	alertdialog: "modal / dialog",
+	menu: "dropdown / menu",
+	menubar: "dropdown / menu",
+	menuitem: "menu item (a hand-rolled control)",
+	tablist: "tabs",
+	tab: "tab (a hand-rolled control)",
+	slider: "slider",
+	tooltip: "tooltip",
+	progressbar: "progress indicator",
+	alert: "alert",
+	status: "live status region",
+	group: "accordion / collapsible",
+	switch: "switch (a hand-rolled control)",
+	checkbox: "checkbox (a hand-rolled control)",
+	radio: "radio (a hand-rolled control)",
+	button: "button (a hand-rolled control)",
+};
+
+/** Raw elements that ALSO go through the behavior error type (input type=range, select, dialog, ...). */
+const RAW_BEHAVIOR_TAGS = new Set(["input", "select", "textarea", "form", "table", "dialog"]);
+
+/** Event-handler attribute names counted as "actions" in a signature. */
+const ACTION_ATTR_NAMES = new Set([
+	"onClick",
+	"onMouseDown",
+	"onMouseUp",
+	"onMouseEnter",
+	"onMouseLeave",
+	"onMouseMove",
+	"onTouchStart",
+	"onTouchEnd",
+	"onTouchMove",
+	"onFocus",
+	"onBlur",
+	"onChange",
+	"onInput",
+	"onSubmit",
+	"onKeyDown",
+	"onKeyUp",
+	"onKeyPress",
+	"onDragStart",
+	"onDragEnd",
+	"onDrop",
+	"onDragOver",
+	"onDoubleClick",
+	"onContextMenu",
+]);
+
+/**
+ * Resolve a data-file option to an absolute path. A relative value is
+ * resolved against the repository root (or cwd as a last resort), so the
+ * default "reports/component-registry.json" works from any working directory.
+ */
+function resolveDataPath(value, root) {
+	if (path.isAbsolute(value)) return value;
+	const base = root || process.cwd();
+	return path.resolve(base, value);
+}
+
+/**
+ * Normalize the ESLint options into a runtime config object.
+ *
+ * @param {object} [opts] the first rule option (may be undefined)
+ * @returns {object} config
+ */
+function normalizeOptions(opts) {
+	const o = opts && typeof opts === "object" ? opts : {};
+	const root = findRepoRoot(process.cwd());
+
+	return {
+		// Error type 1: the registry of canonical component names -> allowed dirs.
+		registry: o.registry || null,
+		registryPath: resolveDataPath(o.registryPath || "reports/component-registry.json", root),
+
+		// Error type 3b: the catalog of canonical component element signatures.
+		catalog: o.catalog || null,
+		catalogPath: resolveDataPath(o.catalogPath || "reports/component-catalog.json", root),
+
+		// Dynamic catalog: signatures captured from a REAL rendered DOM
+		// (playground + getComputedStyle). Covers styles that are invisible
+		// statically — MUI emotion/sx, antd cssinjs. When includeDynamic is
+		// true the dynamic catalog entries are merged into the static one.
+		includeDynamic: o.includeDynamic === true,
+		dynamicCatalog: o.dynamicCatalog || null,
+		dynamicCatalogPath: resolveDataPath(o.dynamicCatalogPath || "reports/component-catalog-dynamic.json", root),
+
+		// Error type 2: raw elements to flag.
+		rawElements: new Set(o.rawElements || DEFAULT_RAW_ELEMENTS),
+
+		// Error type 3: tags eligible for behavior analysis.
+		behaviorTags: new Set(o.behaviorTags || DEFAULT_BEHAVIOR_TAGS),
+
+		// Component folders (raw HTML / styled.* legal inside; catalog source).
+		// Trailing slashes are normalized so "packages/components" and
+		// "packages/components/" mean the same folder.
+		// NO DEFAULT: the canonical layout is the consumer's knowledge — the
+		// ESLint config (or scanner) must pass the folders explicitly. Empty
+		// list = every file is "outside the component folders".
+		componentsFolder: normalizeFolders(o.componentsFolder || []),
+
+		// File filters: include (empty = everything) / exclude (build artifacts).
+		// Each entry is a minimatch glob or a regex ("..." or /.../ form).
+		include: o.include || [],
+		exclude: o.exclude || DEFAULT_EXCLUDE,
+
+		// Debt ledger section (relpath::ruleId -> count).
+		debt: o.debt || null,
+
+		// Repo root (for repo-relative paths in messages).
+		root,
+	};
+}
+
+/**
+ * Normalize a list of folder prefixes: posix separators, no leading "./",
+ * exactly one trailing slash. "packages/components" and "packages/components/"
+ * become the same string. Entries may also be objects: { path, rank } — rank
+ * orders the canonical layers (0 = lowest, e.g. atoms; higher = built on top,
+ * e.g. partials). String entries get their rank from their position.
+ *
+ * @param {Array<string|{path:string, rank?:number}>} folders
+ * @returns {string[]}
+ */
+function normalizeFolders(folders) {
+	return (folders || []).map((f, i) => {
+		const raw = f && typeof f === "object" ? f.path : f;
+		let s = String(raw).trim().split(path.sep).join("/");
+		while (s.startsWith("./")) s = s.slice(2);
+		if (!s.endsWith("/")) s += "/";
+		return s;
+	});
+}
+
+/**
+ * Map of normalized folder prefix -> rank. Object entries carry an explicit
+ * rank; string entries fall back to their position in the list.
+ *
+ * @param {Array<string|{path:string, rank?:number}>} folders
+ * @returns {Map<string, number>}
+ */
+function folderRank(folders) {
+	const map = new Map();
+	(folders || []).forEach((f, i) => {
+		const isObj = f && typeof f === "object";
+		const raw = isObj ? f.path : f;
+		let s = String(raw).trim().split(path.sep).join("/");
+		while (s.startsWith("./")) s = s.slice(2);
+		if (!s.endsWith("/")) s += "/";
+		const r = isObj && typeof f.rank === "number" ? f.rank : i;
+		if (!map.has(s)) map.set(s, r);
+	});
+	return map;
+}
+
+/**
+ * True when a repo-relative path is inside any of the component folders
+ * (folders are normalized to carry a trailing slash).
+ */
+function inComponentsFolder(relPath, componentsFolder) {
+	return componentsFolder.some((d) => relPath.startsWith(d));
+}
+
+/**
+ * Compile an include/exclude entry into a matcher. Accepts a minimatch glob
+ * ("packages/apps/**") or a regex ("^packages/apps/" or /packages\/apps/).
+ */
+function compileMatcher(pattern) {
+	if (pattern instanceof RegExp) return (p) => pattern.test(p);
+	if (typeof pattern !== "string" || pattern.length === 0) return null;
+	if (pattern.startsWith("/") && pattern.endsWith("/") && pattern.length > 2) {
+		try {
+			const re = new RegExp(pattern.slice(1, -1));
+			return (p) => re.test(p);
+		} catch {
+			return null; // invalid regex — treat as glob
+		}
+	}
+	if (pattern.startsWith("^") && pattern.endsWith("$")) {
+		try {
+			const re = new RegExp(pattern);
+			return (p) => re.test(p);
+		} catch {
+			return null;
+		}
+	}
+	return (p) => minimatch(p, pattern);
+}
+
+/**
+ * True when the repo-relative file path should be skipped by the rule.
+ * A non-empty `include` list means the file must match at least one entry;
+ * any matching `exclude` entry always wins.
+ */
+function isIgnored(relPath, include, exclude) {
+	for (const pattern of exclude || []) {
+		const m = compileMatcher(pattern);
+		if (m && m(relPath)) return true;
+	}
+	if (include && include.length > 0) {
+		return !include.some((pattern) => {
+			const m = compileMatcher(pattern);
+			return m ? m(relPath) : false;
+		});
+	}
+	return false;
+}
+
+/**
+ * True when a repo-relative path is exactly one of the given directories or
+ * lives inside any of them. Used by the registry error type to decide whether a
+ * declaration sits in its canonical directory.
+ */
+function inCanonicalDir(relPath, dirs) {
+	return dirs.some((d) => relPath === d || relPath.startsWith(d + "/"));
+}
+
+module.exports = {
+	DEFAULT_RAW_ELEMENTS,
+	DEFAULT_BEHAVIOR_TAGS,
+	DEFAULT_EXCLUDE,
+	SPINNER_CLASS_RE,
+	MODAL_CLASS_RE,
+	CARD_CLASS_RE,
+	CARD_SECOND_RE,
+	CONTAINER_CLASS_RE,
+	ROLE_WHAT,
+	RAW_BEHAVIOR_TAGS,
+	ACTION_ATTR_NAMES,
+	normalizeOptions,
+	inComponentsFolder,
+	inCanonicalDir,
+	isIgnored,
+	folderRank,
+};

package/debt.js

@@ -0,0 +1,105 @@
+"use strict";
+
+/**
+ * debt.js
+ *
+ * Generic debt-ledger mechanism (self-contained copy so this package is
+ * npm-installable on its own).
+ *
+ * Doctrine: a rule is TOTAL. Instance-specific findings go to a
+ * machine-generated debt ledger (reports/lint-debt.json), keyed
+ * "relpath::ruleId" -> count. The ledger is shrink-only: check mode fails if
+ * an entry grows or a new key appears.
+ *
+ * `applyDebt(context, ledger, ruleId)` returns a wrapped ESLint context whose
+ * `report` silently drops findings already recorded in the ledger.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+/**
+ * Load a debt ledger JSON file. Missing/invalid file -> empty ledger
+ * (strict mode: every finding is reported).
+ */
+function loadLedger(filePath) {
+	try {
+		const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+		if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+			return raw;
+		}
+	} catch {
+		// missing or corrupt -> strict
+	}
+	return {};
+}
+
+/**
+ * Wrap an ESLint context so that `report` drops findings that are already
+ * recorded in the debt ledger.
+ *
+ * Ledger key: `<repo-relative path>::<ruleId>` (matches gen-lint-debt.mjs).
+ */
+function applyDebt(context, ledger, ruleId) {
+	if (!ledger || Object.keys(ledger).length === 0) {
+		return context;
+	}
+
+	const rel = repoRelative(context);
+
+	const wrapped = Object.create(context);
+	Object.defineProperty(wrapped, "report", {
+		value: function (descriptor) {
+			const key = `${rel}::${ruleId}`;
+			if (Object.prototype.hasOwnProperty.call(ledger, key)) {
+				return; // known debt — already accounted for
+			}
+			context.report(descriptor);
+		},
+	});
+	return wrapped;
+}
+
+/**
+ * Resolve the repo-relative path of the file being linted.
+ * Walks up from the file looking for pnpm-workspace.yaml.
+ */
+function repoRelative(context) {
+	const filePath = context.getFilename ? context.getFilename() : context.filename;
+	if (!filePath || filePath === "<input>") {
+		return "<unknown>";
+	}
+	const abs = path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
+	let dir = path.dirname(abs);
+	// Walk to the filesystem root (unbounded): deeply nested apps (e.g.
+	// frontend/src/features/... in a monorepo) can be 9+ levels below the
+	// workspace root, so a fixed hop limit would miss pnpm-workspace.yaml.
+	for (;;) {
+		if (fs.existsSync(path.join(dir, "pnpm-workspace.yaml"))) {
+			return path.relative(dir, abs).split(path.sep).join("/");
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return abs.split(path.sep).join("/");
+}
+
+/**
+ * Walk up from a starting directory to the repo root (pnpm-workspace.yaml).
+ */
+function findRepoRoot(startDir) {
+	let dir = startDir;
+	// Walk to the filesystem root (unbounded) — see repoRelative.
+	for (;;) {
+		if (fs.existsSync(path.join(dir, "pnpm-workspace.yaml"))) {
+			return dir;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+
+module.exports = { applyDebt, loadLedger, repoRelative, findRepoRoot };

package/dom.js

@@ -0,0 +1,158 @@
+"use strict";
+
+/**
+ * dom.js
+ *
+ * JSX element inspection: attribute lookup, className / style resolution,
+ * and Signature construction for a JSX element (tag, normalized CSS styles,
+ * actions, a11y markers, data-* attributes).
+ *
+ * Everything here works over an ESTree `JSXOpeningElement` node plus the
+ * eslint-scope scope of the element (dynamic values are resolved via
+ * resolve.js).
+ */
+
+const sig = require("./signature");
+const { ACTION_ATTR_NAMES } = require("./config");
+const { resolveStringCandidates } = require("./resolve");
+
+/** Find a JSX attribute; returns the attribute node or null. */
+function attrOf(opening, name) {
+	return (opening.attributes || []).find((a) => a.type === "JSXAttribute" && a.name && a.name.name === name) || null;
+}
+
+/**
+ * Static attribute value as a string (role, contentEditable, ...).
+ * Returns null when the attribute is absent, `true` for a bare attribute,
+ * the literal string for a Literal value, and "<expr>" for a dynamic one.
+ */
+function attrValueOf(opening, name) {
+	const attr = attrOf(opening, name);
+	if (!attr) return null;
+	if (attr.value == null) return true; // bare attribute, e.g. contentEditable
+	if (attr.value.type === "Literal") return String(attr.value.value ?? "");
+	return "<expr>";
+}
+
+/**
+ * Resolve a className attribute to candidate class strings (literal,
+ * variable, ternary, cn(), imported constant).
+ */
+function classNameCandidates(opening, scope, fileDir) {
+	const attr = attrOf(opening, "className");
+	if (!attr || !attr.value) return [];
+	if (attr.value.type === "Literal") return [String(attr.value.value ?? "")];
+	if (attr.value.type === "JSXExpressionContainer") {
+		const c = resolveStringCandidates(attr.value.expression, scope, 0, fileDir);
+		return c || [];
+	}
+	return [];
+}
+
+/**
+ * Resolve a style attribute to a map of property name -> candidate string
+ * values (inline style object, variable, ternary, import).
+ */
+function stylePropsOf(opening, scope, fileDir) {
+	const attr = attrOf(opening, "style");
+	if (!attr || !attr.value || attr.value.type !== "JSXExpressionContainer") return {};
+	const expr = attr.value.expression;
+	const out = {};
+	const collect = (e, depth) => {
+		if (!e || depth > 3) return;
+		if (e.type === "ObjectExpression") {
+			for (const p of e.properties) {
+				if (p.type !== "Property" || !p.key || !p.key.name) continue;
+				const c = resolveStringCandidates(p.value, scope, depth + 1, fileDir);
+				if (c) out[p.key.name] = (out[p.key.name] || []).concat(c);
+			}
+			return;
+		}
+		if (e.type === "Identifier") {
+			for (let s = scope; s; s = s.upper) {
+				const v = s.variables.find((x) => x.name === e.name);
+				if (!v) continue;
+				for (const def of v.defs || []) {
+					if (def && def.node && def.node.type === "VariableDeclarator" && def.node.init) collect(def.node.init, depth + 1);
+				}
+			}
+			return;
+		}
+		if (e.type === "ConditionalExpression") {
+			collect(e.consequent, depth + 1);
+			collect(e.alternate, depth + 1);
+		}
+	};
+	collect(expr, 0);
+	return out;
+}
+
+/**
+ * Build the flat Signature of a JSX element: tag, normalized CSS styles
+ * (tailwind className + inline style), actions (event handlers), a11y
+ * markers, data-* attributes.
+ */
+function buildSignature(tag, opening, scope, fileDir) {
+	const styles = {};
+	for (const cls of classNameCandidates(opening, scope, fileDir)) {
+		Object.assign(styles, sig.twToStyles(cls));
+	}
+	for (const [prop, values] of Object.entries(stylePropsOf(opening, scope, fileDir))) {
+		const key = sig.camelToKebab(prop);
+		styles[key] = (styles[key] || []).concat(values);
+	}
+	const actions = [];
+	const a11y = [];
+	const data = [];
+	for (const attr of opening.attributes) {
+		if (attr.type !== "JSXAttribute" || !attr.name) continue;
+		const name = attr.name.name;
+		// Normalize the event handler to its action name the SAME way the
+		// catalog scanner does (scanner/extract.js: `aname.slice(2).toLowerCase()`),
+		// so `onClick` -> "click" on BOTH sides. Without the slice the runtime
+		// candidate carries "onclick" while the catalog stores "click", and the
+		// decision matrix's action-overlap check never matches.
+		if (ACTION_ATTR_NAMES.has(name)) actions.push(name.slice(2).toLowerCase());
+		else if (name === "role") a11y.push("role:" + String(attrValueOf(opening, "role")));
+		else if (name.startsWith("aria-")) a11y.push(name + ":" + String(attrValueOf(opening, name)));
+		else if (name === "type" && (tag === "input" || tag === "button")) a11y.push("type:" + String(attrValueOf(opening, "type")));
+		else if (name === "contentEditable") a11y.push("contentEditable");
+		else if (name.startsWith("data-")) data.push(name + ":" + String(attrValueOf(opening, name)));
+	}
+	return { tag, styles, actions, a11y, data };
+}
+
+/**
+ * Name of the nearest enclosing component declaration (the JSX element's
+ * owning component: `const Foo = () => <...>` / `function Foo() { return <...> }`
+ * / `export const Foo = ...`). Returns null for the file's top-level JSX.
+ * Used by includeDynamic to map an element to the rendered-DOM signature of
+ * the component it belongs to.
+ *
+ * @param {object} node any AST node inside the component
+ * @param {object} sourceCode the ESLint SourceCode (provides ancestors)
+ * @returns {string|null} the component name
+ */
+function enclosingComponentName(node, sourceCode) {
+	const ancestors = sourceCode.getAncestors ? sourceCode.getAncestors(node) : [];
+	for (let i = ancestors.length - 1; i >= 0; i -= 1) {
+		const a = ancestors[i];
+		if (!a || !a.type) continue;
+		if (a.type === "VariableDeclarator" && a.id && a.id.name) {
+			const init = a.init;
+			if (init && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")) return a.id.name;
+		}
+		if (a.type === "FunctionDeclaration" && a.id && a.id.name) return a.id.name;
+		if (a.type === "ClassDeclaration" && a.id && a.id.name) return a.id.name;
+	}
+	return null;
+}
+
+module.exports = {
+	attrOf,
+	attrValueOf,
+	classNameCandidates,
+	stylePropsOf,
+	buildSignature,
+	enclosingComponentName,
+};