@nerviq/cli 1.0.0 → 1.2.0

package/src/audit.js

@@ -2,6 +2,7 @@
  * Audit engine - evaluates project against CLAUDEX technique database.
  */
 
+const path = require('path');
 const { TECHNIQUES: CLAUDE_TECHNIQUES, STACKS } = require('./techniques');
 const { ProjectContext } = require('./context');
 const { CODEX_TECHNIQUES } = require('./codex/techniques');
@@ -25,8 +26,13 @@ const { OpenCodeProjectContext } = require('./opencode/context');
 const { getBadgeMarkdown } = require('./badge');
 const { sendInsights, getLocalInsights } = require('./insights');
 const { getRecommendationOutcomeSummary, getRecommendationAdjustment } = require('./activity');
+const { getFeedbackSummary } = require('./feedback');
 const { formatSarif } = require('./formatters/sarif');
+const { formatOtelMetrics } = require('./formatters/otel');
 const { loadPlugins, mergePluginChecks } = require('./plugins');
+const { hasWorkspaceConfig, detectWorkspaceGlobs, detectWorkspaces } = require('./workspace');
+const { detectDeprecationWarnings } = require('./deprecation');
+const { version: packageVersion } = require('../package.json');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -57,6 +63,8 @@ function formatLocation(file, line) {
 
 const IMPACT_ORDER = { critical: 3, high: 2, medium: 1, low: 0 };
 const WEIGHTS = { critical: 15, high: 10, medium: 5, low: 2 };
+const LARGE_INSTRUCTION_WARN_BYTES = 50 * 1024;
+const LARGE_INSTRUCTION_SKIP_BYTES = 1024 * 1024;
 const CATEGORY_MODULES = {
   memory: 'CLAUDE.md',
   quality: 'verification',
@@ -349,6 +357,171 @@ function getAuditSpec(platform = 'claude') {
   };
 }
 
+function normalizeRelativePath(filePath) {
+  return String(filePath || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function addPath(target, filePath) {
+  if (!filePath || typeof filePath !== 'string') return;
+  target.add(normalizeRelativePath(filePath));
+}
+
+function addDirFiles(ctx, target, dirPath, filter) {
+  if (typeof ctx.dirFiles !== 'function') return;
+  for (const file of ctx.dirFiles(dirPath)) {
+    if (filter && !filter.test(file)) continue;
+    addPath(target, path.join(dirPath, file));
+  }
+}
+
+function instructionFileCandidates(spec, ctx) {
+  const candidates = new Set();
+
+  if (spec.platform === 'claude') {
+    addPath(candidates, 'CLAUDE.md');
+    addPath(candidates, '.claude/CLAUDE.md');
+    addDirFiles(ctx, candidates, '.claude/rules', /\.md$/i);
+    addDirFiles(ctx, candidates, '.claude/commands', /\.md$/i);
+    addDirFiles(ctx, candidates, '.claude/agents', /\.md$/i);
+    if (typeof ctx.dirFiles === 'function') {
+      for (const skillDir of ctx.dirFiles('.claude/skills')) {
+        addPath(candidates, path.join('.claude', 'skills', skillDir, 'SKILL.md'));
+      }
+    }
+  }
+
+  if (spec.platform === 'codex') {
+    addPath(candidates, 'AGENTS.md');
+    addPath(candidates, 'AGENTS.override.md');
+    addPath(candidates, typeof ctx.agentsMdPath === 'function' ? ctx.agentsMdPath() : null);
+    addDirFiles(ctx, candidates, 'codex/rules');
+    addDirFiles(ctx, candidates, '.codex/rules');
+    if (typeof ctx.skillDirs === 'function') {
+      for (const skillDir of ctx.skillDirs()) {
+        addPath(candidates, path.join('.agents', 'skills', skillDir, 'SKILL.md'));
+      }
+    }
+  }
+
+  if (spec.platform === 'gemini') {
+    addPath(candidates, 'GEMINI.md');
+    addPath(candidates, '.gemini/GEMINI.md');
+    addDirFiles(ctx, candidates, '.gemini/agents', /\.md$/i);
+    if (typeof ctx.skillDirs === 'function') {
+      for (const skillDir of ctx.skillDirs()) {
+        addPath(candidates, path.join('.gemini', 'skills', skillDir, 'SKILL.md'));
+      }
+    }
+  }
+
+  if (spec.platform === 'copilot') {
+    addPath(candidates, '.github/copilot-instructions.md');
+    addDirFiles(ctx, candidates, '.github/instructions', /\.instructions\.md$/i);
+    addDirFiles(ctx, candidates, '.github/prompts', /\.prompt\.md$/i);
+  }
+
+  if (spec.platform === 'cursor') {
+    addPath(candidates, '.cursorrules');
+    addDirFiles(ctx, candidates, '.cursor/rules', /\.mdc$/i);
+    addDirFiles(ctx, candidates, '.cursor/commands', /\.md$/i);
+  }
+
+  if (spec.platform === 'windsurf') {
+    addPath(candidates, '.windsurfrules');
+    addDirFiles(ctx, candidates, '.windsurf/rules', /\.md$/i);
+    addDirFiles(ctx, candidates, '.windsurf/workflows', /\.md$/i);
+    addDirFiles(ctx, candidates, '.windsurf/memories', /\.(md|json)$/i);
+  }
+
+  if (spec.platform === 'aider' && typeof ctx.conventionFiles === 'function') {
+    for (const file of ctx.conventionFiles()) {
+      addPath(candidates, file);
+    }
+  }
+
+  if (spec.platform === 'opencode') {
+    addPath(candidates, 'AGENTS.md');
+    addPath(candidates, 'CLAUDE.md');
+    addDirFiles(ctx, candidates, '.opencode/commands', /\.(md|markdown|ya?ml)$/i);
+    if (typeof ctx.skillDirs === 'function') {
+      for (const skillDir of ctx.skillDirs()) {
+        addPath(candidates, path.join('.opencode', 'commands', skillDir, 'SKILL.md'));
+      }
+    }
+  }
+
+  return [...candidates];
+}
+
+function inspectInstructionFiles(spec, ctx) {
+  const warnings = [];
+
+  for (const filePath of instructionFileCandidates(spec, ctx)) {
+    const byteCount = typeof ctx.fileSizeBytes === 'function' ? ctx.fileSizeBytes(filePath) : null;
+    if (!Number.isFinite(byteCount) || byteCount <= LARGE_INSTRUCTION_WARN_BYTES) continue;
+
+    const content = typeof ctx.fileContent === 'function' ? ctx.fileContent(filePath) : null;
+    warnings.push({
+      file: normalizeRelativePath(filePath),
+      byteCount,
+      lineCount: typeof content === 'string' ? content.split(/\r?\n/).length : null,
+      skipped: byteCount > LARGE_INSTRUCTION_SKIP_BYTES,
+      severity: byteCount > LARGE_INSTRUCTION_SKIP_BYTES ? 'critical' : 'warning',
+      message: byteCount > LARGE_INSTRUCTION_SKIP_BYTES
+        ? 'Instruction file exceeds 1MB and will be skipped during audit.'
+        : 'Instruction file exceeds 50KB. Audit will continue, but this file may reduce runtime clarity.',
+    });
+  }
+
+  return warnings;
+}
+
+function guardSkippedInstructionFiles(ctx, warnings) {
+  const skippedFiles = new Set(
+    warnings.filter((item) => item.skipped).map((item) => normalizeRelativePath(item.file))
+  );
+
+  if (skippedFiles.size === 0) return;
+
+  const originalFileContent = typeof ctx.fileContent === 'function' ? ctx.fileContent.bind(ctx) : null;
+  const originalLineNumber = typeof ctx.lineNumber === 'function' ? ctx.lineNumber.bind(ctx) : null;
+
+  if (originalFileContent) {
+    ctx.fileContent = (filePath) => {
+      if (skippedFiles.has(normalizeRelativePath(filePath))) return null;
+      return originalFileContent(filePath);
+    };
+  }
+
+  if (originalLineNumber) {
+    ctx.lineNumber = (filePath, matcher) => {
+      if (skippedFiles.has(normalizeRelativePath(filePath))) return null;
+      return originalLineNumber(filePath, matcher);
+    };
+  }
+}
+
+function buildWorkspaceHint(dir) {
+  if (!hasWorkspaceConfig(dir)) {
+    return null;
+  }
+
+  const patterns = detectWorkspaceGlobs(dir);
+  const workspaces = detectWorkspaces(dir);
+  if (patterns.length === 0 && workspaces.length === 0) {
+    return null;
+  }
+
+  return {
+    detected: true,
+    patterns,
+    workspaces,
+    suggestedCommand: patterns.length > 0
+      ? `npx nerviq audit --workspace ${patterns.join(',')}`
+      : `npx nerviq audit --workspace ${workspaces.join(',')}`,
+  };
+}
+
 function riskFromImpact(impact) {
   if (impact === 'critical') return 'high';
   if (impact === 'high') return 'medium';
@@ -441,24 +614,48 @@ function getQuickWins(failed, options = {}) {
     .slice(0, 3);
 }
 
-function getRecommendationPriorityScore(item, outcomeSummaryByKey = {}) {
+/**
+ * Compute a multiplier based on FP (helpful/not-helpful) feedback for a check key.
+ * - >50% "not helpful" feedback: lower priority by 30% (multiplier 0.7)
+ * - >80% "helpful" feedback: boost priority by 20% (multiplier 1.2)
+ * - Otherwise: no change (multiplier 1.0)
+ * @param {Object} fpFeedbackByKey - Keyed feedback summary from getFeedbackSummary().byKey
+ * @param {string} key - The check key to look up
+ * @returns {number} Multiplier to apply to priority score
+ */
+function getFpFeedbackMultiplier(fpFeedbackByKey, key) {
+  if (!fpFeedbackByKey) return 1.0;
+  const bucket = fpFeedbackByKey[key];
+  if (!bucket || bucket.total === 0) return 1.0;
+
+  const unhelpfulRate = bucket.unhelpful / bucket.total;
+  const helpfulRate = bucket.helpful / bucket.total;
+
+  if (unhelpfulRate > 0.5) return 0.7;
+  if (helpfulRate > 0.8) return 1.2;
+  return 1.0;
+}
+
+function getRecommendationPriorityScore(item, outcomeSummaryByKey = {}, fpFeedbackByKey = null) {
   const impactScore = (IMPACT_ORDER[item.impact] ?? 0) * 100;
   const feedbackAdjustment = getRecommendationAdjustment(outcomeSummaryByKey, item.key);
   const brevityPenalty = Math.min((item.fix || '').length, 240) / 20;
-  return impactScore + (feedbackAdjustment * 10) - brevityPenalty;
+  const raw = impactScore + (feedbackAdjustment * 10) - brevityPenalty;
+  return raw * getFpFeedbackMultiplier(fpFeedbackByKey, item.key);
 }
 
 function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, options = {}) {
   const pool = getPrioritizedFailed(failed);
+  const fpByKey = options.fpFeedbackByKey || null;
 
   return [...pool]
     .sort((a, b) => {
       const scoreB = options.platform === 'codex'
         ? codexPriorityScore(b, outcomeSummaryByKey)
-        : getRecommendationPriorityScore(b, outcomeSummaryByKey);
+        : getRecommendationPriorityScore(b, outcomeSummaryByKey, fpByKey);
       const scoreA = options.platform === 'codex'
         ? codexPriorityScore(a, outcomeSummaryByKey)
-        : getRecommendationPriorityScore(a, outcomeSummaryByKey);
+        : getRecommendationPriorityScore(a, outcomeSummaryByKey, fpByKey);
       return scoreB - scoreA;
     })
     .slice(0, limit)
@@ -479,7 +676,7 @@ function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, option
       const evidenceClass = options.platform === 'codex' ? codexEvidenceClass(fullItem) : (feedback ? 'measured' : 'estimated');
       const priorityScore = options.platform === 'codex'
         ? codexPriorityScore(fullItem, outcomeSummaryByKey)
-        : Math.max(0, Math.min(100, Math.round(getRecommendationPriorityScore(fullItem, outcomeSummaryByKey) / 3)));
+        : Math.max(0, Math.min(100, Math.round(getRecommendationPriorityScore(fullItem, outcomeSummaryByKey, fpByKey) / 3)));
 
       signals.push(`evidence:${evidenceClass}`);
       if (options.platform === 'codex' && CODEX_HARD_FAIL_KEYS.has(key)) {
@@ -677,12 +874,20 @@ function printLiteAudit(result, dir) {
   if (result.platformScopeNote) {
     console.log(colorize(`  Scope: ${result.platformScopeNote.message}`, 'dim'));
   }
+  if (result.workspaceHint && result.workspaceHint.workspaces.length > 0) {
+    console.log(colorize(`  Workspaces: ${result.workspaceHint.workspaces.join(', ')}`, 'dim'));
+  }
   if (result.platformCaveats && result.platformCaveats.length > 0) {
     console.log(colorize('  Platform caveats:', 'yellow'));
     result.platformCaveats.slice(0, 2).forEach((item) => {
       console.log(colorize(`     - ${item.title}: ${item.message}`, 'dim'));
     });
   }
+  if (result.largeInstructionFiles && result.largeInstructionFiles.length > 0) {
+    result.largeInstructionFiles.slice(0, 2).forEach((item) => {
+      console.log(colorize(`  Large file: ${item.file} (${Math.round(item.byteCount / 1024)}KB)`, 'yellow'));
+    });
+  }
   console.log('');
 
   if (result.failed === 0) {
@@ -725,9 +930,13 @@ async function audit(options) {
   const spec = getAuditSpec(options.platform || 'claude');
   const silent = options.silent || false;
   const ctx = new spec.ContextClass(options.dir);
+  const largeInstructionFiles = inspectInstructionFiles(spec, ctx);
+  guardSkippedInstructionFiles(ctx, largeInstructionFiles);
   const stacks = ctx.detectStacks(STACKS);
   const results = [];
   const outcomeSummary = getRecommendationOutcomeSummary(options.dir);
+  const fpFeedback = getFeedbackSummary(options.dir);
+  const workspaceHint = buildWorkspaceHint(options.dir);
 
   // Load and merge plugin checks
   const plugins = loadPlugins(options.dir);
@@ -749,6 +958,24 @@ async function audit(options) {
     });
   }
 
+  if (largeInstructionFiles.length > 0) {
+    results.push({
+      key: 'largeInstructionFile',
+      id: null,
+      name: 'Large instruction file warning',
+      category: 'performance',
+      impact: 'medium',
+      rating: null,
+      fix: 'Split oversized instruction files so they stay under 50KB, and keep any single instruction file below 1MB.',
+      sourceUrl: null,
+      confidence: 'high',
+      file: largeInstructionFiles[0].file,
+      line: null,
+      passed: null,
+      details: largeInstructionFiles,
+    });
+  }
+
   // null = not applicable (skip), true = pass, false = fail
   const applicable = results.filter(r => r.passed !== null);
   const skipped = results.filter(r => r.passed === null);
@@ -795,10 +1022,27 @@ async function audit(options) {
   const organicEarned = organicPassed.reduce((sum, r) => sum + (WEIGHTS[r.impact] || 5), 0);
   const organicScore = maxScore > 0 ? Math.round((organicEarned / maxScore) * 100) : 0;
   const quickWins = getQuickWins(failed, { platform: spec.platform });
-  const topNextActions = buildTopNextActions(failed, 5, outcomeSummary.byKey, { platform: spec.platform });
+  const topNextActions = buildTopNextActions(failed, 5, outcomeSummary.byKey, { platform: spec.platform, fpFeedbackByKey: fpFeedback.byKey });
   const categoryScores = computeCategoryScores(applicable, passed);
   const platformScopeNote = getPlatformScopeNote(spec, ctx);
   const platformCaveats = getPlatformCaveats(spec, ctx);
+  const deprecationWarnings = detectDeprecationWarnings(failed, packageVersion);
+  const warnings = [
+    ...largeInstructionFiles.map((item) => ({
+      kind: 'large-instruction-file',
+      severity: item.severity,
+      message: item.message,
+      file: item.file,
+      lineCount: item.lineCount,
+      byteCount: item.byteCount,
+      skipped: item.skipped,
+    })),
+    ...deprecationWarnings.map((item) => ({
+      kind: 'deprecated-feature',
+      severity: 'warning',
+      ...item,
+    })),
+  ];
   const recommendedDomainPacks = spec.platform === 'codex'
     ? detectCodexDomainPacks(ctx, stacks, getCodexDomainPackSignals(ctx))
     : [];
@@ -824,6 +1068,10 @@ async function audit(options) {
       totalEntries: outcomeSummary.totalEntries,
       keysTracked: outcomeSummary.keys,
     },
+    largeInstructionFiles,
+    deprecationWarnings,
+    warnings,
+    workspaceHint,
     platformScopeNote,
     platformCaveats,
     recommendedDomainPacks,
@@ -841,9 +1089,8 @@ async function audit(options) {
   }
 
   if (options.json) {
-    const { version } = require('../package.json');
     console.log(JSON.stringify({
-      version,
+      version: packageVersion,
       timestamp: new Date().toISOString(),
       ...result
     }, null, 2));
@@ -855,6 +1102,11 @@ async function audit(options) {
     return result;
   }
 
+  if (options.format === 'otel') {
+    console.log(JSON.stringify(formatOtelMetrics(result), null, 2));
+    return result;
+  }
+
   if (options.lite) {
     printLiteAudit(result, options.dir);
     sendInsights(result);
@@ -888,6 +1140,35 @@ async function audit(options) {
     console.log('');
   }
 
+  if (largeInstructionFiles.length > 0) {
+    console.log(colorize('  Large instruction files', 'yellow'));
+    for (const item of largeInstructionFiles) {
+      const sizeKb = Math.round(item.byteCount / 1024);
+      console.log(colorize(`     ${item.file} (${sizeKb}KB, ${item.lineCount || '?'} lines)`, 'bold'));
+      console.log(colorize(`     → ${item.message}`, 'dim'));
+    }
+    console.log('');
+  }
+
+  if (deprecationWarnings.length > 0) {
+    console.log(colorize('  Deprecated feature warnings', 'yellow'));
+    for (const item of deprecationWarnings) {
+      console.log(colorize(`     ${item.feature}`, 'bold'));
+      console.log(colorize(`     → ${item.message}`, 'dim'));
+      console.log(colorize(`     Alternative: ${item.alternative}`, 'dim'));
+    }
+    console.log('');
+  }
+
+  if (workspaceHint && !options.workspace) {
+    console.log(colorize('  Monorepo detected', 'blue'));
+    if (workspaceHint.workspaces.length > 0) {
+      console.log(colorize(`     Workspaces: ${workspaceHint.workspaces.join(', ')}`, 'dim'));
+    }
+    console.log(colorize(`     Tip: ${workspaceHint.suggestedCommand}`, 'dim'));
+    console.log('');
+  }
+
   if (stacks.length > 0) {
     console.log(colorize(`  Detected: ${stacks.map(s => s.label).join(', ')}`, 'blue'));
   }
@@ -1008,4 +1289,4 @@ async function audit(options) {
   return result;
 }
 
-module.exports = { audit, buildTopNextActions };
+module.exports = { audit, buildTopNextActions, getFpFeedbackMultiplier, getRecommendationPriorityScore };

package/src/catalog.js

@@ -5,6 +5,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { version } = require('../package.json');
 
 const { TECHNIQUES: CLAUDE_TECHNIQUES } = require('./techniques');
 const { CODEX_TECHNIQUES } = require('./codex/techniques');
@@ -31,7 +32,7 @@ const PLATFORM_MAP = {
  * Generate a unified catalog array from all platform technique files.
  * Each entry contains:
  *   platform, id, key, name, category, impact, rating, fix, sourceUrl,
- *   confidence, template, deprecated
+ *   confidence, lastVerified, template, deprecated
  */
 function generateCatalog() {
   const catalog = [];
@@ -62,6 +63,7 @@ function generateCatalog() {
         fix: tech.fix ?? null,
         sourceUrl: tech.sourceUrl ?? null,
         confidence: tech.confidence ?? null,
+        lastVerified: tech.lastVerified ?? null,
         template: tech.template ?? null,
         deprecated: tech.deprecated ?? false,
       });
@@ -71,6 +73,20 @@ function generateCatalog() {
   return catalog;
 }
 
+/**
+ * Generate a catalog envelope with version metadata.
+ * @returns {{ catalogVersion: string, generatedAt: string, totalChecks: number, checks: Object[] }}
+ */
+function generateCatalogWithVersion() {
+  const checks = generateCatalog();
+  return {
+    catalogVersion: version,
+    generatedAt: new Date().toISOString(),
+    totalChecks: checks.length,
+    checks,
+  };
+}
+
 /**
  * Write the catalog as formatted JSON to the given output path.
  * @param {string} outputPath - Absolute or relative path for the JSON file
@@ -84,4 +100,4 @@ function writeCatalogJson(outputPath) {
   return { path: resolved, count: catalog.length };
 }
 
-module.exports = { generateCatalog, writeCatalogJson };
+module.exports = { generateCatalog, generateCatalogWithVersion, writeCatalogJson };

package/src/codex/domain-packs.js

@@ -1,4 +1,6 @@
-const CODEX_DOMAIN_PACKS = [
+const { buildAdditionalDomainPacks, detectAdditionalDomainPacks } = require('../domain-pack-expansion');
+
+const BASE_CODEX_DOMAIN_PACKS = [
   {
     key: 'baseline-general',
     label: 'Baseline General',
@@ -162,6 +164,13 @@ const CODEX_DOMAIN_PACKS = [
   },
 ];
 
+const CODEX_DOMAIN_PACKS = [
+  ...BASE_CODEX_DOMAIN_PACKS,
+  ...buildAdditionalDomainPacks('codex', {
+    existingKeys: new Set(BASE_CODEX_DOMAIN_PACKS.map((pack) => pack.key)),
+  }),
+];
+
 function uniqueByKey(items) {
   const seen = new Set();
   const result = [];
@@ -354,6 +363,19 @@ function detectCodexDomainPacks(ctx, stacks = [], assets = {}) {
     ]);
   }
 
+  detectAdditionalDomainPacks({
+    ctx,
+    pkg,
+    deps,
+    stackKeys,
+    addMatch,
+    hasBackend,
+    hasFrontend,
+    hasInfra,
+    hasCi,
+    isEnterpriseGoverned,
+  });
+
   if (matches.length === 0) {
     addMatch('baseline-general', [
       'No stronger platform-specific domain dominated, so a safe general Codex baseline is the best starting point.',