@nerviq/cli 1.10.0 → 1.12.0

package/src/audit.js

@@ -24,16 +24,18 @@ const { AiderProjectContext } = require('./aider/context');
 const { OPENCODE_TECHNIQUES } = require('./opencode/techniques');
 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 { t } = require('./i18n');
+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 { collectAuditTerminology, formatTerminologyLines } = require('./terminology');
+const { loadPlugins, mergePluginChecks } = require('./plugins');
+const { hasWorkspaceConfig, detectWorkspaceGlobs, detectWorkspaces } = require('./workspace');
+const { detectDeprecationWarnings } = require('./deprecation');
+const { estimateTokenCount } = require('./token-estimate');
+const { version: packageVersion } = require('../package.json');
+const { t } = require('./i18n');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -62,10 +64,11 @@ function formatLocation(file, line) {
   return line ? `${file}:${line}` : file;
 }
 
-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 IMPACT_ORDER = { critical: 3, high: 2, medium: 1, low: 0 };
+const WEIGHTS = { critical: 15, high: 10, medium: 5, low: 2 };
+const SCORE_MILESTONES = [50, 70, 90, 100];
+const LARGE_INSTRUCTION_WARN_TOKENS = 12000;
+const LARGE_INSTRUCTION_SKIP_TOKENS = 240000;
 const CATEGORY_MODULES = {
   memory: 'CLAUDE.md',
   quality: 'verification',
@@ -358,9 +361,13 @@ function getAuditSpec(platform = 'claude') {
   };
 }
 
-function normalizeRelativePath(filePath) {
-  return String(filePath || '').replace(/\\/g, '/').replace(/^\.\//, '');
-}
+function normalizeRelativePath(filePath) {
+  return String(filePath || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function formatCount(value) {
+  return Number(value || 0).toLocaleString('en-US');
+}
 
 function addPath(target, filePath) {
   if (!filePath || typeof filePath !== 'string') return;
@@ -454,25 +461,27 @@ function instructionFileCandidates(spec, ctx) {
   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.',
-    });
-  }
+function inspectInstructionFiles(spec, ctx) {
+  const warnings = [];
+
+  for (const filePath of instructionFileCandidates(spec, ctx)) {
+    const content = typeof ctx.fileContent === 'function' ? ctx.fileContent(filePath) : null;
+    const byteCount = typeof ctx.fileSizeBytes === 'function' ? ctx.fileSizeBytes(filePath) : null;
+    const tokenCount = typeof content === 'string' ? estimateTokenCount(content) : null;
+    if (!Number.isFinite(tokenCount) || tokenCount <= LARGE_INSTRUCTION_WARN_TOKENS) continue;
+
+    warnings.push({
+      file: normalizeRelativePath(filePath),
+      byteCount,
+      tokenCount,
+      lineCount: typeof content === 'string' ? content.split(/\r?\n/).length : null,
+      skipped: tokenCount > LARGE_INSTRUCTION_SKIP_TOKENS,
+      severity: tokenCount > LARGE_INSTRUCTION_SKIP_TOKENS ? 'critical' : 'warning',
+      message: tokenCount > LARGE_INSTRUCTION_SKIP_TOKENS
+        ? 'Instruction file exceeds ~240,000 tokens and will be skipped during audit.'
+        : 'Instruction file exceeds ~12,000 tokens. Audit will continue, but this file may reduce runtime clarity.',
+    });
+  }
 
   return warnings;
 }
@@ -651,7 +660,7 @@ function getRecommendationPriorityScore(item, outcomeSummaryByKey = {}, fpFeedba
   return raw * getFpFeedbackMultiplier(fpFeedbackByKey, item.key);
 }
 
-function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, options = {}) {
+function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, options = {}) {
   const pool = getPrioritizedFailed(failed);
   const fpByKey = options.fpFeedbackByKey || null;
 
@@ -716,11 +725,65 @@ function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, option
         avgScoreDelta: feedback.avgScoreDelta,
       } : null,
     });
-    });
-}
-
-function computeCategoryScores(applicable, passed) {
-  const grouped = {};
+    });
+}
+
+function getNextScoreMilestone(score) {
+  return SCORE_MILESTONES.find((milestone) => score < milestone) || null;
+}
+
+function buildScoreCoaching({ score, earnedPoints, maxPoints, failed, outcomeSummaryByKey = {}, platform, fpFeedbackByKey = null }) {
+  if (!Array.isArray(failed) || failed.length === 0 || !Number.isFinite(maxPoints) || maxPoints <= 0) {
+    return null;
+  }
+
+  const nextMilestone = getNextScoreMilestone(score);
+  if (!nextMilestone) return null;
+
+  const targetEarnedPoints = Math.ceil((nextMilestone / 100) * maxPoints);
+  const pointsNeeded = Math.max(0, targetEarnedPoints - earnedPoints);
+  if (pointsNeeded <= 0) return null;
+
+  const rankedActions = buildTopNextActions(failed, failed.length, outcomeSummaryByKey, { platform, fpFeedbackByKey });
+  if (rankedActions.length === 0) return null;
+
+  const failedByKey = new Map(failed.map((item) => [item.key, item]));
+  const selected = [];
+  let recoveredPoints = 0;
+
+  for (const action of rankedActions) {
+    const source = failedByKey.get(action.key);
+    if (!source) continue;
+    selected.push({
+      key: source.key,
+      name: source.name,
+      impact: source.impact,
+      weight: WEIGHTS[source.impact] || 0,
+    });
+    recoveredPoints += WEIGHTS[source.impact] || 0;
+    if (recoveredPoints >= pointsNeeded) break;
+  }
+
+  if (selected.length === 0) return null;
+
+  const fixesNeeded = selected.length;
+  const projectedScore = Math.round(((earnedPoints + recoveredPoints) / maxPoints) * 100);
+  const summary = `You're ${fixesNeeded} ${fixesNeeded === 1 ? 'fix' : 'fixes'} away from ${nextMilestone}/100.`;
+
+  return {
+    currentScore: score,
+    nextMilestone,
+    pointsNeeded,
+    fixesNeeded,
+    projectedScore: Math.min(100, projectedScore),
+    summary,
+    recommendedKeys: selected.map((item) => item.key),
+    recommendedNames: selected.map((item) => item.name),
+  };
+}
+
+function computeCategoryScores(applicable, passed) {
+  const grouped = {};
 
   for (const item of applicable) {
     const category = item.category || 'unknown';
@@ -907,6 +970,9 @@ function printLiteAudit(result, dir) {
     scoreExplanation = t('audit.early');
   }
   console.log(colorize(`  ${scoreExplanation}`, 'dim'));
+  if (result.scoreCoaching) {
+    console.log(colorize(`  Milestone: ${result.scoreCoaching.summary}`, 'magenta'));
+  }
   console.log(colorize('  Score type: live repo audit (current files only, not snapshot history or benchmark projection).', 'dim'));
 
   if (result.platformScopeNote) {
@@ -921,11 +987,11 @@ function printLiteAudit(result, dir) {
       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'));
-    });
-  }
+  if (result.largeInstructionFiles && result.largeInstructionFiles.length > 0) {
+    result.largeInstructionFiles.slice(0, 2).forEach((item) => {
+      console.log(colorize(`  Large file: ${item.file} (~${formatCount(item.tokenCount)} tokens)`, 'yellow'));
+    });
+  }
   console.log('');
 
   if (result.failed === 0) {
@@ -957,15 +1023,23 @@ function printLiteAudit(result, dir) {
   console.log('');
   let usagePatterns;
   try { usagePatterns = require('./usage-patterns'); } catch { usagePatterns = null; }
-  result.liteSummary.topNextActions.forEach((item, index) => {
-    const tier = item.impact === 'critical' ? '🔴' : item.impact === 'high' ? '🟡' : '🔵';
-    const suppressed = usagePatterns && usagePatterns.getPriorityAdjustment(dir, item.key) === 'suppress';
-    const suffix = suppressed ? colorize(' (suppressed)', 'dim') : '';
-    console.log(`  ${index + 1}. ${tier} ${colorize(item.name, 'bold')}${suffix}`);
-    console.log(colorize(`     ${item.fix}`, 'dim'));
-  });
-  console.log('');
-  console.log(`  Ready? Run: ${colorize(result.suggestedNextCommand, 'bold')}`);
+  result.liteSummary.topNextActions.forEach((item, index) => {
+    const tier = item.impact === 'critical' ? '🔴' : item.impact === 'high' ? '🟡' : '🔵';
+    const suppressed = usagePatterns && usagePatterns.getPriorityAdjustment(dir, item.key) === 'suppress';
+    const suffix = suppressed ? colorize(' (suppressed)', 'dim') : '';
+    console.log(`  ${index + 1}. ${tier} ${colorize(item.name, 'bold')}${suffix}`);
+    console.log(colorize(`     ${item.fix}`, 'dim'));
+  });
+  console.log('');
+  const liteTerminology = formatTerminologyLines(collectAuditTerminology(result));
+  if (liteTerminology.length > 0) {
+    liteTerminology.forEach((line) => {
+      const color = line.startsWith('  Terms used here:') ? 'blue' : 'dim';
+      console.log(colorize(line, color));
+    });
+    console.log('');
+  }
+  console.log(`  Ready? Run: ${colorize(result.suggestedNextCommand, 'bold')}`);
   if (result.platform === 'codex') {
     console.log(colorize('  Note: Codex now supports no-write advisory flows via augment and suggest-only before setup/apply.', 'dim'));
   }
@@ -1054,12 +1128,12 @@ async function audit(options) {
       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',
+      category: 'performance',
+      impact: 'medium',
+      rating: null,
+      fix: 'Split oversized instruction files so they stay under ~12,000 tokens, and keep any single instruction file below ~240,000 tokens.',
+      sourceUrl: null,
+      confidence: 'high',
       file: largeInstructionFiles[0].file,
       line: null,
       passed: null,
@@ -1127,12 +1201,13 @@ async function audit(options) {
     ...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,
-    })),
+      message: item.message,
+      file: item.file,
+      lineCount: item.lineCount,
+      byteCount: item.byteCount,
+      tokenCount: item.tokenCount,
+      skipped: item.skipped,
+    })),
     ...deprecationWarnings.map((item) => ({
       kind: 'deprecated-feature',
       severity: 'warning',
@@ -1142,7 +1217,7 @@ async function audit(options) {
   const recommendedDomainPacks = spec.platform === 'codex'
     ? detectCodexDomainPacks(ctx, stacks, getCodexDomainPackSignals(ctx))
     : [];
-  const result = {
+  const result = {
     platform: spec.platform,
     platformLabel: spec.platformLabel,
     platformVersion: spec.platformVersion,
@@ -1165,9 +1240,18 @@ async function audit(options) {
       deprecatedReason: r.deprecatedReason || null,
       sunsetDate: r.sunsetDate || null,
     })),
-    categoryScores,
-    quickWins: quickWins.map(({ key, name, impact, fix, category, sourceUrl }) => ({ key, name, impact, category, fix, sourceUrl })),
-    topNextActions,
+    categoryScores,
+    scoreCoaching: buildScoreCoaching({
+      score,
+      earnedPoints: earnedScore,
+      maxPoints: maxScore,
+      failed,
+      outcomeSummaryByKey: outcomeSummary.byKey,
+      platform: spec.platform,
+      fpFeedbackByKey: fpFeedback.byKey,
+    }),
+    quickWins: quickWins.map(({ key, name, impact, fix, category, sourceUrl }) => ({ key, name, impact, category, fix, sourceUrl })),
+    topNextActions,
     recommendationOutcomes: {
       totalEntries: outcomeSummary.totalEntries,
       keysTracked: outcomeSummary.keys,
@@ -1197,11 +1281,12 @@ async function audit(options) {
   result.detectedConfigFiles = configFiles;
 
   result.suggestedNextCommand = inferSuggestedNextCommand(result);
-  result.liteSummary = {
-    topNextActions: topNextActions.slice(0, 3),
-    nextCommand: result.suggestedNextCommand,
-    platformCaveats: platformCaveats.slice(0, 2),
-  };
+  result.liteSummary = {
+    topNextActions: topNextActions.slice(0, 3),
+    nextCommand: result.suggestedNextCommand,
+    platformCaveats: platformCaveats.slice(0, 2),
+    scoreCoaching: result.scoreCoaching,
+  };
 
   // Silent mode: skip all output, just return result
   if (silent) {
@@ -1260,13 +1345,13 @@ 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'));
-    }
+  if (largeInstructionFiles.length > 0) {
+    console.log(colorize('  Large instruction files', 'yellow'));
+    for (const item of largeInstructionFiles) {
+      const sizeKb = Number.isFinite(item.byteCount) ? Math.round(item.byteCount / 1024) : '?';
+      console.log(colorize(`     ${item.file} (~${formatCount(item.tokenCount)} tokens, ${item.lineCount || '?'} lines, ${sizeKb}KB)`, 'bold'));
+      console.log(colorize(`     → ${item.message}`, 'dim'));
+    }
     console.log('');
   }
 
@@ -1296,11 +1381,18 @@ async function audit(options) {
   console.log('');
 
   // Score
-  console.log(`  ${progressBar(score)} ${colorize(`${score}/100`, 'bold')}`);
-  if (isScaffolded && scaffoldedPassed.length > 0) {
-    console.log(colorize(`  Organic: ${organicScore}/100 (without nerviq generated files)`, 'dim'));
-  }
-  console.log('');
+  console.log(`  ${progressBar(score)} ${colorize(`${score}/100`, 'bold')}`);
+  if (isScaffolded && scaffoldedPassed.length > 0) {
+    console.log(colorize(`  Organic: ${organicScore}/100 (without nerviq generated files)`, 'dim'));
+  }
+  if (result.scoreCoaching) {
+    const fastestPath = result.scoreCoaching.recommendedNames.slice(0, 3).join(', ');
+    console.log(colorize(`  Milestone: ${result.scoreCoaching.summary}`, 'magenta'));
+    if (fastestPath) {
+      console.log(colorize(`  Fastest path: ${fastestPath}`, 'dim'));
+    }
+  }
+  console.log('');
 
   // Passed
   if (passed.length > 0) {
@@ -1366,8 +1458,8 @@ async function audit(options) {
   }
 
   // Top next actions
-  if (topNextActions.length > 0) {
-    console.log(colorize('  ⚡ Top 5 Next Actions', 'magenta'));
+  if (topNextActions.length > 0) {
+    console.log(colorize('  ⚡ Top 5 Next Actions', 'magenta'));
     for (let i = 0; i < topNextActions.length; i++) {
       const item = topNextActions[i];
       console.log(`     ${i + 1}. ${colorize(item.name, 'bold')}`);
@@ -1383,11 +1475,20 @@ async function audit(options) {
         console.log(colorize(`        Feedback: accepted ${item.feedback.accepted}, rejected ${item.feedback.rejected}, positive ${item.feedback.positive}, negative ${item.feedback.negative}${avgDelta}`, 'dim'));
       }
       console.log(colorize(`        Fix: ${item.fix}`, 'dim'));
-    }
-    console.log('');
-  }
-
-  // Summary
+    }
+    console.log('');
+  }
+
+  const terminology = formatTerminologyLines(collectAuditTerminology(result));
+  if (terminology.length > 0) {
+    terminology.forEach((line) => {
+      const color = line.startsWith('  Terms used here:') ? 'blue' : 'dim';
+      console.log(colorize(line, color));
+    });
+    console.log('');
+  }
+
+  // Summary
   console.log(colorize('  ─────────────────────────────────────', 'dim'));
   const deprecatedNote = deprecated.length > 0 ? colorize(`, ${deprecated.length} deprecated`, 'dim') : '';
   console.log(`  ${colorize(`${passed.length}/${applicable.length}`, 'bold')} checks passing${skipped.length > 0 ? colorize(` (${skipped.length} not applicable${deprecatedNote})`, 'dim') : (deprecatedNote ? colorize(` (${deprecatedNote})`, 'dim') : '')}`);