@nerviq/cli 1.9.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "The intelligent nervous system for AI coding agents — 2,438 checks (8 platforms × ~300 governance rules), 10 languages, 62 domain packs. Audit, align, and amplify.",
   "main": "src/index.js",
   "bin": {

package/src/activity.js

@@ -136,6 +136,37 @@ function summarizeSnapshot(snapshotKind, payload) {
   return {};
 }
 
+function normalizeSnapshotTags(input) {
+  const values = Array.isArray(input) ? input : (input ? [input] : []);
+  const seen = new Set();
+  const tags = [];
+
+  for (const value of values) {
+    const parts = `${value || ''}`
+      .split(',')
+      .map((item) => item.replace(/\s+/g, ' ').trim())
+      .filter(Boolean);
+
+    for (const part of parts) {
+      const key = part.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      tags.push(part.slice(0, 48));
+      if (tags.length >= 8) {
+        return tags;
+      }
+    }
+  }
+
+  return tags;
+}
+
+function formatSnapshotTags(tags = []) {
+  const normalized = normalizeSnapshotTags(tags);
+  if (normalized.length === 0) return '';
+  return ` [${normalized.join(', ')}]`;
+}
+
 function updateSnapshotIndex(snapshotDir, record) {
   const indexPath = path.join(snapshotDir, 'index.json');
   let entries = [];
@@ -173,6 +204,11 @@ function writeSnapshotArtifact(dir, snapshotKind, payload, meta = {}) {
   const { snapshotDir } = ensureArtifactDirs(dir);
   const filePath = path.join(snapshotDir, `${id}-${snapshotKind}.json`);
   const summary = summarizeSnapshot(snapshotKind, payload);
+  const metaTags = normalizeSnapshotTags([
+    ...(Array.isArray(meta.tags) ? meta.tags : (meta.tags ? [meta.tags] : [])),
+    ...(meta.tag ? [meta.tag] : []),
+  ]);
+  const { tags: _ignoredTags, tag: _ignoredTag, ...restMeta } = meta;
   const envelope = {
     schemaVersion: 1,
     artifactType: 'snapshot',
@@ -183,7 +219,8 @@ function writeSnapshotArtifact(dir, snapshotKind, payload, meta = {}) {
     generatedBy: `nerviq@${version}`,
     directory: dir,
     summary,
-    ...meta,
+    tags: metaTags,
+    ...restMeta,
     payload,
   };
 
@@ -194,6 +231,7 @@ function writeSnapshotArtifact(dir, snapshotKind, payload, meta = {}) {
     snapshotKind,
     createdAt: envelope.createdAt,
     relativePath: path.relative(dir, filePath),
+    tags: metaTags,
     summary,
   };
   updateSnapshotIndex(snapshotDir, record);
@@ -236,6 +274,79 @@ function getHistory(dir, limit = 20) {
     .slice(0, limit);
 }
 
+function buildCheckDiffDetail(previousResult, currentResult) {
+  const source = currentResult || previousResult || {};
+  const previousState = previousResult ? previousResult.passed : undefined;
+  const currentState = currentResult ? currentResult.passed : undefined;
+  return {
+    key: source.key,
+    name: source.name || source.key,
+    impact: source.impact || null,
+    category: source.category || null,
+    previousState,
+    currentState,
+  };
+}
+
+function collectCheckDiff(previousResults = [], currentResults = []) {
+  const prevMap = new Map();
+  const currMap = new Map();
+
+  for (const result of previousResults) {
+    if (result && result.key) prevMap.set(result.key, result);
+  }
+  for (const result of currentResults) {
+    if (result && result.key) currMap.set(result.key, result);
+  }
+
+  const regressions = [];
+  const improvements = [];
+  const newlyApplicable = [];
+  const noLongerApplicable = [];
+  const newChecks = [];
+  const removedChecks = [];
+
+  const allKeys = [...new Set([...prevMap.keys(), ...currMap.keys()])].sort();
+  for (const key of allKeys) {
+    const previousResult = prevMap.get(key);
+    const currentResult = currMap.get(key);
+    const previousState = previousResult ? previousResult.passed : undefined;
+    const currentState = currentResult ? currentResult.passed : undefined;
+    const detail = buildCheckDiffDetail(previousResult, currentResult);
+
+    if (!previousResult) {
+      if (currentState !== undefined) {
+        newChecks.push(detail);
+      }
+      continue;
+    }
+
+    if (!currentResult) {
+      removedChecks.push(detail);
+      continue;
+    }
+
+    if (previousState === true && currentState === false) {
+      regressions.push(detail);
+    } else if (previousState === false && currentState === true) {
+      improvements.push(detail);
+    } else if ((previousState === null || previousState === undefined) && (currentState === true || currentState === false)) {
+      newlyApplicable.push(detail);
+    } else if ((currentState === null || currentState === undefined) && (previousState === true || previousState === false)) {
+      noLongerApplicable.push(detail);
+    }
+  }
+
+  return {
+    regressions,
+    improvements,
+    newlyApplicable,
+    noLongerApplicable,
+    newChecks,
+    removedChecks,
+  };
+}
+
 /**
  * Compare the two most recent audit snapshots and return the delta.
  * @param {string} dir - Project root directory.
@@ -247,6 +358,8 @@ function compareLatest(dir) {
 
   const current = audits[0];
   const previous = audits[1];
+  const currentPayload = loadSnapshotPayload(dir, current);
+  const previousPayload = loadSnapshotPayload(dir, previous);
 
   const delta = {
     score: (current.summary?.score || 0) - (previous.summary?.score || 0),
@@ -254,34 +367,122 @@ function compareLatest(dir) {
     passed: (current.summary?.passed || 0) - (previous.summary?.passed || 0),
   };
 
-  const regressions = [];
-  const improvements = [];
-
-  const prevKeys = new Set(previous.summary?.topActionKeys || []);
-  const currKeys = new Set(current.summary?.topActionKeys || []);
-
-  for (const key of currKeys) {
-    if (!prevKeys.has(key)) regressions.push(key);
-  }
-  for (const key of prevKeys) {
-    if (!currKeys.has(key)) improvements.push(key);
+  let regressionDetails = [];
+  let improvementDetails = [];
+  let newlyApplicableDetails = [];
+  let noLongerApplicableDetails = [];
+  let newChecks = [];
+  let removedChecks = [];
+  let regressions = [];
+  let improvements = [];
+  let detailedDiffAvailable = false;
+
+  if (currentPayload && previousPayload && Array.isArray(currentPayload.results) && Array.isArray(previousPayload.results)) {
+    const diff = collectCheckDiff(previousPayload.results, currentPayload.results);
+    regressionDetails = diff.regressions;
+    improvementDetails = diff.improvements;
+    newlyApplicableDetails = diff.newlyApplicable;
+    noLongerApplicableDetails = diff.noLongerApplicable;
+    newChecks = diff.newChecks;
+    removedChecks = diff.removedChecks;
+    regressions = regressionDetails.map((item) => item.key);
+    improvements = improvementDetails.map((item) => item.key);
+    detailedDiffAvailable = true;
+  } else {
+    const prevKeys = new Set(previous.summary?.topActionKeys || []);
+    const currKeys = new Set(current.summary?.topActionKeys || []);
+    for (const key of currKeys) {
+      if (!prevKeys.has(key)) regressions.push(key);
+    }
+    for (const key of prevKeys) {
+      if (!currKeys.has(key)) improvements.push(key);
+    }
   }
 
   return {
-    current: { date: current.createdAt, score: current.summary?.score, passed: current.summary?.passed },
-    previous: { date: previous.createdAt, score: previous.summary?.score, passed: previous.summary?.passed },
+    scoreType: 'audit-snapshot-score',
+    current: {
+      date: current.createdAt,
+      score: current.summary?.score,
+      passed: current.summary?.passed,
+      tags: current.tags || [],
+      scoreType: 'audit-snapshot-score',
+    },
+    previous: {
+      date: previous.createdAt,
+      score: previous.summary?.score,
+      passed: previous.summary?.passed,
+      tags: previous.tags || [],
+      scoreType: 'audit-snapshot-score',
+    },
     delta,
     regressions,
     improvements,
+    regressionDetails,
+    improvementDetails,
+    newlyApplicableDetails,
+    noLongerApplicableDetails,
+    newChecks,
+    removedChecks,
+    detailedDiffAvailable,
     trend: delta.score > 0 ? 'improving' : delta.score < 0 ? 'regressing' : 'stable',
   };
 }
 
+function formatSnapshotBootstrap(dir, goal = 'history') {
+  const snapshotCount = getHistory(dir, 50).length;
+  const lines = [];
+  const snapshotLabel = snapshotCount === 1
+    ? '1 saved audit snapshot'
+    : `${snapshotCount} saved audit snapshots`;
+
+  if (goal === 'compare') {
+    lines.push(snapshotCount === 0
+      ? 'Compare needs 2 audit snapshots.'
+      : 'Compare needs one more audit snapshot.');
+  } else if (goal === 'trend') {
+    lines.push(snapshotCount === 0
+      ? 'Trend needs 2 audit snapshots to start.'
+      : 'Trend needs one more audit snapshot to become meaningful.');
+  } else {
+    lines.push(snapshotCount === 0
+      ? 'No audit snapshots found yet.'
+      : 'History is initialized, but compare/trend still need one more snapshot.');
+  }
+
+  lines.push(`  Current state: ${snapshotLabel}.`);
+
+  if (snapshotCount === 0) {
+    lines.push('  Bootstrap it with:');
+    lines.push('  1. Run `nerviq audit --snapshot --tag "baseline"` to save the baseline.');
+    lines.push('  2. Make a meaningful repo change (`nerviq setup --auto` or `nerviq fix --all-critical --auto`).');
+    lines.push('  3. Run `nerviq audit --snapshot --tag "after-change"` to capture the next state.');
+  } else {
+    lines.push('  Next:');
+    lines.push('  1. Make a meaningful repo change (`nerviq setup --auto` or `nerviq fix --all-critical --auto`).');
+    lines.push('  2. Run `nerviq audit --snapshot --tag "after-change"` again.');
+  }
+
+  if (goal === 'compare') {
+    lines.push('  Then rerun `nerviq compare`.');
+  } else if (goal === 'trend') {
+    lines.push('  Then rerun `nerviq trend`.');
+  } else {
+    lines.push('  Then rerun `nerviq history`, `nerviq compare`, or `nerviq trend`.');
+  }
+
+  return lines.join('\n');
+}
+
 function formatHistory(dir) {
   const history = getHistory(dir, 10);
-  if (history.length === 0) return 'No snapshots found. Run `npx nerviq --snapshot` to save one.';
+  if (history.length === 0) return formatSnapshotBootstrap(dir, 'history');
 
-  const lines = ['Score history (most recent first):', ''];
+  const lines = [
+    'Audit snapshot history (most recent first):',
+    '  Score type: saved audit snapshot scores only (not live audits or benchmark projections).',
+    '',
+  ];
   for (const entry of history) {
     const dateStr = entry.createdAt || 'unknown';
     const date = dateStr.split('T')[0] || 'unknown';
@@ -290,14 +491,17 @@ function formatHistory(dir) {
     const score = entry.summary?.score ?? '?';
     const passed = entry.summary?.passed ?? '?';
     const total = entry.summary?.checkCount ?? '?';
-    lines.push(`  ${dateDisplay}  ${score}/100  (${passed}/${total} passing)`);
+    lines.push(`  ${dateDisplay}  snapshot${formatSnapshotTags(entry.tags)} ${score}/100  (${passed}/${total} checks passing)`);
   }
 
   const comparison = compareLatest(dir);
   if (comparison) {
     lines.push('');
     const sign = comparison.delta.score >= 0 ? '+' : '';
-    lines.push(`  Trend: ${comparison.trend} (${sign}${comparison.delta.score} since previous)`);
+    lines.push(`  Latest snapshot trend: ${comparison.trend} (${sign}${comparison.delta.score} since previous snapshot)`);
+    if ((comparison.previous.tags || []).length > 0 || (comparison.current.tags || []).length > 0) {
+      lines.push(`  Snapshot tags: previous${formatSnapshotTags(comparison.previous.tags)} -> current${formatSnapshotTags(comparison.current.tags)}`);
+    }
     if (comparison.improvements.length > 0) {
       lines.push(`  Fixed: ${comparison.improvements.join(', ')}`);
     }
@@ -306,6 +510,11 @@ function formatHistory(dir) {
     }
   }
 
+  if (history.length === 1) {
+    lines.push('');
+    lines.push(formatSnapshotBootstrap(dir, 'history'));
+  }
+
   return lines.join('\n');
 }
 
@@ -315,30 +524,31 @@ function exportTrendReport(dir) {
 
   const comparison = compareLatest(dir);
   const lines = [
-    '# Claude Code Setup Trend Report',
+    '# Nerviq Audit Snapshot Trend Report',
     '',
     `**Project:** ${path.basename(dir)}`,
     `**Generated:** ${new Date().toISOString().split('T')[0]}`,
-    `**Snapshots:** ${history.length}`,
+    `**Audit snapshots:** ${history.length}`,
     '',
-    '## Score History',
+    '## Audit Snapshot History',
     '',
-    '| Date | Score | Passed | Checks |',
-    '|------|-------|--------|--------|',
+    '| Date | Tags | Score | Passed | Checks |',
+    '|------|------|-------|--------|--------|',
   ];
 
   for (const entry of history) {
     const date = entry.createdAt?.split('T')[0] || '?';
-    lines.push(`| ${date} | ${entry.summary?.score ?? '?'}/100 | ${entry.summary?.passed ?? '?'} | ${entry.summary?.checkCount ?? '?'} |`);
+    const tags = (entry.tags || []).length > 0 ? entry.tags.join(', ') : '-';
+    lines.push(`| ${date} | ${tags} | ${entry.summary?.score ?? '?'}/100 | ${entry.summary?.passed ?? '?'} | ${entry.summary?.checkCount ?? '?'} |`);
   }
 
   if (comparison) {
     lines.push('');
     lines.push('## Latest Comparison');
     lines.push('');
-    lines.push(`- **Previous:** ${comparison.previous.score}/100 (${comparison.previous.date?.split('T')[0]})`);
-    lines.push(`- **Current:** ${comparison.current.score}/100 (${comparison.current.date?.split('T')[0]})`);
-    lines.push(`- **Delta:** ${comparison.delta.score >= 0 ? '+' : ''}${comparison.delta.score} points`);
+    lines.push(`- **Previous snapshot score:** ${comparison.previous.score}/100 (${comparison.previous.date?.split('T')[0]})${formatSnapshotTags(comparison.previous.tags)}`);
+    lines.push(`- **Current snapshot score:** ${comparison.current.score}/100 (${comparison.current.date?.split('T')[0]})${formatSnapshotTags(comparison.current.tags)}`);
+    lines.push(`- **Snapshot delta:** ${comparison.delta.score >= 0 ? '+' : ''}${comparison.delta.score} points`);
     lines.push(`- **Trend:** ${comparison.trend}`);
     if (comparison.improvements.length > 0) lines.push(`- **Fixed:** ${comparison.improvements.join(', ')}`);
     if (comparison.regressions.length > 0) lines.push(`- **New gaps:** ${comparison.regressions.join(', ')}`);
@@ -572,42 +782,11 @@ function checkHealth(dir) {
 
   const currentResults = currentPayload.results || [];
   const previousResults = previousPayload.results || [];
-
-  // Build maps: key → passed (true/false/null)
-  const prevMap = {};
-  for (const r of previousResults) {
-    if (r.key) prevMap[r.key] = r.passed;
-  }
-  const currMap = {};
-  for (const r of currentResults) {
-    if (r.key) currMap[r.key] = r.passed;
-  }
-
-  const regressions = []; // was passing → now failing
-  const improvements = []; // was failing → now passing
-  const newChecks = []; // not in previous
-  const removedChecks = []; // not in current
-
-  for (const r of currentResults) {
-    if (!r.key) continue;
-    const prev = prevMap[r.key];
-    const curr = r.passed;
-    if (prev === undefined) {
-      if (curr !== null) newChecks.push({ key: r.key, name: r.name, impact: r.impact, passed: curr });
-      continue;
-    }
-    if (prev === true && curr === false) {
-      regressions.push({ key: r.key, name: r.name, impact: r.impact, category: r.category });
-    } else if (prev === false && curr === true) {
-      improvements.push({ key: r.key, name: r.name, impact: r.impact, category: r.category });
-    }
-  }
-
-  for (const r of previousResults) {
-    if (r.key && currMap[r.key] === undefined) {
-      removedChecks.push({ key: r.key, name: r.name });
-    }
-  }
+  const diff = collectCheckDiff(previousResults, currentResults);
+  const regressions = diff.regressions;
+  const improvements = diff.improvements;
+  const newChecks = diff.newChecks;
+  const removedChecks = diff.removedChecks;
 
   // Detect potential platform format changes:
   // If 3+ checks in the same category regressed, flag it
@@ -800,9 +979,12 @@ module.exports = {
   writeActivityArtifact,
   writeRollbackArtifact,
   writeSnapshotArtifact,
+  normalizeSnapshotTags,
+  formatSnapshotTags,
   readSnapshotIndex,
   getHistory,
   compareLatest,
+  formatSnapshotBootstrap,
   formatHistory,
   exportTrendReport,
   readOutcomeIndex,