@everystack/cli 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -33,6 +33,10 @@
       "types": "./src/cli/audit-api.ts",
       "default": "./src/cli/audit-api.ts"
     },
+    "./audit/source": {
+      "types": "./src/cli/audit-source-api.ts",
+      "default": "./src/cli/audit-source-api.ts"
+    },
     "./client": {
       "types": "./src/client/index.ts",
       "default": "./src/client/index.ts"
@@ -69,6 +73,7 @@
     "node-forge": "1.4.0",
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
+    "typescript": "5.9.3",
     "@everystack/model": "0.3.3"
   },
   "peerDependencies": {
@@ -135,8 +140,7 @@
     "drizzle-orm": "0.41.0",
     "jest": "29.7.0",
     "react": "19.2.6",
-    "ts-jest": "29.4.9",
-    "typescript": "5.9.3"
+    "ts-jest": "29.4.9"
   },
   "scripts": {
     "test": "jest",

package/src/cli/audit-api.ts

@@ -1,16 +1,23 @@
 /**
  * Public audit surface — `@everystack/cli/audit`.
  *
- * The governance MCP imports these pure scanners directly to gate authoring and
- * pre-deploy: the secret-leak checks (bundle-audit) and the weight/size checks
- * (bundle-weight), plus the bundle composition helpers they build on. Pure,
+ * The bundle-side scanners: secret-leak (bundle-audit), weight/size (bundle-weight),
+ * remote UI-bloat (ui-bloat), and the composition helpers they build on. Pure,
  * filesystem-free, no CLI/IO coupling — feed them text or {path, size} lists.
+ *
+ * IMPORTANT: this barrel is kept TYPESCRIPT-FREE on purpose. The source-side AST
+ * scanners (component-audit / component-model) pull in the `typescript` compiler, so
+ * they live behind `@everystack/cli/audit/source` instead. The governance MCP imports
+ * this light barrel (e.g. SECRET_PATTERNS) and bundles small; importing the source
+ * subpath would drag the ~10MB compiler into the hook hot-path.
  */
 
 export {
   // types
   type AuditFinding,
   type SecretPattern,
+  type SourceLoc,
+  type FixDescriptor,
   // leak scanners
   SECRET_PATTERNS,
   redact,
@@ -40,6 +47,24 @@ export {
   resolveWeightBudget,
 } from './bundle-weight.js';
 
+export {
+  // types
+  type UiBloatBudget,
+  // UI-bloat scanners (remote / bundle side of the design-bloat loop)
+  DEFAULT_UI_BLOAT_BUDGET,
+  canonicalizeStyle,
+  isDesignStyle,
+  extractStyleLiterals,
+  scanRepeatedStyles,
+  scanHardcodedColors,
+  scanBundleUiBloat,
+  resolveUiBloatBudget,
+} from './ui-bloat.js';
+
+// NOTE: the source-side AST scanners (component-audit + component-model) moved to
+// `@everystack/cli/audit/source` — they pull in `typescript`, which this barrel must
+// stay free of. See audit-source-api.ts.
+
 export {
   // composition (input to scanDependencyWeight)
   type Composition,

package/src/cli/audit-source-api.ts

@@ -0,0 +1,36 @@
+/**
+ * Source-side audit surface — `@everystack/cli/audit/source`.
+ *
+ * The `.tsx` AST scanners: the faithful component model (`component-model`) and the
+ * source-side UI-bloat checks built on it (`component-audit`). These pull in the
+ * `typescript` compiler, so they are kept OUT of the light `@everystack/cli/audit`
+ * barrel and exposed here instead. Import this only when you need to parse/analyze
+ * component source — never from a hot path (it drags ~10MB of compiler).
+ */
+
+export {
+  // source-side UI-bloat checks (located + fixable + self-verifying)
+  type ComponentBudget,
+  type FileRole,
+  DEFAULT_COMPONENT_BUDGET,
+  classifyRole,
+  scanComponentRepeatedStyles,
+  scanComponentHardcodedColors,
+  scanUiReimplementation,
+  discoverUiExports,
+  scanComponentSize,
+  scanDuplicateJsx,
+  scanDuplicateComponents,
+  auditComponents,
+} from './component-audit.js';
+
+export {
+  // types — the faithful component model (shared with the 5b frontend Module)
+  type ComponentDescriptor,
+  type ImportRef,
+  type JsxNode,
+  type StyleLiteral,
+  // the source-side foundation: parse/discover .tsx into neutral descriptors
+  parseComponents,
+  discoverComponents,
+} from './component-model.js';

package/src/cli/bundle-audit.ts

@@ -17,6 +17,29 @@
  * command's operator-run path.
  */
 
+/** A source location an agent can open and edit. */
+export interface SourceLoc {
+  file: string;
+  line: number;
+}
+
+/** A machine-actionable remediation for a finding. Source-side findings carry one
+ *  so the agent can apply it without re-deriving the fix from prose. */
+export interface FixDescriptor {
+  kind:
+    | 'extract-component'
+    | 'replace-with-token'
+    | 'use-ui-component'
+    | 'split-component'
+    | 'unify-component';
+  summary: string;
+  /** extract-component: a suggested name for the new component. */
+  suggestedName?: string;
+  /** replace-with-token: the raw value to replace and the token to use. */
+  from?: string;
+  to?: string;
+}
+
 export interface AuditFinding {
   severity: 'fail' | 'warn';
   check:
@@ -30,9 +53,26 @@ export interface AuditFinding {
     | 'total-weight'
     | 'data-in-bundle'
     | 'js-weight'
-    | 'dep-weight';
+    | 'dep-weight'
+    // UI-bloat checks (ui-bloat.ts / component-audit.ts)
+    | 'ui-repeated-style'
+    | 'ui-hardcoded-color'
+    | 'ui-reimplementation'
+    | 'component-size'
+    | 'jsx-depth'
+    | 'hook-count'
+    | 'duplicate-jsx'
+    | 'duplicate-component';
   source: string;
   detail: string;
+  /** Source-side only: every place the smell occurs (the remote bundle cannot give
+   *  these — it is mangled and pathless). */
+  occurrences?: SourceLoc[];
+  /** Source-side only: how to fix it. */
+  fix?: FixDescriptor;
+  /** How to confirm the fix landed. Uniform: re-run the audit; the finding clears.
+   *  The auditor is its own verifier. */
+  verify?: string;
 }
 
 export interface SecretPattern {

package/src/cli/commands/audit.ts

@@ -10,6 +10,7 @@
 
 import { resolveConfig, opsFunction } from '../config.js';
 import { runBundleAudit, runBundleWeightAudit, reportBundleAudit } from './bundle.js';
+import { runUiAudit, reportUiAudit } from './ui-audit.js';
 import { resolveWeightBudget } from '../bundle-weight.js';
 import { runSecurityProbe, reportProbeResults } from './security-probe.js';
 import { auditDeployedSql, printReport, loadWaivers } from './security.js';
@@ -89,6 +90,21 @@ export async function auditCommand(flags: Record<string, string>): Promise<void>
     warn(`bundle:audit skipped: ${err.message}`);
   }
 
+  // --- ui:audit (source-side design bloat) — advisory, never gates ---------
+  // Runs over the app source dir (--ui-dir, else cwd); skipped silently if there's
+  // no source here (e.g. running the capstone against a remote stage only).
+  const uiDir = flags['ui-dir'] || '.';
+  console.log('');
+  info('── ui:audit ─────────────────────────────────────────────────');
+  try {
+    const result = runUiAudit(uiDir, flags);
+    console.log('');
+    reportUiAudit(result); // advisory — does not add to `failures`
+    ran.push('ui:audit (advisory)');
+  } catch (err: any) {
+    warn(`ui:audit skipped: ${err.message}`);
+  }
+
   // --- audit:lighthouse (perf/SEO) — opt-in; heavy and informational -------
   if (flags.lighthouse) {
     console.log('');

package/src/cli/commands/bundle.ts

@@ -43,6 +43,11 @@ import {
   type AssetFile,
   type WeightBudget,
 } from '../bundle-weight.js';
+import {
+  scanBundleUiBloat,
+  DEFAULT_UI_BLOAT_BUDGET,
+  type UiBloatBudget,
+} from '../ui-bloat.js';
 import { resolveConfig } from '../config.js';
 import { fail, info, step, success, warn } from '../output.js';
 
@@ -176,7 +181,7 @@ export interface BundleAuditResult {
 /** Result-producing core, shared by the command wrapper and the `audit` capstone. */
 export async function runBundleAudit(
   base: string,
-  opts: { valuesFrom?: string; weight?: boolean; budget?: WeightBudget } = {},
+  opts: { valuesFrom?: string; weight?: boolean; budget?: WeightBudget; uiBudget?: UiBloatBudget } = {},
 ): Promise<BundleAuditResult> {
   step(`Fetching ${base} ...`);
   const root = await fetchText(base);
@@ -259,10 +264,13 @@ export async function runBundleAudit(
     findings.push(...scanAssetWeights(files, budget));
     findings.push(...scanTotalWeight(files, budget));
     findings.push(...scanJsWeight(files, budget));
-    // Name the data inlined into JS chunks (the most useful diagnosis).
+    // Name the data inlined into JS chunks (the most useful diagnosis), and flag
+    // UI design-bloat (style repetition + hardcoded colors) in the same chunk text.
+    const uiBudget = opts.uiBudget || DEFAULT_UI_BLOAT_BUDGET;
     for (const a of artifacts) {
       if (classifyAsset(a.source) === 'js') {
         findings.push(...analyzeChunkBloat(a.text, a.source, budget));
+        findings.push(...scanBundleUiBloat(a.text, a.source, uiBudget));
       }
     }
     largest = largestFiles(files);
@@ -329,7 +337,7 @@ export function walkExport(root: string): AssetFile[] {
  */
 export async function runBundleWeightAudit(
   dir: string,
-  opts: { budget?: WeightBudget; valuesFrom?: string } = {},
+  opts: { budget?: WeightBudget; valuesFrom?: string; uiBudget?: UiBloatBudget } = {},
 ): Promise<BundleAuditResult> {
   const root = path.resolve(dir);
   if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
@@ -359,6 +367,7 @@ export async function runBundleWeightAudit(
     findings.push(...classifyPrivateEnvKeys(extractExtraEnvKeys(text), f.path));
     if (classifyAsset(f.path) === 'js') {
       findings.push(...analyzeChunkBloat(text, f.path, budget));
+      findings.push(...scanBundleUiBloat(text, f.path, opts.uiBudget || DEFAULT_UI_BLOAT_BUDGET));
     }
     if (opts.valuesFrom) {
       const secrets = parseDotenv(fs.readFileSync(path.resolve(opts.valuesFrom), 'utf8'));

package/src/cli/commands/ui-audit.ts

@@ -0,0 +1,76 @@
+/**
+ * `everystack ui:audit [dir]` — source-side UI design-bloat audit.
+ *
+ * The local, actionable half of the design-bloat loop (the remote half rides in
+ * `bundle:audit`). It parses the app's `.tsx` source into the component model and
+ * runs the source-side checks: styles copy-pasted across call sites, hardcoded
+ * colors that should be tokens, raw primitives that reimplement a ui component,
+ * oversized components, and duplicated JSX. Every finding carries `file:line`
+ * occurrences and a fix the agent can apply, then verifies by re-running.
+ *
+ * Advisory by design — refactoring is taste, so this never gates (exit 0 even with
+ * findings). Config-free: defaults derived from the model, no per-app setup.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { discoverComponents } from '../component-model.js';
+import { auditComponents } from '../component-audit.js';
+import { resolveUiBloatBudget } from '../ui-bloat.js';
+import { summarize, type AuditFinding } from '../bundle-audit.js';
+import { fail, info, step, success, warn } from '../output.js';
+
+export interface UiAuditResult {
+  findings: AuditFinding[];
+  componentCount: number;
+}
+
+/** Result-producing core, shared by the command and the `audit` capstone. */
+export function runUiAudit(dir: string, flags: Record<string, string> = {}): UiAuditResult {
+  const root = path.resolve(dir);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`${dir} is not a directory — pass the app source dir (defaults to .).`);
+  }
+  const components = discoverComponents(root);
+  const findings = auditComponents(components, resolveUiBloatBudget(flags));
+  return { findings, componentCount: components.length };
+}
+
+/** Print ui:audit findings; returns the number of advisory warnings. */
+export function reportUiAudit(result: UiAuditResult): number {
+  const { findings, componentCount } = result;
+  if (findings.length === 0) {
+    success(`ui:audit — clean. No design bloat across ${componentCount} component(s).`);
+    return 0;
+  }
+  for (const f of findings) {
+    warn(`[${f.check}] ${f.source}: ${f.detail}`);
+    if (f.fix) info(`  fix: ${f.fix.summary}`);
+    if (f.occurrences && f.occurrences.length > 1) {
+      info(`  at: ${f.occurrences.length} sites`);
+    }
+  }
+  console.log('');
+  const { warn: warns } = summarize(findings);
+  warn(`ui:audit — ${warns} advisory finding(s) across ${componentCount} component(s) (advisory; does not gate)`);
+  return warns;
+}
+
+export async function uiAuditCommand(
+  positional: string | undefined,
+  flags: Record<string, string>,
+): Promise<void> {
+  const dir = positional || flags.dir || '.';
+  step(`Scanning components under ${dir} ...`);
+  let result: UiAuditResult;
+  try {
+    result = runUiAudit(dir, flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  console.log('');
+  reportUiAudit(result);
+  // Advisory only — refactoring is taste, so this never gates the build.
+  process.exit(0);
+}

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),
+  ];
+}

package/src/cli/component-model.ts

@@ -0,0 +1,304 @@
+/**
+ * Component model — a faithful, neutral representation of `.tsx` source (Brick 5a-B).
+ *
+ * This is the shared foundation, NOT a private detail of the auditor. The UI-bloat
+ * checks consume it; so will the 5b frontend Module contract (checking screens +
+ * components against a contract). Its reusability comes from *fidelity*: it
+ * represents what a component actually IS — name, location, JSX tree, hooks, props,
+ * imports, inline style literals — not an audit-shaped projection of it. It knows
+ * nothing about `AuditFinding`, checks, budgets, or fixes. The dependency points one
+ * way: the auditor imports this model; this model imports nothing from the auditor.
+ *
+ * Syntactic only (no type checker): everything here is read off the AST, so it needs
+ * a single `createSourceFile` per file — no `tsconfig` resolution, no `Program`, fast
+ * and pure. `parseComponents(file, text)` is the pure core (no filesystem);
+ * `discoverComponents(dir)` is the thin filesystem walk over it.
+ */
+
+import ts from 'typescript';
+import { readFileSync } from 'node:fs';
+import { globSync } from 'glob';
+
+/** A file-level import: `import def, { a, b }, * as ns from 'mod'`. */
+export interface ImportRef {
+  from: string;
+  names: string[];
+  default?: string;
+  namespace?: string;
+}
+
+/** A structural JSX node — tag identity, the element's own attributes and inline
+ *  style, and its nested element children (text and non-JSX expressions are not
+ *  structure). Map/conditional-wrapped JSX is descended into, so genuine reuse (one
+ *  `.map`) stays one node. */
+export interface JsxNode {
+  tag: string;
+  /** 1-based line of this element. */
+  line: number;
+  /** Attribute names present on this element (e.g. ['style', 'onPress']). */
+  attrs: string[];
+  /** Raw inline `style={{…}}` object literal on this element, if any. */
+  style?: string;
+  children: JsxNode[];
+}
+
+/** An inline `style={{…}}` object literal and the line it sits on. */
+export interface StyleLiteral {
+  text: string;
+  line: number;
+}
+
+/** A faithful model of one component. Source facts only — no audit concepts. */
+export interface ComponentDescriptor {
+  name: string;
+  file: string;
+  /** 1-based line of the component declaration. */
+  line: number;
+  /** Line span of the component (for the size metric). */
+  lines: number;
+  jsx: JsxNode[];
+  hooks: string[];
+  props: string[];
+  imports: ImportRef[];
+  styles: StyleLiteral[];
+}
+
+const isJsx = (
+  n: ts.Node,
+): n is ts.JsxElement | ts.JsxSelfClosingElement | ts.JsxFragment =>
+  ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n) || ts.isJsxFragment(n);
+
+/** True if any JSX appears anywhere in the subtree — the test for "is a component". */
+function containsJsx(node: ts.Node): boolean {
+  let found = false;
+  const walk = (n: ts.Node): void => {
+    if (found) return;
+    if (isJsx(n)) {
+      found = true;
+      return;
+    }
+    ts.forEachChild(n, walk);
+  };
+  ts.forEachChild(node, walk);
+  return found;
+}
+
+function collectImports(sf: ts.SourceFile): ImportRef[] {
+  const out: ImportRef[] = [];
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    const ref: ImportRef = { from: stmt.moduleSpecifier.text, names: [] };
+    const clause = stmt.importClause;
+    if (clause?.name) ref.default = clause.name.text;
+    const bindings = clause?.namedBindings;
+    if (bindings) {
+      if (ts.isNamespaceImport(bindings)) ref.namespace = bindings.name.text;
+      else for (const el of bindings.elements) ref.names.push(el.name.text);
+    }
+    out.push(ref);
+  }
+  return out;
+}
+
+function tagName(n: ts.JsxElement | ts.JsxSelfClosingElement | ts.JsxFragment): string {
+  if (ts.isJsxFragment(n)) return 'Fragment';
+  const tag = ts.isJsxElement(n) ? n.openingElement.tagName : n.tagName;
+  return tag.getText();
+}
+
+/** Read an element's attribute names and its inline `style={{…}}` literal. */
+function readAttrs(
+  n: ts.JsxElement | ts.JsxSelfClosingElement | ts.JsxFragment,
+  sf: ts.SourceFile,
+): { attrs: string[]; style?: string } {
+  if (ts.isJsxFragment(n)) return { attrs: [] };
+  const props = (ts.isJsxElement(n) ? n.openingElement : n).attributes.properties;
+  const attrs: string[] = [];
+  let style: string | undefined;
+  for (const p of props) {
+    if (!ts.isJsxAttribute(p) || !ts.isIdentifier(p.name)) continue;
+    attrs.push(p.name.text);
+    if (
+      p.name.text === 'style' &&
+      p.initializer &&
+      ts.isJsxExpression(p.initializer) &&
+      p.initializer.expression &&
+      ts.isObjectLiteralExpression(p.initializer.expression)
+    ) {
+      style = p.initializer.expression.getText(sf);
+    }
+  }
+  return { attrs, style };
+}
+
+/** Build a faithful node for one JSX element, with its attrs, style, line, children. */
+function makeNode(
+  n: ts.JsxElement | ts.JsxSelfClosingElement | ts.JsxFragment,
+  sf: ts.SourceFile,
+): JsxNode {
+  const { attrs, style } = readAttrs(n, sf);
+  const node: JsxNode = {
+    tag: tagName(n),
+    line: sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1,
+    attrs,
+    children: jsxChildren(n, sf),
+  };
+  if (style !== undefined) node.style = style;
+  return node;
+}
+
+/** The element children of a JSX node, descending through expression containers
+ *  ({cond && <X/>}, {items.map(=> <Y/>)}) so structure is captured but text is not. */
+function jsxChildren(
+  n: ts.JsxElement | ts.JsxSelfClosingElement | ts.JsxFragment,
+  sf: ts.SourceFile,
+): JsxNode[] {
+  if (ts.isJsxSelfClosingElement(n)) return [];
+  const kids: JsxNode[] = [];
+  const fromChild = (child: ts.Node): void => {
+    if (isJsx(child)) {
+      kids.push(makeNode(child, sf));
+      return; // don't descend past a JSX element — its own children handle that
+    }
+    // descend through JsxExpression / parens / map callbacks to find nested JSX
+    if (ts.isJsxText(child)) return;
+    ts.forEachChild(child, fromChild);
+  };
+  for (const child of n.children) fromChild(child);
+  return kids;
+}
+
+/** The outermost JSX nodes within a component body — its roots. */
+function collectRoots(fn: ts.Node, sf: ts.SourceFile): JsxNode[] {
+  const roots: JsxNode[] = [];
+  const walk = (n: ts.Node): void => {
+    if (isJsx(n)) {
+      roots.push(makeNode(n, sf));
+      return; // stop — nested JSX is captured as children, not as another root
+    }
+    ts.forEachChild(n, walk);
+  };
+  ts.forEachChild(fn, walk);
+  return roots;
+}
+
+function collectHooks(fn: ts.Node): string[] {
+  const hooks: string[] = [];
+  const walk = (n: ts.Node): void => {
+    if (ts.isCallExpression(n)) {
+      const expr = n.expression;
+      const name = ts.isIdentifier(expr)
+        ? expr.text
+        : ts.isPropertyAccessExpression(expr)
+          ? expr.name.text
+          : '';
+      if (/^use[A-Z]/.test(name)) hooks.push(name);
+    }
+    ts.forEachChild(n, walk);
+  };
+  ts.forEachChild(fn, walk);
+  return hooks;
+}
+
+function collectProps(fn: ts.FunctionLikeDeclarationBase): string[] {
+  const param = fn.parameters[0];
+  if (!param) return [];
+  if (ts.isObjectBindingPattern(param.name)) {
+    return param.name.elements
+      .map((el) => (ts.isIdentifier(el.name) ? el.name.text : ''))
+      .filter(Boolean);
+  }
+  if (ts.isIdentifier(param.name)) return [param.name.text];
+  return [];
+}
+
+function collectStyles(fn: ts.Node, sf: ts.SourceFile): StyleLiteral[] {
+  const styles: StyleLiteral[] = [];
+  const walk = (n: ts.Node): void => {
+    if (
+      ts.isJsxAttribute(n) &&
+      ts.isIdentifier(n.name) &&
+      n.name.text === 'style' &&
+      n.initializer &&
+      ts.isJsxExpression(n.initializer) &&
+      n.initializer.expression &&
+      ts.isObjectLiteralExpression(n.initializer.expression)
+    ) {
+      const obj = n.initializer.expression;
+      styles.push({
+        text: obj.getText(sf),
+        line: sf.getLineAndCharacterOfPosition(obj.getStart(sf)).line + 1,
+      });
+    }
+    ts.forEachChild(n, walk);
+  };
+  ts.forEachChild(fn, walk);
+  return styles;
+}
+
+/**
+ * Pure core: parse one `.tsx` file's source text into faithful component
+ * descriptors. No filesystem, no type checker.
+ */
+export function parseComponents(file: string, text: string): ComponentDescriptor[] {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const imports = collectImports(sf);
+  const out: ComponentDescriptor[] = [];
+  const lineOf = (pos: number) => sf.getLineAndCharacterOfPosition(pos).line + 1;
+
+  const consider = (name: string, declNode: ts.Node, fn: ts.FunctionLikeDeclarationBase): void => {
+    if (!containsJsx(fn)) return;
+    const start = declNode.getStart(sf);
+    out.push({
+      name,
+      file,
+      line: lineOf(start),
+      lines: lineOf(declNode.getEnd()) - lineOf(start) + 1,
+      jsx: collectRoots(fn, sf),
+      hooks: collectHooks(fn),
+      props: collectProps(fn),
+      imports,
+      styles: collectStyles(fn, sf),
+    });
+  };
+
+  for (const node of sf.statements) {
+    if (ts.isFunctionDeclaration(node)) {
+      const name =
+        node.name?.text ??
+        (node.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword) ? 'default' : '');
+      if (name) consider(name, node, node);
+    } else if (ts.isVariableStatement(node)) {
+      for (const d of node.declarationList.declarations) {
+        if (
+          ts.isIdentifier(d.name) &&
+          d.initializer &&
+          (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))
+        ) {
+          consider(d.name.text, node, d.initializer);
+        }
+      }
+    } else if (ts.isExportAssignment(node)) {
+      const e = node.expression;
+      if (ts.isArrowFunction(e) || ts.isFunctionExpression(e)) consider('default', node, e);
+    }
+  }
+  return out;
+}
+
+/**
+ * Walk a directory for `.tsx` files (excluding node_modules) and parse each into
+ * component descriptors. The thin filesystem shell over `parseComponents`.
+ */
+export function discoverComponents(dir: string): ComponentDescriptor[] {
+  const files = globSync('**/*.tsx', {
+    cwd: dir,
+    absolute: true,
+    ignore: ['**/node_modules/**', '**/.expo/**', '**/dist/**'],
+  });
+  const out: ComponentDescriptor[] = [];
+  for (const file of files) {
+    out.push(...parseComponents(file, readFileSync(file, 'utf8')));
+  }
+  return out;
+}

package/src/cli/index.ts

@@ -25,6 +25,7 @@ import { securityProbeCommand } from './commands/security-probe.js';
 import { bundleAnalyzeCommand, bundleAuditCommand } from './commands/bundle.js';
 import { auditLighthouseCommand } from './commands/lighthouse.js';
 import { auditCommand } from './commands/audit.js';
+import { uiAuditCommand } from './commands/ui-audit.js';
 import { fail } from './output.js';
 
 const args = process.argv.slice(2);
@@ -229,6 +230,11 @@ async function main() {
       await bundleAuditCommand(positional, flags);
       break;
     }
+    case 'ui:audit': {
+      const positional = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
+      await uiAuditCommand(positional, flags);
+      break;
+    }
     case 'secrets': {
       // secrets <subcommand> [positional...] [--flags]
       // Extract positional args: everything after subcommand that isn't a flag or flag value
@@ -289,7 +295,8 @@ Usage:
   everystack audit             --stage <name> [--host <url>] [--dir <export>] [--lighthouse]  Capstone: security:audit + security:probe + bundle:audit (+ optional lighthouse), combined report + exit code (CI gate); --dir adds the weight/size gate over a local export
   everystack bundle:analyze    [dir]            Client web-bundle size + composition (run after \`expo export -p web --source-maps\`)
   everystack audit:lighthouse  [--stage <name>] [--host <url>] [--runs 3] [--path /] [--json out.json]  Mobile Lighthouse (perf/a11y/bp/seo), median over N runs
-  everystack bundle:audit      [url|--dir <export>] [--stage <name>] [--values-from <.env>] [--leak-only] [--max-file-mb N] [--max-total-mb N] [--max-js-mb N] [--max-data-mb N]  Audit a bundle for leaked secrets AND weight (oversized assets, data that belongs in the DB, JS bloat). A URL/stage weighs the remote bundle (assets sized via HEAD, no download); --dir scans a local export; --leak-only skips the weight gate
+  everystack bundle:audit      [url|--dir <export>] [--stage <name>] [--values-from <.env>] [--leak-only] [--max-file-mb N] [--max-total-mb N] [--max-js-mb N] [--max-data-mb N]  Audit a bundle for leaked secrets AND weight (oversized assets, data that belongs in the DB, JS bloat) AND UI design-bloat (style repetition + hardcoded colors). A URL/stage weighs the remote bundle (assets sized via HEAD, no download); --dir scans a local export; --leak-only skips the weight gate
+  everystack ui:audit          [dir] [--ui-repeat N] [--ui-color-repeat N]  Source-side UI design-bloat: styles copy-pasted across call sites, hardcoded colors that should be tokens, raw primitives reimplementing a ui component, oversized components, duplicated JSX. Located + fixable; advisory, never gates
   everystack certs:generate    [--output ./certs]
   everystack certs:configure   [--input ./certs] [--keyid main]
   everystack cache:purge       [--stage <name>]                  Bust all cached content (global epoch)

package/src/cli/ui-bloat.ts

@@ -0,0 +1,198 @@
+/**
+ * Bundle UI-bloat audit — pure scanners for the remote `bundle:audit` (Brick 5a).
+ *
+ * The weight scanner (bundle-weight.ts) answers "is the bundle too big / is data
+ * leaking into it?" This answers "is the *frontend* bloated — the same component
+ * shape hand-written N times instead of reused, the same color hardcoded hundreds
+ * of times instead of a token?" It is the universal, gate-to-prod half of the
+ * design-bloat loop: it runs on the shipped bundle, needs no repo, and is blind to
+ * which ui package was intended — it measures *repetition*, not conformance.
+ *
+ * Empirically grounded against a real deployed bundle: `className` does not survive
+ * (build-time tailwind compiles it away) and component identities are mangled, so
+ * the only surviving anchor is the inline `style:{}` object literal. Two truths make
+ * it work:
+ *   - Real reuse (a component rendered N times via `.map`) compiles to ONE call
+ *     site; copy-paste compiles to N identical sites. So the occurrence count of an
+ *     identical `style:{}` literal IS the copy-paste count (Metro does not dedupe
+ *     inline object literals).
+ *   - App design styling references a theme token or a hardcoded hex; bare
+ *     structural styling (`flex:1`) is library noise. Filtering on token-or-hex
+ *     biases the scan to the builder's own code without needing module paths.
+ *
+ * Advisory only. Refactoring is taste (the governance ceiling), so every finding is
+ * `warn` — even at the gate. The stick is that it *shows up* at the gate, never that
+ * it blocks the deploy.
+ *
+ * Everything here is pure: it takes bundle text and returns findings, so the
+ * governance MCP imports it directly. It cannot give locations (the bundle is
+ * mangled, pathless) — that is the local source auditor's job; this proves magnitude.
+ */
+
+import type { AuditFinding } from './bundle-audit.js';
+
+/** Thresholds for the design-bloat gates. All counts are occurrences in the bundle. */
+export interface UiBloatBudget {
+  /** A `style:{}` shape hand-written at this many distinct call sites is an
+   *  un-extracted component. */
+  styleRepeatWarn: number;
+  /** A single hardcoded hex color repeated this many times should be a token. */
+  colorRepeatWarn: number;
+  /** This many *distinct* hardcoded hex values is an ad-hoc palette with no token
+   *  system. */
+  paletteWarn: number;
+  /** Cap on findings per check, so a bloated bundle yields a readable list. */
+  topN: number;
+}
+
+/**
+ * Defaults from the real-bundle measurement, not round numbers: shapes repeated
+ * ≥10× were the clear extract-me set; a single gray hex appeared 470× past a token
+ * that existed; the ad-hoc palette ran to ~300 distinct values. The thresholds sit
+ * just below those so the signal is caught without noise. Overridable via flags.
+ */
+export const DEFAULT_UI_BLOAT_BUDGET: UiBloatBudget = {
+  styleRepeatWarn: 8,
+  colorRepeatWarn: 12,
+  paletteWarn: 24,
+  topN: 12,
+};
+
+const HEX = /'#[0-9a-fA-F]{3,8}'/g;
+// A flat inline style literal: `style:{ … }` with no nested braces. Nested styles
+// (`style:{a:{…}}`) are intentionally out of scope for the count-only remote pass.
+const STYLE_LITERAL = /style:\{[^{}]{4,400}\}/g;
+// A mangled module/theme reference: `a.text`, `p.textSecondary` → folded to `X.`
+// so the same token counts as one shape regardless of its minified alias.
+const MANGLED_REF = /[A-Za-z_$][A-Za-z0-9_$]*\./g;
+
+/**
+ * Canonical form of a style literal for grouping: strip all whitespace and fold any
+ * `ident.prop` reference to `X.prop` (mangled bundle aliases AND source theme refs
+ * like `theme.border` collapse to the same shape). Shared by the remote bundle
+ * scanner and the source-side auditor so both group styles identically.
+ */
+export function canonicalizeStyle(raw: string): string {
+  return raw.replace(/\s+/g, '').replace(MANGLED_REF, 'X.');
+}
+
+/** True if a style literal is app *design* styling (references a token or a hex),
+ *  rather than bare structural layout that libraries emit. */
+export function isDesignStyle(literal: string): boolean {
+  return /X\./.test(literal) || /#[0-9a-fA-F]{3,8}/.test(literal);
+}
+
+/**
+ * Extract and normalize the design `style:{}` literals from bundle text. Mangled
+ * aliases are folded to `X.`; bare structural styling is dropped. Order-preserving,
+ * so the length is the occurrence (copy-paste) count.
+ */
+export function extractStyleLiterals(text: string): string[] {
+  const out: string[] = [];
+  const m = text.match(STYLE_LITERAL);
+  if (!m) return out;
+  for (const raw of m) {
+    const norm = canonicalizeStyle(raw);
+    if (isDesignStyle(norm)) out.push(norm);
+  }
+  return out;
+}
+
+/** A short, safe preview of a style literal for the finding detail. */
+function preview(literal: string, max = 80): string {
+  return literal.length <= max ? literal : `${literal.slice(0, max)}…}`;
+}
+
+/**
+ * Flag `style:{}` shapes hand-written at many distinct call sites — each is a
+ * component that should be extracted once and reused. Count-only (no locations);
+ * the local source auditor pins the `file:line`s.
+ */
+export function scanRepeatedStyles(
+  text: string,
+  source: string,
+  budget: UiBloatBudget = DEFAULT_UI_BLOAT_BUDGET,
+): AuditFinding[] {
+  const counts = new Map<string, number>();
+  for (const lit of extractStyleLiterals(text)) {
+    counts.set(lit, (counts.get(lit) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .filter(([, n]) => n >= budget.styleRepeatWarn)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, budget.topN)
+    .map(([lit, n]) => ({
+      severity: 'warn' as const,
+      check: 'ui-repeated-style' as const,
+      source,
+      detail: `a style is hand-written at ${n} distinct call sites (${preview(lit)}) — extract a component and reuse it instead of repeating the markup`,
+    }));
+}
+
+/**
+ * Flag hardcoded hex colors: a single value repeated past the budget (it should be
+ * a theme token), and — separately — an ad-hoc palette of many distinct hardcoded
+ * values (no token system). Both are token-violation smells.
+ */
+export function scanHardcodedColors(
+  text: string,
+  source: string,
+  budget: UiBloatBudget = DEFAULT_UI_BLOAT_BUDGET,
+): AuditFinding[] {
+  const counts = new Map<string, number>();
+  for (const lit of text.match(STYLE_LITERAL) ?? []) {
+    for (const hex of lit.match(HEX) ?? []) {
+      const v = hex.slice(1, -1); // strip the surrounding quotes
+      counts.set(v, (counts.get(v) ?? 0) + 1);
+    }
+  }
+  if (counts.size === 0) return [];
+
+  const findings: AuditFinding[] = [...counts.entries()]
+    .filter(([, n]) => n >= budget.colorRepeatWarn)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, budget.topN)
+    .map(([hex, n]) => ({
+      severity: 'warn' as const,
+      check: 'ui-hardcoded-color' as const,
+      source,
+      detail: `${hex} is hardcoded ${n} times — replace it with a theme token so it can change in one place (and support dark mode)`,
+    }));
+
+  if (counts.size >= budget.paletteWarn) {
+    findings.push({
+      severity: 'warn',
+      check: 'ui-hardcoded-color',
+      source,
+      detail: `${counts.size} distinct hardcoded hex colors are inlined across the bundle — this is an ad-hoc palette; define a token set instead of scattering raw colors`,
+    });
+  }
+  return findings;
+}
+
+/** The combined remote UI-bloat entry — what the command and the MCP call. */
+export function scanBundleUiBloat(
+  text: string,
+  source: string,
+  budget: UiBloatBudget = DEFAULT_UI_BLOAT_BUDGET,
+): AuditFinding[] {
+  return [...scanRepeatedStyles(text, source, budget), ...scanHardcodedColors(text, source, budget)];
+}
+
+/** Resolve a budget from CLI flags, falling back to the defaults. */
+export function resolveUiBloatBudget(
+  flags: Record<string, string>,
+  base: UiBloatBudget = DEFAULT_UI_BLOAT_BUDGET,
+): UiBloatBudget {
+  const num = (key: string): number | undefined => {
+    const raw = flags[key];
+    if (raw == null) return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+  };
+  return {
+    ...base,
+    styleRepeatWarn: num('ui-repeat') ?? base.styleRepeatWarn,
+    colorRepeatWarn: num('ui-color-repeat') ?? base.colorRepeatWarn,
+  };
+}