@everystack/cli 0.3.3 → 0.3.5

package/src/cli/component-audit.ts

@@ -0,0 +1,487 @@
+/**
+ * Component UI-bloat audit — source-side checks over the component model (Brick 5a-C).
+ *
+ * The remote bundle scanner (ui-bloat.ts) proves *that* design bloat ships and how
+ * much; it cannot say *where*. This is the actionable half of the loop: it runs over
+ * the faithful `ComponentDescriptor` model, so every finding carries the `file:line`
+ * occurrences an agent can edit and a structured `fix` it can apply. Verification is
+ * uniform — re-run the audit and the finding's occurrences drop to zero. The auditor
+ * is its own oracle.
+ *
+ * Same anchor and grouping as the bundle scanner (shared `canonicalizeStyle` /
+ * `isDesignStyle`), so a smell measured at the gate and the smell fixed in source are
+ * the same thing seen from two sides. Advisory only: refactoring is taste, so every
+ * finding is `warn`.
+ *
+ * Pure: takes `ComponentDescriptor[]`, returns findings. The model knows nothing about
+ * this file; this file imports the model, never the reverse.
+ */
+
+import type { AuditFinding, SourceLoc } from './bundle-audit.js';
+import type { ComponentDescriptor, JsxNode } from './component-model.js';
+import { canonicalizeStyle, isDesignStyle, type UiBloatBudget } from './ui-bloat.js';
+
+export { DEFAULT_UI_BLOAT_BUDGET, type UiBloatBudget } from './ui-bloat.js';
+import { DEFAULT_UI_BLOAT_BUDGET } from './ui-bloat.js';
+
+const VERIFY = 'rerun ui:audit; this finding clears when its occurrence count drops below the threshold';
+
+// ── File role: the architectural lens ──────────────────────────────────────────
+//
+// The goal is separation: keep expo-router screens (app/**) thin, and push reusable
+// UI into shared components — ideally a packages/ui in the monorepo. Duplication
+// *across screens* is the high-value "extract a component" signal; markup already in
+// a shared ui package is fine. Role is derived from the file's location (a fact about
+// where it lives), so it stays out of the neutral model and lives with the auditor.
+
+export type FileRole = 'screen' | 'ui' | 'component' | 'other';
+
+/** Classify a file by its place in the architecture (most specific first). */
+export function classifyRole(file: string): FileRole {
+  const p = file.replace(/\\/g, '/');
+  if (/\/packages\/[^/]*ui[^/]*\//.test(p)) return 'ui'; // a shared ui package
+  if (/\/components\//.test(p)) return 'component'; // a reusable component (incl. app/components)
+  if (/\/app\//.test(p)) return 'screen'; // an expo-router route file
+  return 'other';
+}
+
+const HEX = /#[0-9a-fA-F]{3,8}/g;
+
+interface StyleSite {
+  file: string;
+  line: number;
+  raw: string;
+  canon: string;
+}
+
+/** Flatten every design style literal across the tree into located sites. */
+function styleSites(components: ComponentDescriptor[]): StyleSite[] {
+  const sites: StyleSite[] = [];
+  for (const c of components) {
+    for (const s of c.styles) {
+      const canon = canonicalizeStyle(s.text);
+      if (!isDesignStyle(canon)) continue; // skip bare structural styling
+      sites.push({ file: c.file, line: s.line, raw: s.text, canon });
+    }
+  }
+  return sites;
+}
+
+function preview(raw: string, max = 80): string {
+  const flat = raw.replace(/\s+/g, ' ').trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max)}…`;
+}
+
+/**
+ * A style hand-written at many distinct call sites is an un-extracted component.
+ * Groups by canonical shape, reports each over-threshold group with all its
+ * `file:line`s and an extract-component fix.
+ */
+export function scanComponentRepeatedStyles(
+  components: ComponentDescriptor[],
+  budget: UiBloatBudget = DEFAULT_UI_BLOAT_BUDGET,
+): AuditFinding[] {
+  const groups = new Map<string, StyleSite[]>();
+  for (const site of styleSites(components)) {
+    const g = groups.get(site.canon);
+    if (g) g.push(site);
+    else groups.set(site.canon, [site]);
+  }
+
+  return [...groups.values()]
+    .filter((sites) => sites.length >= budget.styleRepeatWarn)
+    .sort((a, b) => b.length - a.length)
+    .slice(0, budget.topN)
+    .map((sites) => {
+      const occurrences: SourceLoc[] = sites.map((s) => ({ file: s.file, line: s.line }));
+      return {
+        severity: 'warn' as const,
+        check: 'ui-repeated-style' as const,
+        source: sites[0].canon,
+        detail: `a style is hand-written at ${sites.length} distinct call sites (${preview(sites[0].raw)}) — extract a component and reuse it`,
+        occurrences,
+        fix: {
+          kind: 'extract-component' as const,
+          summary: `Extract a component that renders this style once, then replace the ${sites.length} inline copies with it`,
+        },
+        verify: VERIFY,
+      };
+    });
+}
+
+/**
+ * Hardcoded hex colors: a single value repeated past the budget (it should be a
+ * token) and an ad-hoc palette of many distinct values (no token system). Both carry
+ * located occurrences and a replace-with-token fix.
+ */
+export function scanComponentHardcodedColors(
+  components: ComponentDescriptor[],
+  budget: UiBloatBudget = DEFAULT_UI_BLOAT_BUDGET,
+): AuditFinding[] {
+  const byHex = new Map<string, SourceLoc[]>();
+  const distinct = new Set<string>();
+  for (const site of styleSites(components)) {
+    for (const hex of site.raw.match(HEX) ?? []) {
+      const v = hex.toLowerCase();
+      distinct.add(v);
+      const locs = byHex.get(v);
+      const loc = { file: site.file, line: site.line };
+      if (locs) locs.push(loc);
+      else byHex.set(v, [loc]);
+    }
+  }
+
+  const findings: AuditFinding[] = [...byHex.entries()]
+    .filter(([, locs]) => locs.length >= budget.colorRepeatWarn)
+    .sort((a, b) => b[1].length - a[1].length)
+    .slice(0, budget.topN)
+    .map(([hex, locs]) => ({
+      severity: 'warn' as const,
+      check: 'ui-hardcoded-color' as const,
+      source: hex,
+      detail: `${hex} is hardcoded ${locs.length} times — replace it with a theme token so it changes in one place (and supports dark mode)`,
+      occurrences: locs,
+      fix: {
+        kind: 'replace-with-token' as const,
+        summary: `Define a theme token for ${hex} and replace each hardcoded use with it`,
+        from: hex,
+      },
+      verify: VERIFY,
+    }));
+
+  if (distinct.size >= budget.paletteWarn) {
+    findings.push({
+      severity: 'warn',
+      check: 'ui-hardcoded-color',
+      source: 'palette',
+      detail: `${distinct.size} distinct hardcoded hex colors across the components — this is an ad-hoc palette; define a token set instead of scattering raw colors`,
+      fix: {
+        kind: 'replace-with-token',
+        summary: 'Introduce a theme token set and migrate the raw hex colors onto it',
+      },
+      verify: VERIFY,
+    });
+  }
+  return findings;
+}
+
+// ── Check 3: "you rebuilt a ui primitive" (named, source-side only) ────────────
+//
+// The reference set is the ui package the app actually uses. We always seed the
+// everystack primitives (this is the everystack auditor, so we know our own export
+// list — naming our own components is fine), and union any `*/ui` imports so a
+// consumer's own design system is covered too. Matchers are a hand-authored
+// signature table gated by that set; deriving each signature from the ui component's
+// own source is the elegant target (see the spec), not a v1 requirement.
+
+/** everystack/ui's primitives — our own package, so the list is known. */
+const EVERYSTACK_UI = [
+  'Button', 'Card', 'TextInput', 'FormField', 'Avatar', 'Badge',
+  'LoadingState', 'EmptyState', 'ErrorState', 'DataTable',
+];
+
+const TOUCHABLES = new Set([
+  'Pressable', 'TouchableOpacity', 'TouchableHighlight', 'TouchableWithoutFeedback',
+]);
+
+/** True if an import source names a ui package (the framework's or a consumer's). */
+function isUiSource(from: string): boolean {
+  return from === '@everystack/ui' || /(^|\/)ui$/.test(from);
+}
+
+/** The primitive names available to the app: the everystack set plus any ui-package imports. */
+export function discoverUiExports(components: ComponentDescriptor[]): Set<string> {
+  const set = new Set<string>(EVERYSTACK_UI);
+  for (const c of components) {
+    for (const imp of c.imports) {
+      if (isUiSource(imp.from) && imp.from !== '@everystack/ui') {
+        for (const n of imp.names) set.add(n);
+      }
+    }
+  }
+  return set;
+}
+
+/** Map each imported name to the module it came from, for disambiguation. */
+function importSources(c: ComponentDescriptor): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const imp of c.imports) {
+    for (const n of imp.names) map.set(n, imp.from);
+    if (imp.default) map.set(imp.default, imp.from);
+  }
+  return map;
+}
+
+function walkNodes(nodes: JsxNode[], fn: (n: JsxNode) => void): void {
+  for (const n of nodes) {
+    fn(n);
+    walkNodes(n.children, fn);
+  }
+}
+
+/**
+ * Flag raw React Native primitives shaped to mimic a ui component that already
+ * exists. Each finding names the ui component and carries a use-ui-component fix.
+ */
+export function scanUiReimplementation(
+  components: ComponentDescriptor[],
+  available: Set<string> = discoverUiExports(components),
+): AuditFinding[] {
+  const findings: AuditFinding[] = [];
+  for (const c of components) {
+    const sources = importSources(c);
+    walkNodes(c.jsx, (n) => {
+      // Button: a touchable with background + rounded + onPress.
+      if (
+        available.has('Button') &&
+        TOUCHABLES.has(n.tag) &&
+        n.attrs.includes('onPress') &&
+        n.style &&
+        /background/i.test(n.style) &&
+        /(borderRadius|rounded)/i.test(n.style)
+      ) {
+        findings.push({
+          severity: 'warn',
+          check: 'ui-reimplementation',
+          source: `${c.file}:${n.line}`,
+          detail: `a hand-rolled <${n.tag}> with background + rounded + onPress reimplements <Button> — import Button from the ui package`,
+          occurrences: [{ file: c.file, line: n.line }],
+          fix: {
+            kind: 'use-ui-component',
+            summary: `Replace this <${n.tag}> with <Button> from the ui package`,
+            from: n.tag,
+            to: 'Button',
+          },
+          verify: VERIFY,
+        });
+        return;
+      }
+      // Raw TextInput: react-native's, styled like an input (the ui one is disambiguated by import source).
+      if (
+        available.has('TextInput') &&
+        n.tag === 'TextInput' &&
+        sources.get('TextInput') === 'react-native' &&
+        n.style &&
+        /(border|padding)/i.test(n.style)
+      ) {
+        findings.push({
+          severity: 'warn',
+          check: 'ui-reimplementation',
+          source: `${c.file}:${n.line}`,
+          detail: `a raw <TextInput> from react-native with input styling — use <TextInput> or <FormField> from the ui package for consistent styling and validation`,
+          occurrences: [{ file: c.file, line: n.line }],
+          fix: {
+            kind: 'use-ui-component',
+            summary: 'Use <TextInput> or <FormField> from the ui package',
+            from: 'TextInput',
+            to: 'FormField',
+          },
+          verify: VERIFY,
+        });
+      }
+    });
+  }
+  return findings;
+}
+
+// ── Checks 4 & 5: size / complexity, and structural duplication ────────────────
+//
+// Mechanical, universal, config-free defaults. Output is always a "candidate"
+// (warn), never a verdict — decomposition is taste, the ceiling we do not cross.
+
+/** Per-component size/complexity thresholds and the duplication floor. */
+export interface ComponentBudget {
+  /** Line span past which a component is a split candidate. */
+  linesWarn: number;
+  /** Total JSX nodes in one component. */
+  jsxCountWarn: number;
+  /** Max JSX nesting depth. */
+  depthWarn: number;
+  /** Hooks in one component (a responsibilities proxy). */
+  hookCountWarn: number;
+  /** Props on one component. */
+  propCountWarn: number;
+  /** A duplicated subtree must have at least this many nodes to count (no trivial dup). */
+  dupMinNodes: number;
+  /** A subtree recurring this many times is flagged. */
+  dupRepeatWarn: number;
+  /** Cap on findings per check. */
+  topN: number;
+}
+
+/** Defaults against RN/Expo norms, not round numbers: a 200+ line component, 40+
+ *  JSX nodes, depth past 7, or 10+ hooks/props in one file is worth a second look. */
+export const DEFAULT_COMPONENT_BUDGET: ComponentBudget = {
+  linesWarn: 200,
+  jsxCountWarn: 40,
+  depthWarn: 7,
+  hookCountWarn: 10,
+  propCountWarn: 10,
+  dupMinNodes: 5,
+  dupRepeatWarn: 3,
+  topN: 12,
+};
+
+function countNodes(n: JsxNode): number {
+  return 1 + n.children.reduce((s, c) => s + countNodes(c), 0);
+}
+function maxDepth(n: JsxNode): number {
+  return 1 + n.children.reduce((d, c) => Math.max(d, maxDepth(c)), 0);
+}
+function treeStat(roots: JsxNode[], f: (n: JsxNode) => number): number {
+  return roots.reduce((m, r) => Math.max(m, f(r)), 0);
+}
+
+/**
+ * Per-component size/complexity gate. Each tripped dimension is a split *candidate*
+ * (warn), located at the component, with a split-component fix.
+ */
+export function scanComponentSize(
+  components: ComponentDescriptor[],
+  budget: ComponentBudget = DEFAULT_COMPONENT_BUDGET,
+): AuditFinding[] {
+  const findings: AuditFinding[] = [];
+  for (const c of components) {
+    const jsxCount = c.jsx.reduce((s, r) => s + countNodes(r), 0);
+    const depth = treeStat(c.jsx, maxDepth);
+    const at: SourceLoc[] = [{ file: c.file, line: c.line }];
+    const fix = {
+      kind: 'split-component' as const,
+      summary: `Split ${c.name} into smaller components`,
+    };
+
+    const dims: Array<[boolean, AuditFinding['check'], string]> = [
+      [c.lines >= budget.linesWarn, 'component-size', `is ${c.lines} lines`],
+      [jsxCount >= budget.jsxCountWarn, 'component-size', `has ${jsxCount} JSX nodes`],
+      [c.props.length >= budget.propCountWarn, 'component-size', `takes ${c.props.length} props`],
+      [depth >= budget.depthWarn, 'jsx-depth', `nests JSX ${depth} deep`],
+      [c.hooks.length >= budget.hookCountWarn, 'hook-count', `uses ${c.hooks.length} hooks`],
+    ];
+    for (const [tripped, check, why] of dims) {
+      if (!tripped) continue;
+      findings.push({
+        severity: 'warn',
+        check,
+        source: `${c.file}:${c.line}`,
+        detail: `${c.name} ${why} — a split candidate, not a verdict (decomposition is your call)`,
+        occurrences: at,
+        fix,
+        verify: VERIFY,
+      });
+    }
+  }
+  return findings.slice(0, budget.topN);
+}
+
+/** A stable structural signature of a JSX subtree — tag nesting only, text-free. */
+function structuralSig(n: JsxNode): string {
+  return n.children.length ? `${n.tag}(${n.children.map(structuralSig).join(',')})` : n.tag;
+}
+
+/**
+ * Structural duplication: identical JSX subtrees (above the size floor) recurring
+ * across the codebase — copy-paste that should become a shared component.
+ */
+export function scanDuplicateJsx(
+  components: ComponentDescriptor[],
+  budget: ComponentBudget = DEFAULT_COMPONENT_BUDGET,
+): AuditFinding[] {
+  const groups = new Map<string, { size: number; locs: SourceLoc[] }>();
+  for (const c of components) {
+    const visit = (n: JsxNode): void => {
+      const size = countNodes(n);
+      if (size >= budget.dupMinNodes) {
+        const sig = structuralSig(n);
+        const g = groups.get(sig);
+        if (g) g.locs.push({ file: c.file, line: n.line });
+        else groups.set(sig, { size, locs: [{ file: c.file, line: n.line }] });
+      }
+      for (const child of n.children) visit(child);
+    };
+    for (const root of c.jsx) visit(root);
+  }
+
+  return [...groups.values()]
+    .filter((g) => g.locs.length >= budget.dupRepeatWarn)
+    .sort((a, b) => b.size * b.locs.length - a.size * a.locs.length)
+    .slice(0, budget.topN)
+    .map((g) => {
+      const screens = new Set(
+        g.locs.filter((l) => classifyRole(l.file) === 'screen').map((l) => l.file),
+      );
+      const acrossScreens = screens.size >= 2;
+      return {
+        severity: 'warn' as const,
+        check: 'duplicate-jsx' as const,
+        source: `${g.locs.length}×${g.size}-node`,
+        detail:
+          `a ${g.size}-node JSX structure is repeated at ${g.locs.length} sites` +
+          (acrossScreens ? ` across ${screens.size} screens` : '') +
+          ` — extract a reusable component` +
+          (acrossScreens ? ' (e.g. into packages/ui)' : ''),
+        occurrences: g.locs,
+        fix: {
+          kind: 'extract-component' as const,
+          summary: `Extract the repeated ${g.size}-node structure into one reusable component`,
+        },
+        verify: VERIFY,
+      };
+    });
+}
+
+/**
+ * Whole-component structural duplication: N components with an identical JSX
+ * structure are one component waiting to happen. The stronger sibling of
+ * scanDuplicateJsx — it compares entire components, not subtrees, so it catches
+ * "these two screens/cards are the same, parameterize the difference".
+ */
+export function scanDuplicateComponents(
+  components: ComponentDescriptor[],
+  budget: ComponentBudget = DEFAULT_COMPONENT_BUDGET,
+): AuditFinding[] {
+  const groups = new Map<string, ComponentDescriptor[]>();
+  for (const c of components) {
+    const jsxCount = c.jsx.reduce((s, r) => s + countNodes(r), 0);
+    if (jsxCount < budget.dupMinNodes) continue; // skip trivial components
+    const sig = c.jsx.map(structuralSig).join('|');
+    if (!sig) continue;
+    const g = groups.get(sig);
+    if (g) g.push(c);
+    else groups.set(sig, [c]);
+  }
+
+  return [...groups.values()]
+    .filter((g) => g.length >= 2)
+    .sort((a, b) => b.length - a.length)
+    .slice(0, budget.topN)
+    .map((g) => {
+      const names = g.map((c) => c.name).join(', ');
+      return {
+        severity: 'warn' as const,
+        check: 'duplicate-component' as const,
+        source: names,
+        detail: `${g.length} components share an identical structure (${names}) — unify into one reusable component (parameterize what differs), ideally in packages/ui`,
+        occurrences: g.map((c) => ({ file: c.file, line: c.line })),
+        fix: {
+          kind: 'unify-component' as const,
+          summary: `Replace ${names} with one parameterized component in a shared ui package`,
+        },
+        verify: VERIFY,
+      };
+    });
+}
+
+/** The combined source-side entry — what `ui:audit` and the MCP call. */
+export function auditComponents(
+  components: ComponentDescriptor[],
+  budget: UiBloatBudget = DEFAULT_UI_BLOAT_BUDGET,
+): AuditFinding[] {
+  return [
+    ...scanComponentRepeatedStyles(components, budget),
+    ...scanComponentHardcodedColors(components, budget),
+    ...scanUiReimplementation(components),
+    ...scanComponentSize(components),
+    ...scanDuplicateComponents(components),
+    ...scanDuplicateJsx(components),
+  ];
+}