iikit-dashboard 1.1.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iikit-dashboard",
-  "version": "1.1.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

@@ -855,4 +855,328 @@ function parseResearchDecisions(content) {
   return decisions;
 }
 
-module.exports = { parseSpecStories, parseTasks, parseChecklists, parseChecklistsDetailed, parseConstitutionTDD, hasClarifications, parseConstitutionPrinciples, parseRequirements, parseSuccessCriteria, parseClarifications, parseStoryRequirementRefs, parseTechContext, parseFileStructure, parseAsciiDiagram, parseTesslJson, parseResearchDecisions };
+/**
+ * Parse tests/test-specs.md to extract test specification entries.
+ * Pattern: ### TS-XXX: Title, then **Type**: value, **Priority**: value, **Traceability**: refs
+ *
+ * @param {string} content - Raw markdown content of test-specs.md
+ * @returns {Array<{id: string, title: string, type: string, priority: string, traceability: string[]}>}
+ */
+function parseTestSpecs(content) {
+  if (!content || typeof content !== 'string') return [];
+
+  const specs = [];
+  const headingRegex = /### TS-(\d+): (.+)/g;
+  const headingStarts = [];
+  let match;
+
+  while ((match = headingRegex.exec(content)) !== null) {
+    headingStarts.push({
+      id: `TS-${match[1]}`,
+      title: match[2].trim(),
+      index: match.index
+    });
+  }
+
+  for (let i = 0; i < headingStarts.length; i++) {
+    const start = headingStarts[i].index;
+    const end = i + 1 < headingStarts.length ? headingStarts[i + 1].index : content.length;
+    const section = content.substring(start, end);
+
+    // Extract type
+    const typeMatch = section.match(/\*\*Type\*\*:\s*(acceptance|contract|validation)/);
+    const type = typeMatch ? typeMatch[1] : 'validation';
+
+    // Extract priority
+    const priorityMatch = section.match(/\*\*Priority\*\*:\s*(P\d+)/);
+    const priority = priorityMatch ? priorityMatch[1] : 'P3';
+
+    // Extract traceability — comma-separated IDs, filter to FR-/SC- only
+    let traceability = [];
+    const traceMatch = section.match(/\*\*Traceability\*\*:\s*(.+)/);
+    if (traceMatch) {
+      traceability = traceMatch[1]
+        .split(/,\s*/)
+        .map(s => s.trim())
+        .filter(s => /^(FR|SC)-\d+$/.test(s));
+    }
+
+    specs.push({
+      id: headingStarts[i].id,
+      title: headingStarts[i].title,
+      type,
+      priority,
+      traceability
+    });
+  }
+
+  return specs;
+}
+
+/**
+ * Extract "must pass TS-xxx" references from already-parsed task descriptions.
+ *
+ * @param {Array<{id: string, description: string}>} tasks - Parsed tasks array
+ * @returns {Object<string, string[]>} Map of taskId to testSpecIds array
+ */
+function parseTaskTestRefs(tasks) {
+  if (!tasks || !Array.isArray(tasks)) return {};
+
+  const refs = {};
+  for (const task of tasks) {
+    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 {
+      // 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();
+    }
+  }
+
+  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, parseAnalysisFindings, parseAnalysisCoverage, parseAnalysisMetrics, parseConstitutionAlignment, parsePhaseSeparation };