@hone-ai/cli 1.4.0

package/lib/metrics-collect.js

@@ -0,0 +1,214 @@
+'use strict';
+/**
+ * metrics-collect.js — H-008 pure helpers for the `hone metrics collect`
+ * CLI command. No I/O — callers (hone-cli.js) do all filesystem reads,
+ * git/gh shells, file writes, and pass parsed inputs in.
+ *
+ * Same shape as cli/lib/pipeline-status.js (H-009) +
+ * cli/lib/auto-detect.js (H-018) + cli/lib/learnings-parse.js (H-035).
+ * 4th instance of the pure-helpers + thin-CLI-wrapper pattern.
+ *
+ * Closes #17 (sub-task (a) — CLI command). Sub-tasks (b) Code Reviewer
+ * agent prompt wiring and (c) CI gate are deferred to Phase 3.7+.
+ */
+
+const yaml = require('js-yaml');
+
+// ── Pipeline-metadata → metrics-schema name mapping (H-008/A1) ────
+// Verified against docs/metrics/README.md and 16 existing pipeline
+// metadata.yml files. step_3b is conditional (manual E2E mode only).
+const PIPELINE_TO_METRICS_NAME = {
+  step_0:  'story_groomer',
+  step_1:  'implementation_planner',
+  step_2:  'unit_test_writer',
+  step_3a: 'e2e_qa_planner',
+  step_3b: 'e2e_test_spec_writer',
+  step_4:  'code_builder',
+  step_5:  'code_reviewer',
+};
+
+// ─────────────────────────────────────────────────────────────────────
+// parseISODate — parse a YYYY-MM-DD string to a local-midnight Date
+// ─────────────────────────────────────────────────────────────────────
+//   Avoids the `new Date('2026-04-27')` timezone trap (parses as UTC,
+//   which becomes the previous day in west-of-UTC locales).
+function parseISODate(s) {
+  if (!s) return null;
+  const m = String(s).match(/^(\d{4})-(\d{2})-(\d{2})/);
+  if (!m) return null;
+  return new Date(+m[1], +m[2] - 1, +m[3]);
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// businessDaysBetween — count weekdays (Mon-Fri) inclusive in a date range
+// ─────────────────────────────────────────────────────────────────────
+//   Returns null if start is missing or unparseable.
+//   end defaults to today if missing.
+function businessDaysBetween(startStr, endStr) {
+  if (!startStr) return null;
+  const start = parseISODate(startStr);
+  const end = endStr ? parseISODate(endStr) : new Date();
+  if (!start || !end || Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) {
+    return null;
+  }
+  if (end < start) return 0;
+
+  let days = 0;
+  // Iterate day-by-day inclusive on both ends
+  const cur = new Date(start.getFullYear(), start.getMonth(), start.getDate());
+  const last = new Date(end.getFullYear(), end.getMonth(), end.getDate());
+  while (cur <= last) {
+    const dow = cur.getDay(); // 0=Sun, 6=Sat
+    if (dow !== 0 && dow !== 6) days++;
+    cur.setDate(cur.getDate() + 1);
+  }
+  return days;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// filterTestFiles — restrict a file list to recognizable test files
+// ─────────────────────────────────────────────────────────────────────
+//   Matches: *.test.{js,ts,tsx,jsx,mjs,cjs} OR *.spec.{js,ts,...} anywhere
+//   under tests/, server/test/, etc. Conservative — a file is a "test"
+//   if its name matches a recognizable test/spec pattern.
+function filterTestFiles(files) {
+  if (!Array.isArray(files)) return [];
+  const TEST_RE = /\.(?:test|spec)\.[jt]sx?$|\.(?:test|spec)\.(?:mjs|cjs)$/;
+  return files.filter(f => typeof f === 'string' && TEST_RE.test(f));
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// buildScorecard — pure transformer
+// ─────────────────────────────────────────────────────────────────────
+//   inputs: {
+//     parsedPipelineMetadata: { storyId, branch, title, base, created, steps },
+//     artifactPresence: { step_0: bool, step_1: bool, ... }   // filesystem truth
+//     gitInfo: { author? },
+//     prInfo: { pr_number? },
+//     learningsCount: number,
+//     filesChanged: string[],
+//     today: string (ISO date — for cycle_days computation)
+//   }
+//   returns: { story, branch, date, started_date, completed_date, author, steps, totals }
+function buildScorecard(inputs) {
+  const meta = inputs.parsedPipelineMetadata || {};
+  const presence = inputs.artifactPresence || {};
+  const git = inputs.gitInfo || {};
+  const pr = inputs.prInfo || {};
+  const today = inputs.today;
+
+  // ── Header ────────────────────────────────────────────────
+  const startedDate = meta.created || null;
+  const hasPr = !!(pr && pr.pr_number);
+  // completed_date: when the PR was opened (proxy = step_5.completed if PR exists)
+  const completedDate = hasPr
+    ? ((meta.steps && meta.steps.step_5 && meta.steps.step_5.completed) || null)
+    : null;
+
+  // ── Per-step blocks ─────────────────────────────────────
+  const steps = {};
+  for (const [pipKey, metKey] of Object.entries(PIPELINE_TO_METRICS_NAME)) {
+    const stepMeta = (meta.steps && meta.steps[pipKey]) || null;
+    const fileExists = !!presence[pipKey];
+
+    // Skip step_3b if absent in metadata AND no artifact (it's conditional)
+    if (pipKey === 'step_3b' && !stepMeta && !fileExists) continue;
+
+    // Filesystem-as-source-of-truth (AC-5):
+    // metadata.completed + artifact-missing → 'not-run' (don't lie)
+    let status = 'not-run';
+    if (stepMeta && stepMeta.status === 'completed' && fileExists) {
+      status = 'completed';
+    }
+
+    const block = { status };
+    if (stepMeta && stepMeta.started) block.started_date = stepMeta.started;
+    if (stepMeta && stepMeta.gate_result) block.gate_result = stepMeta.gate_result;
+    // gate_attempts, cross_validation, test_results, findings → v2 enrichment
+
+    steps[metKey] = block;
+  }
+
+  // ── pre_commit / pre_push (automated, not in pipeline metadata) ───
+  // v1 records as not-run; agents (D1) or CI (D2) can fill later
+  steps.pre_commit = { status: 'not-run' };
+  steps.pre_push = { status: 'not-run' };
+
+  // ── pr_opened block (when PR exists) ──────────────────
+  if (hasPr) {
+    steps.pr_opened = {
+      status: 'completed',
+      pr_number: pr.pr_number,
+    };
+    if (completedDate) steps.pr_opened.started_date = completedDate;
+  }
+
+  // ── Totals ─────────────────────────────────────────────
+  const stepsCompleted = Object.values(steps)
+    .filter(s => s.status === 'completed').length;
+
+  const filesChanged = Array.isArray(inputs.filesChanged) ? inputs.filesChanged : [];
+  const testsWritten = filterTestFiles(filesChanged).length;
+
+  const cycleDays = startedDate && today
+    ? Math.max(0, Math.floor((new Date(today) - new Date(startedDate)) / 86400000))
+    : null;
+  const businessCycleDays = startedDate
+    ? businessDaysBetween(startedDate, today)
+    : null;
+
+  const totals = {
+    steps_completed: stepsCompleted,
+    learnings_captured: inputs.learningsCount || 0,
+    files_changed: filesChanged.length,
+    tests_written: testsWritten,
+    pipeline_result: hasPr ? 'completed' : 'in-progress',
+    abandoned_at_step: null,
+    cycle_days: cycleDays,
+    business_cycle_days: businessCycleDays,
+    // gate_pass_rate, total_gate_attempts, cross_validation_catches
+    // → v2 enrichment (omitted in v1 to avoid emitting fake zeros)
+  };
+
+  // ── Final scorecard ────────────────────────────────────
+  const scorecard = {
+    story: meta.storyId || null,
+    branch: meta.branch || null,
+    date: today || null,
+    started_date: startedDate,
+    completed_date: completedDate,
+  };
+  if (git.author) scorecard.author = git.author;
+  scorecard.steps = steps;
+  scorecard.totals = totals;
+  return scorecard;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// renderScorecardYaml — render scorecard object to YAML string
+// ─────────────────────────────────────────────────────────────────────
+//   Adds a header comment so adopters know it was bootstrapped by H-008.
+function renderScorecardYaml(scorecard) {
+  const header = [
+    '# Pipeline metrics scorecard',
+    '# Bootstrapped by `hone metrics collect` (H-008).',
+    '# Schema: docs/metrics/README.md',
+    '# Agents may append richer fields (gate_attempts, cross_validation,',
+    '# test_results, findings) per the "Who Writes What" protocol.',
+    '',
+  ].join('\n');
+  const body = yaml.dump(scorecard, {
+    lineWidth: 120,
+    noRefs: true,
+    sortKeys: false,
+  });
+  return header + body;
+}
+
+module.exports = {
+  PIPELINE_TO_METRICS_NAME,
+  buildScorecard,
+  businessDaysBetween,
+  filterTestFiles,
+  renderScorecardYaml,
+};

package/lib/overlay-merge.js

@@ -0,0 +1,267 @@
+'use strict';
+/**
+ * overlay-merge.js — H-084 layer adopter overlays onto canonical defaults.
+ *
+ * Adopter customizations (rule additions like E24-A regression policy) live in
+ * `.hone-local/rule-overlays/<step>.<rule>.md`. Each overlay file is a chunk
+ * of Markdown PLUS optional YAML front-matter declaring where to insert:
+ *
+ *   ---
+ *   target_step: code-reviewer
+ *   rule_id: E24-A-regression-policy
+ *   insert: after-section "Hard Rules"   # or "before-section X" or "append"
+ *   ---
+ *   ## Custom rule
+ *   ... markdown content ...
+ *
+ * `mergeOverlays(defaultText, overlays)` returns the merged result.
+ *
+ * Pure helper. Caller does I/O (reads defaults, walks .hone-local/, writes
+ * projection output).
+ *
+ * Closes #84 (M scope). L scope: hone init --upgrade integration; hone
+ * migrate-overlays; CUSTOMIZATION.md docs.
+ */
+
+/**
+ * Parse YAML front-matter from a Markdown overlay file.
+ * Minimal: scans for `---\n...\n---\n` at the top.
+ *
+ * @param {string} text
+ * @returns {{ frontMatter: object, body: string }}
+ */
+function parseFrontMatter(text) {
+  if (typeof text !== 'string') return { frontMatter: {}, body: '' };
+  const m = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!m) return { frontMatter: {}, body: text };
+  const frontMatter = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^([a-z_]+):\s*(.*)$/i);
+    if (!kv) continue;
+    let value = kv[2].trim();
+    // Strip surrounding quotes
+    if (/^["'].*["']$/.test(value)) value = value.slice(1, -1);
+    frontMatter[kv[1].trim()] = value;
+  }
+  return { frontMatter, body: m[2].replace(/^\n+/, '') };
+}
+
+/**
+ * Merge an array of overlays onto a canonical default text.
+ *
+ * Insertion semantics (front-matter `insert` field):
+ *   - `append` (default): overlay body appended at end
+ *   - `prepend`: overlay body prepended at top (after any title)
+ *   - `after-section "X"`: insert AFTER the heading line `## X` (and any
+ *     content before next `## ` heading)
+ *   - `before-section "X"`: insert BEFORE the heading line `## X`
+ *
+ * Order: overlays are applied in the order provided. Each overlay's rule_id
+ * is inserted as a marker comment so a downstream drift guard can verify
+ * the rule landed: `<!-- overlay:RULE-ID -->`.
+ *
+ * @param {string} defaultText - the canonical default file content
+ * @param {Array<{path?: string, content: string}>} overlays - overlay files
+ * @param {object} [opts]
+ * @param {'error'|'skip'|'both'} [opts.onConflict='error'] - #118 conflict mode:
+ *   - 'error' (default): conflict adds entry to `errors`; overlay is NOT applied
+ *   - 'skip': conflict adds entry to `conflicts` (warning); overlay is skipped silently
+ *   - 'both': conflict adds entry to `conflicts`; overlay IS applied (allows duplicate
+ *     headings to coexist with marker comments distinguishing them)
+ *   Adopters can also bypass conflict detection per-overlay by setting
+ *   `insert: replace-section "Name"` in the overlay's front-matter.
+ * @returns {{ merged: string, applied: Array<{ruleId, insertSpec, ok}>, errors: string[],
+ *   conflicts: Array<{heading, sources}> }}
+ */
+function mergeOverlays(defaultText, overlays, opts) {
+  if (typeof defaultText !== 'string') {
+    return { merged: '', applied: [], errors: ['defaultText must be a string'], conflicts: [] };
+  }
+  if (!Array.isArray(overlays)) overlays = [];
+  // Defensive: opts may be null / undefined / non-object — treat as empty
+  if (opts === null || opts === undefined || typeof opts !== 'object') opts = {};
+
+  // #118: conflict-mode option (default 'error' surfaces conflicts as merge failures)
+  const onConflict = opts.onConflict || 'error';
+  if (!['error', 'skip', 'both'].includes(onConflict)) {
+    return {
+      merged: defaultText,
+      applied: [],
+      errors: [`invalid opts.onConflict "${onConflict}" — must be 'error' | 'skip' | 'both'`],
+      conflicts: [],
+    };
+  }
+
+  let result = defaultText;
+  const applied = [];
+  const errors = [];
+  const conflicts = [];  // #118: collisions detected during merge
+
+  // #118: track headings already defined (canonical + already-merged overlays)
+  // to detect collisions before each overlay applies.
+  const definedHeadings = collectH2Headings(defaultText);
+
+  for (let i = 0; i < overlays.length; i++) {
+    const overlay = overlays[i];
+    if (!overlay || typeof overlay.content !== 'string') {
+      errors.push(`overlay[${i}] missing content`);
+      continue;
+    }
+    const { frontMatter, body } = parseFrontMatter(overlay.content);
+    const ruleId = frontMatter.rule_id || frontMatter.ruleId || `overlay-${i}`;
+    const insert = frontMatter.insert || 'append';
+    const marker = `<!-- overlay:${ruleId} -->`;
+    const wrappedBody = `${marker}\n${body.trimEnd()}\n`;
+
+    // #118: collision detection (skip when insert spec is explicitly replace-section,
+    // which signals "I'm replacing, not adding")
+    const isReplaceMode = /^replace-section\s+["']/.test(insert);
+    if (!isReplaceMode) {
+      const overlayHeadings = collectH2Headings(body);
+      const collisions = overlayHeadings.filter((h) => definedHeadings.includes(h));
+      if (collisions.length > 0) {
+        for (const heading of collisions) {
+          conflicts.push({
+            heading,
+            sources: ['canonical or earlier overlay', `overlay ${ruleId}`],
+            ruleId,
+          });
+        }
+        if (onConflict === 'error') {
+          errors.push(`overlay ${ruleId}: heading collision on [${collisions.join(', ')}] — use insert: replace-section "..." to resolve, or pass opts.onConflict='skip'/'both'`);
+          applied.push({ ruleId, insertSpec: insert, ok: false });
+          continue;  // don't apply; default is fail-fast
+        }
+        if (onConflict === 'skip') {
+          applied.push({ ruleId, insertSpec: insert, ok: false });
+          continue;  // skip overlay
+        }
+        // onConflict === 'both' falls through to apply normally
+      }
+    }
+
+    let inserted = false;
+
+    if (insert === 'append') {
+      result = result.replace(/\n*$/, '\n\n') + wrappedBody;
+      inserted = true;
+    } else if (insert === 'prepend') {
+      // Insert AFTER the first H1 (title line) if present, otherwise at top
+      const titleMatch = result.match(/^(# [^\n]+\n)/);
+      if (titleMatch) {
+        result = result.replace(titleMatch[0], titleMatch[0] + '\n' + wrappedBody + '\n');
+      } else {
+        result = wrappedBody + '\n' + result;
+      }
+      inserted = true;
+    } else if (/^after-section\s+["']?(.+?)["']?$/.test(insert)) {
+      const sectionName = insert.match(/^after-section\s+["']?(.+?)["']?$/)[1];
+      // Find `## SectionName` heading; insert wrappedBody before next `## ` or end
+      const sectionRe = new RegExp(`(^## ${escapeRegex(sectionName)}\\s*\\n[\\s\\S]*?)(?=\\n## |$)`, 'm');
+      const m = result.match(sectionRe);
+      if (m) {
+        const insertAt = m.index + m[0].length;
+        result = result.slice(0, insertAt) + '\n' + wrappedBody + '\n' + result.slice(insertAt);
+        inserted = true;
+      } else {
+        errors.push(`overlay ${ruleId}: target section "${sectionName}" not found in default`);
+      }
+    } else if (/^before-section\s+["']?(.+?)["']?$/.test(insert)) {
+      const sectionName = insert.match(/^before-section\s+["']?(.+?)["']?$/)[1];
+      const sectionRe = new RegExp(`^## ${escapeRegex(sectionName)}`, 'm');
+      const m = result.match(sectionRe);
+      if (m) {
+        result = result.slice(0, m.index) + wrappedBody + '\n' + result.slice(m.index);
+        inserted = true;
+      } else {
+        errors.push(`overlay ${ruleId}: target section "${sectionName}" not found in default`);
+      }
+    } else if (/^replace-section\s+["']?(.+?)["']?$/.test(insert)) {
+      // #118: replace-section directive — explicit collision-resolution mode
+      // The overlay body REPLACES the named section's content (heading + body
+      // until next ## or EOF). Adopter has signaled they intend to replace.
+      // Regex notes:
+      //   - No /m flag (so $ matches end-of-string only, not end-of-line)
+      //   - Match `## SectionName\n` then everything up to (but not including)
+      //     the next `\n## ` heading OR end-of-string
+      const sectionName = insert.match(/^replace-section\s+["']?(.+?)["']?$/)[1];
+      const sectionRe = new RegExp(
+        `## ${escapeRegex(sectionName)}\\s*\\n[\\s\\S]*?(?=\\n## |$(?![\\s\\S]))`,
+      );
+      const m = result.match(sectionRe);
+      if (m) {
+        result = result.slice(0, m.index) + wrappedBody + result.slice(m.index + m[0].length);
+        inserted = true;
+      } else {
+        errors.push(`overlay ${ruleId}: replace-section target "${sectionName}" not found in default (cannot replace what doesn't exist)`);
+      }
+    } else {
+      errors.push(`overlay ${ruleId}: unrecognized insert spec "${insert}" (valid: append | prepend | after-section "X" | before-section "X" | replace-section "X")`);
+    }
+
+    applied.push({ ruleId, insertSpec: insert, ok: inserted });
+
+    // #118: track newly-added headings so subsequent overlays detect intra-overlay collisions
+    if (inserted) {
+      const newHeadings = collectH2Headings(body);
+      for (const h of newHeadings) {
+        if (!definedHeadings.includes(h)) definedHeadings.push(h);
+      }
+    }
+  }
+
+  return { merged: result, applied, errors, conflicts };
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * #118: extract level-2 headings (`## Heading`) from markdown content.
+ * Used by mergeOverlays to detect heading collisions.
+ *
+ * @param {string} text
+ * @returns {string[]} array of heading text (without `## ` prefix), trimmed
+ */
+function collectH2Headings(text) {
+  if (typeof text !== 'string') return [];
+  const out = [];
+  const re = /^##\s+(.+?)\s*$/gm;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const heading = m[1].trim();
+    // Skip H3+ (matched as part of multi-line context) — guard against false matches
+    if (heading.startsWith('#')) continue;
+    out.push(heading);
+  }
+  return out;
+}
+
+/**
+ * Verify each overlay's rule-id marker appears in the merged output.
+ * Used as a drift-guard check.
+ *
+ * @param {string} mergedText
+ * @param {Array<{ruleId: string}>} applied - from mergeOverlays
+ * @returns {{ allPresent: boolean, missing: string[] }}
+ */
+function verifyOverlayMarkers(mergedText, applied) {
+  if (typeof mergedText !== 'string' || !Array.isArray(applied)) {
+    return { allPresent: false, missing: [] };
+  }
+  const missing = [];
+  for (const a of applied) {
+    if (!a || !a.ok) continue;  // skip ones that failed to insert
+    const marker = `<!-- overlay:${a.ruleId} -->`;
+    if (!mergedText.includes(marker)) missing.push(a.ruleId);
+  }
+  return { allPresent: missing.length === 0, missing };
+}
+
+module.exports = {
+  parseFrontMatter,
+  mergeOverlays,
+  verifyOverlayMarkers,
+  collectH2Headings,  // #118: exposed for tests + adopter tooling
+};

package/lib/performance-analyzer.js

@@ -0,0 +1,142 @@
+'use strict';
+/**
+ * performance-analyzer.js — HC-028-new + HC-029 static analysis for
+ * performance anti-patterns: N+1 queries, unbounded queries, sync blocking,
+ * plus platform-specific governor/governance rules.
+ *
+ * Pure helper — no I/O. Mirrors security-scanner.js pattern exactly.
+ *
+ * Architecture: docs/architecture/master-roadmap.md (Epic 3)
+ */
+
+// ── Core Rules ─────────────────────────────────────────────────
+
+const QUERY_PATTERNS = [
+  {
+    id: 'query-in-loop',
+    pattern: /for\s*\([\s\S]{0,300}(?:query|select|find|fetch|get)\s*\(/i,
+    severity: 'HIGH',
+    message: 'Database query inside a loop (N+1 pattern). Batch the query outside the loop.',
+  },
+  {
+    id: 'unbounded-select',
+    pattern: /(?:SELECT\s+\*?\s+FROM\s+\w+)(?![\s\S]{0,100}(?:LIMIT|WHERE|TOP)\b)/i,
+    severity: 'MEDIUM',
+    message: 'Unbounded SELECT without LIMIT or WHERE. Add pagination or filtering.',
+  },
+];
+
+const BLOCKING_PATTERNS = [
+  {
+    id: 'sync-blocking',
+    pattern: /(?:readFileSync|writeFileSync|execSync|spawnSync)\s*\(/,
+    severity: 'MEDIUM',
+    message: 'Synchronous blocking call. Use async alternative in request handlers.',
+  },
+];
+
+// ── Salesforce Governor Rules (HC-029) ─────────────────────────
+
+const SALESFORCE_PERF_RULES = [
+  {
+    id: 'sf-dml-in-loop',
+    pattern: /for\s*\([\s\S]{0,200}(?:insert|update|delete|upsert)\s+/i,
+    severity: 'HIGH',
+    message: 'DML inside loop — governor limit (150 DML/transaction). Collect and execute outside loop.',
+  },
+  {
+    id: 'sf-unbounded-soql',
+    pattern: /\[SELECT\s+[\s\S]{0,200}FROM\s+\w+(?![\s\S]{0,100}LIMIT\b)/i,
+    severity: 'MEDIUM',
+    message: 'SOQL without LIMIT — may return more records than expected. Add LIMIT clause.',
+  },
+];
+
+// ── NetSuite Governance Rules (HC-029) ─────────────────────────
+
+const NETSUITE_PERF_RULES = [
+  {
+    id: 'ns-load-in-loop',
+    pattern: /for\s*\([\s\S]{0,300}record\.load\s*\(/i,
+    severity: 'HIGH',
+    message: 'record.load() inside loop — governance unit intensive. Use search or lookupFields instead.',
+  },
+  {
+    id: 'ns-unbounded-search',
+    pattern: /search\.create\s*\([\s\S]{0,300}\.run\s*\(\)/,
+    severity: 'MEDIUM',
+    message: 'Search without maxResults or paging. Use runPaged() or set maxResults for bounded results.',
+  },
+];
+
+const PLATFORM_RULES = {
+  salesforce: SALESFORCE_PERF_RULES,
+  netsuite: NETSUITE_PERF_RULES,
+};
+
+// ── Analyzer ───────────────────────────────────────────────────
+
+/**
+ * Analyze files for performance anti-patterns.
+ *
+ * @param {object} opts
+ * @param {object} opts.files — { path: content } map
+ * @param {string} [opts.platform] — 'salesforce' | 'netsuite' | etc.
+ * @returns {{ findings: Array<{file, line, rule, severity, message}>, summary: string }}
+ */
+function analyzeFiles(opts = {}) {
+  const files = opts.files || {};
+  const platform = opts.platform || null;
+  const findings = [];
+
+  const rules = [...QUERY_PATTERNS, ...BLOCKING_PATTERNS];
+  if (platform && PLATFORM_RULES[platform]) {
+    rules.push(...PLATFORM_RULES[platform]);
+  }
+
+  for (const [filePath, content] of Object.entries(files)) {
+    if (typeof content !== 'string') continue;
+
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Skip comments
+      if (/^\s*(\/\/|#|--|\/\*|\*)/.test(line)) continue;
+
+      for (const rule of rules) {
+        // Some patterns need multi-line context (e.g., for-loop with query inside)
+        const context = lines.slice(Math.max(0, i - 1), Math.min(lines.length, i + 3)).join('\n');
+
+        if (rule.pattern.test(line) || (rule.id.includes('in-loop') && rule.pattern.test(context))) {
+          // Avoid duplicate: only report on the first matching line in context
+          if (rule.id.includes('in-loop') && !rule.pattern.test(line) && i > 0) continue;
+
+          findings.push({
+            file: filePath,
+            line: i + 1,
+            rule: rule.id,
+            severity: rule.severity,
+            message: rule.message,
+          });
+        }
+      }
+    }
+  }
+
+  const high = findings.filter(f => f.severity === 'HIGH').length;
+  const medium = findings.filter(f => f.severity === 'MEDIUM').length;
+  const low = findings.filter(f => f.severity === 'LOW').length;
+  const summary = findings.length === 0
+    ? 'No performance findings.'
+    : `${findings.length} finding(s): ${high} HIGH, ${medium} MEDIUM, ${low} LOW.`;
+
+  return { findings, summary };
+}
+
+module.exports = {
+  analyzeFiles,
+  QUERY_PATTERNS,
+  BLOCKING_PATTERNS,
+  PLATFORM_RULES,
+};