iikit-dashboard 1.2.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iikit-dashboard",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Real-time dashboard for Intent Integrity Kit (IIKit) — visualizes every phase of specification-driven AI development",
   "main": "src/server.js",
   "bin": {
@@ -26,7 +26,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/intent-integrity-chain/iikit-dashboard"
+    "url": "git+https://github.com/intent-integrity-chain/iikit-dashboard.git"
   },
   "author": "Baruch Sadogursky",
   "license": "MIT",

package/src/analyze.js

@@ -0,0 +1,244 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  parseAnalysisFindings,
+  parseAnalysisCoverage,
+  parseAnalysisMetrics,
+  parseConstitutionAlignment,
+  parsePhaseSeparation,
+  parseRequirements,
+  parseSuccessCriteria
+} = require('./parser');
+
+const SEVERITY_PENALTIES = { CRITICAL: 25, HIGH: 15, MEDIUM: 5, LOW: 2 };
+
+/**
+ * Compute phase separation score from violation entries.
+ * Score = max(0, 100 - sum(penalties)).
+ *
+ * @param {Array<{severity: string}>} violations
+ * @returns {number}
+ */
+function computePhaseSeparationScore(violations) {
+  if (!violations || violations.length === 0) return 100;
+
+  const penalty = violations.reduce((sum, v) => {
+    return sum + (SEVERITY_PENALTIES[v.severity] || 0);
+  }, 0);
+
+  return Math.max(0, 100 - penalty);
+}
+
+/**
+ * Compute constitution compliance percentage from alignment entries.
+ * (ALIGNED count / total) * 100, rounded.
+ *
+ * @param {Array<{status: string}>} entries
+ * @returns {number}
+ */
+function computeConstitutionCompliance(entries) {
+  if (!entries || entries.length === 0) return 100;
+
+  const aligned = entries.filter(e => e.status === 'ALIGNED').length;
+  return Math.round((aligned / entries.length) * 100);
+}
+
+/**
+ * Compute health score from four factors (25% each).
+ *
+ * @param {{requirementsCoverage: number, constitutionCompliance: number, phaseSeparation: number, testCoverage: number}} factors
+ * @returns {{score: number, zone: string, factors: Object}}
+ */
+function computeHealthScore(factors) {
+  const { requirementsCoverage, constitutionCompliance, phaseSeparation, testCoverage } = factors;
+
+  const score = Math.round(
+    (requirementsCoverage + constitutionCompliance + phaseSeparation + testCoverage) / 4
+  );
+
+  let zone;
+  if (score <= 40) zone = 'red';
+  else if (score <= 70) zone = 'yellow';
+  else zone = 'green';
+
+  return {
+    score,
+    zone,
+    factors: {
+      requirementsCoverage: { value: requirementsCoverage, label: 'Requirements Coverage' },
+      constitutionCompliance: { value: constitutionCompliance, label: 'Constitution Compliance' },
+      phaseSeparation: { value: phaseSeparation, label: 'Phase Separation' },
+      testCoverage: { value: testCoverage, label: 'Test Coverage' }
+    }
+  };
+}
+
+/**
+ * Map a coverage entry to a cell status object.
+ *
+ * @param {boolean} hasArtifact
+ * @param {string[]} ids
+ * @param {string|null} statusStr - e.g., "Partial", "Full"
+ * @returns {{status: string, refs: string[]}}
+ */
+function mapCellStatus(hasArtifact, ids, statusStr) {
+  if (statusStr && /partial/i.test(statusStr)) {
+    return { status: 'partial', refs: ids || [] };
+  }
+  if (hasArtifact && ids && ids.length > 0) {
+    return { status: 'covered', refs: ids };
+  }
+  if (!hasArtifact || !ids || ids.length === 0) {
+    return { status: 'missing', refs: [] };
+  }
+  return { status: 'covered', refs: ids };
+}
+
+/**
+ * Build heatmap rows from requirements and coverage data.
+ *
+ * @param {Array<{id: string, text: string}>} requirements
+ * @param {Array} coverageEntries
+ * @returns {Array<{id: string, text: string, cells: Object}>}
+ */
+function buildHeatmapRows(requirements, coverageEntries) {
+  if (!requirements || requirements.length === 0) return [];
+
+  const coverageMap = {};
+  for (const entry of (coverageEntries || [])) {
+    coverageMap[entry.id] = entry;
+  }
+
+  return requirements.map(req => {
+    const coverage = coverageMap[req.id];
+    if (!coverage) {
+      return {
+        id: req.id,
+        text: req.text,
+        cells: {
+          tasks: { status: 'missing', refs: [] },
+          tests: { status: 'missing', refs: [] },
+          plan: { status: 'na', refs: [] }
+        }
+      };
+    }
+
+    return {
+      id: req.id,
+      text: req.text,
+      cells: {
+        tasks: mapCellStatus(coverage.hasTask, coverage.taskIds, coverage.status === 'Partial' && !coverage.hasTask ? 'Partial' : null),
+        tests: mapCellStatus(coverage.hasTest, coverage.testIds, null),
+        plan: coverage.hasPlan !== undefined
+          ? mapCellStatus(coverage.hasPlan, coverage.planRefs, null)
+          : { status: 'na', refs: [] }
+      }
+    };
+  });
+}
+
+/**
+ * Compute the full analyze view state for a feature.
+ *
+ * @param {string} projectPath
+ * @param {string} featureId
+ * @returns {Object}
+ */
+function computeAnalyzeState(projectPath, featureId) {
+  const featureDir = path.join(projectPath, 'specs', featureId);
+  const analysisPath = path.join(featureDir, 'analysis.md');
+  const specPath = path.join(featureDir, 'spec.md');
+
+  if (!fs.existsSync(analysisPath)) {
+    return {
+      healthScore: null,
+      heatmap: { columns: [], rows: [] },
+      issues: [],
+      metrics: null,
+      constitutionAlignment: [],
+      exists: false
+    };
+  }
+
+  const analysisContent = fs.readFileSync(analysisPath, 'utf-8');
+  const specContent = fs.existsSync(specPath) ? fs.readFileSync(specPath, 'utf-8') : '';
+
+  // Parse all sections
+  const findings = parseAnalysisFindings(analysisContent);
+  const coverage = parseAnalysisCoverage(analysisContent);
+  const metrics = parseAnalysisMetrics(analysisContent);
+  const constitutionAlignment = parseConstitutionAlignment(analysisContent);
+  const phaseSeparationViolations = parsePhaseSeparation(analysisContent);
+
+  // Build heatmap from spec requirements + coverage data
+  const requirements = [
+    ...parseRequirements(specContent),
+    ...parseSuccessCriteria(specContent)
+  ];
+  const heatmapRows = buildHeatmapRows(requirements, coverage);
+
+  // Compute health score factors
+  const reqCovPct = metrics.requirementCoveragePct || 0;
+  const testCovPct = metrics.testCoveragePct || 100;
+  const constitutionCompliancePct = computeConstitutionCompliance(constitutionAlignment);
+  const phaseSepScore = computePhaseSeparationScore(
+    phaseSeparationViolations.filter(v => v.severity)
+  );
+
+  const healthScore = computeHealthScore({
+    requirementsCoverage: reqCovPct,
+    constitutionCompliance: constitutionCompliancePct,
+    phaseSeparation: phaseSepScore,
+    testCoverage: testCovPct
+  });
+
+  // Map findings to issues (API terminology)
+  const issues = findings.map(f => ({
+    id: f.id,
+    category: f.category,
+    severity: f.severity.toLowerCase(),
+    location: f.location,
+    summary: f.summary,
+    recommendation: f.recommendation,
+    resolved: f.resolved
+  }));
+
+  return {
+    healthScore: {
+      ...healthScore,
+      trend: null
+    },
+    heatmap: {
+      columns: ['tasks', 'tests', 'plan'],
+      rows: heatmapRows
+    },
+    issues,
+    metrics: {
+      totalRequirements: metrics.totalRequirements,
+      totalTasks: metrics.totalTasks,
+      totalTestSpecs: metrics.totalTestSpecs,
+      requirementCoverage: metrics.requirementCoverage,
+      criticalIssues: metrics.criticalIssues,
+      highIssues: metrics.highIssues,
+      mediumIssues: metrics.mediumIssues,
+      lowIssues: metrics.lowIssues
+    },
+    constitutionAlignment: constitutionAlignment.map(a => ({
+      principle: a.principle,
+      status: a.status,
+      evidence: a.evidence
+    })),
+    exists: true
+  };
+}
+
+module.exports = {
+  computeHealthScore,
+  computeAnalyzeState,
+  buildHeatmapRows,
+  mapCellStatus,
+  computePhaseSeparationScore,
+  computeConstitutionCompliance
+};

package/src/parser.js

@@ -924,14 +924,259 @@ function parseTaskTestRefs(tasks) {
 
   const refs = {};
   for (const task of tasks) {
-    const match = task.description ? task.description.match(/must pass ((?:TS-\d+(?:,\s*)?)+)/) : null;
-    if (match) {
-      refs[task.id] = match[1].split(/,\s*/).map(s => s.trim()).filter(Boolean);
+    const matches = task.description ? task.description.match(/TS-\d+/g) : null;
+    refs[task.id] = matches ? [...new Set(matches)] : [];
+  }
+  return refs;
+}
+
+/**
+ * Extract a markdown section by heading (## Title), returning content until next ## heading.
+ */
+function extractSection(content, heading) {
+  const regex = new RegExp(`^## ${heading}\\s*$`, 'm');
+  const match = content.match(regex);
+  if (!match) return null;
+
+  const start = match.index + match[0].length;
+  const nextSection = content.indexOf('\n## ', start);
+  return content.substring(start, nextSection >= 0 ? nextSection : content.length).trim();
+}
+
+/**
+ * Parse rows from a pipe-delimited markdown table.
+ * Returns array of arrays (one per row, cells trimmed). Skips header separator row (|---|).
+ */
+function parseMarkdownTable(text) {
+  const lines = text.split('\n').filter(l => l.trim().startsWith('|'));
+  if (lines.length < 2) return [];
+
+  // Skip header row (index 0) and separator row (index 1)
+  return lines.slice(2).map(line =>
+    line.split('|').slice(1, -1).map(cell => cell.trim())
+  ).filter(cells => cells.length > 0 && cells.some(c => c !== ''));
+}
+
+/**
+ * Parse analysis.md Findings section.
+ * Extracts issues with id, category, severity, resolved, location, summary, recommendation.
+ *
+ * @param {string} content - Raw analysis.md content
+ * @returns {Array<{id: string, category: string, severity: string, resolved: boolean, location: string, summary: string, recommendation: string}>}
+ */
+function parseAnalysisFindings(content) {
+  if (!content || typeof content !== 'string') return [];
+
+  const section = extractSection(content, 'Findings');
+  if (!section) return [];
+
+  const rows = parseMarkdownTable(section);
+  if (rows.length === 0) return [];
+
+  return rows.map(cells => {
+    if (cells.length < 6) return null;
+
+    const rawSeverity = cells[2];
+    // Detect ~~SEVERITY~~ RESOLVED pattern
+    const resolvedMatch = rawSeverity.match(/~~(\w+)~~\s*RESOLVED/);
+    const resolved = !!resolvedMatch;
+    const severity = resolved ? resolvedMatch[1] : rawSeverity;
+
+    return {
+      id: cells[0],
+      category: cells[1],
+      severity,
+      resolved,
+      location: cells[3],
+      summary: cells[4],
+      recommendation: cells[5]
+    };
+  }).filter(Boolean);
+}
+
+/**
+ * Parse analysis.md Coverage Summary section.
+ * Handles both simple (Requirement, Has Task?, Notes) and
+ * detailed (Requirement, Has Task?, Task IDs, Has Test?, Test IDs, Status) formats.
+ *
+ * @param {string} content - Raw analysis.md content
+ * @returns {Array<{id: string, hasTask: boolean, taskIds: string[], hasTest: boolean, testIds: string[], status: string|null, notes: string}>}
+ */
+function parseAnalysisCoverage(content) {
+  if (!content || typeof content !== 'string') return [];
+
+  const section = extractSection(content, 'Coverage Summary');
+  if (!section) return [];
+
+  const rows = parseMarkdownTable(section);
+  if (rows.length === 0) return [];
+
+  // Detect format by number of columns in first data row
+  const hasPlanCols = rows[0].length >= 8;
+  const isDetailed = rows[0].length >= 6;
+
+  return rows.map(cells => {
+    const id = cells[0];
+    const hasTask = /^yes$/i.test(cells[1]);
+
+    if (isDetailed) {
+      // Detailed: Requirement | Has Task? | Task IDs | Has Test? | Test IDs | [Has Plan? | Plan Refs |] Status
+      const taskIds = parseIdList(cells[2]);
+      const hasTest = /^yes$/i.test(cells[3]);
+      const testIds = parseIdList(cells[4]);
+
+      if (hasPlanCols) {
+        const hasPlan = /^yes$/i.test(cells[5]);
+        const planRefs = parseIdList(cells[6]);
+        const status = cells[7] && cells[7] !== '—' && cells[7] !== '-' ? cells[7] : null;
+        return { id, hasTask, taskIds, hasTest, testIds, hasPlan, planRefs, status, notes: '' };
+      }
+
+      const status = cells[5] && cells[5] !== '—' && cells[5] !== '-' ? cells[5] : null;
+      return { id, hasTask, taskIds, hasTest, testIds, status, notes: '' };
     } else {
-      refs[task.id] = [];
+      // Simple: Requirement | Has Task? | Notes
+      const notes = cells[2] || '';
+      return { id, hasTask, taskIds: [], hasTest: false, testIds: [], status: null, notes };
+    }
+  });
+}
+
+/**
+ * Parse a comma-separated list of IDs (e.g., "T001, T002" or "TS-001, TS-037").
+ * Filters out dashes and empty entries.
+ */
+function parseIdList(cell) {
+  if (!cell || cell === '—' || cell === '-' || cell === '–') return [];
+  return cell.split(',').map(s => s.trim()).filter(s => s && s !== '—' && s !== '-' && s !== '–');
+}
+
+/**
+ * Parse analysis.md Metrics section.
+ * Handles both table format (| Metric | Value |) and bullet format (- Metric: Value).
+ *
+ * @param {string} content - Raw analysis.md content
+ * @returns {{totalRequirements: number, totalTasks: number, totalTestSpecs: number, requirementCoverage: string, requirementCoveragePct: number, testCoverage: string|null, testCoveragePct: number, criticalIssues: number, highIssues: number, mediumIssues: number, lowIssues: number}}
+ */
+function parseAnalysisMetrics(content) {
+  const defaults = {
+    totalRequirements: 0, totalTasks: 0, totalTestSpecs: 0,
+    requirementCoverage: '', requirementCoveragePct: 0,
+    testCoverage: null, testCoveragePct: 100,
+    criticalIssues: 0, highIssues: 0, mediumIssues: 0, lowIssues: 0
+  };
+  if (!content || typeof content !== 'string') return defaults;
+
+  const section = extractSection(content, 'Metrics');
+  if (!section) return defaults;
+
+  // Build key-value map from either table or bullet format
+  const kvMap = {};
+
+  // Try table format first
+  const tableRows = parseMarkdownTable(section);
+  if (tableRows.length > 0) {
+    for (const cells of tableRows) {
+      if (cells.length >= 2) kvMap[cells[0].toLowerCase()] = cells[1];
+    }
+  } else {
+    // Try bullet format: - Key: Value
+    const bulletRegex = /^-\s+(.+?):\s+(.+)$/gm;
+    let match;
+    while ((match = bulletRegex.exec(section)) !== null) {
+      kvMap[match[1].trim().toLowerCase()] = match[2].trim();
     }
   }
-  return refs;
+
+  function findValue(keys) {
+    for (const key of keys) {
+      for (const [k, v] of Object.entries(kvMap)) {
+        if (k.includes(key)) return v;
+      }
+    }
+    return null;
+  }
+
+  function extractPct(raw) {
+    if (!raw) return null;
+    const pctMatch = raw.match(/(\d+)%/);
+    if (pctMatch) return parseInt(pctMatch[1], 10);
+    const fracMatch = raw.match(/\((\d+)%\)/);
+    if (fracMatch) return parseInt(fracMatch[1], 10);
+    return null;
+  }
+
+  const reqCovRaw = findValue(['requirement coverage']);
+  const testCovRaw = findValue(['test coverage']);
+
+  return {
+    totalRequirements: parseInt(findValue(['total requirements']) || '0', 10),
+    totalTasks: parseInt(findValue(['total tasks']) || '0', 10),
+    totalTestSpecs: parseInt(findValue(['total test spec']) || '0', 10),
+    requirementCoverage: reqCovRaw || '',
+    requirementCoveragePct: extractPct(reqCovRaw) || 0,
+    testCoverage: testCovRaw || null,
+    testCoveragePct: testCovRaw ? (extractPct(testCovRaw) || 0) : 100,
+    criticalIssues: parseInt(findValue(['critical']) || '0', 10),
+    highIssues: parseInt(findValue(['high']) || '0', 10),
+    mediumIssues: parseInt(findValue(['medium']) || '0', 10),
+    lowIssues: parseInt(findValue(['low']) || '0', 10)
+  };
+}
+
+/**
+ * Parse analysis.md Constitution Alignment section.
+ *
+ * @param {string} content - Raw analysis.md content
+ * @returns {Array<{principle: string, status: string, evidence: string}>}
+ */
+function parseConstitutionAlignment(content) {
+  if (!content || typeof content !== 'string') return [];
+
+  const section = extractSection(content, 'Constitution Alignment');
+  if (!section) return [];
+
+  // Check for "None detected" text
+  if (/none detected/i.test(section) && !section.includes('|')) return [];
+
+  const rows = parseMarkdownTable(section);
+  return rows.map(cells => {
+    if (cells.length < 3) return null;
+    return {
+      principle: cells[0],
+      status: cells[1],
+      evidence: cells[2]
+    };
+  }).filter(Boolean);
+}
+
+/**
+ * Parse analysis.md Phase Separation Violations section.
+ *
+ * @param {string} content - Raw analysis.md content
+ * @returns {Array<{artifact: string, status: string, severity: string|null}>}
+ */
+function parsePhaseSeparation(content) {
+  if (!content || typeof content !== 'string') return [];
+
+  const section = extractSection(content, 'Phase Separation Violations');
+  if (!section) return [];
+
+  // Check for "None detected" before the table
+  const noneIdx = section.search(/none detected/i);
+  const tableIdx = section.indexOf('|');
+  if (noneIdx >= 0 && (tableIdx < 0 || noneIdx < tableIdx)) return [];
+
+  const rows = parseMarkdownTable(section);
+  return rows.map(cells => {
+    if (cells.length < 2) return null;
+    const severity = cells.length >= 3 && cells[2] && cells[2] !== '—' && cells[2] !== '-' && cells[2] !== '–' ? cells[2] : null;
+    return {
+      artifact: cells[0],
+      status: cells[1],
+      severity
+    };
+  }).filter(Boolean);
 }
 
-module.exports = { parseSpecStories, parseTasks, parseChecklists, parseChecklistsDetailed, parseConstitutionTDD, hasClarifications, parseConstitutionPrinciples, parseRequirements, parseSuccessCriteria, parseClarifications, parseStoryRequirementRefs, parseTechContext, parseFileStructure, parseAsciiDiagram, parseTesslJson, parseResearchDecisions, parseTestSpecs, parseTaskTestRefs };
+module.exports = { parseSpecStories, parseTasks, parseChecklists, parseChecklistsDetailed, parseConstitutionTDD, hasClarifications, parseConstitutionPrinciples, parseRequirements, parseSuccessCriteria, parseClarifications, parseStoryRequirementRefs, parseTechContext, parseFileStructure, parseAsciiDiagram, parseTesslJson, parseResearchDecisions, parseTestSpecs, parseTaskTestRefs, parseAnalysisFindings, parseAnalysisCoverage, parseAnalysisMetrics, parseConstitutionAlignment, parsePhaseSeparation };

package/src/planview.js

@@ -2,9 +2,11 @@
 
 const fs = require('fs');
 const path = require('path');
+const childProcess = require('child_process');
+const { promisify } = require('util');
 const { parseTechContext, parseFileStructure, parseAsciiDiagram, parseTesslJson, parseResearchDecisions } = require('./parser');
 
-module.exports = { computePlanViewState, classifyNodeTypes };
+module.exports = { computePlanViewState, classifyNodeTypes, fetchTesslEvalData };
 
 // In-memory cache for LLM classification results per feature
 const classificationCache = new Map();
@@ -15,9 +17,12 @@ const classificationCache = new Map();
  *
  * @param {string} projectPath - Path to project root
  * @param {string} featureId - Feature directory name
+ * @param {Object} [options] - Optional configuration
+ * @param {Function} [options.fetchEvalData] - Custom eval data fetcher (for testing)
  * @returns {Promise<Object>} Plan view state
  */
-async function computePlanViewState(projectPath, featureId) {
+async function computePlanViewState(projectPath, featureId, options = {}) {
+  const evalFetcher = options.fetchEvalData || fetchTesslEvalData;
   const featureDir = path.join(projectPath, 'specs', featureId);
   const planPath = path.join(featureDir, 'plan.md');
 
@@ -77,8 +82,14 @@ async function computePlanViewState(projectPath, featureId) {
     }
   }
 
-  // Parse tessl.json
+  // Parse tessl.json and enrich with eval data
   const tesslTiles = parseTesslJson(projectPath);
+  const evalResults = await Promise.all(
+    tesslTiles.map(tile => evalFetcher(tile.name).catch(() => null))
+  );
+  tesslTiles.forEach((tile, i) => {
+    tile.eval = evalResults[i];
+  });
 
   return {
     techContext,
@@ -181,6 +192,108 @@ No explanation, just the JSON.`
   return result;
 }
 
+// In-memory cache for eval data per tile name
+const evalCache = new Map();
+
+/**
+ * Fetch eval data for a Tessl tile using the tessl CLI.
+ * Returns structured eval data or null if unavailable.
+ *
+ * @param {string} tileName - Tile name (e.g., "tessl/npm-express")
+ * @returns {Promise<{score: number, multiplier: number, chartData: {pass: number, fail: number}}|null>}
+ */
+async function fetchTesslEvalData(tileName) {
+  if (evalCache.has(tileName)) return evalCache.get(tileName);
+
+  try {
+    const execAsync = promisify(childProcess.exec);
+
+    // List eval runs for the tile
+    const { stdout: listOut } = await execAsync(
+      `tessl eval list --json --tile "${tileName}" --limit 1`,
+      { timeout: 10000 }
+    );
+    const listJson = JSON.parse(listOut.substring(listOut.indexOf('{')));
+
+    if (!listJson.data || listJson.data.length === 0) {
+      evalCache.set(tileName, null);
+      return null;
+    }
+
+    // Find the most recent completed eval run
+    const completedRun = listJson.data.find(r => r.attributes && r.attributes.status === 'completed');
+    if (!completedRun) {
+      evalCache.set(tileName, null);
+      return null;
+    }
+
+    // Fetch detailed eval results
+    const { stdout: viewOut } = await execAsync(
+      `tessl eval view --json ${completedRun.id}`,
+      { timeout: 15000 }
+    );
+    const viewJson = JSON.parse(viewOut.substring(viewOut.indexOf('{')));
+
+    const evalData = computeEvalSummary(viewJson.data);
+    evalCache.set(tileName, evalData);
+    return evalData;
+  } catch {
+    evalCache.set(tileName, null);
+    return null;
+  }
+}
+
+/**
+ * Compute eval summary from a detailed eval run response.
+ * Extracts score, multiplier, and pass/fail chart data from scenarios.
+ */
+function computeEvalSummary(evalRun) {
+  if (!evalRun || !evalRun.attributes || !evalRun.attributes.scenarios) return null;
+
+  let usageTotal = 0, usageMax = 0, baselineTotal = 0;
+  let pass = 0, fail = 0;
+
+  for (const scenario of evalRun.attributes.scenarios) {
+    if (!scenario.solutions) continue;
+
+    const usageSpec = scenario.solutions.find(s => s.variant === 'usage-spec');
+    const baseline = scenario.solutions.find(s => s.variant === 'baseline');
+
+    if (usageSpec && usageSpec.assessmentResults) {
+      for (const r of usageSpec.assessmentResults) {
+        usageTotal += r.score;
+        usageMax += r.max_score;
+        if (r.score === r.max_score) pass++;
+        else fail++;
+      }
+    }
+
+    if (baseline && baseline.assessmentResults) {
+      for (const r of baseline.assessmentResults) {
+        baselineTotal += r.score;
+      }
+    }
+  }
+
+  if (usageMax === 0) return null;
+
+  const score = Math.round(usageTotal / usageMax * 100);
+  const multiplier = baselineTotal > 0
+    ? Math.round(usageTotal / baselineTotal * 100) / 100
+    : null;
+
+  return { score, multiplier, chartData: { pass, fail } };
+}
+
+/**
+ * Invalidate eval cache (e.g., when tessl.json changes).
+ */
+function invalidateEvalCache() {
+  evalCache.clear();
+}
+
+module.exports.invalidateEvalCache = invalidateEvalCache;
+
 /**
  * Invalidate classification cache for a feature.
  */