@chemx/starter-kit 26.10.8-344 → 26.10.10-75

package/cli/audit/autofix.js

@@ -1,5 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { resolveSafePath } from '../path-scope.js';
+import { applyEdits } from '../apply-edits.js';
+import { autofixContent } from './autofix-content.js';
+import { STATUS, inconclusive } from '../result-status.js';
+
+export { autofixContent } from './autofix-content.js';
 
 const IGNORED_DIRS = new Set([
   'node_modules',
@@ -9,183 +15,92 @@ const IGNORED_DIRS = new Set([
   '.git',
   '.next',
   '.turbo',
-  '.cache'
+  '.cache',
+  '.chemx',
+  '.claude'
 ]);
 
-const FIXABLE_EXTENSIONS = new Set(['.tsx', '.ts', '.jsx', '.js', '.vue', '.md', '.scss', '.css']);
-
-const RESIDUE_PATTERNS = [
-  ['hope this', 'helps'].join(' '),
-  ['feel free', 'to tweak'].join(' '),
-  ['let me know', 'if you need'].join(' '),
-  ['as an ai', 'language model'].join(' ')
-];
-
-const RESIDUE_REGEX = new RegExp(`\\b(?:${RESIDUE_PATTERNS.join('|')})\\b`, 'i');
-const PREAMBLE_REGEX = /\b(?:here(?:'s| is) the (?:complete|updated|refactored|full) (?:code|implementation|file|component|version))\b/i;
-const TRUNCATION_REGEX = /^\s*\/\/\s*\.\.\.\s*(?:existing|rest of|remaining)\s+(?:code|implementation|logic|imports)/i;
-const MARKDOWN_FENCE_REGEX = /^\s*```(?:typescript|javascript|tsx|jsx|vue|js|ts|html|css|scss)?\s*$/;
-
-export const autofixContent = (content, options = {}) => {
-  const allowedRules = options.rules ? new Set(options.rules) : null;
-  const shouldFix = (rule) => !allowedRules || allowedRules.has(rule);
-
-  const lines = content.split('\n');
-  const fixes = [];
-  const resultLines = [];
-
-  for (let i = 0; i < lines.length; i++) {
-    let line = lines[i];
-    const lineNumber = i + 1;
-    let shouldDropLine = false;
-
-    // 1. Leaked markdown fence removal
-    if (shouldFix('AI_SLOP_CONVERSATIONAL_ARTIFACT') && MARKDOWN_FENCE_REGEX.test(line)) {
-      fixes.push({
-        line: lineNumber,
-        rule: 'AI_SLOP_CONVERSATIONAL_ARTIFACT',
-        action: 'Removed leaked markdown code fence'
-      });
-      shouldDropLine = true;
-    }
-
-    // 2. Pure conversational preamble or residue comment removal
-    if (!shouldDropLine && shouldFix('AI_SLOP_CONVERSATIONAL_ARTIFACT')) {
-      const isComment = /^\s*(?:\/\/|\/\*|<!--)/.test(line);
-      if (isComment && (PREAMBLE_REGEX.test(line) || RESIDUE_REGEX.test(line))) {
-        fixes.push({
-          line: lineNumber,
-          rule: 'AI_SLOP_CONVERSATIONAL_ARTIFACT',
-          action: 'Removed AI conversational residue comment'
-        });
-        shouldDropLine = true;
-      }
-    }
+// Markdown is deliberately absent: fences and prose are content there, not AI residue.
+export const FIXABLE_EXTENSIONS = new Set(['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs', '.vue', '.svelte', '.scss', '.css']);
 
-    // 3. AI lazy placeholder comment removal
-    const hasLazyTruncation = TRUNCATION_REGEX.test(line);
-    const isLazyTruncationEligible = !shouldDropLine && shouldFix('AI_SLOP_LAZY_PLACEHOLDER');
-    if (isLazyTruncationEligible && hasLazyTruncation) {
-      fixes.push({
-        line: lineNumber,
-        rule: 'AI_SLOP_LAZY_PLACEHOLDER',
-        action: 'Removed lazy AI truncation placeholder comment'
-      });
-      shouldDropLine = true;
-    }
+const isFixable = (filePath) => FIXABLE_EXTENSIONS.has(path.extname(filePath).toLowerCase());
 
-    const hasEmDash = line.includes('\u2014');
-    const isEmDashEligible = !shouldDropLine && shouldFix('TYPOGRAPHY_EM_DASH');
-    if (isEmDashEligible && hasEmDash) {
-      line = line.replace(/\u2014/g, '-');
-      fixes.push({
-        line: lineNumber,
-        rule: 'TYPOGRAPHY_EM_DASH',
-        action: 'Replaced em dash with standard hyphen'
-      });
-    }
-
-    const hasTimeoutMacro = /setTimeout\([^,]+,\s*0\)/.test(line);
-    const isTimeoutEligible = !shouldDropLine && shouldFix('MACRO_TASK_OVER_MICRO_TASK');
-    if (isTimeoutEligible && hasTimeoutMacro) {
-      line = line.replace(/setTimeout\(([^,]+),\s*0\)/g, 'queueMicrotask($1)');
-      fixes.push({
-        line: lineNumber,
-        rule: 'MACRO_TASK_OVER_MICRO_TASK',
-        action: 'Replaced setTimeout(fn, 0) with queueMicrotask(fn)'
-      });
-    }
-
-    if (!shouldDropLine) {
-      resultLines.push(line);
-    }
-  }
-
-  return {
-    fixedContent: resultLines.join('\n'),
-    fixes
-  };
-};
-
-const collectFiles = (targetPath, baseDir) => {
-  const stat = fs.statSync(targetPath);
-  if (stat.isFile()) {
-    return [targetPath];
-  }
+const collectFiles = (targetPath) => {
+  const isFile = fs.statSync(targetPath).isFile();
+  if (isFile) return isFixable(targetPath) ? [targetPath] : [];
 
   let files = [];
-  const entries = fs.readdirSync(targetPath, { withFileTypes: true });
-  for (const entry of entries) {
-    if (IGNORED_DIRS.has(entry.name)) continue;
+  for (const entry of fs.readdirSync(targetPath, { withFileTypes: true })) {
+    const isIgnored = IGNORED_DIRS.has(entry.name);
+    if (isIgnored) continue;
     const fullPath = path.join(targetPath, entry.name);
-    if (entry.isDirectory()) {
-      files = files.concat(collectFiles(fullPath, baseDir));
-    } else if (FIXABLE_EXTENSIONS.has(path.extname(entry.name))) {
-      files.push(fullPath);
-    }
+    const isDirectory = entry.isDirectory();
+    const isFixableFile = !isDirectory && isFixable(entry.name);
+    if (isDirectory) files = files.concat(collectFiles(fullPath));
+    else if (isFixableFile) files.push(fullPath);
   }
   return files;
 };
 
+// No fixable file was looked at: that proves nothing, so it is inconclusive (exit 3), never a green check.
+const NOTHING_CHECKED = inconclusive('NO_FILES_CHECKED');
+
+const excludedReason = (filePath) => {
+  const ext = path.extname(filePath).toLowerCase() || 'extensionless';
+  return `${ext} files are not autofix targets (fixable: ${[...FIXABLE_EXTENSIONS].join(' ')}); nothing was checked`;
+};
+
+/**
+ * Applies token-aware mechanical fixes to a file or directory, through applyEdits
+ * (parse check, declaration-loss check, team locks, atomic writes, one rollback-able batch).
+ *
+ * @param {string} targetPath File or directory (default 'src').
+ * @param {object} [options] { cwd, dryRun, rules, agentId }
+ * @returns {object} status (pass, or inconclusive when no fixable file was checked), the uncapped
+ *   fix list, suggestions, skipped files, and the diff on a dry run.
+ */
 export const runAutofix = (targetPath, options = {}) => {
   const cwd = options.cwd || process.cwd();
-  const resolvedTarget = path.resolve(cwd, targetPath || 'src');
+  const target = targetPath || 'src';
   const dryRun = Boolean(options.dryRun);
-
-  if (!fs.existsSync(resolvedTarget)) {
-    return {
-      target: targetPath || 'src',
-      dryRun,
-      filesScanned: 0,
-      filesChanged: 0,
-      totalFixes: 0,
-      fixes: []
-    };
-  }
-
-  const files = collectFiles(resolvedTarget, cwd);
-  const allFixes = [];
-  let filesChanged = 0;
-
+  const resolvedTarget = resolveSafePath(target, cwd);
+  const root = fs.realpathSync(cwd);
+  const empty = { ...NOTHING_CHECKED, target, dryRun, filesScanned: 0, filesChanged: 0, totalFixes: 0, fixes: [], suggestions: [], skipped: [] };
+  const isMissing = !fs.existsSync(resolvedTarget);
+  if (isMissing) return { ...empty, skipped: [{ file: target, reason: 'target does not exist; nothing was checked' }] };
+  const isExcludedFile = fs.statSync(resolvedTarget).isFile() && !isFixable(resolvedTarget);
+  if (isExcludedFile) return { ...empty, skipped: [{ file: path.relative(root, resolvedTarget), reason: excludedReason(resolvedTarget) }] };
+
+  const files = collectFiles(resolvedTarget);
+  const fixes = [];
+  const suggestions = [];
+  const skipped = [];
+  const edits = [];
   for (const filePath of files) {
-    const relPath = path.relative(cwd, filePath);
-    const originalContent = fs.readFileSync(filePath, 'utf-8');
-    const { fixedContent, fixes } = autofixContent(originalContent, options);
-
-    if (fixes.length > 0) {
-      filesChanged += 1;
-      for (const fix of fixes) {
-        allFixes.push({
-          file: relPath,
-          line: fix.line,
-          rule: fix.rule,
-          action: fix.action
-        });
-      }
-
-      if (!dryRun) {
-        fs.writeFileSync(filePath, fixedContent, 'utf-8');
-      }
-    }
+    const file = path.relative(root, filePath);
+    const original = fs.readFileSync(filePath, 'utf-8');
+    const result = autofixContent(original, { ...options, filePath });
+    const isSkipped = Boolean(result.skipped);
+    if (isSkipped) skipped.push({ file, reason: result.skipped });
+    result.suggestions.forEach((s) => suggestions.push({ file, ...s }));
+    const isChanged = result.fixes.length > 0 && result.fixedContent !== original;
+    if (!isChanged) continue;
+    result.fixes.forEach((f) => fixes.push({ file, line: f.line, rule: f.rule, action: f.action }));
+    edits.push({ path: filePath, content: result.fixedContent });
   }
 
-  // Token optimization: cap fixes list to top 15 samples if very large
-  const MAX_REPORTED_FIXES = 15;
-  const isCapped = allFixes.length > MAX_REPORTED_FIXES;
-  const reportedFixes = isCapped ? allFixes.slice(0, MAX_REPORTED_FIXES) : allFixes;
-
-  const result = {
-    target: targetPath || 'src',
+  const applied = edits.length > 0 ? applyEdits(edits, { cwd, dryRun, agentId: options.agentId }) : null;
+  const isNothingChecked = files.length === 0;
+  return {
+    ...(isNothingChecked ? NOTHING_CHECKED : { status: STATUS.PASS }),
+    target,
     dryRun,
     filesScanned: files.length,
-    filesChanged,
-    totalFixes: allFixes.length,
-    fixes: reportedFixes
+    filesChanged: edits.length,
+    totalFixes: fixes.length,
+    fixes,
+    suggestions,
+    skipped,
+    ...(dryRun && applied ? { diff: applied.diff } : {})
   };
-
-  if (isCapped) {
-    result.omittedFixesCount = allFixes.length - MAX_REPORTED_FIXES;
-  }
-
-  return result;
 };

package/cli/audit/budget-rules.js

@@ -0,0 +1,84 @@
+/**
+ * LINE_BUDGET_FILE, LINE_BUDGET_MOLECULE and VIEW_MONOLITH from the one budget
+ * policy in line-budgets.js (finding line-budget-chaos).
+ */
+import { PILLARS } from './rules-registry.js';
+import {
+  countLines,
+  getLineBudgets,
+  resolveFileTier,
+  isViewMarkupFile,
+  classifyFileSize
+} from './line-budgets.js';
+
+const fileViolation = (relativePath, rule, severity, hazard, directive) => ({
+  filePath: relativePath,
+  line: 1,
+  column: 1,
+  hazard,
+  rule,
+  severity,
+  pillar: PILLARS.PILLAR_1,
+  directive
+});
+
+const FILE_SEVERITY_BY_CLASS = Object.freeze({
+  extreme: { severity: 'CRITICAL', limitKey: 'critical', label: 'Extreme monolith hazard' },
+  severe: { severity: 'HIGH', limitKey: 'high', label: 'Severe monolith hazard' },
+  warning: { severity: 'MEDIUM', limitKey: 'warn', label: 'Monolith line budget warning' }
+});
+
+const resolveFileSeverity = (lineCount, budget) => {
+  const { severity, limitKey, label } = FILE_SEVERITY_BY_CLASS[classifyFileSize(lineCount, budget)];
+  return { severity, limit: budget[limitKey], label };
+};
+
+const resolveMoleculeSeverity = (lineCount, limit) => {
+  const isCriticalMolecule = lineCount >= limit * 5;
+  if (isCriticalMolecule) return 'CRITICAL';
+  const isHighMolecule = lineCount >= limit * 2.5;
+  if (isHighMolecule) return 'HIGH';
+  return 'MEDIUM';
+};
+
+const resolveTemplateLines = (content, sfc) => {
+  const template = sfc?.template;
+  if (template) return template.endLine - template.startLine + 1;
+  return countLines(content);
+};
+
+/**
+ * @param {{ content: string, relativePath: string, config?: object, sfc?: object|null, hasHighComplexity?: boolean }} input
+ */
+export const checkLineBudgets = ({ content, relativePath, config = {}, sfc = null, hasHighComplexity = false }) => {
+  const budgets = getLineBudgets(config);
+  const lineCount = countLines(content);
+  const tier = resolveFileTier(relativePath, config);
+
+  const isFileMonolith = classifyFileSize(lineCount, budgets.file) !== null;
+  if (isFileMonolith) {
+    const { severity, limit, label } = resolveFileSeverity(lineCount, budgets.file);
+    return [fileViolation(relativePath, 'LINE_BUDGET_FILE', severity, `${label} (${lineCount} > ${limit} lines)`,
+      'Decompose monolith into domain capsules and molecules (Directive 1.A)')];
+  }
+
+  const isOverMoleculeBudget = tier === 'molecule' && lineCount > budgets.molecule;
+  const isMoleculeEnforced = budgets.isMoleculeHardCap || hasHighComplexity;
+  const isMoleculeViolation = Boolean(isOverMoleculeBudget && isMoleculeEnforced);
+  if (isMoleculeViolation) {
+    const severity = resolveMoleculeSeverity(lineCount, budgets.molecule);
+    return [fileViolation(relativePath, 'LINE_BUDGET_MOLECULE', severity, `Molecule capsule over budget (${lineCount} > ${budgets.molecule} lines, ${budgets.profile})`,
+      'Split molecule into focused sub-molecules or extract state to a composable (Directive 1.C)')];
+  }
+
+  const isViewEntry = tier === 'view' && isViewMarkupFile(relativePath);
+  const templateLines = isViewEntry ? resolveTemplateLines(content, sfc) : 0;
+  const isViewMonolith = templateLines > budgets.viewTemplate.warn;
+  if (isViewMonolith) {
+    const isSevere = templateLines >= budgets.viewTemplate.critical;
+    return [fileViolation(relativePath, 'VIEW_MONOLITH', isSevere ? 'CRITICAL' : 'MEDIUM',
+      `View template over budget (${templateLines} > ${budgets.viewTemplate.warn} lines)`,
+      'Refactor top-level view to a 10 to 20 line Table of Contents (Directive 1.B)')];
+  }
+  return [];
+};

package/cli/audit/catch-predicates.js

@@ -0,0 +1,51 @@
+/**
+ * Catch-clause handling predicates for ERROR_SWALLOWED_EXCEPTION (Directive 2.H).
+ * A catch is handled when it throws, returns a value, calls anything (logger,
+ * notifier, handler), or assigns state that outlives the catch (error state,
+ * a fallback value, a member of an outer object).
+ */
+import * as t from '@babel/types';
+
+const isMeaningfulStatement = (stmt) => !t.isEmptyStatement(stmt);
+
+export const isEmptyCatchBody = (catchNode) => {
+  const body = catchNode.body?.body || [];
+  return !body.some(isMeaningfulStatement);
+};
+
+const isOuterBindingTarget = (left, catchPath) => {
+  const isMember = t.isMemberExpression(left) || t.isOptionalMemberExpression(left);
+  if (isMember) return true;
+  if (!t.isIdentifier(left)) return false;
+  const binding = catchPath.scope.getBinding(left.name);
+  if (!binding) return true;
+  const isDeclaredInsideCatch = Boolean(binding.path.findParent((p) => p === catchPath));
+  return !isDeclaredInsideCatch;
+};
+
+/** True when the catch body neither propagates, reports, nor records the failure. */
+export const isSwallowedCatch = (astPath) => {
+  if (isEmptyCatchBody(astPath.node)) return true;
+
+  let hasActiveHandling = false;
+  const markHandled = () => { hasActiveHandling = true; };
+  astPath.traverse({
+    ThrowStatement: markHandled,
+    CallExpression: markHandled,
+    OptionalCallExpression: markHandled,
+    NewExpression: markHandled,
+    ReturnStatement(retPath) {
+      const hasValue = retPath.node.argument !== null;
+      if (hasValue) markHandled();
+    },
+    AssignmentExpression(assignPath) {
+      const isOuterTarget = isOuterBindingTarget(assignPath.node.left, astPath);
+      if (isOuterTarget) markHandled();
+    },
+    Function(fnPath) {
+      fnPath.skip();
+    }
+  });
+
+  return !hasActiveHandling;
+};

package/cli/audit/chemx-dir.js

@@ -0,0 +1,76 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isSqliteMemoryTarget, isLinkedWorktreeRoot } from '../sqlite-memory.js';
+import { hasProjectMarker, isForbiddenRoot, forbiddenRootRefusal } from '../project-markers.js';
+
+// Locates (and creates) the .chemx directory that holds history and the index db.
+// The walk prefers an existing ancestor .chemx, but stops at the first project marker (.git,
+// package.json, .chemxrc; a linked worktree has a .git file): each package and each checkout keeps
+// its own index instead of sharing a parent's. It never climbs into the OS temp dir, its ancestors
+// or the filesystem root, and never answers one of them (#2570): a stray /tmp/.chemx is ignored.
+const isIndexBoundary = (dir) => isLinkedWorktreeRoot(fs, path, dir) || hasProjectMarker(dir);
+
+// Throws for a forbidden root: callers would otherwise create a db at /tmp or /.
+const refuseForbidden = (dir) => {
+  const refusal = forbiddenRootRefusal(dir);
+  if (refusal) throw new Error(refusal);
+  return dir;
+};
+
+export const findChemxDir = (startDir = process.cwd()) => {
+  const hasCustomRoot = Boolean(process.env.CHEMX_PROJECT_ROOT);
+  if (hasCustomRoot) {
+    return path.join(refuseForbidden(path.resolve(process.env.CHEMX_PROJECT_ROOT)), '.chemx');
+  }
+
+  let current = path.resolve(startDir);
+  while (!isForbiddenRoot(current)) {
+    const candidate = path.join(current, '.chemx');
+    const hasExistingChemx = fs.existsSync(candidate);
+    if (hasExistingChemx) {
+      return candidate;
+    }
+    if (isIndexBoundary(current)) return candidate;
+    current = path.dirname(current);
+  }
+
+  return path.join(refuseForbidden(path.resolve(startDir)), '.chemx');
+};
+
+export const ensureChemxDir = (cwd = process.cwd()) => {
+  const isMemoryTarget = isSqliteMemoryTarget(cwd);
+  if (isMemoryTarget) {
+    throw new Error(`ensureChemxDir: "${cwd}" is an in-memory SQLite target, not a directory`);
+  }
+  const dir = findChemxDir(cwd);
+  try {
+    const isDirMissing = !fs.existsSync(dir);
+    if (isDirMissing) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  } catch {
+    return dir;
+  }
+
+  // Ensure .chemx is gitignored if git repo exists
+  const targetParent = path.dirname(dir);
+  const gitDir = path.resolve(targetParent, '.git');
+  const hasGit = fs.existsSync(gitDir);
+  if (hasGit) {
+    const gitignorePath = path.resolve(targetParent, '.gitignore');
+    try {
+      const hasGitignore = fs.existsSync(gitignorePath);
+      let content = hasGitignore ? fs.readFileSync(gitignorePath, 'utf-8') : '';
+      const hasChemxEntry = content.includes('.chemx');
+      if (!hasChemxEntry) {
+        const hasTrailingNewline = content.endsWith('\n') || content.length === 0;
+        const trailingNewline = hasTrailingNewline ? '' : '\n';
+        fs.appendFileSync(gitignorePath, `${trailingNewline}# Chemical X local telemetry & audit history\n.chemx/\n`, 'utf-8');
+      }
+    } catch {
+      return dir;
+    }
+  }
+
+  return dir;
+};

package/cli/audit/clone-detector.js

@@ -2,7 +2,8 @@ import path from 'node:path';
 import { deserializeVector, cosineSimilarity } from '../embeddings/vectorizer.js';
 
 const isSpecOrTest = (filePath) => {
-  if (!filePath || typeof filePath !== 'string') return false;
+  const isInvalidPath = !filePath || typeof filePath !== 'string';
+  if (isInvalidPath) return false;
   return filePath.includes('.spec.') || filePath.includes('.test.') || filePath.includes('__tests__');
 };
 
@@ -10,7 +11,8 @@ export const detectSemanticClones = (db, options = {}) => {
   const isValidDb = Boolean(db);
   if (!isValidDb) return { count: 0, threshold: 0.85, pairs: [] };
 
-  const threshold = typeof options.threshold === 'number' ? options.threshold : 0.85;
+  const hasNumericThreshold = typeof options.threshold === 'number';
+  const threshold = hasNumericThreshold ? options.threshold : 0.85;
   const limit = options.limit || 50;
 
   const rows = db.prepare(

package/cli/audit/comment-regions.js

@@ -0,0 +1,83 @@
+/**
+ * Where comments sit on a source line, outside string literals, so a `chemx-allow:` marker
+ * quoted in a string never counts as an annotation. One pass per line; the state carries an
+ * open block comment and an open template literal into the next line.
+ *
+ * Known gaps (they err towards flagging): a lone apostrophe in markup text or a quote inside
+ * a regex literal opens a string for the rest of that line, and C# verbatim strings are read
+ * with backslash escapes.
+ */
+const BLOCK_OPENERS = [['/*', '*/'], ['<!--', '-->']];
+const QUOTES = new Set(['"', "'", '`']);
+const BACKSLASH = '\\';
+const CARRIED_QUOTE = '`';
+
+export const INITIAL_SCAN_STATE = Object.freeze({ inBlock: false, blockCloser: null, quote: null });
+
+const findBlockOpener = (line, index) => BLOCK_OPENERS.find(([opener]) => line.startsWith(opener, index));
+
+const isHashComment = (line, index) => line[index] === '#' && (index === 0 || /\s/.test(line[index - 1]));
+
+const isLineCommentStart = (line, index) => line.startsWith('//', index) || isHashComment(line, index);
+
+// Index just past the string that is open at index (quote already consumed), or -1 when it
+// runs past the end of the line.
+const skipString = (line, index, quote) => {
+  let cursor = index;
+  while (cursor < line.length) {
+    const char = line[cursor];
+    const isEscape = char === BACKSLASH;
+    const isClosingQuote = char === quote;
+    if (isClosingQuote) return cursor + 1;
+    cursor += isEscape ? 2 : 1;
+  }
+  return -1;
+};
+
+/**
+ * Comment regions on one line as [start, end) column pairs, and the state for the next line.
+ */
+export const scanCommentRegions = (line, state = INITIAL_SCAN_STATE) => {
+  const regions = [];
+  let { inBlock, blockCloser, quote } = state;
+  let regionStart = 0;
+  let index = 0;
+  while (index < line.length) {
+    if (inBlock) {
+      const closeAt = line.indexOf(blockCloser, index);
+      const isStillOpen = closeAt === -1;
+      if (isStillOpen) break;
+      regions.push([regionStart, closeAt + blockCloser.length]);
+      index = closeAt + blockCloser.length;
+      inBlock = false;
+      continue;
+    }
+    if (quote) {
+      const afterString = skipString(line, index, quote);
+      const isUnterminated = afterString === -1;
+      if (isUnterminated) break;
+      quote = null;
+      index = afterString;
+      continue;
+    }
+    if (isLineCommentStart(line, index)) {
+      regions.push([index, line.length]);
+      index = line.length;
+      break;
+    }
+    const block = findBlockOpener(line, index);
+    if (block) {
+      inBlock = true;
+      blockCloser = block[1];
+      regionStart = index;
+      index += block[0].length;
+      continue;
+    }
+    const isQuote = QUOTES.has(line[index]);
+    if (isQuote) quote = line[index];
+    index += 1;
+  }
+  if (inBlock) regions.push([regionStart, line.length]);
+  const carriedQuote = quote === CARRIED_QUOTE ? quote : null;
+  return { regions, state: { inBlock, blockCloser: inBlock ? blockCloser : null, quote: carriedQuote } };
+};

package/cli/audit/coverage.js

@@ -0,0 +1,48 @@
+/**
+ * Audit coverage: how much of each scanned file the AST rules actually saw. A file
+ * that only got line-level text checks (unsupported language, --fast, parse error,
+ * an SFC template that failed to parse) is reported as partial so a low hazard
+ * count is never presented as a confident pass.
+ */
+export const COVERAGE_KINDS = Object.freeze({
+  AST: 'ast',
+  TEXT_ONLY: 'text-only',
+  PARSE_ERROR: 'parse-error',
+  EMPTY: 'empty'
+});
+
+export const createCoverageCollector = () => ({ files: [] });
+
+/** Records one file. `sfc` is { scriptBlocks, hasTemplate, isTemplateParsed } for .vue files. */
+export const recordFileCoverage = (collector, { relativePath, kind, sfc = null }) => {
+  if (!collector) return;
+  collector.files.push({ relativePath, kind, sfc });
+};
+
+const isPartialEntry = (entry) => {
+  const isAstless = entry.kind !== COVERAGE_KINDS.AST && entry.kind !== COVERAGE_KINDS.EMPTY;
+  const hasUnparsedTemplate = Boolean(entry.sfc?.hasTemplate) && !entry.sfc?.isTemplateParsed;
+  return isAstless || hasUnparsedTemplate;
+};
+
+export const summarizeCoverage = (collector) => {
+  const entries = collector?.files ?? [];
+  const countKind = (kind) => entries.filter((e) => e.kind === kind).length;
+  const sfcEntries = entries.filter((e) => e.sfc);
+  const partialFiles = entries.filter(isPartialEntry).map((e) => e.relativePath);
+  const astFiles = countKind(COVERAGE_KINDS.AST);
+  return {
+    files: entries.length,
+    astParsed: astFiles,
+    textOnly: countKind(COVERAGE_KINDS.TEXT_ONLY),
+    parseErrors: countKind(COVERAGE_KINDS.PARSE_ERROR),
+    astPct: entries.length > 0 ? Math.round((astFiles / entries.length) * 100) : 100,
+    sfc: {
+      files: sfcEntries.length,
+      scriptBlocks: sfcEntries.reduce((sum, e) => sum + (e.sfc.scriptBlocks ?? 0), 0),
+      templatesParsed: sfcEntries.filter((e) => e.sfc.isTemplateParsed).length
+    },
+    isPartial: partialFiles.length > 0,
+    partialFiles: partialFiles.slice(0, 20)
+  };
+};