@nerviq/cli 1.10.0 → 1.12.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.10.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.",
+  "version": "1.12.0",
+  "description": "The intelligent nervous system for AI coding agents — 2,441 checks (8 platforms × ~300 governance rules), 10 languages, 62 domain packs. Audit, align, and amplify.",
   "main": "src/index.js",
   "bin": {
     "nerviq": "bin/cli.js",

package/src/activity.js

@@ -25,6 +25,8 @@ function getUserId() {
 let _lastTimestamp = '';
 let _counter = 0;
 
+const SNAPSHOT_MILESTONES = ['baseline', 'post-fix', 'pre-upgrade', 'release'];
+
 function timestampId() {
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
   if (ts === _lastTimestamp) {
@@ -133,9 +135,66 @@ function summarizeSnapshot(snapshotKind, payload) {
     };
   }
 
+  if (snapshotKind === 'behavioral-drift') {
+    return {
+      score: payload.score,
+      sourceFiles: payload.repoSummary?.sourceFiles ?? 0,
+      findingCount: Array.isArray(payload.findings) ? payload.findings.length : 0,
+      driftLabels: Array.isArray(payload.driftLabels) ? payload.driftLabels.slice(0, 5) : [],
+      utilityShare: payload.structuralSignals?.utilityBalance?.utilityShare ?? null,
+      layerBreaks: payload.structuralSignals?.layering?.count ?? 0,
+    };
+  }
+
   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 normalizeSnapshotMilestone(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const normalized = `${value}`.trim().toLowerCase();
+  if (!SNAPSHOT_MILESTONES.includes(normalized)) {
+    throw new Error(`snapshot milestone must be one of: ${SNAPSHOT_MILESTONES.join(', ')}`);
+  }
+  return normalized;
+}
+
+function formatSnapshotMilestone(value) {
+  const milestone = normalizeSnapshotMilestone(value);
+  if (!milestone) return '';
+  return ` (${milestone})`;
+}
+
 function updateSnapshotIndex(snapshotDir, record) {
   const indexPath = path.join(snapshotDir, 'index.json');
   let entries = [];
@@ -173,6 +232,12 @@ 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 milestone = normalizeSnapshotMilestone(meta.milestone);
+  const { tags: _ignoredTags, tag: _ignoredTag, ...restMeta } = meta;
   const envelope = {
     schemaVersion: 1,
     artifactType: 'snapshot',
@@ -183,7 +248,9 @@ function writeSnapshotArtifact(dir, snapshotKind, payload, meta = {}) {
     generatedBy: `nerviq@${version}`,
     directory: dir,
     summary,
-    ...meta,
+    tags: metaTags,
+    milestone,
+    ...restMeta,
     payload,
   };
 
@@ -194,6 +261,8 @@ function writeSnapshotArtifact(dir, snapshotKind, payload, meta = {}) {
     snapshotKind,
     createdAt: envelope.createdAt,
     relativePath: path.relative(dir, filePath),
+    tags: metaTags,
+    milestone,
     summary,
   };
   updateSnapshotIndex(snapshotDir, record);
@@ -236,6 +305,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 +389,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,26 +398,66 @@ 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 {
     scoreType: 'audit-snapshot-score',
-    current: { date: current.createdAt, score: current.summary?.score, passed: current.summary?.passed, scoreType: 'audit-snapshot-score' },
-    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 || [],
+      milestone: current.milestone || null,
+      scoreType: 'audit-snapshot-score',
+    },
+    previous: {
+      date: previous.createdAt,
+      score: previous.summary?.score,
+      passed: previous.summary?.passed,
+      tags: previous.tags || [],
+      milestone: previous.milestone || null,
+      scoreType: 'audit-snapshot-score',
+    },
     delta,
     regressions,
     improvements,
+    regressionDetails,
+    improvementDetails,
+    newlyApplicableDetails,
+    noLongerApplicableDetails,
+    newChecks,
+    removedChecks,
+    detailedDiffAvailable,
     trend: delta.score > 0 ? 'improving' : delta.score < 0 ? 'regressing' : 'stable',
   };
 }
@@ -303,13 +487,13 @@ function formatSnapshotBootstrap(dir, goal = 'history') {
 
   if (snapshotCount === 0) {
     lines.push('  Bootstrap it with:');
-    lines.push('  1. Run `nerviq audit --snapshot` to save the baseline.');
+    lines.push('  1. Run `nerviq audit --snapshot --milestone baseline --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` again to capture the next state.');
+    lines.push('  3. Run `nerviq audit --snapshot --milestone post-fix --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` again.');
+    lines.push('  2. Run `nerviq audit --snapshot --milestone post-fix --tag "after-change"` again.');
   }
 
   if (goal === 'compare') {
@@ -340,7 +524,7 @@ function formatHistory(dir) {
     const score = entry.summary?.score ?? '?';
     const passed = entry.summary?.passed ?? '?';
     const total = entry.summary?.checkCount ?? '?';
-    lines.push(`  ${dateDisplay}  snapshot ${score}/100  (${passed}/${total} checks passing)`);
+    lines.push(`  ${dateDisplay}  snapshot${formatSnapshotMilestone(entry.milestone)}${formatSnapshotTags(entry.tags)} ${score}/100  (${passed}/${total} checks passing)`);
   }
 
   const comparison = compareLatest(dir);
@@ -348,6 +532,12 @@ function formatHistory(dir) {
     lines.push('');
     const sign = comparison.delta.score >= 0 ? '+' : '';
     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.previous.milestone || comparison.current.milestone) {
+      lines.push(`  Lifecycle: previous${formatSnapshotMilestone(comparison.previous.milestone)} -> current${formatSnapshotMilestone(comparison.current.milestone)}`);
+    }
     if (comparison.improvements.length > 0) {
       lines.push(`  Fixed: ${comparison.improvements.join(', ')}`);
     }
@@ -378,21 +568,23 @@ function exportTrendReport(dir) {
     '',
     '## Audit Snapshot History',
     '',
-    '| Date | Score | Passed | Checks |',
-    '|------|-------|--------|--------|',
+    '| Date | Milestone | 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 milestone = entry.milestone || '-';
+    const tags = (entry.tags || []).length > 0 ? entry.tags.join(', ') : '-';
+    lines.push(`| ${date} | ${milestone} | ${tags} | ${entry.summary?.score ?? '?'}/100 | ${entry.summary?.passed ?? '?'} | ${entry.summary?.checkCount ?? '?'} |`);
   }
 
   if (comparison) {
     lines.push('');
     lines.push('## Latest Comparison');
     lines.push('');
-    lines.push(`- **Previous snapshot score:** ${comparison.previous.score}/100 (${comparison.previous.date?.split('T')[0]})`);
-    lines.push(`- **Current snapshot score:** ${comparison.current.score}/100 (${comparison.current.date?.split('T')[0]})`);
+    lines.push(`- **Previous snapshot score:** ${comparison.previous.score}/100 (${comparison.previous.date?.split('T')[0]})${formatSnapshotMilestone(comparison.previous.milestone)}${formatSnapshotTags(comparison.previous.tags)}`);
+    lines.push(`- **Current snapshot score:** ${comparison.current.score}/100 (${comparison.current.date?.split('T')[0]})${formatSnapshotMilestone(comparison.current.milestone)}${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(', ')}`);
@@ -627,42 +819,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
@@ -855,6 +1016,11 @@ module.exports = {
   writeActivityArtifact,
   writeRollbackArtifact,
   writeSnapshotArtifact,
+  normalizeSnapshotTags,
+  formatSnapshotTags,
+  normalizeSnapshotMilestone,
+  formatSnapshotMilestone,
+  SNAPSHOT_MILESTONES,
   readSnapshotIndex,
   getHistory,
   compareLatest,