claudex-setup 1.16.0 → 1.16.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claudex-setup",
-  "version": "1.16.0",
-  "description": "Score your repo's Claude Code setup against 84 checks. See gaps, apply fixes selectively with rollback, govern hooks and permissions, and benchmark impact — without breaking existing config.",
+  "version": "1.16.1",
+  "description": "Score your repo's Claude Code setup against 85 checks. See gaps, apply fixes selectively with rollback, govern hooks and permissions, and benchmark impact — without breaking existing config.",
   "main": "src/index.js",
   "bin": {
     "claudex-setup": "bin/cli.js"

package/src/activity.js

@@ -21,10 +21,12 @@ function ensureArtifactDirs(dir) {
   const activityDir = path.join(root, 'activity');
   const rollbackDir = path.join(root, 'rollbacks');
   const snapshotDir = path.join(root, 'snapshots');
+  const outcomesDir = path.join(root, 'outcomes');
   fs.mkdirSync(activityDir, { recursive: true });
   fs.mkdirSync(rollbackDir, { recursive: true });
   fs.mkdirSync(snapshotDir, { recursive: true });
-  return { root, activityDir, rollbackDir, snapshotDir };
+  fs.mkdirSync(outcomesDir, { recursive: true });
+  return { root, activityDir, rollbackDir, snapshotDir, outcomesDir };
 }
 
 function writeJson(filePath, payload) {
@@ -322,6 +324,192 @@ function exportTrendReport(dir) {
   return lines.join('\n');
 }
 
+function readOutcomeIndex(dir) {
+  const indexPath = path.join(dir, '.claude', 'claudex-setup', 'outcomes', 'index.json');
+  if (!fs.existsSync(indexPath)) return [];
+  try {
+    const entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+    return Array.isArray(entries) ? entries : [];
+  } catch {
+    return [];
+  }
+}
+
+function updateOutcomeIndex(outcomesDir, record) {
+  const indexPath = path.join(outcomesDir, 'index.json');
+  let entries = [];
+
+  if (fs.existsSync(indexPath)) {
+    try {
+      entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+      if (!Array.isArray(entries)) entries = [];
+    } catch {
+      entries = [];
+    }
+  }
+
+  entries.push(record);
+  const MAX_INDEX_ENTRIES = 500;
+  if (entries.length > MAX_INDEX_ENTRIES) {
+    entries = entries.slice(entries.length - MAX_INDEX_ENTRIES);
+  }
+  fs.writeFileSync(indexPath, JSON.stringify(entries, null, 2), 'utf8');
+}
+
+function normalizeOutcomeStatus(value) {
+  const normalized = `${value || ''}`.trim().toLowerCase();
+  if (!['accepted', 'rejected', 'deferred'].includes(normalized)) {
+    throw new Error('feedback status must be one of: accepted, rejected, deferred');
+  }
+  return normalized;
+}
+
+function normalizeOutcomeEffect(value) {
+  const normalized = `${value || ''}`.trim().toLowerCase();
+  if (!['positive', 'neutral', 'negative'].includes(normalized)) {
+    throw new Error('feedback effect must be one of: positive, neutral, negative');
+  }
+  return normalized;
+}
+
+function recordRecommendationOutcome(dir, payload) {
+  const key = `${payload.key || ''}`.trim();
+  if (!key) {
+    throw new Error('feedback requires a recommendation key');
+  }
+
+  const status = normalizeOutcomeStatus(payload.status);
+  const effect = normalizeOutcomeEffect(payload.effect || 'neutral');
+  const scoreDelta = Number.isFinite(payload.scoreDelta) ? payload.scoreDelta : (
+    payload.scoreDelta === null || payload.scoreDelta === undefined || payload.scoreDelta === ''
+      ? null
+      : Number(payload.scoreDelta)
+  );
+
+  if (scoreDelta !== null && !Number.isFinite(scoreDelta)) {
+    throw new Error('feedback scoreDelta must be a number when provided');
+  }
+
+  const id = timestampId();
+  const { outcomesDir } = ensureArtifactDirs(dir);
+  const filePath = path.join(outcomesDir, `${id}.json`);
+  const record = {
+    id,
+    createdAt: new Date().toISOString(),
+    key,
+    status,
+    effect,
+    source: `${payload.source || 'manual-cli'}`.trim() || 'manual-cli',
+    notes: `${payload.notes || ''}`.trim(),
+    scoreDelta,
+  };
+
+  writeJson(filePath, record);
+  updateOutcomeIndex(outcomesDir, {
+    ...record,
+    relativePath: path.relative(dir, filePath),
+  });
+
+  return {
+    id,
+    filePath,
+    relativePath: path.relative(dir, filePath),
+    record,
+  };
+}
+
+function summarizeOutcomeEntries(entries = []) {
+  const byKey = {};
+
+  for (const entry of entries) {
+    if (!entry || !entry.key) continue;
+    const bucket = byKey[entry.key] || {
+      key: entry.key,
+      total: 0,
+      accepted: 0,
+      rejected: 0,
+      deferred: 0,
+      positive: 0,
+      neutral: 0,
+      negative: 0,
+      scoreDeltaTotal: 0,
+      scoreDeltaCount: 0,
+      latestAt: null,
+    };
+
+    bucket.total += 1;
+    if (bucket[entry.status] !== undefined) bucket[entry.status] += 1;
+    if (bucket[entry.effect] !== undefined) bucket[entry.effect] += 1;
+    if (Number.isFinite(entry.scoreDelta)) {
+      bucket.scoreDeltaTotal += entry.scoreDelta;
+      bucket.scoreDeltaCount += 1;
+    }
+    if (!bucket.latestAt || new Date(entry.createdAt) > new Date(bucket.latestAt)) {
+      bucket.latestAt = entry.createdAt;
+    }
+
+    byKey[entry.key] = bucket;
+  }
+
+  for (const bucket of Object.values(byKey)) {
+    bucket.avgScoreDelta = bucket.scoreDeltaCount > 0
+      ? Number((bucket.scoreDeltaTotal / bucket.scoreDeltaCount).toFixed(2))
+      : null;
+    bucket.evidenceClass = bucket.total > 0 ? 'measured' : 'estimated';
+  }
+
+  return {
+    totalEntries: entries.length,
+    byKey,
+    keys: Object.keys(byKey).sort(),
+  };
+}
+
+function getRecommendationOutcomeSummary(dir) {
+  return summarizeOutcomeEntries(readOutcomeIndex(dir));
+}
+
+function getRecommendationAdjustment(summaryByKey, key) {
+  const bucket = summaryByKey && summaryByKey[key];
+  if (!bucket) return 0;
+
+  let adjustment = 0;
+  adjustment += bucket.accepted * 2;
+  adjustment += bucket.positive * 3;
+  adjustment -= bucket.rejected * 3;
+  adjustment -= bucket.negative * 4;
+
+  if (Number.isFinite(bucket.avgScoreDelta)) {
+    if (bucket.avgScoreDelta > 0) adjustment += Math.min(4, Math.round(bucket.avgScoreDelta / 4));
+    if (bucket.avgScoreDelta < 0) adjustment -= Math.min(4, Math.round(Math.abs(bucket.avgScoreDelta) / 4));
+  }
+
+  if (adjustment > 8) return 8;
+  if (adjustment < -8) return -8;
+  return adjustment;
+}
+
+function formatRecommendationOutcomeSummary(dir) {
+  const summary = getRecommendationOutcomeSummary(dir);
+  if (summary.totalEntries === 0) {
+    return 'No recommendation outcomes recorded yet. Use `npx claudex-setup feedback --key permissionDeny --status accepted --effect positive` after a real run.';
+  }
+
+  const lines = [
+    'Recommendation outcome summary:',
+    '',
+  ];
+
+  for (const key of summary.keys) {
+    const bucket = summary.byKey[key];
+    const avg = Number.isFinite(bucket.avgScoreDelta) ? ` | avg score delta ${bucket.avgScoreDelta >= 0 ? '+' : ''}${bucket.avgScoreDelta}` : '';
+    const adjustment = getRecommendationAdjustment(summary.byKey, key);
+    lines.push(`  ${key}: total ${bucket.total} | accepted ${bucket.accepted} | rejected ${bucket.rejected} | deferred ${bucket.deferred} | positive ${bucket.positive} | negative ${bucket.negative}${avg} | ranking ${adjustment >= 0 ? '+' : ''}${adjustment}`);
+  }
+
+  return lines.join('\n');
+}
+
 module.exports = {
   ensureArtifactDirs,
   writeActivityArtifact,
@@ -332,4 +520,10 @@ module.exports = {
   compareLatest,
   formatHistory,
   exportTrendReport,
+  readOutcomeIndex,
+  recordRecommendationOutcome,
+  summarizeOutcomeEntries,
+  getRecommendationOutcomeSummary,
+  getRecommendationAdjustment,
+  formatRecommendationOutcomeSummary,
 };

package/src/analyze.js

@@ -244,12 +244,15 @@ function toGaps(results) {
 }
 
 function toRecommendations(auditResult) {
-  const failed = auditResult.results
-    .filter(r => r.passed === false)
-    .sort((a, b) => {
-      const order = { critical: 3, high: 2, medium: 1, low: 0 };
-      return (order[b.impact] || 0) - (order[a.impact] || 0);
-    });
+  const failed = auditResult.results.filter(r => r.passed === false);
+  const topActionOrder = new Map((auditResult.topNextActions || []).map((item, index) => [item.key, index]));
+  failed.sort((a, b) => {
+    const rankedA = topActionOrder.has(a.key) ? topActionOrder.get(a.key) : Number.MAX_SAFE_INTEGER;
+    const rankedB = topActionOrder.has(b.key) ? topActionOrder.get(b.key) : Number.MAX_SAFE_INTEGER;
+    if (rankedA !== rankedB) return rankedA - rankedB;
+    const order = { critical: 3, high: 2, medium: 1, low: 0 };
+    return (order[b.impact] || 0) - (order[a.impact] || 0);
+  });
 
   return failed.slice(0, 10).map((r, index) => ({
     priority: index + 1,
@@ -259,6 +262,8 @@ function toRecommendations(auditResult) {
     module: moduleFromCategory(r.category),
     risk: riskFromImpact(r.impact),
     why: r.fix,
+    evidenceClass: (auditResult.topNextActions || []).find(item => item.key === r.key)?.evidenceClass || 'estimated',
+    rankingAdjustment: (auditResult.topNextActions || []).find(item => item.key === r.key)?.rankingAdjustment || 0,
   }));
 }
 

package/src/audit.js

@@ -6,6 +6,7 @@ const { TECHNIQUES, STACKS } = require('./techniques');
 const { ProjectContext } = require('./context');
 const { getBadgeMarkdown } = require('./badge');
 const { sendInsights, getLocalInsights } = require('./insights');
+const { getRecommendationOutcomeSummary, getRecommendationAdjustment } = require('./activity');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -98,18 +99,35 @@ function getQuickWins(failed) {
     .slice(0, 3);
 }
 
-function buildTopNextActions(failed, limit = 5) {
+function getRecommendationPriorityScore(item, outcomeSummaryByKey = {}) {
+  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;
+}
+
+function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}) {
   const pool = getPrioritizedFailed(failed);
 
   return [...pool]
     .sort((a, b) => {
-      const impactA = IMPACT_ORDER[a.impact] ?? 0;
-      const impactB = IMPACT_ORDER[b.impact] ?? 0;
-      if (impactA !== impactB) return impactB - impactA;
-      return (a.fix || '').length - (b.fix || '').length;
+      return getRecommendationPriorityScore(b, outcomeSummaryByKey) - getRecommendationPriorityScore(a, outcomeSummaryByKey);
     })
     .slice(0, limit)
-    .map(({ key, name, impact, fix, category }) => ({
+    .map(({ key, name, impact, fix, category }) => {
+      const feedback = outcomeSummaryByKey[key] || null;
+      const rankingAdjustment = getRecommendationAdjustment(outcomeSummaryByKey, key);
+      const signals = [
+        `failed-check:${key}`,
+        `impact:${impact}`,
+        `category:${category}`,
+      ];
+      if (feedback) {
+        signals.push(`feedback:${feedback.total}`);
+        signals.push(`ranking-adjustment:${rankingAdjustment >= 0 ? '+' : ''}${rankingAdjustment}`);
+      }
+
+      return ({
       key,
       name,
       impact,
@@ -119,12 +137,20 @@ function buildTopNextActions(failed, limit = 5) {
       why: ACTION_RATIONALES[key] || fix,
       risk: riskFromImpact(impact),
       confidence: confidenceFromImpact(impact),
-      signals: [
-        `failed-check:${key}`,
-        `impact:${impact}`,
-        `category:${category}`,
-      ],
-    }));
+      signals,
+      evidenceClass: feedback ? 'measured' : 'estimated',
+      rankingAdjustment,
+      feedback: feedback ? {
+        total: feedback.total,
+        accepted: feedback.accepted,
+        rejected: feedback.rejected,
+        deferred: feedback.deferred,
+        positive: feedback.positive,
+        negative: feedback.negative,
+        avgScoreDelta: feedback.avgScoreDelta,
+      } : null,
+    });
+    });
 }
 
 function inferSuggestedNextCommand(result) {
@@ -194,6 +220,7 @@ async function audit(options) {
   const ctx = new ProjectContext(options.dir);
   const stacks = ctx.detectStacks(STACKS);
   const results = [];
+  const outcomeSummary = getRecommendationOutcomeSummary(options.dir);
 
   // Run all technique checks
   for (const [key, technique] of Object.entries(TECHNIQUES)) {
@@ -235,7 +262,7 @@ 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);
-  const topNextActions = buildTopNextActions(failed, 5);
+  const topNextActions = buildTopNextActions(failed, 5, outcomeSummary.byKey);
   const result = {
     score,
     organicScore,
@@ -248,6 +275,10 @@ async function audit(options) {
     results,
     quickWins: quickWins.map(({ key, name, impact, fix, category }) => ({ key, name, impact, category, fix })),
     topNextActions,
+    recommendationOutcomes: {
+      totalEntries: outcomeSummary.totalEntries,
+      keysTracked: outcomeSummary.keys,
+    },
   };
   result.suggestedNextCommand = inferSuggestedNextCommand(result);
   result.liteSummary = {
@@ -344,6 +375,10 @@ async function audit(options) {
       console.log(colorize(`        Why: ${item.why}`, 'dim'));
       console.log(colorize(`        Trace: ${item.signals.join(' | ')}`, 'dim'));
       console.log(colorize(`        Risk: ${item.risk} | Confidence: ${item.confidence}`, 'dim'));
+      if (item.feedback) {
+        const avgDelta = Number.isFinite(item.feedback.avgScoreDelta) ? ` | Avg score delta: ${item.feedback.avgScoreDelta >= 0 ? '+' : ''}${item.feedback.avgScoreDelta}` : '';
+        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('');
@@ -382,4 +417,4 @@ async function audit(options) {
   return result;
 }
 
-module.exports = { audit };
+module.exports = { audit, buildTopNextActions };

package/src/context.js

@@ -14,6 +14,7 @@ class ProjectContext {
     this.dir = dir;
     this.files = [];
     this._cache = {};
+    this._dependencyCache = null;
     this._scan();
   }
 
@@ -107,6 +108,52 @@ class ProjectContext {
     }
   }
 
+  projectDependencies() {
+    if (this._dependencyCache) return this._dependencyCache;
+
+    const deps = {};
+    const addDependency = (name, source) => {
+      if (!name) return;
+      const normalized = `${name}`.trim().toLowerCase().replace(/\[.*\]$/, '');
+      if (!normalized || normalized === 'python') return;
+      if (!deps[normalized]) {
+        deps[normalized] = source || true;
+      }
+    };
+
+    const pkg = this.jsonFile('package.json') || {};
+    for (const source of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
+      for (const name of Object.keys(pkg[source] || {})) {
+        addDependency(name, 'package.json');
+      }
+    }
+
+    const pyproject = this.fileContent('pyproject.toml') || '';
+    for (const name of extractPyprojectDependencies(pyproject)) {
+      addDependency(name, 'pyproject.toml');
+    }
+
+    const requirementFiles = [
+      'requirements.txt',
+      'requirements-dev.txt',
+      'requirements-dev.in',
+      'requirements-prod.txt',
+      'requirements/base.txt',
+      'requirements/dev.txt',
+      'requirements/test.txt',
+    ];
+    for (const filePath of requirementFiles) {
+      const content = this.fileContent(filePath);
+      if (!content) continue;
+      for (const name of extractRequirementsDependencies(content)) {
+        addDependency(name, filePath);
+      }
+    }
+
+    this._dependencyCache = deps;
+    return deps;
+  }
+
   detectStacks(STACKS) {
     const detected = [];
     for (const [key, stack] of Object.entries(STACKS)) {
@@ -132,4 +179,63 @@ class ProjectContext {
   }
 }
 
+function extractPyprojectDependencies(content) {
+  if (!content) return [];
+
+  const deps = new Set();
+  const add = (value) => {
+    if (!value) return;
+    deps.add(value.trim().toLowerCase().replace(/\[.*\]$/, ''));
+  };
+
+  const extractSection = (sectionName) => {
+    const escaped = sectionName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`\\[${escaped}\\]([\\s\\S]*?)(?:\\n\\s*\\[|$)`);
+    const match = content.match(pattern);
+    return match ? match[1] : '';
+  };
+
+  const poetryDeps = extractSection('tool.poetry.dependencies');
+  for (const match of poetryDeps.matchAll(/^\s*([A-Za-z0-9_.-]+)\s*=/gm)) {
+    add(match[1]);
+  }
+
+  const projectDeps = extractSection('project');
+  const projectDepsArrayMatch = projectDeps.match(/dependencies\s*=\s*\[([\s\S]*?)\]/m);
+  if (projectDepsArrayMatch) {
+    for (const item of projectDepsArrayMatch[1].matchAll(/["']([^"']+)["']/g)) {
+      const name = item[1].split(/[<>=!~ ]/)[0];
+      add(name);
+    }
+  }
+
+  const optionalDepsSection = extractSection('project.optional-dependencies');
+  for (const item of optionalDepsSection.matchAll(/["']([^"']+)["']/g)) {
+    const name = item[1].split(/[<>=!~ ]/)[0];
+    add(name);
+  }
+
+  const dependencyGroupsSection = extractSection('dependency-groups');
+  for (const item of dependencyGroupsSection.matchAll(/["']([^"']+)["']/g)) {
+    const name = item[1].split(/[<>=!~ ]/)[0];
+    add(name);
+  }
+
+  return [...deps].filter(Boolean);
+}
+
+function extractRequirementsDependencies(content) {
+  if (!content) return [];
+
+  const deps = new Set();
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.replace(/#.*$/, '').trim();
+    if (!line || line.startsWith('-')) continue;
+    const match = line.match(/^([A-Za-z0-9_.-]+)/);
+    if (!match) continue;
+    deps.add(match[1].toLowerCase().replace(/\[.*\]$/, ''));
+  }
+  return [...deps];
+}
+
 module.exports = { ProjectContext };