@monoes/monodesign 1.2.20 → 1.2.23

package/cli/engine/engines/static-html/detect-html.mjs

@@ -176,7 +176,12 @@ async function detectHtml(filePath, options = {}) {
       const tag = el.tagName.toLowerCase();
       const style = window.getComputedStyle(el);
       for (const f of runElementCheck(rule.id, () => rule.run(el, tag, style, window, customPropMap))) {
-        findings.push(finding(f.id, filePath, f.snippet));
+        // Contrast the static cascade can't resolve (translucent colours,
+        // overlays, gradients) is not a definite failure: callers opt in (#424).
+        if (f.unverified && !options?.includeUnverified) continue;
+        const item = finding(f.id, filePath, f.snippet);
+        if (f.unverified) item.unverified = true;
+        findings.push(item);
       }
     }
   }

package/cli/engine/findings-group.mjs

@@ -0,0 +1,94 @@
+// Collapse repeated findings into one entry per (rule, snippet). A single
+// dark-theme token can fail contrast on hundreds of elements; reporting each
+// occurrence floods agents and humans with the same line (#424).
+
+import path from 'node:path';
+
+const SEVERITY_RANK = { error: 3, warning: 2, advisory: 1, info: 0 };
+
+function severityRank(severity) {
+  return SEVERITY_RANK[severity] ?? SEVERITY_RANK.warning;
+}
+
+function normalizeSnippet(snippet) {
+  return String(snippet ?? '').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Group findings by (antipattern, normalized snippet).
+ * Returns groups sorted by severity, then occurrence count (both descending),
+ * each carrying the first `maxLocations` locations as examples.
+ */
+function groupFindings(findings, { maxLocations = 3 } = {}) {
+  const groups = new Map();
+  for (const f of findings) {
+    const snippet = normalizeSnippet(f.snippet);
+    const key = `${f.antipattern}\u0000${snippet}`;
+    let g = groups.get(key);
+    if (!g) {
+      g = {
+        antipattern: f.antipattern,
+        name: f.name,
+        severity: f.severity,
+        description: f.description,
+        snippet,
+        count: 0,
+        files: new Set(),
+        seen: new Set(),
+        locations: [],
+      };
+      groups.set(key, g);
+    }
+    g.count += 1;
+    g.files.add(f.file);
+    // Static-HTML findings carry no line, so dedupe locations: one entry per
+    // distinct file:line rather than the same file repeated.
+    const loc = f.line ? { file: f.file, line: f.line } : { file: f.file };
+    if (f.importedBy?.length) loc.importedBy = f.importedBy;
+    const locKey = `${loc.file}:${loc.line ?? ''}`;
+    if (!g.seen.has(locKey) && g.locations.length < maxLocations) {
+      g.seen.add(locKey);
+      g.locations.push(loc);
+    }
+  }
+  // Keep a rule's groups together: order rules by severity then total
+  // occurrences, and groups within a rule by their own count.
+  const ruleTotals = new Map();
+  for (const g of groups.values()) ruleTotals.set(g.antipattern, (ruleTotals.get(g.antipattern) ?? 0) + g.count);
+  return [...groups.values()]
+    .map(({ files, seen, ...g }) => ({ ...g, fileCount: files.size }))
+    .sort((a, b) =>
+      severityRank(b.severity) - severityRank(a.severity)
+      || ruleTotals.get(b.antipattern) - ruleTotals.get(a.antipattern)
+      || a.antipattern.localeCompare(b.antipattern)
+      || b.count - a.count);
+}
+
+function formatLocation(loc, cwd) {
+  const rel = cwd && path.isAbsolute(loc.file) ? path.relative(cwd, loc.file) || loc.file : loc.file;
+  const where = loc.line ? `${rel}:${loc.line}` : rel;
+  return loc.importedBy?.length ? `${where} (imported by ${loc.importedBy.join(', ')})` : where;
+}
+
+/** Human-readable grouped report: one line per unique finding. */
+function formatGroupedFindings(findings, cwd = process.cwd()) {
+  const groups = groupFindings(findings);
+  const out = [];
+  let lastRule = null;
+  for (const g of groups) {
+    if (g.antipattern !== lastRule) {
+      out.push(`\n[${g.antipattern}] ${g.name} (${g.severity})`);
+      out.push(`  → ${g.description}`);
+      lastRule = g.antipattern;
+    }
+    const where = g.locations.map(loc => formatLocation(loc, cwd)).join(', ');
+    const more = g.fileCount > g.locations.length ? `, +${g.fileCount - g.locations.length} more file(s)` : '';
+    out.push(`  ×${g.count}  ${g.snippet}`);
+    out.push(`       at ${where}${more}`);
+  }
+  const unique = groups.length;
+  out.push(`\n${findings.length} anti-pattern${findings.length === 1 ? '' : 's'} found (${unique} unique). Use --no-group to list every occurrence.`);
+  return out.join('\n');
+}
+
+export { groupFindings, formatGroupedFindings, severityRank };

package/cli/engine/fix/index.mjs

@@ -23,6 +23,7 @@ import {
 } from '../../lib/monodesign-config.mjs';
 import { HTML_EXTENSIONS, walkDir } from '../node/file-system.mjs';
 import { UNFIXABLE_REASONS, getFixer, fixableRuleIds, FIXERS } from './fixers.mjs';
+import { unifiedDiff } from './unified-diff.mjs';
 
 // ---------------------------------------------------------------------------
 // Edit application
@@ -57,32 +58,6 @@ function writeFileAtomic(filePath, content) {
   fs.renameSync(tmp, filePath);
 }
 
-// ---------------------------------------------------------------------------
-// Unified diff (minimal single-hunk implementation for --dry-run)
-// ---------------------------------------------------------------------------
-
-function unifiedDiff(oldText, newText, label) {
-  if (oldText === newText) return '';
-  const a = oldText.split('\n');
-  const b = newText.split('\n');
-  let p = 0;
-  while (p < a.length && p < b.length && a[p] === b[p]) p++;
-  let s = 0;
-  while (s < a.length - p && s < b.length - p && a[a.length - 1 - s] === b[b.length - 1 - s]) s++;
-  const aEnd = a.length - s;
-  const bEnd = b.length - s;
-  const ctxStart = Math.max(0, p - 3);
-  const ctxEnd = Math.min(a.length, aEnd + 3);
-  const oldLen = ctxEnd - ctxStart;
-  const newLen = (p - ctxStart) + (bEnd - p) + (ctxEnd - aEnd);
-  const lines = [`--- a/${label}`, `+++ b/${label}`, `@@ -${ctxStart + 1},${oldLen} +${ctxStart + 1},${newLen} @@`];
-  for (let i = ctxStart; i < p; i++) lines.push(` ${a[i]}`);
-  for (let i = p; i < aEnd; i++) lines.push(`-${a[i]}`);
-  for (let i = p; i < bEnd; i++) lines.push(`+${b[i]}`);
-  for (let i = aEnd; i < ctxEnd; i++) lines.push(` ${a[i]}`);
-  return lines.join('\n');
-}
-
 // ---------------------------------------------------------------------------
 // Linked stylesheet resolution (HTML findings whose declaration lives in CSS)
 // ---------------------------------------------------------------------------

package/cli/engine/fix/unified-diff.mjs

@@ -0,0 +1,107 @@
+// Line-level unified diff for `fix --dry-run`. The old single-hunk version
+// spanned the first to the last changed line, so 30 one-line edits spread
+// across a big file printed nearly the whole file (#424). This uses Myers'
+// O((N+M)D) algorithm — D (edited lines) is small for codemods — and emits
+// one hunk per cluster of changes with 3 lines of context.
+
+const CONTEXT = 3;
+// Beyond this many edited lines the trace gets large; fall back to replacing
+// the changed middle wholesale (still trimmed of the shared prefix/suffix).
+const MAX_EDITS = 2000;
+
+// Returns an edit script: [{ op: ' ' | '-' | '+', a, b }] where a/b index the
+// old/new line arrays; null when the diff exceeds MAX_EDITS.
+function myersDiff(a, b) {
+  const n = a.length;
+  const m = b.length;
+  const max = n + m;
+  const offset = max;
+  const v = new Array(2 * max + 2).fill(0);
+  const trace = [];
+  let found = false;
+  for (let d = 0; d <= max && !found; d++) {
+    if (d > MAX_EDITS) return null;
+    // Only diagonals -d..d can be read back for this step: O(D^2) memory.
+    trace.push(v.slice(offset - d, offset + d + 1));
+    for (let k = -d; k <= d; k += 2) {
+      let x = (k === -d || (k !== d && v[offset + k - 1] < v[offset + k + 1]))
+        ? v[offset + k + 1]
+        : v[offset + k - 1] + 1;
+      let y = x - k;
+      while (x < n && y < m && a[x] === b[y]) { x++; y++; }
+      v[offset + k] = x;
+      if (x >= n && y >= m) { found = true; break; }
+    }
+  }
+  // Backtrack through the saved frontiers.
+  const script = [];
+  let x = n;
+  let y = m;
+  for (let d = trace.length - 1; d >= 0; d--) {
+    const vd = trace[d];
+    const at = (kk) => vd[kk + d];
+    const k = x - y;
+    const prevK = (k === -d || (k !== d && at(k - 1) < at(k + 1))) ? k + 1 : k - 1;
+    const prevX = d === 0 ? 0 : at(prevK);
+    const prevY = prevX - prevK;
+    while (x > prevX && y > prevY) { script.push({ op: ' ', a: --x, b: --y }); }
+    if (d > 0) {
+      if (x === prevX) script.push({ op: '+', a: x, b: --y });
+      else script.push({ op: '-', a: --x, b: y });
+    }
+  }
+  return script.reverse();
+}
+
+function unifiedDiff(oldText, newText, label) {
+  if (oldText === newText) return '';
+  const a = oldText.split('\n');
+  const b = newText.split('\n');
+  // A trailing newline yields an empty last element, which is not a line.
+  if (a.length > 1 && b.length > 1 && a[a.length - 1] === '' && b[b.length - 1] === '') { a.pop(); b.pop(); }
+  // Trim the shared prefix/suffix first so Myers only sees the changed middle.
+  let p = 0;
+  while (p < a.length && p < b.length && a[p] === b[p]) p++;
+  let s = 0;
+  while (s < a.length - p && s < b.length - p && a[a.length - 1 - s] === b[b.length - 1 - s]) s++;
+  const oldMid = a.slice(p, a.length - s);
+  const newMid = b.slice(p, b.length - s);
+  const middle = myersDiff(oldMid, newMid) ?? [
+    ...oldMid.map((_, i) => ({ op: '-', a: i, b: 0 })),
+    ...newMid.map((_, i) => ({ op: '+', a: oldMid.length, b: i })),
+  ];
+  const script = [];
+  for (let i = 0; i < p; i++) script.push({ op: ' ', a: i, b: i });
+  for (const e of middle) script.push({ op: e.op, a: e.a + p, b: e.b + p });
+  for (let i = 0; i < s; i++) script.push({ op: ' ', a: a.length - s + i, b: b.length - s + i });
+
+  const lines = [`--- a/${label}`, `+++ b/${label}`];
+  let i = 0;
+  while (i < script.length) {
+    while (i < script.length && script[i].op === ' ') i++;
+    if (i >= script.length) break;
+    const start = Math.max(0, i - CONTEXT);
+    // Extend the hunk until a run of more than 2*CONTEXT unchanged lines.
+    let end = i;
+    let j = i;
+    while (j < script.length) {
+      if (script[j].op !== ' ') { end = j; j++; continue; }
+      let run = 0;
+      while (j + run < script.length && script[j + run].op === ' ') run++;
+      if (j + run >= script.length || run > 2 * CONTEXT) break;
+      j += run;
+    }
+    const stop = Math.min(script.length, end + 1 + CONTEXT);
+    const hunk = script.slice(start, stop);
+    const oldStart = hunk.find(e => e.op !== '+')?.a ?? script[start].a;
+    const newStart = hunk.find(e => e.op !== '-')?.b ?? script[start].b;
+    const oldLen = hunk.filter(e => e.op !== '+').length;
+    const newLen = hunk.filter(e => e.op !== '-').length;
+    lines.push(`@@ -${oldStart + 1},${oldLen} +${newStart + 1},${newLen} @@`);
+    for (const e of hunk) lines.push(`${e.op}${e.op === '+' ? b[e.b] : a[e.a]}`);
+    i = stop;
+  }
+  return lines.join('\n');
+}
+
+export { unifiedDiff };

package/cli/engine/rules/checks-background.mjs

@@ -32,9 +32,22 @@ function readOwnBackgroundColor(el, computedStyle) {
   return bg;
 }
 
+// Static mode marks the result `uncertain` when the colour is a guess: a
+// translucent layer was stacked on (or skipped over) the surface we found, a
+// body-level gradient was assumed white, or the walk never reached <body> and
+// fell back to the default white (a fragment's real surface is unknown).
+// Contrast measured against an uncertain surface is reported as unverified.
+function markUncertain(bg, uncertain) {
+  if (!DETECTOR_IS_BROWSER && uncertain) bg.uncertain = true;
+  return bg;
+}
+
 function resolveBackground(el, win, customPropMap) {
   let current = el;
+  let sawTranslucent = false;
+  let sawBody = false;
   while (current && current.nodeType === 1) {
+    if (current.tagName === 'BODY' || current.tagName === 'HTML') sawBody = true;
     const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
     const bgImage = style.backgroundImage || '';
     const hasGradientOrUrl = bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage));
@@ -66,8 +79,9 @@ function resolveBackground(el, win, customPropMap) {
     }
 
     if (bg && bg.a > 0.1) {
-      if (DETECTOR_IS_BROWSER || bg.a >= 0.5) return bg;
+      if (DETECTOR_IS_BROWSER || bg.a >= 0.5) return markUncertain(bg, sawTranslucent || bg.a < 1);
     }
+    if (bg && bg.a > 0) sawTranslucent = true;
     // No solid bg-color at this level. If THIS level has a gradient/url
     // with no underlying solid color we can read:
     //   • on body/html: assume white. Body-level gradients are almost
@@ -82,13 +96,13 @@ function resolveBackground(el, win, customPropMap) {
     //     bgs worth checking against).
     if (hasGradientOrUrl) {
       if (current.tagName === 'BODY' || current.tagName === 'HTML') {
-        return { r: 255, g: 255, b: 255, a: 1 };
+        return markUncertain({ r: 255, g: 255, b: 255, a: 1 }, true);
       }
       return null;
     }
     current = current.parentElement;
   }
-  return { r: 255, g: 255, b: 255 };
+  return markUncertain({ r: 255, g: 255, b: 255 }, sawTranslucent || !sawBody);
 }
 
 // Walk parents looking for a gradient background and return its color stops.

package/cli/engine/rules/checks-element.mjs

@@ -164,6 +164,8 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
     bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
     bgImage: style.backgroundImage || '',
     classList: el.getAttribute?.('class') || el.className || '',
+    // SVG text paints with `fill`, not `color`, so its CSS colour says nothing.
+    isSvgText: tag === 'text' || tag === 'tspan' || tag === 'textpath',
   });
 }
 

package/cli/engine/rules/checks-pure.mjs

@@ -60,7 +60,7 @@ function isEmojiOnlyText(text) {
 }
 
 function checkColors(opts) {
-  const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList } = opts;
+  const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList, isSvgText } = opts;
   if (SAFE_TAGS.has(tag)) {
     // Exception for <a> and <button> elements styled as buttons. SAFE_TAGS
     // exists to suppress contrast noise on inline links and unstyled controls,
@@ -108,7 +108,14 @@ function checkColors(opts) {
         // like `text-paper/60` on `bg-ink` sections are the FP pattern.
         const isAlphaFallbackFP = !DETECTOR_IS_BROWSER && !effectiveBg && (textColor.a != null && textColor.a < 1);
         if (!isAlphaFallbackFP) {
-          findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}` });
+          const snippet = `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}`;
+          // Static analysis can't composite translucent text/surfaces, see
+          // through gradients, or read SVG `fill`, so those ratios are guesses:
+          // report them as unverified rather than definite failures (#424).
+          const unverified = !DETECTOR_IS_BROWSER && (
+            (textColor.a ?? 1) < 1 || !effectiveBg || (effectiveBg.a ?? 1) < 1 || effectiveBg.uncertain || isSvgText
+          );
+          findings.push(unverified ? { id: 'low-contrast', snippet, unverified: true } : { id: 'low-contrast', snippet });
         }
       }
     }

package/cli/lib/monodesign-config-consent.mjs

@@ -0,0 +1,93 @@
+/**
+ * Design-hook consent persistence for monodesign-config.mjs: the recorded
+ * per-developer accept/decline decision in config.local.json, and keeping
+ * that file out of git via `.git/info/exclude`.
+ *
+ * Split out of monodesign-config.mjs. See that file for context.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
+import { join, dirname, isAbsolute } from 'node:path';
+import { getConfigPath, getLocalConfigPath, hookSection, safeReadJson } from './monodesign-config-core.mjs';
+
+/**
+ * The recorded design-hook decision: 'accepted' | 'declined' | undefined.
+ * config.local.json (per-developer) overrides config.json.
+ */
+export function getHookConsent(root) {
+  let consent;
+  for (const filePath of [getConfigPath(root), getLocalConfigPath(root)]) {
+    const hook = hookSection(safeReadJson(filePath));
+    if (hook && (hook.consent === 'accepted' || hook.consent === 'declined')) consent = hook.consent;
+  }
+  return consent;
+}
+
+/**
+ * Persist the per-developer decision to config.local.json, preserving any
+ * sibling keys, and ensure the file is gitignored.
+ */
+export function setHookConsent(root, value) {
+  const filePath = getLocalConfigPath(root);
+  const existing = safeReadJson(filePath) || {};
+  const hook = hookSection(existing) || {};
+  const next = { ...existing, hook: { ...hook, consent: value } };
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`);
+  ensureConfigGitExclude(root);
+  return filePath;
+}
+
+const EXCLUDE_OPEN = '# monodesign-config-ignore-start';
+const EXCLUDE_CLOSE = '# monodesign-config-ignore-end';
+const EXCLUDE_PATTERNS = ['.monodesign/config.local.json'];
+
+/**
+ * Add config.local.json to `.git/info/exclude` so a developer's decision is
+ * never committed. Idempotent via marker comments. Best-effort; returns false
+ * when there is no resolvable git dir.
+ */
+export function ensureConfigGitExclude(root) {
+  try {
+    const gitDir = resolveGitDir(root);
+    if (!gitDir) return false;
+    const target = join(gitDir, 'info', 'exclude');
+    const existing = existsSync(target) ? readFileSync(target, 'utf-8') : '';
+    const block = [EXCLUDE_OPEN, ...EXCLUDE_PATTERNS, EXCLUDE_CLOSE].join('\n');
+    const markerRe = new RegExp(`${escapeRegExp(EXCLUDE_OPEN)}[\\s\\S]*?${escapeRegExp(EXCLUDE_CLOSE)}`);
+    let updated;
+    if (markerRe.test(existing)) {
+      updated = existing.replace(markerRe, block);
+    } else {
+      const prefix = existing.length === 0 ? '' : existing.endsWith('\n') ? existing : `${existing}\n`;
+      updated = `${prefix}${block}\n`;
+    }
+    if (updated !== existing) {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, updated);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveGitDir(root) {
+  const dotGit = join(root, '.git');
+  if (!existsSync(dotGit)) return null;
+  try {
+    if (statSync(dotGit).isDirectory()) return dotGit;
+    // A `.git` file (worktree/submodule) points elsewhere: "gitdir: <path>".
+    const match = readFileSync(dotGit, 'utf-8').match(/gitdir:\s*(.+)/);
+    if (match) {
+      const resolved = match[1].trim();
+      return isAbsolute(resolved) ? resolved : join(root, resolved);
+    }
+  } catch {
+    /* fall through */
+  }
+  return null;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/cli/lib/monodesign-config-core.mjs

@@ -0,0 +1,37 @@
+/**
+ * Config-file path layout and raw JSON section readers shared by the
+ * monodesign-config.mjs sibling modules.
+ *
+ * Split out of monodesign-config.mjs. See that file for context.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function getConfigPath(root) {
+  return join(root, '.monodesign', 'config.json');
+}
+
+export function getLocalConfigPath(root) {
+  return join(root, '.monodesign', 'config.local.json');
+}
+
+export function safeReadJson(filePath) {
+  try {
+    const raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+    return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+export function hookSection(raw) {
+  return raw?.hook && typeof raw.hook === 'object' && !Array.isArray(raw.hook) ? raw.hook : null;
+}
+
+export function detectorSection(raw) {
+  return raw?.detector && typeof raw.detector === 'object' && !Array.isArray(raw.detector) ? raw.detector : null;
+}
+
+export function uniqueStrings(values) {
+  return Array.from(new Set(values.map(String)));
+}

package/cli/lib/monodesign-config-detection.mjs

@@ -0,0 +1,133 @@
+/**
+ * Reading and writing the detector-filter subtree (`detector.*`, with
+ * back-compat fallback to legacy `hook.*`) of the unified `.monodesign`
+ * config for monodesign-config.mjs.
+ *
+ * Split out of monodesign-config.mjs. See that file for context.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { detectorSection, getConfigPath, getLocalConfigPath, hookSection, safeReadJson, uniqueStrings } from './monodesign-config-core.mjs';
+import { mergeIgnoreValues, normalizeIgnoreRule, normalizeIgnoreValueEntries } from './monodesign-config-ignore-value.mjs';
+import { ensureConfigGitExclude } from './monodesign-config-consent.mjs';
+
+const DETECTOR_CONFIG_KEYS = new Set(['ignoreRules', 'ignoreFiles', 'ignoreValues', 'designSystem']);
+
+const DEFAULT_DETECTION_CONFIG = Object.freeze({
+  ignoreRules: [],
+  ignoreFiles: [],
+  ignoreValues: [],
+  designSystem: { enabled: true },
+});
+
+function cloneDetectionConfig() {
+  return {
+    ignoreRules: [],
+    ignoreFiles: [],
+    ignoreValues: [],
+    designSystem: { ...DEFAULT_DETECTION_CONFIG.designSystem },
+  };
+}
+
+function cloneRawDetectionConfig() {
+  return {
+    ignoreRules: [],
+    ignoreFiles: [],
+    ignoreValues: [],
+  };
+}
+
+function applyDetectionConfigSource(config, raw) {
+  if (!raw || typeof raw !== 'object') return config;
+  if (raw.designSystem && typeof raw.designSystem === 'object' && !Array.isArray(raw.designSystem)) {
+    config.designSystem = {
+      ...config.designSystem,
+      enabled: raw.designSystem.enabled !== false,
+    };
+  }
+  if (Array.isArray(raw.ignoreRules)) {
+    config.ignoreRules = uniqueStrings([...config.ignoreRules, ...raw.ignoreRules]);
+  }
+  if (Array.isArray(raw.ignoreFiles)) {
+    config.ignoreFiles = uniqueStrings([...config.ignoreFiles, ...raw.ignoreFiles]);
+  }
+  if (Array.isArray(raw.ignoreValues)) {
+    config.ignoreValues = mergeIgnoreValues(config.ignoreValues, raw.ignoreValues);
+  }
+  return config;
+}
+
+/**
+ * Detector filters shared by `monomind design detect` and the design hook.
+ * `hook.enabled` remains hook lifecycle state; manual CLI scans still run when
+ * the hook is disabled, but they honor the same ignore rules and design-system
+ * toggle.
+ */
+export function readDetectionConfig(root) {
+  const config = cloneDetectionConfig();
+  for (const filePath of [getConfigPath(root), getLocalConfigPath(root)]) {
+    const raw = safeReadJson(filePath);
+    // Back-compat: old builds stored detector filters under hook.*.
+    applyDetectionConfigSource(config, hookSection(raw));
+    applyDetectionConfigSource(config, detectorSection(raw));
+  }
+  return config;
+}
+
+export function readRawDetectionConfig(root, opts = {}) {
+  const raw = safeReadJson(opts.local ? getLocalConfigPath(root) : getConfigPath(root));
+  const config = cloneRawDetectionConfig();
+  applyDetectionConfigSource(config, hookSection(raw));
+  applyDetectionConfigSource(config, detectorSection(raw));
+  return config;
+}
+
+export function writeDetectionConfig(root, detectorConfig, opts = {}) {
+  const filePath = opts.local ? getLocalConfigPath(root) : getConfigPath(root);
+  if (opts.local) ensureConfigGitExclude(root);
+  const existing = safeReadJson(filePath) || {};
+  const existingHook = hookSection(existing);
+  const nextHook = stripDetectorKeys(existingHook);
+  const nextDetector = {
+    ...(detectorSection(existing) || {}),
+    ...normalizeDetectionConfigForWrite(detectorConfig),
+  };
+  const next = {
+    ...existing,
+    detector: nextDetector,
+  };
+  if (nextHook && Object.keys(nextHook).length > 0) {
+    next.hook = nextHook;
+  } else {
+    delete next.hook;
+  }
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`);
+  return filePath;
+}
+
+function normalizeDetectionConfigForWrite(config) {
+  const out = {};
+  if (Array.isArray(config?.ignoreRules)) {
+    out.ignoreRules = uniqueStrings(config.ignoreRules.map((rule) => normalizeIgnoreRule(rule)).filter(Boolean));
+  }
+  if (Array.isArray(config?.ignoreFiles)) {
+    out.ignoreFiles = uniqueStrings(config.ignoreFiles.filter(v => typeof v === 'string' && v.trim()).map(v => v.trim()));
+  }
+  out.ignoreValues = normalizeIgnoreValueEntries(config?.ignoreValues || []);
+  if (config?.designSystem && typeof config.designSystem === 'object' && !Array.isArray(config.designSystem)) {
+    out.designSystem = {
+      enabled: config.designSystem.enabled !== false,
+    };
+  }
+  return out;
+}
+
+function stripDetectorKeys(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (!DETECTOR_CONFIG_KEYS.has(key)) out[key] = value;
+  }
+  return out;
+}