@devinilabs/reelstack 1.2.0

package/cli/lint.js

@@ -0,0 +1,865 @@
+/**
+ * `reelstack lint <file> [--critique]` — static-analysis pass over a reel composition.
+ *
+ * Reports (default mode — list of violations with line numbers):
+ *   - SAFE_ZONE_BREACH:           element y-coords overlap reserved bands.
+ *   - MOTION_FLOOR_VIOLATION:     scenes with too few simultaneous animation layers.
+ *   - HERO_TEXT_OVERFLOW:         counter or hero text wider than canvas - 64px gutter.
+ *   - AUDIO_NOT_LOCKED:           file imports <Audio> but defines no BEAT const block.
+ *   - HAND_DRAWN_BRAND:           inline <svg> longer than 800 chars in a logo-sized element.
+ *   - BANNED_FONT:                fontFamily uses one of the generic LLM-default fonts.
+ *   - PURE_BLACK_TEXT:            color: "#000" / "#000000" — kills warmth on cream/glass families.
+ *   - AI_PURPLE_ACCENT:           hex color in the AI-purple blocklist (#7c3aed, etc.).
+ *   - EMOJI_GLYPH:                literal emoji in JSX text — hand-drawn brand violation.
+ *   - ACCENT_ALLOWLIST_VIOLATION: hex color outside the resolved family's ALLOWED_ACCENTS list.
+ *   - SPACING_NON_GRID:           padding/margin/gap not on the 4px grid.
+ *   - MISSING_REDUCE_MOTION:      component imports useCurrentFrame but lacks a `reduceMotion` prop.
+ *   - GENERIC_PLACEHOLDER:        "Lorem ipsum", "John Doe", "Acme Corp" — leftover stub copy.
+ *   - PILL_TAG_OVERSTRETCHED:     pill/tag/chip/badge component forced wider than its content via style overrides.
+ *   - RIPPLE_TOO_LOUD:            SonarRings/ParticleBurst/IridescentRing exceeds house-style intensity ceiling.
+ *   - RIPPLE_STACK:               more than 2 ripple emitters anchored to the same (cx, cy) in one scene.
+ *
+ * With `--critique`, the same set of static checks drives a 5-dimension radar
+ * (Palette · Motion · Timing · Hierarchy · Brand fit) plus a Keep / Fix / Quick
+ * punch list. Inspired by alchaincyf/huashu-design's 5-dim expert critique pattern.
+ *
+ * The lint pass is intentionally conservative — false positives are
+ * acceptable; false negatives ship bad reels.
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const { c, info, success, fail, warn } = require("./utils");
+
+const TOP_SAFE = 290;
+const BOTTOM_SAFE = 422;
+const CANVAS_H = 1920;
+const CANVAS_W = 1080;
+const HERO_TEXT_MAX = CANVAS_W - 64; // 1016
+
+// ─── Inline taste-skill blocklists ──────────────────────────────────────
+// Maintenance note: these mirror the canonical lists in utils/banned-fonts.ts
+// and utils/ai-purple-blocklist.ts. We inline here because cli/* is plain
+// CommonJS and importing TS source would require a build step. Refactor in
+// v1.2 if/when we add tsc emit to the publish pipeline.
+const BANNED_FONTS = [
+  "Inter",
+  "Roboto",
+  "Helvetica",
+  "Arial",
+  "Open Sans",
+  "Lato",
+  "Montserrat",
+  "Poppins",
+  "Raleway",
+];
+
+const AI_PURPLE_HEXES = [
+  "#7c3aed",
+  "#8b5cf6",
+  "#6366f1",
+  "#a78bfa",
+  "#c084fc",
+  "#9333ea",
+  "#7e22ce",
+  "#a855f7",
+];
+
+const FAMILY_ALLOWED_ACCENTS = {
+  glass: [
+    "#7FE8D4", "#8B7FE8", "#E89BC4", "#F2D88F",
+    "#9D8BF2", "#85DDC9", "#0E0E12",
+  ],
+  paper: [
+    "#1a1a1a", "#2d2d2d", "#6b6b6b", "#1e3a27",
+    "#2d4433", "#D4663A", "#1e7a45", "#c0392b", "#5be8a0",
+  ],
+  forbidden: [
+    "#0E0B12", "#D97757", "#C4506B", "#6B5BD9", "#A87FE8",
+  ],
+  // dark + warm: skip allowlist enforcement here.
+  // - "warm" is enforced via Warm's ALLOWED_ACCENTS in palette.ts (single-accent rule).
+  // - "dark" allows multi-brand accents by design (cinematic partnership reels).
+};
+
+const GENERIC_PLACEHOLDERS = [
+  /lorem ipsum/i,
+  /\bjohn doe\b/i,
+  /\backme corp\b/i,
+  /\bfoo bar\b/i,
+  /placeholder text/i,
+];
+
+// Emoji & symbol ranges (covers most emoji + dingbats).
+const EMOJI_REGEX = /[\u{1F300}-\u{1F9FF}\u{2600}-\u{27BF}]/u;
+
+function lint(file) {
+  if (!fs.existsSync(file)) {
+    fail(`File not found: ${file}`);
+    // Sentinel: `null` means "couldn't lint" (file missing/unreadable),
+    // which is distinct from `[]` which means "linted, no violations".
+    // run() must check for null and exit non-zero WITHOUT printing
+    // "Lint clean" — see v1.1 audit blocker.
+    return null;
+  }
+  const src = fs.readFileSync(file, "utf8");
+  const lines = src.split(/\r?\n/);
+  const violations = [];
+  const isTemplate = /[\\/]templates[\\/]/.test(file);
+  const lineOfIdx = (idx) => src.slice(0, idx).split("\n").length;
+
+  // ─── Safe-zone breaches ──────────────────────────────────────────────
+  // Naive: find `top:` / `bottom:` literal pixel values and flag if inside
+  // the reserved bands.
+  lines.forEach((line, i) => {
+    const topMatch = line.match(/top:\s*(-?\d+)\s*,?/);
+    if (topMatch) {
+      const y = Number(topMatch[1]);
+      if (y >= 0 && y < TOP_SAFE && !line.includes("data-reelstack-safe-override")) {
+        violations.push({ line: i + 1, code: "SAFE_ZONE_BREACH", msg: `top: ${y} overlaps top reserved band (0..${TOP_SAFE}).` });
+      }
+    }
+    const bottomMatch = line.match(/bottom:\s*(-?\d+)\s*,?/);
+    if (bottomMatch) {
+      const b = Number(bottomMatch[1]);
+      if (b >= 0 && b < BOTTOM_SAFE && !line.includes("data-reelstack-safe-override")) {
+        violations.push({ line: i + 1, code: "SAFE_ZONE_BREACH", msg: `bottom: ${b} overlaps bottom reserved band (0..${BOTTOM_SAFE}).` });
+      }
+    }
+  });
+
+  // ─── Audio lock ──────────────────────────────────────────────────────
+  const importsAudio = /from\s+["']remotion["'][^;]*\bAudio\b/.test(src) || /<Audio\b/.test(src);
+  const definesBeats = /\bBEATS\s*=\s*\{/.test(src);
+  if (importsAudio && !definesBeats) {
+    violations.push({ line: 1, code: "AUDIO_NOT_LOCKED", msg: "Reel imports <Audio> but defines no BEATS const block. Run /reelstack-beats to lock motion to whisper SRT." });
+  }
+
+  // ─── Hand-drawn brand logos ──────────────────────────────────────────
+  const inlineSvgs = src.match(/<svg[\s\S]*?<\/svg>/g) || [];
+  for (const svg of inlineSvgs) {
+    if (svg.length > 800) {
+      const idx = src.indexOf(svg);
+      const lineNum = src.slice(0, idx).split("\n").length;
+      violations.push({
+        line: lineNum,
+        code: "HAND_DRAWN_BRAND",
+        msg: `Inline <svg> is ${svg.length} chars — likely hand-drawn. Use /reelstack-icons to pull a real brand SVG.`,
+      });
+    }
+  }
+
+  // ─── Motion-floor heuristic ──────────────────────────────────────────
+  // Walk Sequences explicitly (depth-tracked) and count motion-related
+  // calls inside each balanced <Sequence>...</Sequence> block.
+  // Opener (from={0}): require ≥4. Anchor/body/cta: require ≥3.
+  const motionCallsRegex = /interpolate\s*\(|\bspring\s*\(|useCurrentFrame\s*\(/g;
+  const lineOf = (idx) => src.slice(0, idx).split("\n").length;
+
+  let cursor = 0;
+  while (true) {
+    const openIdx = src.indexOf("<Sequence", cursor);
+    if (openIdx === -1) break;
+
+    // Find end of opening tag — track > but skip those inside JSX expressions.
+    // Simple scan: walk forward, balance { } depth; close on > at depth 0.
+    let braceDepth = 0;
+    let tagEnd = -1;
+    for (let i = openIdx; i < src.length; i++) {
+      const ch = src[i];
+      if (ch === "{") braceDepth++;
+      else if (ch === "}") braceDepth--;
+      else if (ch === ">" && braceDepth === 0) {
+        tagEnd = i;
+        break;
+      }
+    }
+    if (tagEnd === -1) break;
+
+    const openTag = src.slice(openIdx, tagEnd + 1);
+
+    // Self-closing? Skip — cannot contain motion calls.
+    if (openTag.endsWith("/>")) {
+      cursor = tagEnd + 1;
+      continue;
+    }
+
+    // Extract from={N} (only flag explicitly-numeric froms).
+    const fromMatch = openTag.match(/\bfrom=\{(-?\d+)\}/);
+    if (!fromMatch) {
+      // No literal-number `from`; can't classify as opener vs anchor reliably.
+      // Skip this Sequence rather than misreport.
+      cursor = tagEnd + 1;
+      continue;
+    }
+    const fromValue = Number(fromMatch[1]);
+
+    // Walk forward to find the matching </Sequence>, balancing depth.
+    let depth = 1;
+    let scan = tagEnd + 1;
+    let bodyEnd = -1;
+    while (scan < src.length) {
+      const nextOpen = src.indexOf("<Sequence", scan);
+      const nextClose = src.indexOf("</Sequence>", scan);
+      if (nextClose === -1) break;
+      if (nextOpen !== -1 && nextOpen < nextClose) {
+        depth++;
+        scan = nextOpen + "<Sequence".length;
+      } else {
+        depth--;
+        if (depth === 0) {
+          bodyEnd = nextClose;
+          break;
+        }
+        scan = nextClose + "</Sequence>".length;
+      }
+    }
+    if (bodyEnd === -1) {
+      // Unbalanced; don't crash — just stop walking Sequences.
+      break;
+    }
+
+    const body = src.slice(tagEnd + 1, bodyEnd);
+    const motionCalls = (body.match(motionCallsRegex) || []).length;
+
+    const required = fromValue === 0 ? 4 : 3;
+    if (motionCalls < required) {
+      violations.push({
+        line: lineOf(openIdx),
+        code: "MOTION_FLOOR_VIOLATION",
+        msg: `Sequence at frame ${fromValue} has ${motionCalls} motion calls, family rule is ≥3 (≥4 in opener).`,
+      });
+    }
+
+    // Advance past this opener tag so nested Sequences are re-discovered
+    // on the next iteration. We don't skip past the whole block.
+    cursor = tagEnd + 1;
+  }
+
+  // ─── Hero-text overflow ──────────────────────────────────────────────
+  // Heuristic: fontSize > 256 paired with hero-text signals (tabularNums,
+  // letterSpacing, Counter, HeroText) within a 5-line window.
+  lines.forEach((line, i) => {
+    const fsMatch = line.match(/fontSize:\s*(\d+)/);
+    if (!fsMatch) return;
+    const px = Number(fsMatch[1]);
+    if (px <= 256) return;
+    const window = lines.slice(Math.max(0, i - 2), Math.min(lines.length, i + 3)).join(" ");
+    if (/(tabular-?nums|tabularNums|Counter|HeroText|letterSpacing)/i.test(window)) {
+      violations.push({
+        line: i + 1,
+        code: "HERO_TEXT_OVERFLOW",
+        msg: `fontSize ${px}px on apparent hero-counter; cap at 256px or wrap with maxWidth=${HERO_TEXT_MAX}.`,
+      });
+    }
+  });
+
+  // ─── Banned fonts (taste-skill rule) ─────────────────────────────────
+  try {
+    const fontFamilyRegex = /fontFamily:\s*["'`]([^"'`]+)["'`]/g;
+    let mFF;
+    while ((mFF = fontFamilyRegex.exec(src)) !== null) {
+      const decl = mFF[1].toLowerCase();
+      const hit = BANNED_FONTS.find((f) => decl.includes(f.toLowerCase()));
+      if (hit) {
+        violations.push({
+          line: lineOfIdx(mFF.index),
+          code: "BANNED_FONT",
+          msg: `fontFamily "${mFF[1]}" includes generic LLM-default font "${hit}". Use the family's typography preset instead.`,
+        });
+      }
+    }
+  } catch {}
+
+  // ─── Pure-black text (taste-skill rule) ──────────────────────────────
+  // Detects pure black across multiple CSS color forms on color/background/
+  // fill/stroke properties:
+  //   - #000 / #000000 (case insensitive)
+  //   - rgb(0,0,0) / rgb( 0 , 0 , 0 ) (whitespace tolerant)
+  //   - rgba(0,0,0, 1) (alpha 0..1)
+  //   - "black" CSS keyword
+  try {
+    const blackHexRe = /^#0{3}$|^#0{6}$/i;
+    const blackRgbRe = /^rgba?\(\s*0\s*,\s*0\s*,\s*0\s*(?:,\s*(?:0|0?\.\d+|1(?:\.0+)?)\s*)?\)$/i;
+    const propRe = /(color|background|fill|stroke):\s*["'`]([^"'`]+)["'`]/g;
+    let mB;
+    while ((mB = propRe.exec(src)) !== null) {
+      const prop = mB[1];
+      const val = mB[2].trim();
+      const isBlack =
+        blackHexRe.test(val) ||
+        blackRgbRe.test(val) ||
+        val.toLowerCase() === "black";
+      if (isBlack) {
+        violations.push({
+          line: lineOfIdx(mB.index),
+          code: "PURE_BLACK_TEXT",
+          msg: `${prop}: "${val}" is pure black — kills warmth. Use the family's text-primary token (e.g. #0E0E12 / #1a1a1a / #0E0B12).`,
+        });
+      }
+    }
+  } catch {}
+
+  // ─── AI-purple accent (taste-skill rule) ─────────────────────────────
+  // Catches purple references across:
+  //   - 6-char hex (#7c3aed)
+  //   - 3-char hex shorthand normalized to 6-char (#73e → #7733ee)
+  //   - rgb(R, G, B) / rgba(R, G, B, A) numeric forms (converted to hex)
+  // Forbidden-family files (importing @devinilabs/reelstack/families/forbidden)
+  // get an exemption for #6B5BD9 (ultraviolet) and #A87FE8 (plasma) since
+  // those are family-native accents that happen to land in the purple gamut.
+  try {
+    const blocklist = new Set(AI_PURPLE_HEXES.map((h) => h.toLowerCase()));
+    const isForbiddenFamily =
+      /from\s+["']@devinilabs\/reelstack\/families\/forbidden/.test(src);
+    const forbiddenExempt = new Set(["#6b5bd9", "#a87fe8"]);
+
+    const toHex = (n) => {
+      const v = Math.max(0, Math.min(255, Number(n)));
+      return v.toString(16).padStart(2, "0");
+    };
+    const expandShortHex = (hex) =>
+      "#" + hex.slice(1).split("").map((ch) => ch + ch).join("");
+
+    const flaggedAt = new Set(); // dedupe by hex+line
+    const pushIfBlocked = (canonHex, displayValue, idx) => {
+      const lc = canonHex.toLowerCase();
+      if (!blocklist.has(lc)) return;
+      if (isForbiddenFamily && forbiddenExempt.has(lc)) return;
+      const line = lineOfIdx(idx);
+      const key = lc + ":" + line;
+      if (flaggedAt.has(key)) return;
+      flaggedAt.add(key);
+      violations.push({
+        line,
+        code: "AI_PURPLE_ACCENT",
+        msg: `${displayValue} is on the AI-purple blocklist — every "AI" demo uses these. Pick a family-native accent instead.`,
+      });
+    };
+
+    // 6-char hex
+    const hex6Re = /#[0-9a-fA-F]{6}\b/g;
+    let mH6;
+    while ((mH6 = hex6Re.exec(src)) !== null) {
+      pushIfBlocked(mH6[0], `Hex ${mH6[0]}`, mH6.index);
+    }
+
+    // 3-char hex (NOT followed by another hex pair so we don't double-match #abcdef).
+    // Use lookahead to ensure exactly 3 hex digits, terminated by non-hex.
+    const hex3Re = /#[0-9a-fA-F]{3}(?![0-9a-fA-F])/g;
+    let mH3;
+    while ((mH3 = hex3Re.exec(src)) !== null) {
+      const expanded = expandShortHex(mH3[0]);
+      pushIfBlocked(expanded, `Hex ${mH3[0]} (≡ ${expanded})`, mH3.index);
+    }
+
+    // rgb()/rgba() numeric color
+    const rgbRe = /rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*(?:,\s*(?:0|0?\.\d+|1(?:\.0+)?)\s*)?\)/gi;
+    let mRgb;
+    while ((mRgb = rgbRe.exec(src)) !== null) {
+      const canon = "#" + toHex(mRgb[1]) + toHex(mRgb[2]) + toHex(mRgb[3]);
+      pushIfBlocked(canon, `${mRgb[0]} (≡ ${canon})`, mRgb.index);
+    }
+  } catch {}
+
+  // ─── Emoji glyphs in JSX text ────────────────────────────────────────
+  try {
+    const textRegex = />([^<>]+)</g;
+    let mE;
+    while ((mE = textRegex.exec(src)) !== null) {
+      if (EMOJI_REGEX.test(mE[1])) {
+        violations.push({
+          line: lineOfIdx(mE.index),
+          code: "EMOJI_GLYPH",
+          msg: `Literal emoji in JSX text — hand-drawn brand violation. Use /reelstack-icons or a custom motion glyph.`,
+        });
+      }
+    }
+  } catch {}
+
+  // ─── Accent allowlist (per-family) ───────────────────────────────────
+  try {
+    const familyMatch = src.match(/from\s+["']@devinilabs\/reelstack\/families\/(\w+)/);
+    const family = familyMatch ? familyMatch[1].toLowerCase() : null;
+    const allowed = family && FAMILY_ALLOWED_ACCENTS[family];
+    if (allowed) {
+      const allowLc = allowed.map((h) => h.toLowerCase());
+      const hexAccentRegex = /#[0-9a-fA-F]{6}\b/g;
+      const flagged = new Set();
+      let mA;
+      while ((mA = hexAccentRegex.exec(src)) !== null) {
+        const lc = mA[0].toLowerCase();
+        if (/^#0{6}$/.test(lc)) continue;
+        if (AI_PURPLE_HEXES.includes(lc)) continue;
+        if (allowLc.includes(lc)) continue;
+        const key = lc + ":" + lineOfIdx(mA.index);
+        if (flagged.has(key)) continue;
+        flagged.add(key);
+        violations.push({
+          line: lineOfIdx(mA.index),
+          code: "ACCENT_ALLOWLIST_VIOLATION",
+          msg: `Hex ${mA[0]} is not in the ${family} family's ALLOWED_ACCENTS list. Use the palette tokens instead.`,
+        });
+      }
+    }
+  } catch {}
+
+  // ─── Spacing non-grid (taste-skill rule) ─────────────────────────────
+  // Catches off-grid spacing in three forms:
+  //   - numeric:  padding: 23
+  //   - string:   padding: "23"  / padding: "23px"
+  //   - shorthand string: padding: "16 30 16 8"  → check each component
+  try {
+    const checkVal = (rawProp, val, idx) => {
+      if (!Number.isFinite(val)) return;
+      if (val === 0) return;
+      if (val === 1 || val === 2) return; // hairlines allowed.
+      if (val % 4 !== 0) {
+        violations.push({
+          line: lineOfIdx(idx),
+          code: "SPACING_NON_GRID",
+          msg: `${rawProp}: ${val} is off the 4px grid. Round to ${Math.round(val / 4) * 4}.`,
+        });
+      }
+    };
+    const propPattern =
+      "(padding|margin|gap)(?:Top|Bottom|Left|Right|Inline|Block)?";
+
+    // Numeric form: padding: 23
+    const numRe = new RegExp(propPattern + ":\\s*(\\d+)\\b(?!\\s*[\"'`])", "g");
+    let mN;
+    while ((mN = numRe.exec(src)) !== null) {
+      checkVal(mN[1], Number(mN[2]), mN.index);
+    }
+
+    // String form: padding: "23" / "23px" / "16 30 16 8" / "16px 8px"
+    const strRe = new RegExp(propPattern + ":\\s*[\"'`]([^\"'`]+)[\"'`]", "g");
+    let mStr;
+    while ((mStr = strRe.exec(src)) !== null) {
+      const prop = mStr[1];
+      const raw = mStr[2].trim();
+      // Split shorthand on whitespace; check each component.
+      const parts = raw.split(/\s+/);
+      for (const part of parts) {
+        const m = /^(\d+)(?:px)?$/.exec(part);
+        if (!m) continue; // skip non-numeric tokens (auto, %, var(...), etc.)
+        checkVal(prop, Number(m[1]), mStr.index);
+      }
+    }
+  } catch {}
+
+  // ─── Missing reduceMotion prop ───────────────────────────────────────
+  try {
+    if (!isTemplate) {
+      const usesFrame = /\buseCurrentFrame\s*\(/.test(src);
+      if (usesFrame) {
+        const fcRegex = /React\.FC<\{([^}]*)\}>/g;
+        let mFC;
+        let foundFC = false;
+        while ((mFC = fcRegex.exec(src)) !== null) {
+          foundFC = true;
+          if (!/reduceMotion/.test(mFC[1])) {
+            violations.push({
+              line: lineOfIdx(mFC.index),
+              code: "MISSING_REDUCE_MOTION",
+              msg: `React.FC component uses useCurrentFrame but prop type lacks "reduceMotion". Add reduceMotion?: boolean for accessibility.`,
+            });
+          }
+        }
+        if (!foundFC && /export\s+const\s+\w+\s*[:=]\s*React\.FC/.test(src) && !/reduceMotion/.test(src)) {
+          violations.push({
+            line: 1,
+            code: "MISSING_REDUCE_MOTION",
+            msg: `Component uses useCurrentFrame but no reduceMotion prop found anywhere. Add reduceMotion?: boolean.`,
+          });
+        }
+      }
+    }
+  } catch {}
+
+  // ─── Generic placeholder copy ────────────────────────────────────────
+  try {
+    if (!isTemplate) {
+      lines.forEach((line, i) => {
+        for (const re of GENERIC_PLACEHOLDERS) {
+          if (re.test(line)) {
+            violations.push({
+              line: i + 1,
+              code: "GENERIC_PLACEHOLDER",
+              msg: `Stub copy detected ("${line.match(re)[0]}"). Replace with real product copy before shipping.`,
+            });
+            break;
+          }
+        }
+      });
+    }
+  } catch {}
+
+  // ─── Pill / tag width discipline ─────────────────────────────────────
+  // Pill, Tag, Chip, and Badge components must hug their content. When
+  // they sit inside a flex column the default `align-items: stretch`
+  // bleeds across the canvas and breaks the eyebrow-callout pattern.
+  // The components themselves now ship with `alignSelf: flex-start` +
+  // `width: max-content`, so this rule catches the only remaining gap:
+  // call-site `style` overrides that re-stretch the pill.
+  try {
+    const HUG_OK = /^(max-content|fit-content|min-content|auto)$/i;
+    for (const mTag of src.matchAll(/<(\w+(?:Pill|Tag|Chip|Badge))\b([^>]*?)(?:\/?>|>)/g)) {
+      const componentName = mTag[1];
+      const opener = mTag[0];
+      const idx = mTag.index;
+      const styleMatch = opener.match(/style=\{\{([\s\S]*?)\}\}/);
+      if (!styleMatch) continue;
+      const styleBlock = styleMatch[1];
+
+      const widthMatch = styleBlock.match(/\bwidth:\s*["'`]?([^,"\s'`}]+)["'`]?/);
+      if (widthMatch && !HUG_OK.test(widthMatch[1])) {
+        violations.push({
+          line: lineOfIdx(idx),
+          code: "PILL_TAG_OVERSTRETCHED",
+          msg: `<${componentName}> has style.width="${widthMatch[1]}" — tag/pill components must hug content. Remove width or set "max-content".`,
+        });
+      }
+
+      if (/\balignSelf:\s*["'`]stretch["'`]/.test(styleBlock)) {
+        violations.push({
+          line: lineOfIdx(idx),
+          code: "PILL_TAG_OVERSTRETCHED",
+          msg: `<${componentName}> has alignSelf: "stretch" — tag/pill components must hug content. Remove or set "flex-start".`,
+        });
+      }
+
+      if (/\bflex:\s*["'`]?[1-9]/.test(styleBlock)) {
+        violations.push({
+          line: lineOfIdx(idx),
+          code: "PILL_TAG_OVERSTRETCHED",
+          msg: `<${componentName}> has flex grow > 0 — tag/pill components must hug content.`,
+        });
+      }
+
+      if (/\bflexGrow:\s*[1-9]/.test(styleBlock)) {
+        violations.push({
+          line: lineOfIdx(idx),
+          code: "PILL_TAG_OVERSTRETCHED",
+          msg: `<${componentName}> has flexGrow > 0 — tag/pill components must hug content.`,
+        });
+      }
+    }
+  } catch {}
+
+  // ─── Ripple-effect intensity ceiling ─────────────────────────────────
+  // Ripple primitives (SonarRings, ParticleBurst, IridescentRing) read
+  // as ambient texture, not protagonist. When their counts climb or when
+  // multiple ripple emitters stack at the same anchor in the same scene,
+  // the eye loses the hero copy. Ceilings here are the values used in
+  // the canonical reels (ClaudeWatchReel, GraphifyReel) — anything above
+  // is louder than the house style sanctions.
+  try {
+    const RIPPLE_CEILINGS = {
+      SonarRings:     { prop: "count", max: 4,  msg: "SonarRings count > 4 reads as visual noise. House ceiling is 4." },
+      ParticleBurst:  { prop: "count", max: 20, msg: "ParticleBurst count > 20 overwhelms the hero. House ceiling is 20." },
+      IridescentRing: { prop: "radius", max: 260, msg: "IridescentRing radius > 260 dominates the frame. House ceiling is 260." },
+    };
+    for (const [name, rule] of Object.entries(RIPPLE_CEILINGS)) {
+      const tagRe = new RegExp(`<${name}\\b([^>]*?)(?:/?>|>)`, "g");
+      for (const mTag of src.matchAll(tagRe)) {
+        const opener = mTag[0];
+        const idx = mTag.index;
+        const propRe = new RegExp(`\\b${rule.prop}=\\{(-?\\d+)\\}`);
+        const propMatch = opener.match(propRe);
+        if (!propMatch) continue;
+        const value = Number(propMatch[1]);
+        if (value > rule.max) {
+          violations.push({
+            line: lineOfIdx(idx),
+            code: "RIPPLE_TOO_LOUD",
+            msg: `<${name} ${rule.prop}={${value}}> — ${rule.msg}`,
+          });
+        }
+      }
+    }
+
+    // Ripple-stack penalty: more than 2 ripple emitters anchored to the
+    // same (cx, cy) in the same Sequence implies overlapping shockwaves.
+    // We approximate "same anchor" by exact-match cx + cy props in adjacent
+    // JSX nodes within ~12 lines.
+    const ripplePoints = []; // { cx, cy, line, name }
+    const rippleRe = /<(SonarRings|ParticleBurst|IridescentRing)\b([^>]*?)(?:\/?>|>)/g;
+    for (const mR of src.matchAll(rippleRe)) {
+      const opener = mR[0];
+      const cx = (opener.match(/\bcx=\{(-?\d+)\}/) || [])[1];
+      const cy = (opener.match(/\bcy=\{(-?\d+)\}/) || [])[1];
+      if (cx == null || cy == null) continue;
+      ripplePoints.push({
+        key: `${cx},${cy}`,
+        line: lineOfIdx(mR.index),
+        name: mR[1],
+      });
+    }
+    const stackCounts = {};
+    for (const p of ripplePoints) {
+      stackCounts[p.key] = (stackCounts[p.key] || []);
+      stackCounts[p.key].push(p);
+    }
+    for (const [anchor, group] of Object.entries(stackCounts)) {
+      if (group.length > 2) {
+        violations.push({
+          line: group[0].line,
+          code: "RIPPLE_STACK",
+          msg: `${group.length} ripple primitives anchored at (${anchor}) — house rule: max 2 ripple emitters per anchor. Spread them or remove one.`,
+        });
+      }
+    }
+  } catch {}
+
+  return violations;
+}
+
+// ─── Critique mode (5-dim radar + Keep/Fix/Quick) ────────────────────────
+
+function bar(score, max = 10) {
+  const filled = Math.max(0, Math.min(max, Math.round(score)));
+  return "█".repeat(filled) + "░".repeat(max - filled);
+}
+
+function countCode(violations, code) {
+  return violations.filter((v) => v.code === code).length;
+}
+
+/**
+ * computeCritique(violations, src?) — pure scoring helper extracted for tests.
+ *
+ * Takes a violations array (from lint()) and an optional source string (used
+ * only for the "un-eased interpolate" timing-penalty heuristic and the
+ * BEATS-present keep-line). Returns the radar scores plus keep/fix/quick.
+ *
+ * Returned shape exposes both `brand` (legacy renderCritique consumer) and
+ * `brandFit` (camelCase form preferred by external callers / tests).
+ */
+function computeCritique(violations, src = "") {
+  const v = violations || [];
+
+  const accentViols = countCode(v, "ACCENT_ALLOWLIST_VIOLATION");
+  const motionViols = countCode(v, "MOTION_FLOOR_VIOLATION");
+  const audioViols = countCode(v, "AUDIO_NOT_LOCKED");
+  const spacingViols = countCode(v, "SPACING_NON_GRID");
+  const heroOverflowViols = countCode(v, "HERO_TEXT_OVERFLOW");
+  const bannedFontViols = countCode(v, "BANNED_FONT");
+  const blackTextViols = countCode(v, "PURE_BLACK_TEXT");
+  const aiPurpleViols = countCode(v, "AI_PURPLE_ACCENT");
+  const emojiViols = countCode(v, "EMOJI_GLYPH");
+  const placeholderViols = countCode(v, "GENERIC_PLACEHOLDER");
+
+  // interpolate(frame,…) without explicit `easing:` option in same call.
+  let unEasedInterp = 0;
+  const interpRe = /interpolate\s*\(\s*frame\b[\s\S]*?\)/g;
+  let mi;
+  while ((mi = interpRe.exec(src)) !== null) {
+    if (!/easing\s*:/.test(mi[0])) unEasedInterp++;
+  }
+
+  // ─── Placeholder-BEATS detection ───────────────────────────────────────
+  // A freshly-scaffolded reel ships with a stub BEATS block whose values are
+  // round-number-frame defaults (hook:0, reveal:90, body:540, anchor:1200,
+  // cta:1620). Real whisper-SRT-derived BEATs come from `seconds * 30` of
+  // arbitrary VO timestamps and are almost never multiples of 30.
+  //
+  // We use BOTH heuristics together for robustness:
+  //   1) Strict scaffold-default match: exact hook/reveal/body/anchor/cta
+  //      values from templates/{family}/template.tsx.
+  //   2) Loose "all values multiples of 30" check on any BEATS block
+  //      with ≥3 entries — covers hand-edited scaffolds where someone
+  //      bumped one value but left the rest stub-round.
+  // Either one trips the placeholder flag.
+  let placeholderBeats = false;
+  try {
+    const beatsBlockRe = /\bBEATS\s*=\s*\{([\s\S]*?)\}/;
+    const m = beatsBlockRe.exec(src);
+    if (m) {
+      const body = m[1];
+      const entryRe = /(\w+)\s*:\s*(\d+)/g;
+      const entries = {};
+      let me;
+      while ((me = entryRe.exec(body)) !== null) {
+        entries[me[1]] = Number(me[2]);
+      }
+      const values = Object.values(entries);
+
+      // Heuristic 1: exact scaffold defaults.
+      const isScaffoldDefault =
+        entries.hook === 0 &&
+        entries.reveal === 90 &&
+        entries.body === 540 &&
+        entries.anchor === 1200 &&
+        entries.cta === 1620;
+
+      // Heuristic 2: ≥3 entries and ALL values are multiples of 30.
+      const allMultiplesOf30 =
+        values.length >= 3 && values.every((n) => n % 30 === 0);
+
+      placeholderBeats = isScaffoldDefault || allMultiplesOf30;
+    }
+  } catch {}
+
+  const palette = Math.max(0, 10 - Math.min(10, accentViols));
+  const motion = Math.max(0, 10 - motionViols * 2);
+  const timing = Math.max(
+    0,
+    10 - audioViols * 5 - (unEasedInterp > 0 ? 1 : 0) - (placeholderBeats ? 4 : 0),
+  );
+  const hierarchy = Math.max(0, 10 - spacingViols * 1 - heroOverflowViols * 3);
+  const brand = Math.max(
+    0,
+    10 - bannedFontViols * 5 - blackTextViols * 2 - aiPurpleViols * 5 - emojiViols * 3 - placeholderViols * 2,
+  );
+
+  const keep = [];
+  if (motionViols === 0) keep.push("Motion floor met across all sequences (≥3 layers, ≥4 in opener).");
+  if (audioViols === 0 && !placeholderBeats && /\bBEATS\s*=\s*\{/.test(src)) {
+    keep.push("Audio-locked beats present — motion choreographed to whisper SRT.");
+  }
+  if (countCode(v, "SAFE_ZONE_BREACH") === 0) keep.push("IG safe zones respected (no top/bottom-band breaches).");
+  if (bannedFontViols === 0 && blackTextViols === 0 && aiPurpleViols === 0) keep.push("Typography + palette stay on-family — no LLM-default fonts or AI-purple hexes.");
+  if (heroOverflowViols === 0) keep.push("Hero text fits the 1080 width gutter.");
+  if (keep.length === 0) keep.push("(No clean wins detected — work the punch list below.)");
+
+  const severityOrder = [
+    "AUDIO_NOT_LOCKED",
+    "BANNED_FONT",
+    "AI_PURPLE_ACCENT",
+    "MOTION_FLOOR_VIOLATION",
+    "HERO_TEXT_OVERFLOW",
+    "SAFE_ZONE_BREACH",
+    "HAND_DRAWN_BRAND",
+    "ACCENT_ALLOWLIST_VIOLATION",
+    "PURE_BLACK_TEXT",
+    "EMOJI_GLYPH",
+    "GENERIC_PLACEHOLDER",
+    "MISSING_REDUCE_MOTION",
+  ];
+  const sorted = [...v].sort(
+    (a, b) => severityOrder.indexOf(a.code) - severityOrder.indexOf(b.code),
+  );
+  const fix = sorted.filter((x) => x.code !== "SPACING_NON_GRID").slice(0, 2);
+
+  // Synthesize a Fix punch-list item for placeholder BEATS even though it
+  // isn't a numbered violation in the lint() output. Prepend so it surfaces
+  // above other Fix items.
+  if (placeholderBeats) {
+    fix.unshift({
+      line: 1,
+      code: "PLACEHOLDER_BEATS",
+      msg: "Audio not locked — BEATS contains placeholder values. Run /reelstack-beats <vo.wav> to lock motion to whisper SRT.",
+    });
+    // Cap at 2 so we don't blow out the Fix line.
+    fix.length = Math.min(fix.length, 2);
+  }
+
+  const quick = v.filter((x) => x.code === "SPACING_NON_GRID").slice(0, 2);
+  if (quick.length === 0) {
+    const minor = v.filter((x) => x.code === "MISSING_REDUCE_MOTION" || x.code === "GENERIC_PLACEHOLDER").slice(0, 1);
+    quick.push(...minor);
+  }
+
+  return {
+    scores: { palette, motion, timing, hierarchy, brand },
+    palette,
+    motion,
+    timing,
+    hierarchy,
+    brandFit: brand,
+    keep,
+    fix,
+    quick,
+  };
+}
+
+function critique(file) {
+  const v = lint(file);
+  const src = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  // lint() returns null when the file is missing; computeCritique already
+  // tolerates null/undefined (defaults to []), but be explicit.
+  return computeCritique(v || [], src);
+}
+
+function renderCritique(file, result) {
+  const rel = path.relative(process.cwd(), file);
+  const lines = [];
+  lines.push("");
+  lines.push(`${c.bold("ReelStack Critique")} ${c.gray("·")} ${c.cyan(rel)}`);
+  lines.push("");
+  const rows = [
+    ["Palette  ", result.scores.palette],
+    ["Motion   ", result.scores.motion],
+    ["Timing   ", result.scores.timing],
+    ["Hierarchy", result.scores.hierarchy],
+    ["Brand fit", result.scores.brand],
+  ];
+  for (const [label, score] of rows) {
+    const b = bar(score);
+    const tag =
+      score >= 9 ? c.green(b) : score >= 6 ? c.yellow(b) : c.red(b);
+    lines.push(`  ${c.bold(label)}   ${tag}  ${score}/10`);
+  }
+  lines.push("");
+  lines.push(`  ${c.green(c.bold("Keep:"))}    ${result.keep.join(" ")}`);
+  if (result.fix.length > 0) {
+    const fixStr = result.fix
+      .map((f) => `${f.code} at L${f.line} — ${f.msg}`)
+      .join("  |  ");
+    lines.push(`  ${c.yellow(c.bold("Fix:"))}     ${fixStr}`);
+  } else {
+    lines.push(`  ${c.yellow(c.bold("Fix:"))}     (none — strong reel.)`);
+  }
+  if (result.quick.length > 0) {
+    const quickStr = result.quick
+      .map((q) => `${q.code} at L${q.line} — ${q.msg}`)
+      .join("  |  ");
+    lines.push(`  ${c.cyan(c.bold("Quick:"))}   ${quickStr}`);
+  } else {
+    lines.push(`  ${c.cyan(c.bold("Quick:"))}   (no quick fixes.)`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+async function run(argv) {
+  const file = argv.find((a) => !a.startsWith("--"));
+  const useCritique = argv.includes("--critique");
+  if (!file) {
+    fail("Usage: reelstack lint <src/MyReel.tsx> [--critique]");
+    process.exit(2);
+  }
+  const abs = path.resolve(process.cwd(), file);
+
+  if (useCritique) {
+    if (!fs.existsSync(abs)) {
+      fail(`File not found: ${abs}`);
+      process.exit(2);
+    }
+    const result = critique(abs);
+    console.log(renderCritique(abs, result));
+    const avg = (result.scores.palette + result.scores.motion + result.scores.timing + result.scores.hierarchy + result.scores.brand) / 5;
+    process.exit(avg >= 7 ? 0 : 1);
+  }
+
+  const v = lint(abs);
+  // Distinguish "couldn't lint" (null) from "no violations" ([]).
+  // lint() already printed the failure reason; just exit non-zero.
+  if (v === null) {
+    process.exit(2);
+  }
+  console.log("");
+  if (v.length === 0) {
+    success(`Lint clean: ${path.relative(process.cwd(), abs)}`);
+    process.exit(0);
+  }
+  warn(`${v.length} violation(s) in ${path.relative(process.cwd(), abs)}:`);
+  console.log("");
+  for (const item of v) {
+    console.log(`  ${c.gray(`L${item.line}`)}  ${c.yellow(item.code)}  ${item.msg}`);
+  }
+  console.log("");
+  process.exit(1);
+}
+
+module.exports = { run, lint, critique, computeCritique, renderCritique };