@nerviq/cli 1.9.0 → 1.11.0

package/src/techniques.js

@@ -4,8 +4,16 @@
  * Each technique includes: what to check, how to fix, impact level.
  */
 
-const fs = require('fs');
-const path = require('path');
+const fs = require('fs');
+const path = require('path');
+const { collectClaudeDenyRules } = require('./permission-rules');
+const {
+  getClaudeInstructionBundle,
+  hasDocumentedVerificationGuidance,
+  hasDocumentedTestCommand,
+  hasDocumentedLintCommand,
+  hasDocumentedBuildCommand,
+} = require('./instruction-surfaces');
 
 function hasFrontendSignals(ctx) {
   const pkg = ctx.fileContent('package.json') || '';
@@ -444,62 +452,58 @@ const TECHNIQUES = {
   // === QUALITY & TESTING (category: 'quality') ================
   // ============================================================
 
-  verificationLoop: {
-    id: 93,
-    name: 'Verification criteria in CLAUDE.md',
-    check: (ctx) => {
-      const md = ctx.claudeMdContent() || '';
-      return /\b(npm test|yarn test|pnpm test|pytest|go test|make test|npm run lint|yarn lint|npx |ruff |eslint)\b/i.test(md) ||
-        /\b(test command|lint command|build command|verify|run tests|run lint)\b/i.test(md);
-    },
-    impact: 'critical',
-    rating: 5,
-    category: 'quality',
-    fix: 'Add test/lint/build commands to CLAUDE.md so Claude can verify its own work.',
-    template: null
-  },
-
-  testCommand: {
-    id: 93001,
-    name: 'CLAUDE.md contains a test command',
-    check: (ctx) => {
-      const md = ctx.claudeMdContent() || '';
-      return /npm test|pytest|jest|vitest|cargo test|go test|mix test|rspec/.test(md);
-    },
-    impact: 'high',
-    rating: 5,
-    category: 'quality',
-    fix: 'Add an explicit test command to CLAUDE.md (e.g. "Run `npm test` before committing").',
-    template: null
-  },
-
-  lintCommand: {
-    id: 93002,
-    name: 'CLAUDE.md contains a lint command',
-    check: (ctx) => {
-      const md = ctx.claudeMdContent() || '';
-      return /eslint|prettier|ruff|black|clippy|golangci-lint|rubocop|npm run lint|yarn lint|pnpm lint|bun lint/.test(md);
-    },
-    impact: 'high',
-    rating: 4,
-    category: 'quality',
-    fix: 'Add a lint command to CLAUDE.md so Claude auto-formats and checks code style.',
-    template: null
-  },
-
-  buildCommand: {
-    id: 93003,
-    name: 'CLAUDE.md contains a build command',
-    check: (ctx) => {
-      const md = ctx.claudeMdContent() || '';
-      return /npm run build|cargo build|go build|make|tsc|gradle build|mvn compile/.test(md);
-    },
-    impact: 'medium',
-    rating: 4,
-    category: 'quality',
-    fix: 'Add a build command to CLAUDE.md so Claude can verify compilation before committing.',
-    template: null
-  },
+  verificationLoop: {
+    id: 93,
+    name: 'Claude instruction surfaces include verification criteria',
+    check: (ctx) => {
+      const docs = getClaudeInstructionBundle(ctx);
+      return hasDocumentedVerificationGuidance(docs);
+    },
+    impact: 'critical',
+    rating: 5,
+    category: 'quality',
+    fix: 'Add canonical test/lint/build commands to your Claude instruction surfaces (CLAUDE.md, imported docs, or .claude/commands) so Claude can verify its own work.',
+    template: null
+  },
+
+  testCommand: {
+    id: 93001,
+    name: 'Claude instruction surfaces include a test command',
+    check: (ctx) => {
+      return hasDocumentedTestCommand(getClaudeInstructionBundle(ctx));
+    },
+    impact: 'high',
+    rating: 5,
+    category: 'quality',
+    fix: 'Add an explicit test command to your Claude instruction surfaces (for example "Run `npm test` before committing").',
+    template: null
+  },
+
+  lintCommand: {
+    id: 93002,
+    name: 'Claude instruction surfaces include a lint command',
+    check: (ctx) => {
+      return hasDocumentedLintCommand(getClaudeInstructionBundle(ctx));
+    },
+    impact: 'high',
+    rating: 4,
+    category: 'quality',
+    fix: 'Add a lint command to your Claude instruction surfaces so Claude can check style and static quality automatically.',
+    template: null
+  },
+
+  buildCommand: {
+    id: 93003,
+    name: 'Claude instruction surfaces include a build command',
+    check: (ctx) => {
+      return hasDocumentedBuildCommand(getClaudeInstructionBundle(ctx));
+    },
+    impact: 'medium',
+    rating: 4,
+    category: 'quality',
+    fix: 'Add a build command to your Claude instruction surfaces so Claude can verify compilation before committing.',
+    template: null
+  },
 
   // ============================================================
   // === GIT SAFETY (category: 'git') ===========================
@@ -557,19 +561,19 @@ const TECHNIQUES = {
     template: null
   },
 
-  noSecretsInClaude: {
-    id: 1039,
-    name: 'CLAUDE.md has no embedded API keys',
-    check: (ctx) => {
-      const md = ctx.claudeMdContent() || '';
-      return !containsEmbeddedSecret(md);
-    },
-    impact: 'critical',
-    rating: 5,
-    category: 'git',
-    fix: 'Remove API keys from CLAUDE.md. Use environment variables or .env files instead.',
-    template: null
-  },
+  noSecretsInClaude: {
+    id: 1039,
+    name: 'CLAUDE.md has no embedded secrets',
+    check: (ctx) => {
+      const md = ctx.claudeMdContent() || '';
+      return !containsEmbeddedSecret(md);
+    },
+    impact: 'critical',
+    rating: 5,
+    category: 'git',
+    fix: 'Remove hardcoded secrets, tokens, private keys, and connection strings from CLAUDE.md. Use environment variables or external secret stores instead.',
+    template: null
+  },
 
   // ============================================================
   // === WORKFLOW (category: 'workflow') =========================
@@ -714,16 +718,13 @@ const TECHNIQUES = {
     template: null
   },
 
-  permissionDeny: {
-    id: 2401,
-    name: 'Deny rules configured in permissions',
-    check: (ctx) => {
-      const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      if (!settings || !settings.permissions) return false;
-      const deny = settings.permissions.deny;
-      return Array.isArray(deny) && deny.length > 0;
-    },
-    impact: 'high',
+  permissionDeny: {
+    id: 2401,
+    name: 'Deny rules configured in permissions',
+    check: (ctx) => {
+      return collectClaudeDenyRules(ctx).length > 0;
+    },
+    impact: 'high',
     rating: 5,
     category: 'security',
     fix: 'Add permissions.deny rules to block dangerous operations (e.g. rm -rf, dropping databases).',
@@ -751,18 +752,19 @@ const TECHNIQUES = {
     template: null
   },
 
-  secretsProtection: {
-    id: 1096,
-    name: 'Secrets protection configured',
-    check: (ctx) => {
-      // Prefer shared settings.json (committed) over local override
-      const settings = ctx.jsonFile('.claude/settings.json') || ctx.jsonFile('.claude/settings.local.json');
-      if (!settings || !settings.permissions) return false;
-      const deny = JSON.stringify(settings.permissions.deny || []);
-      const hasDeny = deny.includes('.env') || deny.includes('secrets');
-      // Fail if allow includes "*" (overly broad — bypasses deny rules)
-      const allow = settings.permissions.allow || [];
-      if (Array.isArray(allow) && allow.includes('*')) return false;
+  secretsProtection: {
+    id: 1096,
+    name: 'Secrets protection configured',
+    check: (ctx) => {
+      const shared = ctx.jsonFile('.claude/settings.json');
+      const local = ctx.jsonFile('.claude/settings.local.json');
+      const settings = shared || local;
+      if (!settings || !settings.permissions) return false;
+      const denyRules = collectClaudeDenyRules(ctx);
+      const hasDeny = denyRules.some((rule) => rule.protectsSecrets);
+      // Fail if allow includes "*" (overly broad — bypasses deny rules)
+      const allow = settings.permissions.allow || [];
+      if (Array.isArray(allow) && allow.includes('*')) return false;
       return hasDeny;
     },
     impact: 'critical',
@@ -1524,16 +1526,13 @@ const TECHNIQUES = {
     template: null
   },
 
-  denyRulesDepth: {
-    id: 2014,
-    name: 'Deny rules cover 3+ patterns',
-    check: (ctx) => {
-      const shared = ctx.jsonFile('.claude/settings.json');
-      const local = ctx.jsonFile('.claude/settings.local.json');
-      const deny = (shared?.permissions?.deny || []).concat(local?.permissions?.deny || []);
-      return deny.length >= 3;
-    },
-    impact: 'high', rating: 4, category: 'security',
+  denyRulesDepth: {
+    id: 2014,
+    name: 'Deny rules cover 3+ patterns',
+    check: (ctx) => {
+      return collectClaudeDenyRules(ctx).length >= 3;
+    },
+    impact: 'high', rating: 4, category: 'security',
     fix: 'Add at least 3 deny rules: rm -rf, force-push, and .env reads. More patterns = safer Claude.',
     template: null
   },

package/src/terminology.js

@@ -0,0 +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,
+};

package/src/token-estimate.js

@@ -0,0 +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,
+};

package/src/workspace.js

@@ -166,6 +166,115 @@ function parseWorkspaceSelection(value) {
   return unique(String(value).split(',').map((item) => item.trim()).filter(Boolean));
 }
 
+function summarizeAuditResult(result, scoreType, scope) {
+  return {
+    scope,
+    scoreType,
+    score: typeof result?.score === 'number' ? result.score : null,
+    passed: typeof result?.passed === 'number' ? result.passed : 0,
+    total: typeof result?.checkCount === 'number' ? result.checkCount : 0,
+    topAction: result?.topNextActions?.[0]?.name || null,
+  };
+}
+
+function summarizeWorkspaceEntry(result, workspacePath, absPath, platform) {
+  const stackKeys = (result.stacks || []).map((item) => item.key);
+  const stackLabels = (result.stacks || []).map((item) => item.label);
+  return {
+    name: path.basename(workspacePath),
+    workspace: workspacePath,
+    dir: absPath,
+    platform,
+    stackKeys,
+    stackLabels,
+    workspaceProfile: classifyWorkspaceProfile(stackKeys),
+    ...summarizeAuditResult(result, 'workspace-live-audit', 'workspace-package'),
+  };
+}
+
+function classifyWorkspaceProfile(stackKeys) {
+  const keys = new Set(Array.isArray(stackKeys) ? stackKeys : []);
+  const matchAny = (candidates) => candidates.some((candidate) => keys.has(candidate));
+
+  if (matchAny(['go'])) {
+    return { key: 'go-workspace', label: 'Go workspace' };
+  }
+  if (matchAny(['python', 'django', 'fastapi'])) {
+    return { key: 'python-workspace', label: 'Python workspace' };
+  }
+  if (matchAny(['dotnet'])) {
+    return { key: 'dotnet-workspace', label: '.NET workspace' };
+  }
+  if (matchAny(['java', 'spring'])) {
+    return { key: 'java-workspace', label: 'Java workspace' };
+  }
+  if (matchAny(['flutter', 'dart'])) {
+    return { key: 'flutter-workspace', label: 'Flutter workspace' };
+  }
+  if (matchAny(['swift'])) {
+    return { key: 'swift-workspace', label: 'Swift workspace' };
+  }
+  if (matchAny(['kotlin'])) {
+    return { key: 'kotlin-workspace', label: 'Kotlin workspace' };
+  }
+  if (matchAny(['react', 'nextjs', 'node', 'typescript', 'javascript', 'nestjs', 'vue', 'angular', 'svelte'])) {
+    return { key: 'node-workspace', label: 'Node / JS workspace' };
+  }
+
+  return { key: 'general-workspace', label: 'General workspace' };
+}
+
+function buildProfileBreakdown(results) {
+  const grouped = new Map();
+
+  for (const item of results) {
+    const profileKey = item.workspaceProfile?.key || 'general-workspace';
+    const profileLabel = item.workspaceProfile?.label || 'General workspace';
+    if (!grouped.has(profileKey)) {
+      grouped.set(profileKey, {
+        profileKey,
+        profileLabel,
+        scoreType: 'workspace-live-audit',
+        workspaceCount: 0,
+        workspaces: [],
+        stackLabels: new Set(),
+        scores: [],
+        totals: [],
+      });
+    }
+
+    const entry = grouped.get(profileKey);
+    entry.workspaceCount += 1;
+    entry.workspaces.push(item.workspace);
+    for (const label of item.stackLabels || []) {
+      entry.stackLabels.add(label);
+    }
+    if (typeof item.score === 'number') {
+      entry.scores.push(item.score);
+    }
+    if (typeof item.total === 'number') {
+      entry.totals.push(item.total);
+    }
+  }
+
+  return [...grouped.values()]
+    .map((entry) => ({
+      profileKey: entry.profileKey,
+      profileLabel: entry.profileLabel,
+      scoreType: 'workspace-live-audit',
+      workspaceCount: entry.workspaceCount,
+      averageScore: entry.scores.length > 0
+        ? Math.round(entry.scores.reduce((sum, value) => sum + value, 0) / entry.scores.length)
+        : 0,
+      averageTotal: entry.totals.length > 0
+        ? Math.round(entry.totals.reduce((sum, value) => sum + value, 0) / entry.totals.length)
+        : 0,
+      stackLabels: [...entry.stackLabels].sort(),
+      workspaces: entry.workspaces.sort(),
+    }))
+    .sort((left, right) => left.profileLabel.localeCompare(right.profileLabel));
+}
+
 async function auditWorkspaces(dir, workspaceGlobs, platform = 'claude') {
   const { audit } = require('./audit');
   const rootDir = path.resolve(dir);
@@ -175,32 +284,43 @@ async function auditWorkspaces(dir, workspaceGlobs, platform = 'claude') {
     ? expandWorkspacePatterns(rootDir, selectedPatterns)
     : detectWorkspaces(rootDir);
   const results = [];
+  let rootGovernance;
+
+  try {
+    const rootResult = await audit({ dir: rootDir, platform, silent: true });
+    rootGovernance = summarizeAuditResult(rootResult, 'root-live-audit', 'root-governance');
+  } catch (error) {
+    rootGovernance = {
+      scope: 'root-governance',
+      scoreType: 'root-live-audit',
+      score: null,
+      passed: 0,
+      total: 0,
+      topAction: null,
+      error: error.message,
+    };
+  }
 
   for (const workspacePath of workspacePaths) {
     const absPath = path.join(rootDir, workspacePath);
     try {
       const result = await audit({ dir: absPath, platform, silent: true });
-      results.push({
-        name: path.basename(workspacePath),
-        workspace: workspacePath,
-        dir: absPath,
-        platform,
-        score: result.score,
-        passed: result.passed,
-        total: result.checkCount,
-        topAction: result.topNextActions?.[0]?.name || null,
-        result,
-      });
+      results.push(summarizeWorkspaceEntry(result, workspacePath, absPath, platform));
     } catch (error) {
       results.push({
         name: path.basename(workspacePath),
         workspace: workspacePath,
         dir: absPath,
         platform,
+        scope: 'workspace-package',
+        scoreType: 'workspace-live-audit',
         score: null,
         passed: 0,
         total: 0,
         topAction: null,
+        stackKeys: [],
+        stackLabels: [],
+        workspaceProfile: { key: 'general-workspace', label: 'General workspace' },
         error: error.message,
       });
     }
@@ -210,17 +330,39 @@ async function auditWorkspaces(dir, workspaceGlobs, platform = 'claude') {
   const averageScore = validScores.length > 0
     ? Math.round(validScores.reduce((sum, value) => sum + value, 0) / validScores.length)
     : 0;
+  const maxScore = validScores.length > 0 ? Math.max(...validScores) : 0;
+  const minScore = validScores.length > 0 ? Math.min(...validScores) : 0;
+  const profileBreakdown = buildProfileBreakdown(results);
 
   return {
+    summaryType: 'monorepo-workspace-audit',
     rootDir,
     platform,
+    selectionMode: selectedPatterns.length > 0 ? 'explicit-patterns' : 'detected-workspaces',
     patterns: sourcePatterns,
+    rootGovernance,
+    workspaceAggregate: {
+      scope: 'workspace-aggregate',
+      scoreType: 'workspace-average-live-audit',
+      score: averageScore,
+      workspaceCount: workspacePaths.length,
+      maxScore,
+      minScore,
+    },
+    profileBreakdown,
+    scoreSemantics: {
+      rootGovernance: 'Root repo live audit for shared instructions, hooks, permissions, and top-level governance files.',
+      workspaceAggregate: 'Average of the selected workspace live audit scores. This is a package coverage rollup, not the root repo score.',
+      workspaceEntries: 'Each workspace row is a package-level live audit. Package scores can differ from the root governance score for legitimate reasons.',
+      workspaceProfiles: 'Workspace totals can differ because each package uses a stack-specific check profile based on detected languages and frameworks.',
+    },
     workspaces: results,
     detectedWorkspaces: workspacePaths,
     workspaceCount: workspacePaths.length,
+    averageScoreType: 'workspace-average-live-audit',
     averageScore,
-    maxScore: validScores.length > 0 ? Math.max(...validScores) : 0,
-    minScore: validScores.length > 0 ? Math.min(...validScores) : 0,
+    maxScore,
+    minScore,
   };
 }