@assure-one/design-system 1.31.0 → 1.32.0

package/codemods/transforms/cm-15-dom-selectors.mjs

@@ -0,0 +1,573 @@
+/**
+ * CM-15 — DOM-selector finder (class X, report-only; plan §29, registry C-DOM-*).
+ *
+ * Finds consumer code that depends on the internal DOM of design-system
+ * components and maps each hit to a compatibility-registry id:
+ *
+ * - class tokens on a DS component that reach into its children
+ *   (descendant/child arbitrary variants, `*:`, `has-[…]`, nth/first/last-child)
+ * - the same tokens on a wrapper element whose JSX subtree holds a DS component
+ * - file-level group references to groups or attributes the DS sets
+ *   (`group-data-[labels…]`, `…/sidebar`, `…/row`)
+ * - DOM queries (`querySelector`, `closest`, `matches`, Playwright `locator`)
+ *   whose selector names DS internals, and header/label text matching
+ * - text queries for copy the DS renders itself ("Next", "Notifications"…)
+ * - tests that read the DS `dist` bundle
+ * - global CSS selectors that name DS internals
+ *
+ * Findings without a registry id are reported as `unregistered`: they are
+ * DOM coupling the registry does not track yet. Radix `data-state`-style
+ * attributes, ARIA roles and cmdk attributes are permanent contracts
+ * (P-DATA-STATE, P-ROLES, C-CMDK-ATTR) and are not reported.
+ *
+ * Never modifies files.
+ */
+import { analyse, splitVariants } from "../lib/jsx.mjs";
+import { cssSelectors } from "../lib/css-selectors.mjs";
+
+export const meta = {
+  id: "CM-15",
+  title: "DOM-selector finder on design-system components",
+  class: "X",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code", "css"],
+  includeTests: true,
+  usesTypeScript: true,
+  registryIds: [
+    "C-DOM-01",
+    "C-DOM-02",
+    "C-DOM-03",
+    "C-DOM-04",
+    "C-DOM-05",
+    "C-DOM-06",
+    "C-DOM-07",
+    "C-DOM-09",
+    "C-DOM-10",
+    "C-DOM-11",
+    "C-DOM-12",
+    "C-DOM-13",
+    "C-DOM-14",
+    "C-DOM-15",
+    "C-DOM-16",
+    "C-DOM-17",
+    "C-DOM-18",
+    "C-DOM-19",
+    "C-TOAST-ARIALABEL",
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// Token classification
+
+const SIBLING_OR_CHILD = /^&\s*(?:_|>|\+|~)|^&\s*:(?:has|is|where)\(|^&_|^&>/;
+
+/**
+ * How a class token reaches into DOM it does not own, or `null`.
+ * Returns `{ kind, selector }`; `selector` is the variant text (for matching).
+ */
+export function domReach(token) {
+  const { variants } = splitVariants(token.replace(/^!/, ""));
+  for (const v of variants) {
+    const bare = v.replace(/^!/, "");
+    if (bare === "*" || bare === "**")
+      return { kind: bare === "*" ? "child" : "descendant", selector: bare };
+    if (bare.startsWith("[") && bare.endsWith("]") && bare.includes("&")) {
+      const inner = bare.slice(1, -1);
+      const afterAmp = inner.slice(inner.indexOf("&"));
+      if (SIBLING_OR_CHILD.test(afterAmp) || /[_>+~]/.test(afterAmp.replace(/\[[^\]]*\]/g, ""))) {
+        return { kind: /^&\s*>|^&>/.test(afterAmp) ? "child" : "descendant", selector: inner };
+      }
+      continue; // self-only (`[&[data-state=open]]`, `[&:hover]`)
+    }
+    if (/^(?:group-|peer-)?has-\[/.test(bare)) {
+      return {
+        kind: "has",
+        selector: bare.replace(/^(?:group-|peer-)?has-\[/, "").replace(/\]$/, ""),
+      };
+    }
+    if (
+      /^(?:nth|nth-last|first|last|only)-(?:child|of-type)?\[?/.test(bare) &&
+      /child|\[/.test(bare)
+    ) {
+      // `nth-[2]:` etc. style the element's own position: not DS internals.
+      continue;
+    }
+  }
+  return null;
+}
+
+/** Group references the DS provides: `{ group, attribute }` or `null`. */
+export function groupReach(token) {
+  const { variants } = splitVariants(token.replace(/^!/, ""));
+  for (const v of variants) {
+    const m = v.match(/^(?:group|peer)-(?:data-\[([a-z-]+)[^\]]*\]|[^/]*)(?:\/([a-z][a-z-]*))?$/);
+    if (!m || !v.startsWith("group")) continue;
+    const attribute = m[1] ?? null;
+    const group = m[2] ?? null;
+    if (attribute || group) return { attribute, group, variant: v };
+  }
+  return null;
+}
+
+// Attributes the DS sets on its own elements that are not permanent
+// contracts. Radix/ARIA-style attributes (state, side, align, orientation,
+// disabled, highlighted) are P-DATA-STATE and skipped.
+const PERMANENT_ATTRIBUTES = new Set([
+  "state",
+  "side",
+  "align",
+  "orientation",
+  "disabled",
+  "highlighted",
+  "placeholder",
+]);
+
+// Named groups declared inside DS components, with the components that own them.
+const DS_GROUPS = {
+  sidebar: { components: /^Sidebar/, registryId: "C-DOM-06" },
+  "brand-trigger": { components: /^SidebarBrandSwitcher/, registryId: "C-DOM-06" },
+  link: { components: /^Sidebar/, registryId: "C-DOM-06" },
+  row: {
+    components: /^(?:Table|DataTable|FolderTree|DocumentDetailPanel)/,
+    registryId: "C-DOM-07",
+  },
+  agreement: { components: /^AgreementViewer$/, registryId: "C-DOM-01" },
+  step: { components: /^AgreementViewer$/, registryId: "C-DOM-01" },
+  dash: { components: /^DashGrid/, registryId: null },
+  bubble: { components: /^MessageBubble/, registryId: null },
+  addon: { components: /^Proposal/, registryId: null },
+  timelogger: { components: /^TimeLogger/, registryId: null },
+  "attachment-chip": { components: /^AttachmentChip/, registryId: null },
+};
+
+// DS-set attributes and the registry id they belong to.
+const DS_ATTRIBUTES = {
+  labels: "C-DOM-06",
+  collapsible: "C-DOM-06",
+  "with-toolbar": "C-DOM-18",
+  "detail-open": null,
+  peek: null,
+  "sticky-stack-host": null,
+  "sticky-stack-layer": null,
+  "sticky-stack-section-header": null,
+  "sticky-stack-sticky": null,
+  slot: null,
+};
+
+// ---------------------------------------------------------------------------
+// Component rules (tag scope). Order matters: first match wins.
+
+const has = (re) => (reach) => re.test(reach.selector);
+const any = () => true;
+const TAG_RULES = [
+  { id: "C-DOM-01", components: /^AgreementViewer$/, test: any },
+  { id: "C-DOM-02", components: /^ProposalSignatureBlock$/, test: any },
+  { id: "C-DOM-03", components: /^MasterDetailLayout$/, test: (r) => r.kind === "child" },
+  { id: "C-DOM-04", components: /^FileUpload$/, test: has(/label/) },
+  {
+    id: "C-DOM-05",
+    components: /^(?:IconTile|Button|LinkButton|SubmitButton)$/,
+    test: has(/(?:^|[_>\s])svg\b/),
+  },
+  { id: "C-DOM-06", components: /^Sidebar/, test: any },
+  {
+    id: "C-DOM-09",
+    components: /^(?:Table|TableBody|TableHeader|DataTable|DataTableBody)$/,
+    test: has(/(?:^|[_>\s])(?:tr|th|td)\b/),
+  },
+  {
+    id: "C-DOM-10",
+    components: /^(?:Select|SelectTrigger)$/,
+    test: has(/(?:^|[_>\s])(?:span|svg)\b/),
+  },
+  { id: "C-DOM-11", components: /^Accordion/, test: any },
+  { id: "C-DOM-12", components: /^ProgressBar$/, test: has(/role/) },
+  { id: "C-DOM-13", components: /^(?:DataTableHeader|DataTableHead)$/, test: has(/button/) },
+  { id: "C-DOM-15", components: /^DocumentRequestCard/, test: any },
+  {
+    id: "C-DOM-16",
+    components: /^(?:MetadataGrid|DataItem)$/,
+    test: has(/(?:^|[_>\s])(?:dt|dd|span)\b/),
+  },
+];
+
+const ruleFor = (component, reach) =>
+  TAG_RULES.find((r) => r.components.test(component) && r.test(reach)) ?? null;
+
+/**
+ * Whether an unmapped selector on a *wrapper* element is worth reporting: it
+ * must name an element, `*`, or a `data-`/`role` attribute. A wrapper selector
+ * that only targets classes of the app or of another library
+ * (`[&_.react-pdf__Page]`), or only a pseudo-class (`has-[:focus-visible]`),
+ * is the consumer's own markup. On a design-system tag every reaching selector
+ * is reported, class targets included: those classes are inside DS markup.
+ */
+const namesStructure = (selector) =>
+  /(?:^|[\s_>+~([])(?:\*|[a-z][a-z0-9]*\b)/.test(selector.replace(/\.[\w-]+/g, "")) ||
+  /\[(?:data-|role)/.test(selector);
+
+// ---------------------------------------------------------------------------
+// DOM queries and text
+
+const QUERY_METHODS = new Set([
+  "querySelector",
+  "querySelectorAll",
+  "closest",
+  "matches",
+  "locator",
+]);
+const TEXT_QUERY = /^(?:get|getAll|query|queryAll|find|findAll)By(?:Text|LabelText|Title)$/;
+const ROLE_QUERY = /^(?:get|getAll|query|queryAll|find|findAll)ByRole$/;
+
+// Copy the DS renders by default, with the components that render it.
+const DS_TEXT = [
+  { text: "Next", components: /^AgreementViewer$/, registryId: "C-DOM-01" },
+  {
+    text: "Notifications",
+    components: /^(?:Toaster|ToastProvider|useToast|toast)$/,
+    registryId: "C-TOAST-ARIALABEL",
+  },
+  {
+    text: "Next page",
+    components: /^(?:Pagination|DataTablePagination|DataTableView)/,
+    registryId: null,
+  },
+  {
+    text: "Previous page",
+    components: /^(?:Pagination|DataTablePagination|DataTableView)/,
+    registryId: null,
+  },
+  { text: "Clear search", components: /^SearchInput$/, registryId: null },
+  { text: "Back", components: /^MasterDetailLayout$/, registryId: null },
+];
+
+const mentions = (text, pattern) => {
+  const names = new Set(text.match(/\b[A-Za-z_$][\w$]*\b/g) ?? []);
+  return [...names].filter((n) => pattern.test(n));
+};
+
+const selectorFindings = (selector) => {
+  const out = [];
+  if (/:has\([^)]*data-esign-cover/.test(selector))
+    out.push({ id: "C-DOM-17", why: "esign-cover" });
+  if (/data-radix-select-viewport/.test(selector))
+    out.push({ id: "C-DOM-19", why: "radix-select-viewport" });
+  if (/aria-label=["']?Notifications/.test(selector))
+    out.push({ id: "C-TOAST-ARIALABEL", why: "toast-region" });
+  for (const m of selector.matchAll(/\[data-([a-z][a-z-]*)/g)) {
+    const attribute = m[1];
+    if (attribute in DS_ATTRIBUTES)
+      out.push({ id: DS_ATTRIBUTES[attribute], why: `data-${attribute}` });
+  }
+  const seen = new Set();
+  return out.filter((f) => {
+    const key = `${f.id}:${f.why}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+};
+
+// ---------------------------------------------------------------------------
+
+export function transform(file, { ts }) {
+  if (file.kind === "css") return { findings: cssFindings(file) };
+  return codeFindings(file, ts);
+}
+
+function cssFindings(file) {
+  if (file.test) return [];
+  const findings = [];
+  for (const { selector, line } of cssSelectors(file.source)) {
+    for (const hit of selectorFindings(selector)) {
+      findings.push({
+        line,
+        registryId: hit.id,
+        rule: "css-selector",
+        scope: "selector",
+        component: null,
+        match: selector.slice(0, 200),
+        confidence: hit.id ? "high" : "medium",
+      });
+    }
+  }
+  return findings;
+}
+
+function codeFindings(file, ts) {
+  const facts = analyse(ts, file.source, file.rel);
+  const findings = [];
+  const add = (f) => findings.push({ confidence: "high", component: null, ...f });
+  const text = file.source;
+  const used = facts.componentsUsed;
+  const usedList = [...used].sort();
+
+  if (!file.test) {
+    // 1. Tokens on DS component tags.
+    for (const usage of facts.usages) {
+      for (const { token, line } of usage.tokens) {
+        const reach = domReach(token);
+        if (!reach) continue;
+        const rule = ruleFor(usage.component, reach) ?? ruleFor(usage.base, reach);
+        add({
+          line,
+          registryId: rule?.id ?? null,
+          rule: rule ? "class-on-component" : "unregistered-class-on-component",
+          scope: "tag",
+          component: usage.component,
+          match: token,
+          confidence: rule ? "high" : "medium",
+        });
+      }
+    }
+
+    // 2. Descendant tokens on wrappers of DS components.
+    for (const el of facts.rawElements) {
+      if (!el.dsDescendants.length) continue;
+      for (const { token, line } of el.tokens) {
+        const reach = domReach(token);
+        if (!reach || reach.kind === "child") continue;
+        const rules = el.dsDescendants
+          .map((c) => ({ c, rule: ruleFor(c, reach) }))
+          .filter((x) => x.rule && x.rule.test !== any);
+        const hit = rules[0];
+        if (!hit && !namesStructure(reach.selector)) continue;
+        add({
+          line,
+          registryId: hit?.rule.id ?? null,
+          rule: hit ? "class-on-wrapper" : "unregistered-class-on-wrapper",
+          scope: "ancestor",
+          component: hit?.c ?? el.dsDescendants.join(", "),
+          match: token,
+          confidence: hit ? "medium" : "low",
+        });
+      }
+    }
+
+    // 3. File-level group and attribute references.
+    const ownGroups = new Set(
+      facts.rawElements.flatMap((el) =>
+        el.tokens.map((t) => t.token.match(/^group\/([a-z][a-z-]*)$/)?.[1]).filter(Boolean),
+      ),
+    );
+    const onTags = new Set(facts.usages.flatMap((u) => u.tokens.map((t) => `${t.line}${t.token}`)));
+    for (const { token, line } of facts.fileTokens) {
+      const g = groupReach(token);
+      if (!g) continue;
+      if (g.attribute && PERMANENT_ATTRIBUTES.has(g.attribute) && g.group !== "row") continue;
+      let registryId;
+      let component;
+      if (g.group && DS_GROUPS[g.group]) {
+        const owner = DS_GROUPS[g.group];
+        const owners = usedList.filter((c) => owner.components.test(c));
+        if (!owners.length) continue;
+        if (ownGroups.has(g.group) && g.group !== "row") continue;
+        registryId = owner.registryId;
+        component = owners.join(", ");
+      } else if (g.attribute && g.attribute in DS_ATTRIBUTES && usedList.length) {
+        registryId = DS_ATTRIBUTES[g.attribute];
+        component = null;
+      } else continue;
+      if (onTags.has(`${line}${token}`) && domReach(token)) continue; // already reported
+      add({
+        line,
+        registryId,
+        rule: registryId ? "group-reference" : "unregistered-group-reference",
+        scope: "file",
+        component,
+        match: token,
+        confidence: "medium",
+      });
+    }
+
+    // 4. MetadataGrid / DataItem wrappers style dt/dd from anywhere in the file.
+    if (used.has("MetadataGrid") || used.has("DataItem")) {
+      const reported = new Set(findings.map((f) => `${f.line}${f.match}`));
+      for (const { token, line } of facts.fileTokens) {
+        const reach = domReach(token);
+        if (!reach || !/(?:^|[_>\s])(?:dt|dd)\b/.test(reach.selector)) continue;
+        if (reported.has(`${line}${token}`)) continue;
+        add({
+          line,
+          registryId: "C-DOM-16",
+          rule: "class-in-file",
+          scope: "file",
+          component: usedList.filter((c) => /^(?:MetadataGrid|DataItem)$/.test(c)).join(", "),
+          match: token,
+          confidence: "medium",
+        });
+      }
+    }
+  }
+
+  // 5. Calls: DOM queries, text queries, dist parsing.
+  const argText = (node) => {
+    if (!node) return null;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+    if (ts.isIdentifier(node)) {
+      const parts = facts.resolveConstant(node.text);
+      return parts ? parts.map((p) => p.text).join("") : null;
+    }
+    return null;
+  };
+  const dataTableFile = /\bDataTableView\b/.test(text);
+  const agreementFile = used.has("AgreementViewer") || /\bAgreementViewer\b/.test(text);
+
+  const visit = (node) => {
+    if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      const name = ts.isPropertyAccessExpression(callee)
+        ? callee.name.text
+        : ts.isIdentifier(callee)
+          ? callee.text
+          : null;
+      const first = argText(node.arguments[0]);
+      const line = facts.lineOf(node);
+      if (name && QUERY_METHODS.has(name) && first !== null) {
+        const hits = selectorFindings(first);
+        for (const hit of hits) {
+          add({
+            line,
+            registryId: hit.id,
+            rule: "dom-query",
+            scope: "call",
+            match: `${name}(${JSON.stringify(first)})`,
+            confidence: hit.id ? "high" : "medium",
+          });
+        }
+        if (!hits.length && name !== "locator" && !file.test) {
+          const tag = first.trim();
+          if (agreementFile && /^button\b/.test(tag)) {
+            add({
+              line,
+              registryId: "C-DOM-01",
+              rule: "dom-query",
+              scope: "call",
+              component: "AgreementViewer",
+              match: `${name}(${JSON.stringify(first)})`,
+            });
+          } else if (dataTableFile && /^(?:th|thead)\b/.test(tag)) {
+            add({
+              line,
+              registryId: "C-DOM-14",
+              rule: "dom-query",
+              scope: "call",
+              component: "DataTableView",
+              match: `${name}(${JSON.stringify(first)})`,
+            });
+          } else if (
+            dataTableFile &&
+            /^button\b/.test(tag) &&
+            /\bth\b|header/i.test(node.expression.getText(facts.sf))
+          ) {
+            add({
+              line,
+              registryId: "C-DOM-14",
+              rule: "dom-query",
+              scope: "call",
+              component: "DataTableView",
+              match: `${name}(${JSON.stringify(first)})`,
+            });
+          }
+        }
+      }
+      if (name && (TEXT_QUERY.test(name) || ROLE_QUERY.test(name) || name === "getByText")) {
+        let literal = TEXT_QUERY.test(name) ? first : null;
+        if (
+          ROLE_QUERY.test(name) &&
+          node.arguments[1] &&
+          ts.isObjectLiteralExpression(node.arguments[1])
+        ) {
+          const prop = node.arguments[1].properties.find(
+            (p) => ts.isPropertyAssignment(p) && p.name.getText(facts.sf) === "name",
+          );
+          literal = prop ? argText(prop.initializer) : null;
+        }
+        const entry = literal && DS_TEXT.find((d) => d.text === literal.trim());
+        const owners = entry ? mentions(text, entry.components) : [];
+        if (entry && owners.length) {
+          const shown = ROLE_QUERY.test(name)
+            ? `${name}(…, { name: ${JSON.stringify(literal)} })`
+            : `${name}(${JSON.stringify(literal)})`;
+          add({
+            line,
+            registryId: entry.registryId,
+            rule: entry.registryId ? "text-query" : "unregistered-text-query",
+            scope: "call",
+            component: owners.join(", "),
+            match: shown,
+            confidence: "medium",
+          });
+        }
+      }
+      if (name && /^(?:readFileSync|readFile|require|resolve)$/.test(name)) {
+        const path = node.arguments
+          .map((a) => argText(a))
+          .find((a) => a && /design-system\/dist\b|(?:^|\/)dist\/index\.js$/.test(a));
+        if (path) {
+          const owners = mentions(text, /^Proposal/);
+          add({
+            line,
+            registryId: owners.length ? "C-DOM-02" : null,
+            rule: owners.length ? "dist-parsing" : "unregistered-dist-parsing",
+            scope: "call",
+            component: owners.join(", ") || null,
+            match: `${name}(${JSON.stringify(path.slice(0, 160))})`,
+          });
+        }
+      }
+    }
+    // Header/label text matching in production code.
+    if (
+      !file.test &&
+      ts.isBinaryExpression(node) &&
+      /^===?$|^!==?$/.test(node.operatorToken.getText(facts.sf))
+    ) {
+      const sides = [node.left, node.right];
+      const lit = sides.map(argText).find((v) => v !== null);
+      const other = sides.find((s) => argText(s) === null);
+      const reads = other && /\.(?:textContent|innerText)\b/.test(other.getText(facts.sf));
+      if (lit !== undefined && reads) {
+        const entry = DS_TEXT.find((d) => d.text === lit.trim());
+        if (entry && mentions(text, entry.components).length) {
+          add({
+            line: facts.lineOf(node),
+            registryId: entry.registryId,
+            rule: "text-match",
+            scope: "call",
+            component: mentions(text, entry.components).join(", "),
+            match: node.getText(facts.sf).slice(0, 160),
+          });
+        }
+      }
+    }
+    if (
+      !file.test &&
+      dataTableFile &&
+      ts.isPropertyAccessExpression(node) &&
+      /^(?:textContent|innerText)$/.test(node.name.text)
+    ) {
+      const target = node.expression.getText(facts.sf);
+      if (/header|\bth\b|cell/i.test(target)) {
+        add({
+          line: facts.lineOf(node),
+          registryId: "C-DOM-14",
+          rule: "text-match",
+          scope: "call",
+          component: "DataTableView",
+          match: node.getText(facts.sf).slice(0, 160),
+          confidence: "medium",
+        });
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(facts.sf);
+
+  return {
+    findings,
+    parseErrors: facts.parseErrors,
+    context: { components: usedList },
+  };
+}