@nerviq/cli 1.20.1 → 1.21.0

package/src/techniques.js

@@ -1,81 +1,81 @@
-/**
- * NERVIQ Technique Database
- * Curated from 1118 verified techniques, filtered to actionable setup recommendations.
- * Each technique includes: what to check, how to fix, impact level.
- */
-
-const { attachSourceUrls, buildSupplementalChecks, CLAUDE_SUPPLEMENTAL_SOURCE_URLS, STACK_CATEGORY_DETECTORS, containsEmbeddedSecret } = require('./techniques/shared');
-const instructionTechniques = require('./techniques/instructions');
-const qualityTechniques = require('./techniques/quality');
-const apiTechniques = require('./techniques/api');
-const automationTechniques = require('./techniques/automation');
-const hygieneTechniques = require('./techniques/hygiene');
-const observabilityTechniques = require('./techniques/observability');
-const workflowTechniques = require('./techniques/workflow');
-const toolTechniques = require('./techniques/tools');
-const securityTechniques = require('./techniques/security');
-const complianceTechniques = require('./techniques/compliance');
-const optimizationTechniques = require('./techniques/optimization');
-const stackTechniques = require('./techniques/stacks');
-
-const TECHNIQUES = Object.assign({},
-  instructionTechniques,
-  qualityTechniques,
-  apiTechniques,
-  automationTechniques,
-  hygieneTechniques,
-  observabilityTechniques,
-  workflowTechniques,
-  toolTechniques,
-  securityTechniques,
-  complianceTechniques,
-  optimizationTechniques,
-  stackTechniques,
-);
-
-Object.assign(TECHNIQUES, buildSupplementalChecks({
-  idPrefix: 'CL-T',
-  urlMap: CLAUDE_SUPPLEMENTAL_SOURCE_URLS,
-  docs: (ctx) => [
-    ctx.claudeMdContent ? ctx.claudeMdContent() : (ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md') || ''),
-    ctx.fileContent('README.md') || '',
-  ].filter(Boolean).join('\n'),
-}));
-
-// Stack detection
-const STACKS = {
-  react: { files: ['package.json'], content: { 'package.json': 'react' }, label: 'React' },
-  vue: { files: ['package.json'], content: { 'package.json': 'vue' }, label: 'Vue' },
-  angular: { files: ['angular.json'], content: {}, label: 'Angular' },
-  nextjs: { files: ['next.config'], content: {}, label: 'Next.js' },
-  python: { files: ['requirements.txt', 'setup.py', 'pyproject.toml', 'Pipfile'], content: {}, label: 'Python' },
-  django: { files: ['manage.py'], content: {}, label: 'Django' },
-  fastapi: { files: ['requirements.txt'], content: { 'requirements.txt': 'fastapi' }, label: 'FastAPI' },
-  node: { files: ['package.json'], content: {}, label: 'Node.js' },
-  typescript: { files: ['tsconfig.json'], content: {}, label: 'TypeScript' },
-  rust: { files: ['Cargo.toml'], content: {}, label: 'Rust' },
-  go: { files: ['go.mod'], content: {}, label: 'Go' },
-  docker: { files: ['Dockerfile', 'docker-compose.yml', 'docker-compose.yaml'], content: {}, label: 'Docker' },
-  svelte: { files: ['svelte.config.js'], content: {}, label: 'Svelte' },
-  flutter: { files: ['pubspec.yaml'], content: {}, label: 'Flutter' },
-  ruby: { files: ['Gemfile'], content: {}, label: 'Ruby' },
-  java: { files: ['pom.xml'], content: {}, label: 'Java' },
-  kotlin: { files: ['build.gradle.kts'], content: {}, label: 'Kotlin' },
-  swift: { files: ['Package.swift', '.xcodeproj'], content: {}, label: 'Swift' },
-  terraform: { files: ['main.tf', 'terraform'], content: {}, label: 'Terraform' },
-  kubernetes: { files: ['k8s', 'kubernetes', 'helm'], content: {}, label: 'Kubernetes' },
-  cpp: { files: ['CMakeLists.txt', 'Makefile', '.clang-format'], content: {}, label: 'C++' },
-  bazel: { files: ['BUILD', 'WORKSPACE', 'BUILD.bazel', 'WORKSPACE.bazel'], content: {}, label: 'Bazel' },
-  deno: { files: ['deno.json', 'deno.jsonc', 'deno.lock'], content: {}, label: 'Deno' },
-  bun: { files: ['bun.lockb', 'bunfig.toml'], content: {}, label: 'Bun' },
-  elixir: { files: ['mix.exs'], content: {}, label: 'Elixir' },
-  astro: { files: ['astro.config.mjs', 'astro.config.ts'], content: {}, label: 'Astro' },
-  remix: { files: ['remix.config.js', 'remix.config.ts'], content: {}, label: 'Remix' },
-  nestjs: { files: ['nest-cli.json'], content: {}, label: 'NestJS' },
-  laravel: { files: ['artisan'], content: {}, label: 'Laravel' },
-  dotnet: { files: ['global.json', 'Directory.Build.props'], content: {}, label: '.NET' },
-};
-
-attachSourceUrls('claude', TECHNIQUES);
-
-module.exports = { TECHNIQUES, STACKS, STACK_CATEGORY_DETECTORS, containsEmbeddedSecret };
+/**
+ * NERVIQ Technique Database
+ * Curated from 1118 verified techniques, filtered to actionable setup recommendations.
+ * Each technique includes: what to check, how to fix, impact level.
+ */
+
+const { attachSourceUrls, buildSupplementalChecks, CLAUDE_SUPPLEMENTAL_SOURCE_URLS, STACK_CATEGORY_DETECTORS, containsEmbeddedSecret } = require('./techniques/shared');
+const instructionTechniques = require('./techniques/instructions');
+const qualityTechniques = require('./techniques/quality');
+const apiTechniques = require('./techniques/api');
+const automationTechniques = require('./techniques/automation');
+const hygieneTechniques = require('./techniques/hygiene');
+const observabilityTechniques = require('./techniques/observability');
+const workflowTechniques = require('./techniques/workflow');
+const toolTechniques = require('./techniques/tools');
+const securityTechniques = require('./techniques/security');
+const complianceTechniques = require('./techniques/compliance');
+const optimizationTechniques = require('./techniques/optimization');
+const stackTechniques = require('./techniques/stacks');
+
+const TECHNIQUES = Object.assign({},
+  instructionTechniques,
+  qualityTechniques,
+  apiTechniques,
+  automationTechniques,
+  hygieneTechniques,
+  observabilityTechniques,
+  workflowTechniques,
+  toolTechniques,
+  securityTechniques,
+  complianceTechniques,
+  optimizationTechniques,
+  stackTechniques,
+);
+
+Object.assign(TECHNIQUES, buildSupplementalChecks({
+  idPrefix: 'CL-T',
+  urlMap: CLAUDE_SUPPLEMENTAL_SOURCE_URLS,
+  docs: (ctx) => [
+    ctx.claudeMdContent ? ctx.claudeMdContent() : (ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md') || ''),
+    ctx.fileContent('README.md') || '',
+  ].filter(Boolean).join('\n'),
+}));
+
+// Stack detection
+const STACKS = {
+  react: { files: ['package.json'], content: { 'package.json': 'react' }, label: 'React' },
+  vue: { files: ['package.json'], content: { 'package.json': 'vue' }, label: 'Vue' },
+  angular: { files: ['angular.json'], content: {}, label: 'Angular' },
+  nextjs: { files: ['next.config'], content: {}, label: 'Next.js' },
+  python: { files: ['requirements.txt', 'setup.py', 'pyproject.toml', 'Pipfile'], content: {}, label: 'Python' },
+  django: { files: ['manage.py'], content: {}, label: 'Django' },
+  fastapi: { files: ['requirements.txt'], content: { 'requirements.txt': 'fastapi' }, label: 'FastAPI' },
+  node: { files: ['package.json'], content: {}, label: 'Node.js' },
+  typescript: { files: ['tsconfig.json'], content: {}, label: 'TypeScript' },
+  rust: { files: ['Cargo.toml'], content: {}, label: 'Rust' },
+  go: { files: ['go.mod'], content: {}, label: 'Go' },
+  docker: { files: ['Dockerfile', 'docker-compose.yml', 'docker-compose.yaml'], content: {}, label: 'Docker' },
+  svelte: { files: ['svelte.config.js'], content: {}, label: 'Svelte' },
+  flutter: { files: ['pubspec.yaml'], content: {}, label: 'Flutter' },
+  ruby: { files: ['Gemfile'], content: {}, label: 'Ruby' },
+  java: { files: ['pom.xml'], content: {}, label: 'Java' },
+  kotlin: { files: ['build.gradle.kts'], content: {}, label: 'Kotlin' },
+  swift: { files: ['Package.swift', '.xcodeproj'], content: {}, label: 'Swift' },
+  terraform: { files: ['main.tf', 'terraform'], content: {}, label: 'Terraform' },
+  kubernetes: { files: ['k8s', 'kubernetes', 'helm'], content: {}, label: 'Kubernetes' },
+  cpp: { files: ['CMakeLists.txt', 'Makefile', '.clang-format'], content: {}, label: 'C++' },
+  bazel: { files: ['BUILD', 'WORKSPACE', 'BUILD.bazel', 'WORKSPACE.bazel'], content: {}, label: 'Bazel' },
+  deno: { files: ['deno.json', 'deno.jsonc', 'deno.lock'], content: {}, label: 'Deno' },
+  bun: { files: ['bun.lockb', 'bunfig.toml'], content: {}, label: 'Bun' },
+  elixir: { files: ['mix.exs'], content: {}, label: 'Elixir' },
+  astro: { files: ['astro.config.mjs', 'astro.config.ts'], content: {}, label: 'Astro' },
+  remix: { files: ['remix.config.js', 'remix.config.ts'], content: {}, label: 'Remix' },
+  nestjs: { files: ['nest-cli.json'], content: {}, label: 'NestJS' },
+  laravel: { files: ['artisan'], content: {}, label: 'Laravel' },
+  dotnet: { files: ['global.json', 'Directory.Build.props'], content: {}, label: '.NET' },
+};
+
+attachSourceUrls('claude', TECHNIQUES);
+
+module.exports = { TECHNIQUES, STACKS, STACK_CATEGORY_DETECTORS, containsEmbeddedSecret };

package/src/terminology.js

@@ -1,73 +1,73 @@
-'use strict';
-
-const TERMINOLOGY = {
-  governance: {
-    label: 'governance',
-    description: 'the rollout safety layer: permissions, hooks, profiles, and policy packs',
-  },
-  hooks: {
-    label: 'hooks',
-    description: 'auto-run checks or scripts triggered before or after agent tool actions',
-  },
-  denyRules: {
-    label: 'deny rules',
-    description: 'explicit blocks for risky reads or commands like .env access or rm -rf',
-  },
-  mcp: {
-    label: 'MCP',
-    description: 'live external tool connectors for docs, APIs, databases, and other systems',
-  },
-};
-
-const TERM_ORDER = ['governance', 'hooks', 'denyRules', 'mcp'];
-
-function normalizeTermKeys(keys = []) {
-  const seen = new Set();
-  for (const key of keys) {
-    if (!TERMINOLOGY[key]) continue;
-    seen.add(key);
-  }
-  return TERM_ORDER.filter((key) => seen.has(key));
-}
-
-function collectAuditTerminology(result = {}) {
-  const terms = new Set();
-  const texts = [];
-
-  for (const item of result.topNextActions || []) {
-    texts.push(item.name || '', item.fix || '', item.why || '', item.module || '', ...(item.signals || []));
-  }
-
-  for (const item of result.results || []) {
-    if (item.passed === false) {
-      texts.push(item.key || '', item.name || '', item.fix || '', item.category || '');
-    }
-  }
-
-  const blob = texts.join('\n');
-  if (/\bhook/i.test(blob)) terms.add('hooks');
-  if (/\bdeny rules?\b|permissions?\.deny|bypasspermissions|\.env access|rm -rf/i.test(blob)) terms.add('denyRules');
-  if (/\bmcp\b|context7|external tool/i.test(blob)) terms.add('mcp');
-  if (/\bgovernance\b|policy pack|permission profile/i.test(blob) || terms.size > 0) terms.add('governance');
-
-  return normalizeTermKeys([...terms]);
-}
-
-function formatTerminologyLines(keys, options = {}) {
-  const normalized = normalizeTermKeys(keys);
-  if (normalized.length === 0) return [];
-  const title = options.title || '  Terms used here:';
-  const indent = options.indent || '  ';
-  const bullet = options.bullet || '-';
-
-  return [
-    title,
-    ...normalized.map((key) => `${indent}${bullet} ${TERMINOLOGY[key].label}: ${TERMINOLOGY[key].description}`),
-  ];
-}
-
-module.exports = {
-  TERMINOLOGY,
-  collectAuditTerminology,
-  formatTerminologyLines,
-};
+'use strict';
+
+const TERMINOLOGY = {
+  governance: {
+    label: 'governance',
+    description: 'the rollout safety layer: permissions, hooks, profiles, and policy packs',
+  },
+  hooks: {
+    label: 'hooks',
+    description: 'auto-run checks or scripts triggered before or after agent tool actions',
+  },
+  denyRules: {
+    label: 'deny rules',
+    description: 'explicit blocks for risky reads or commands like .env access or rm -rf',
+  },
+  mcp: {
+    label: 'MCP',
+    description: 'live external tool connectors for docs, APIs, databases, and other systems',
+  },
+};
+
+const TERM_ORDER = ['governance', 'hooks', 'denyRules', 'mcp'];
+
+function normalizeTermKeys(keys = []) {
+  const seen = new Set();
+  for (const key of keys) {
+    if (!TERMINOLOGY[key]) continue;
+    seen.add(key);
+  }
+  return TERM_ORDER.filter((key) => seen.has(key));
+}
+
+function collectAuditTerminology(result = {}) {
+  const terms = new Set();
+  const texts = [];
+
+  for (const item of result.topNextActions || []) {
+    texts.push(item.name || '', item.fix || '', item.why || '', item.module || '', ...(item.signals || []));
+  }
+
+  for (const item of result.results || []) {
+    if (item.passed === false) {
+      texts.push(item.key || '', item.name || '', item.fix || '', item.category || '');
+    }
+  }
+
+  const blob = texts.join('\n');
+  if (/\bhook/i.test(blob)) terms.add('hooks');
+  if (/\bdeny rules?\b|permissions?\.deny|bypasspermissions|\.env access|rm -rf/i.test(blob)) terms.add('denyRules');
+  if (/\bmcp\b|context7|external tool/i.test(blob)) terms.add('mcp');
+  if (/\bgovernance\b|policy pack|permission profile/i.test(blob) || terms.size > 0) terms.add('governance');
+
+  return normalizeTermKeys([...terms]);
+}
+
+function formatTerminologyLines(keys, options = {}) {
+  const normalized = normalizeTermKeys(keys);
+  if (normalized.length === 0) return [];
+  const title = options.title || '  Terms used here:';
+  const indent = options.indent || '  ';
+  const bullet = options.bullet || '-';
+
+  return [
+    title,
+    ...normalized.map((key) => `${indent}${bullet} ${TERMINOLOGY[key].label}: ${TERMINOLOGY[key].description}`),
+  ];
+}
+
+module.exports = {
+  TERMINOLOGY,
+  collectAuditTerminology,
+  formatTerminologyLines,
+};

package/src/token-estimate.js

@@ -1,35 +1,35 @@
-function splitIdentifierSegments(value) {
-  return String(value || '')
-    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-    .replace(/[_./:-]+/g, ' ')
-    .split(/\s+/)
-    .filter(Boolean);
-}
-
-function estimateSegmentTokens(segment) {
-  const charCount = [...String(segment || '')].length;
-  return Math.max(1, Math.ceil(charCount / 4));
-}
-
-function estimateTokenCount(text) {
-  if (typeof text !== 'string' || !text) return 0;
-
-  const parts = text.match(/[\p{L}\p{N}_]+|[^\s]/gu) || [];
-  let total = 0;
-
-  for (const part of parts) {
-    if (/^[\p{L}\p{N}_]+$/u.test(part)) {
-      const segments = splitIdentifierSegments(part);
-      total += segments.reduce((sum, segment) => sum + estimateSegmentTokens(segment), 0);
-      continue;
-    }
-
-    total += 1;
-  }
-
-  return total;
-}
-
-module.exports = {
-  estimateTokenCount,
-};
+function splitIdentifierSegments(value) {
+  return String(value || '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_./:-]+/g, ' ')
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function estimateSegmentTokens(segment) {
+  const charCount = [...String(segment || '')].length;
+  return Math.max(1, Math.ceil(charCount / 4));
+}
+
+function estimateTokenCount(text) {
+  if (typeof text !== 'string' || !text) return 0;
+
+  const parts = text.match(/[\p{L}\p{N}_]+|[^\s]/gu) || [];
+  let total = 0;
+
+  for (const part of parts) {
+    if (/^[\p{L}\p{N}_]+$/u.test(part)) {
+      const segments = splitIdentifierSegments(part);
+      total += segments.reduce((sum, segment) => sum + estimateSegmentTokens(segment), 0);
+      continue;
+    }
+
+    total += 1;
+  }
+
+  return total;
+}
+
+module.exports = {
+  estimateTokenCount,
+};

package/src/usage-patterns.js

@@ -1,99 +1,99 @@
-const fs = require('fs');
-const path = require('path');
-const { ensureProjectStateDir, resolveProjectStateReadPath } = require('./state-paths');
-
-const PATTERNS_FILE = 'patterns.json';
-const SUPPRESS_THRESHOLD = 3;
-
-function patternsPath(dir, writable) {
-  if (writable) {
-    const feedbackDir = ensureProjectStateDir(dir, 'feedback');
-    return path.join(feedbackDir, PATTERNS_FILE);
-  }
-  const feedbackDir = resolveProjectStateReadPath(dir, 'feedback');
-  return path.join(feedbackDir, PATTERNS_FILE);
-}
-
-function loadPatterns(dir) {
-  const filePath = patternsPath(dir, false);
-  if (!fs.existsSync(filePath)) return {};
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch {
-    return {};
-  }
-}
-
-function savePatterns(dir, patterns) {
-  const filePath = patternsPath(dir, true);
-  fs.writeFileSync(filePath, JSON.stringify(patterns, null, 2), 'utf8');
-}
-
-function recordPattern(dir, checkKey, action) {
-  if (!['accepted', 'rejected', 'skipped'].includes(action)) return;
-  const patterns = loadPatterns(dir);
-  if (!patterns[checkKey]) {
-    patterns[checkKey] = { accepted: 0, rejected: 0, skipped: 0, lastAction: null, lastDate: null };
-  }
-  patterns[checkKey][action] += 1;
-  patterns[checkKey].lastAction = action;
-  patterns[checkKey].lastDate = new Date().toISOString();
-  savePatterns(dir, patterns);
-}
-
-function getPriorityAdjustment(dir, checkKey) {
-  const patterns = loadPatterns(dir);
-  const entry = patterns[checkKey];
-  if (!entry) return null;
-  const total = entry.accepted + entry.rejected;
-  if (total < 2) return null;
-  if (entry.accepted > 0 && entry.rejected === 0) return 'boost';
-  if (entry.rejected >= SUPPRESS_THRESHOLD && entry.accepted === 0) return 'suppress';
-  return null;
-}
-
-function getUsageSummary(dir) {
-  const patterns = loadPatterns(dir);
-  const keys = Object.keys(patterns);
-  const totalEvents = keys.reduce((sum, k) => {
-    const e = patterns[k];
-    return sum + e.accepted + e.rejected + e.skipped;
-  }, 0);
-
-  const withRates = keys
-    .filter(k => (patterns[k].accepted + patterns[k].rejected) > 0)
-    .map(k => {
-      const e = patterns[k];
-      const total = e.accepted + e.rejected;
-      return { key: k, accepted: e.accepted, rejected: e.rejected, total, rate: total > 0 ? e.accepted / total : 0 };
-    });
-
-  withRates.sort((a, b) => b.rate - a.rate || b.total - a.total);
-  const topAccepted = withRates.filter(e => e.rate > 0).slice(0, 5);
-  const topRejected = withRates.filter(e => e.rate < 1).sort((a, b) => a.rate - b.rate || b.total - a.total).slice(0, 5);
-
-  return { totalEvents, topAccepted, topRejected, patterns };
-}
-
-function formatUsageSummary(dir) {
-  const summary = getUsageSummary(dir);
-  if (summary.totalEvents === 0) return '  No usage patterns recorded yet.\n  Patterns are tracked when you run nerviq fix.';
-
-  const lines = [`  Usage Patterns (${summary.totalEvents} events recorded):`];
-  if (summary.topAccepted.length > 0) {
-    lines.push('', '  Most accepted:');
-    summary.topAccepted.forEach((e, i) => {
-      lines.push(`  ${i + 1}. ${e.key.padEnd(20)} ${e.accepted}/${e.total} (${Math.round(e.rate * 100)}%)`);
-    });
-  }
-  if (summary.topRejected.length > 0) {
-    lines.push('', '  Most rejected:');
-    summary.topRejected.forEach((e, i) => {
-      const hint = e.rate === 0 && e.total >= SUPPRESS_THRESHOLD ? ' -- consider suppressing' : '';
-      lines.push(`  ${i + 1}. ${e.key.padEnd(20)} ${e.accepted}/${e.total} (${Math.round(e.rate * 100)}%)${hint}`);
-    });
-  }
-  return lines.join('\n');
-}
-
-module.exports = { loadPatterns, recordPattern, getPriorityAdjustment, getUsageSummary, formatUsageSummary };
+const fs = require('fs');
+const path = require('path');
+const { ensureProjectStateDir, resolveProjectStateReadPath } = require('./state-paths');
+
+const PATTERNS_FILE = 'patterns.json';
+const SUPPRESS_THRESHOLD = 3;
+
+function patternsPath(dir, writable) {
+  if (writable) {
+    const feedbackDir = ensureProjectStateDir(dir, 'feedback');
+    return path.join(feedbackDir, PATTERNS_FILE);
+  }
+  const feedbackDir = resolveProjectStateReadPath(dir, 'feedback');
+  return path.join(feedbackDir, PATTERNS_FILE);
+}
+
+function loadPatterns(dir) {
+  const filePath = patternsPath(dir, false);
+  if (!fs.existsSync(filePath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function savePatterns(dir, patterns) {
+  const filePath = patternsPath(dir, true);
+  fs.writeFileSync(filePath, JSON.stringify(patterns, null, 2), 'utf8');
+}
+
+function recordPattern(dir, checkKey, action) {
+  if (!['accepted', 'rejected', 'skipped'].includes(action)) return;
+  const patterns = loadPatterns(dir);
+  if (!patterns[checkKey]) {
+    patterns[checkKey] = { accepted: 0, rejected: 0, skipped: 0, lastAction: null, lastDate: null };
+  }
+  patterns[checkKey][action] += 1;
+  patterns[checkKey].lastAction = action;
+  patterns[checkKey].lastDate = new Date().toISOString();
+  savePatterns(dir, patterns);
+}
+
+function getPriorityAdjustment(dir, checkKey) {
+  const patterns = loadPatterns(dir);
+  const entry = patterns[checkKey];
+  if (!entry) return null;
+  const total = entry.accepted + entry.rejected;
+  if (total < 2) return null;
+  if (entry.accepted > 0 && entry.rejected === 0) return 'boost';
+  if (entry.rejected >= SUPPRESS_THRESHOLD && entry.accepted === 0) return 'suppress';
+  return null;
+}
+
+function getUsageSummary(dir) {
+  const patterns = loadPatterns(dir);
+  const keys = Object.keys(patterns);
+  const totalEvents = keys.reduce((sum, k) => {
+    const e = patterns[k];
+    return sum + e.accepted + e.rejected + e.skipped;
+  }, 0);
+
+  const withRates = keys
+    .filter(k => (patterns[k].accepted + patterns[k].rejected) > 0)
+    .map(k => {
+      const e = patterns[k];
+      const total = e.accepted + e.rejected;
+      return { key: k, accepted: e.accepted, rejected: e.rejected, total, rate: total > 0 ? e.accepted / total : 0 };
+    });
+
+  withRates.sort((a, b) => b.rate - a.rate || b.total - a.total);
+  const topAccepted = withRates.filter(e => e.rate > 0).slice(0, 5);
+  const topRejected = withRates.filter(e => e.rate < 1).sort((a, b) => a.rate - b.rate || b.total - a.total).slice(0, 5);
+
+  return { totalEvents, topAccepted, topRejected, patterns };
+}
+
+function formatUsageSummary(dir) {
+  const summary = getUsageSummary(dir);
+  if (summary.totalEvents === 0) return '  No usage patterns recorded yet.\n  Patterns are tracked when you run nerviq fix.';
+
+  const lines = [`  Usage Patterns (${summary.totalEvents} events recorded):`];
+  if (summary.topAccepted.length > 0) {
+    lines.push('', '  Most accepted:');
+    summary.topAccepted.forEach((e, i) => {
+      lines.push(`  ${i + 1}. ${e.key.padEnd(20)} ${e.accepted}/${e.total} (${Math.round(e.rate * 100)}%)`);
+    });
+  }
+  if (summary.topRejected.length > 0) {
+    lines.push('', '  Most rejected:');
+    summary.topRejected.forEach((e, i) => {
+      const hint = e.rate === 0 && e.total >= SUPPRESS_THRESHOLD ? ' -- consider suppressing' : '';
+      lines.push(`  ${i + 1}. ${e.key.padEnd(20)} ${e.accepted}/${e.total} (${Math.round(e.rate * 100)}%)${hint}`);
+    });
+  }
+  return lines.join('\n');
+}
+
+module.exports = { loadPatterns, recordPattern, getPriorityAdjustment, getUsageSummary, formatUsageSummary };