monomind 2.5.2 → 2.5.3

package/packages/@monomind/cli/.claude/skills/monodesign/scripts/detector/fix/css-regions.mjs

@@ -0,0 +1,181 @@
+/**
+ * CSS region extraction and declaration scanning for the auto-fix engine.
+ *
+ * Fixers never parse a full DOM — they operate on the raw source text of the
+ * "CSS-shaped" regions of a file:
+ *   - whole file for .css/.scss/.sass/.less
+ *   - <style> blocks and style="" attributes for HTML-family files
+ *   - styled-components / emotion template literals for JS/TS files
+ *
+ * All offsets returned here are absolute within the original file content, so
+ * edits computed against a region can be applied directly to the file.
+ */
+
+const CSS_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
+const HTML_FAMILY_EXTENSIONS = new Set(['.html', '.htm', '.vue', '.svelte', '.astro']);
+const JS_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs']);
+
+/**
+ * A region of file content that can be scanned as CSS declarations.
+ * kind:
+ *   'css'        — full stylesheet syntax (selectors + blocks)
+ *   'style-attr' — a bare declaration list from a style="" attribute;
+ *                  selectorHint carries the owning tag name
+ */
+function extractCssRegions(content, ext) {
+  ext = (ext || '').toLowerCase();
+  if (CSS_EXTENSIONS.has(ext)) {
+    return [{ start: 0, end: content.length, text: content, kind: 'css', selectorHint: null }];
+  }
+
+  const regions = [];
+  if (HTML_FAMILY_EXTENSIONS.has(ext)) {
+    const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+    let m;
+    while ((m = styleBlockRe.exec(content)) !== null) {
+      const start = m.index + m[0].indexOf(m[1]);
+      regions.push({ start, end: start + m[1].length, text: m[1], kind: 'css', selectorHint: null });
+    }
+    const styleAttrRe = /<([a-zA-Z][\w-]*)\b[^>]*?\sstyle\s*=\s*("([^"]*)"|'([^']*)')/gi;
+    while ((m = styleAttrRe.exec(content)) !== null) {
+      const value = m[3] !== undefined ? m[3] : m[4];
+      if (!value) continue;
+      const start = m.index + m[0].length - value.length - 1; // inside the closing quote
+      regions.push({
+        start,
+        end: start + value.length,
+        text: value,
+        kind: 'style-attr',
+        selectorHint: m[1].toLowerCase(),
+      });
+    }
+    return regions;
+  }
+
+  if (JS_EXTENSIONS.has(ext)) {
+    const cssInJsRe = /(?:styled(?:\.\w+|\([^)]+\))|css)\s*`([\s\S]*?)`/g;
+    let m;
+    while ((m = cssInJsRe.exec(content)) !== null) {
+      const start = m.index + m[0].indexOf('`') + 1;
+      regions.push({ start, end: start + m[1].length, text: m[1], kind: 'css', selectorHint: null });
+    }
+    return regions;
+  }
+
+  return regions;
+}
+
+/**
+ * Find every `prop: value` declaration in a CSS-shaped text. Returns local
+ * offsets (relative to the given text):
+ *   { declStart, valueStart, valueEnd, value, terminator }
+ * `value` is the raw trimmed value text (may include !important).
+ * `terminator` is the index just past the trailing `;` when present,
+ * otherwise valueEnd.
+ */
+function findDeclarations(text, prop) {
+  const re = new RegExp(`(^|[{;])(\\s*)(${prop})\\s*:\\s*([^;{}]*)`, 'gi');
+  const results = [];
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const declStart = m.index + m[1].length + m[2].length;
+    const rawValue = m[4];
+    const trimmed = rawValue.replace(/\s+$/, '');
+    const valueStart = m.index + m[0].length - rawValue.length;
+    const valueEnd = valueStart + trimmed.length;
+    const terminator = text[m.index + m[0].length] === ';'
+      ? m.index + m[0].length + 1
+      : valueEnd;
+    results.push({ declStart, valueStart, valueEnd, value: trimmed.trim(), terminator });
+  }
+  return results;
+}
+
+/**
+ * The enclosing `{ ... }` block for a declaration at `index`, with its
+ * selector text. For bare declaration lists (style attributes) there is no
+ * block — the whole text is the body and selector is null.
+ */
+function declBlockInfo(text, index) {
+  let i = index - 1;
+  let depth = 0;
+  while (i >= 0) {
+    const ch = text[i];
+    if (ch === '}') depth++;
+    else if (ch === '{') {
+      if (depth === 0) break;
+      depth--;
+    }
+    i--;
+  }
+  if (i < 0) {
+    return { bodyStart: 0, bodyEnd: text.length, body: text, selector: null };
+  }
+  const braceIdx = i;
+  let s = braceIdx - 1;
+  while (s >= 0 && !'};{'.includes(text[s])) s--;
+  const selector = text.slice(s + 1, braceIdx).trim();
+  let j = braceIdx + 1;
+  let d = 0;
+  while (j < text.length) {
+    const ch = text[j];
+    if (ch === '{') d++;
+    else if (ch === '}') {
+      if (d === 0) break;
+      d--;
+    }
+    j++;
+  }
+  return { bodyStart: braceIdx + 1, bodyEnd: j, body: text.slice(braceIdx + 1, j), selector };
+}
+
+/** Parse a single CSS length/number value, tolerating !important. */
+function parseCssValue(raw) {
+  const important = /!\s*important/i.test(raw);
+  const cleaned = raw.replace(/!\s*important/i, '').trim();
+  const m = cleaned.match(/^(-?(?:\d+\.?\d*|\.\d+))([a-z%]*)$/i);
+  if (!m) return null;
+  return { num: parseFloat(m[1]), unit: (m[2] || '').toLowerCase(), important };
+}
+
+/** Resolve a block's font-size to px when statically computable, else null. */
+function blockFontSizePx(body) {
+  const decls = findDeclarations(body, 'font-size');
+  if (decls.length === 0) return null;
+  const parsed = parseCssValue(decls[decls.length - 1].value);
+  if (!parsed) return null;
+  if (parsed.unit === 'px') return parsed.num;
+  if (parsed.unit === 'rem') return parsed.num * 16;
+  return null;
+}
+
+/** Split a CSS value list on top-level commas (paren-aware, for cubic-bezier). */
+function splitTopLevel(value) {
+  const parts = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of value) {
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    if (ch === ',' && depth === 0) {
+      parts.push(current.trim());
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}
+
+export {
+  CSS_EXTENSIONS,
+  HTML_FAMILY_EXTENSIONS,
+  JS_EXTENSIONS,
+  extractCssRegions,
+  findDeclarations,
+  declBlockInfo,
+  parseCssValue,
+  blockFontSizePx,
+  splitTopLevel,
+};

package/packages/@monomind/cli/.claude/skills/monodesign/scripts/detector/fix/fixers.mjs

@@ -0,0 +1,373 @@
+/**
+ * Per-rule auto-fixers for the monodesign detector.
+ *
+ * A fixer is pure: it takes file content (plus its extension) and returns a
+ * list of precise text edits `{ start, end, replacement, note }` — or an empty
+ * list when nothing in this file is safely rewritable. Only rules with a
+ * deterministic, idempotent codemod get a fixer; everything else is reported
+ * as skipped by the fix loop.
+ *
+ * Idempotency invariant: every rewrite lands the value on the safe side of
+ * the detector's threshold, so re-running a fixer on fixed output produces
+ * zero edits (the fix loop's convergence guarantee relies on this).
+ */
+
+import {
+  extractCssRegions,
+  findDeclarations,
+  declBlockInfo,
+  parseCssValue,
+  blockFontSizePx,
+  splitTopLevel,
+} from './css-regions.mjs';
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+function withImportant(value, important) {
+  return important ? `${value} !important` : value;
+}
+
+/** Walk each region and each `prop` declaration, calling cb with full context.
+ *  cb may return one edit (region-local offsets) or null. */
+function eachDeclaration(content, ext, prop, cb) {
+  const edits = [];
+  for (const region of extractCssRegions(content, ext)) {
+    for (const decl of findDeclarations(region.text, prop)) {
+      const block = declBlockInfo(region.text, decl.declStart);
+      const selector = block.selector !== null ? block.selector : region.selectorHint;
+      const edit = cb({ region, decl, block, selector });
+      if (edit) {
+        edits.push({
+          start: region.start + edit.start,
+          end: region.start + edit.end,
+          replacement: edit.replacement,
+          note: edit.note,
+        });
+      }
+    }
+  }
+  return edits;
+}
+
+/** Edit that removes a whole declaration, including its trailing `;` and any
+ *  leading whitespace back to the previous boundary. Region-local offsets. */
+function removeDeclaration(text, decl, note) {
+  let start = decl.declStart;
+  while (start > 0 && /\s/.test(text[start - 1])) start--;
+  return { start, end: decl.terminator, replacement: '', note };
+}
+
+const LAYOUT_PROP_RE = /^(?:(?:max|min)-)?(?:width|height)$|^padding(?:-(?:top|right|bottom|left))?$|^margin(?:-(?:top|right|bottom|left))?$/i;
+
+const BODY_COPY_TAGS = new Set(['p', 'li', 'blockquote', 'dd']);
+
+/** Does a selector list unambiguously target body copy? Every selector in the
+ *  list must qualify — either its final element is a body-copy tag, or it
+ *  carries a body-copy class name with no label/heading counter-signal. */
+function selectorTargetsBodyCopy(selector) {
+  if (!selector) return false;
+  const parts = selector.split(',').map(s => s.trim()).filter(Boolean);
+  if (parts.length === 0) return false;
+  return parts.every(sel => {
+    const last = sel.split(/[\s>+~]+/).filter(Boolean).pop() || '';
+    if (/^(p|li|blockquote|dd)(?![\w-])/i.test(last)) return true;
+    const classes = last.match(/\.[\w-]+/g) || [];
+    return classes.some(c =>
+      /(body|paragraph|prose|copy|desc|text)/i.test(c) &&
+      !/(label|badge|button|nav|heading|title|caps|eyebrow|kicker|tag|chip)/i.test(c));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Fixers
+// ---------------------------------------------------------------------------
+
+/** tight-leading — line-height computing below 1.3x font size → 1.5. */
+function fixTightLeading(content, ext) {
+  return eachDeclaration(content, ext, 'line-height', ({ decl, block }) => {
+    const parsed = parseCssValue(decl.value);
+    if (!parsed) return null;
+    let ratio = null;
+    if (parsed.unit === '' ) ratio = parsed.num;
+    else if (parsed.unit === 'em') ratio = parsed.num;
+    else if (parsed.unit === '%') ratio = parsed.num / 100;
+    else if (parsed.unit === 'px') {
+      const fs = blockFontSizePx(block.body);
+      if (fs) ratio = parsed.num / fs;
+    }
+    if (ratio === null || ratio <= 0 || ratio >= 1.3) return null;
+    return {
+      start: decl.valueStart,
+      end: decl.valueEnd,
+      replacement: withImportant('1.5', parsed.important),
+      note: `line-height ${decl.value} -> 1.5`,
+    };
+  });
+}
+
+/** tiny-text — font-size below 12px → 12px (px / rem only; em is
+ *  parent-relative and not statically computable). */
+function fixTinyText(content, ext) {
+  return eachDeclaration(content, ext, 'font-size', ({ decl }) => {
+    const parsed = parseCssValue(decl.value);
+    if (!parsed) return null;
+    let replacement = null;
+    if (parsed.unit === 'px' && parsed.num > 0 && parsed.num < 12) replacement = '12px';
+    else if (parsed.unit === 'rem' && parsed.num > 0 && parsed.num < 0.75) replacement = '0.75rem';
+    if (!replacement) return null;
+    return {
+      start: decl.valueStart,
+      end: decl.valueEnd,
+      replacement: withImportant(replacement, parsed.important),
+      note: `font-size ${decl.value} -> ${replacement}`,
+    };
+  });
+}
+
+/** justified-text — text-align: justify without hyphenation → add
+ *  `hyphens: auto` in the same declaration block (or rewrite a non-auto
+ *  hyphens declaration already present). */
+function fixJustifiedText(content, ext) {
+  return eachDeclaration(content, ext, 'text-align', ({ region, decl, block }) => {
+    if (!/^justify$/i.test(decl.value.replace(/!\s*important/i, '').trim())) return null;
+    const hyphens = findDeclarations(block.body, '(?:-webkit-)?hyphens');
+    const hasAuto = hyphens.some(h => /^auto$/i.test(h.value.replace(/!\s*important/i, '').trim()));
+    if (hasAuto) return null;
+    if (hyphens.length > 0) {
+      // A hyphens declaration exists but isn't auto — rewrite it.
+      const h = hyphens[hyphens.length - 1];
+      return {
+        start: block.bodyStart + h.valueStart,
+        end: block.bodyStart + h.valueEnd,
+        replacement: 'auto',
+        note: `hyphens ${h.value} -> auto (justified text)`,
+      };
+    }
+    // Insert after the text-align declaration.
+    const afterSemi = region.text[decl.terminator - 1] === ';';
+    return afterSemi
+      ? { start: decl.terminator, end: decl.terminator, replacement: ' hyphens: auto;', note: 'add hyphens: auto next to text-align: justify' }
+      : { start: decl.valueEnd, end: decl.valueEnd, replacement: '; hyphens: auto', note: 'add hyphens: auto next to text-align: justify' };
+  });
+}
+
+/** wide-tracking — letter-spacing above 0.05em on body text → clamp to
+ *  0.05em. Skips blocks that set uppercase (the detector exempts uppercase
+ *  labels, where wide tracking is legitimate). */
+function fixWideTracking(content, ext) {
+  return eachDeclaration(content, ext, 'letter-spacing', ({ decl, block }) => {
+    if (/text-transform\s*:\s*uppercase/i.test(block.body)) return null;
+    const parsed = parseCssValue(decl.value);
+    if (!parsed || parsed.num <= 0) return null;
+    let em = null;
+    if (parsed.unit === 'em') em = parsed.num;
+    else if (parsed.unit === 'px' || parsed.unit === 'rem') {
+      const fs = blockFontSizePx(block.body);
+      if (fs) em = (parsed.unit === 'px' ? parsed.num : parsed.num * 16) / fs;
+    }
+    if (em === null || em <= 0.05) return null;
+    return {
+      start: decl.valueStart,
+      end: decl.valueEnd,
+      replacement: withImportant('0.05em', parsed.important),
+      note: `letter-spacing ${decl.value} -> 0.05em`,
+    };
+  });
+}
+
+/** extreme-negative-tracking — letter-spacing at or below -0.05em → clamp to
+ *  -0.04em (optical tightening territory, below the detector's floor). */
+function fixExtremeNegativeTracking(content, ext) {
+  return eachDeclaration(content, ext, 'letter-spacing', ({ decl, block }) => {
+    const parsed = parseCssValue(decl.value);
+    if (!parsed || parsed.num >= 0) return null;
+    let em = null;
+    if (parsed.unit === 'em') em = parsed.num;
+    else if (parsed.unit === 'px' || parsed.unit === 'rem') {
+      const fs = blockFontSizePx(block.body);
+      if (fs) em = (parsed.unit === 'px' ? parsed.num : parsed.num * 16) / fs;
+    }
+    if (em === null || em > -0.05) return null;
+    return {
+      start: decl.valueStart,
+      end: decl.valueEnd,
+      replacement: withImportant('-0.04em', parsed.important),
+      note: `letter-spacing ${decl.value} -> -0.04em`,
+    };
+  });
+}
+
+/** layout-transition — drop width/height/padding/margin entries from
+ *  transition lists (transform/opacity and everything else stay). Removes the
+ *  declaration entirely when no entries survive. */
+function fixLayoutTransition(content, ext) {
+  const edits = [];
+  for (const propName of ['transition', 'transition-property']) {
+    edits.push(...eachDeclaration(content, ext, propName, ({ region, decl }) => {
+      const important = /!\s*important/i.test(decl.value);
+      const value = decl.value.replace(/!\s*important/i, '').trim();
+      if (/\ball\b/i.test(value)) return null; // detector skips `all` too
+      const items = splitTopLevel(value);
+      const kept = items.filter(item => {
+        const prop = propName === 'transition-property'
+          ? item.trim()
+          : (item.trim().split(/\s+/)[0] || '');
+        return !LAYOUT_PROP_RE.test(prop);
+      });
+      if (kept.length === items.length) return null;
+      if (kept.length === 0) {
+        return { ...removeDeclaration(region.text, decl, `remove ${propName} (all entries animated layout)`) };
+      }
+      return {
+        start: decl.valueStart,
+        end: decl.valueEnd,
+        replacement: withImportant(kept.join(', '), important),
+        note: `${propName}: drop layout properties, keep ${kept.join(', ')}`,
+      };
+    }));
+  }
+  return edits;
+}
+
+/** all-caps-body — remove text-transform: uppercase, but only where the
+ *  selector unambiguously targets body copy (or the inline style sits on a
+ *  body-copy tag). Anything selector-ambiguous is left for a human. */
+function fixAllCapsBody(content, ext) {
+  return eachDeclaration(content, ext, 'text-transform', ({ region, decl, block, selector }) => {
+    if (!/^uppercase$/i.test(decl.value.replace(/!\s*important/i, '').trim())) return null;
+    const qualifies = block.selector !== null
+      ? selectorTargetsBodyCopy(selector)
+      : BODY_COPY_TAGS.has(region.selectorHint || '');
+    if (!qualifies) return null;
+    return { ...removeDeclaration(region.text, decl, `remove text-transform: uppercase from ${selector || 'body copy'}`) };
+  });
+}
+
+/** skipped-heading — demote headings whose level skips past the previous
+ *  heading (h1 -> h3 becomes h1 -> h2), walking the document in source order
+ *  exactly like the detector does. Only the unambiguous "close the gap"
+ *  demotion is applied; open and close tags are rewritten in pairs. */
+function fixSkippedHeadings(content, ext) {
+  if (!['.html', '.htm', '.vue', '.svelte', '.astro'].includes((ext || '').toLowerCase())) return [];
+  const edits = [];
+  const tagRe = /<(\/?)h([1-6])\b/gi;
+  let prevLevel = 0;
+  let pending = null; // { origLevel, newLevel } awaiting the matching close tag
+  let m;
+  while ((m = tagRe.exec(content)) !== null) {
+    const isClose = m[1] === '/';
+    const level = parseInt(m[2], 10);
+    const digitIdx = m.index + m[0].length - 1;
+    if (isClose) {
+      if (pending && level === pending.origLevel) {
+        edits.push({
+          start: digitIdx,
+          end: digitIdx + 1,
+          replacement: String(pending.newLevel),
+          note: `</h${pending.origLevel}> -> </h${pending.newLevel}>`,
+        });
+        pending = null;
+      }
+      continue;
+    }
+    let newLevel = level;
+    if (prevLevel > 0 && level > prevLevel + 1) {
+      newLevel = prevLevel + 1;
+      edits.push({
+        start: digitIdx,
+        end: digitIdx + 1,
+        replacement: String(newLevel),
+        note: `<h${level}> -> <h${newLevel}> (closes gap after h${prevLevel})`,
+      });
+      pending = { origLevel: level, newLevel };
+    } else {
+      pending = null;
+    }
+    prevLevel = newLevel;
+  }
+  return edits;
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Rules with a deterministic, safe, idempotent codemod.
+ * fix(content, ext) -> [{ start, end, replacement, note }]
+ */
+const FIXERS = {
+  'tight-leading': {
+    description: 'raise sub-1.3 line-height to 1.5',
+    fix: fixTightLeading,
+  },
+  'tiny-text': {
+    description: 'raise sub-12px font-size to the 12px minimum',
+    fix: fixTinyText,
+  },
+  'justified-text': {
+    description: 'add hyphens: auto next to text-align: justify',
+    fix: fixJustifiedText,
+  },
+  'wide-tracking': {
+    description: 'clamp body-text letter-spacing to 0.05em',
+    fix: fixWideTracking,
+  },
+  'extreme-negative-tracking': {
+    description: 'clamp crushed letter-spacing to -0.04em',
+    fix: fixExtremeNegativeTracking,
+  },
+  'layout-transition': {
+    description: 'drop width/height/padding/margin from transition lists',
+    fix: fixLayoutTransition,
+  },
+  'all-caps-body': {
+    description: 'remove text-transform: uppercase from body-copy selectors',
+    fix: fixAllCapsBody,
+  },
+  'skipped-heading': {
+    description: 'demote heading tags to close skipped levels',
+    fix: fixSkippedHeadings,
+  },
+};
+
+/**
+ * Rules deliberately without a fixer, with the reason surfaced in reports.
+ * broken-image is the canonical example: choosing a real image (or deciding
+ * the tag should go) is a content decision — any deterministic rewrite
+ * (placeholder URL, removing the tag) would guess at intent, so it is not
+ * safely fixable.
+ */
+const UNFIXABLE_REASONS = {
+  'broken-image': 'not safely fixable: supplying a real image (or removing the tag) is a content decision, not a codemod',
+  'low-contrast': 'not safely fixable: picking replacement colors is a palette decision',
+  'overused-font': 'not safely fixable: choosing a replacement typeface is a brand decision',
+  'skipped-heading-ambiguous': 'heading structure too ambiguous to rewrite automatically',
+};
+
+function getFixer(ruleId) {
+  return FIXERS[ruleId] || null;
+}
+
+function fixableRuleIds() {
+  return Object.keys(FIXERS);
+}
+
+export {
+  FIXERS,
+  UNFIXABLE_REASONS,
+  getFixer,
+  fixableRuleIds,
+  // exported for direct unit testing
+  fixTightLeading,
+  fixTinyText,
+  fixJustifiedText,
+  fixWideTracking,
+  fixExtremeNegativeTracking,
+  fixLayoutTransition,
+  fixAllCapsBody,
+  fixSkippedHeadings,
+  selectorTargetsBodyCopy,
+};