aios-core 4.0.4 → 4.2.0

package/.aios-core/core/synapse/diagnostics/report-formatter.js

@@ -0,0 +1,484 @@
+/**
+ * Report Formatter — Generates structured markdown diagnostic report.
+ *
+ * Takes collector results and produces a human-readable report
+ * with sections for each diagnostic area.
+ *
+ * @module core/synapse/diagnostics/report-formatter
+ * @version 1.0.0
+ * @created Story SYN-13
+ */
+
+'use strict';
+
+/**
+ * Format a complete diagnostic report from collector results.
+ *
+ * @param {object} data - Collected diagnostic data
+ * @param {object} data.hook - Hook collector results
+ * @param {object} data.session - Session collector results
+ * @param {object} data.manifest - Manifest collector results
+ * @param {object} data.pipeline - Pipeline collector results
+ * @param {object} data.uap - UAP collector results
+ * @returns {string} Formatted markdown report
+ */
+function formatReport(data) {
+  if (!data || typeof data !== 'object') {
+    return '# SYNAPSE Diagnostic Report\n**Error:** No diagnostic data provided.\n';
+  }
+
+  const lines = [];
+  const timestamp = new Date().toISOString();
+
+  // Header
+  lines.push('# SYNAPSE Diagnostic Report');
+  lines.push(`**Timestamp:** ${timestamp}`);
+
+  if (data.pipeline) {
+    const bracket = data.pipeline.bracket || 'UNKNOWN';
+    const contextPercent = typeof data.pipeline.contextPercent === 'number'
+      ? data.pipeline.contextPercent.toFixed(1)
+      : '?';
+    lines.push(`**Bracket:** ${bracket} (${contextPercent}% context remaining)`);
+  }
+
+  const agentId = _extractAgentId(data);
+  if (agentId) {
+    const quality = data.session?.raw?.bridgeData?.activation_quality || 'unknown';
+    lines.push(`**Agent:** @${agentId} (activation_quality: ${quality})`);
+  }
+
+  lines.push('');
+
+  // Section 1: Hook Status
+  lines.push('## 1. Hook Status');
+  if (data.hook && data.hook.checks) {
+    lines.push('| Check | Status | Detail |');
+    lines.push('|-------|--------|--------|');
+    for (const check of data.hook.checks) {
+      lines.push(`| ${check.name} | ${check.status} | ${check.detail} |`);
+    }
+  } else {
+    lines.push('*No hook data collected*');
+  }
+  lines.push('');
+
+  // Section 2: Session Status
+  lines.push('## 2. Session Status');
+  if (data.session && data.session.fields) {
+    lines.push('| Field | Expected | Actual | Status |');
+    lines.push('|-------|----------|--------|--------|');
+    for (const field of data.session.fields) {
+      lines.push(`| ${field.field} | ${field.expected} | ${field.actual} | ${field.status} |`);
+    }
+  } else {
+    lines.push('*No session data collected*');
+  }
+  lines.push('');
+
+  // Section 3: Manifest Integrity
+  lines.push('## 3. Manifest Integrity');
+  if (data.manifest && data.manifest.entries) {
+    lines.push('| Domain | In Manifest | File Exists | Status |');
+    lines.push('|--------|-------------|-------------|--------|');
+    for (const entry of data.manifest.entries) {
+      lines.push(`| ${entry.domain} | ${entry.inManifest} | ${entry.fileExists ? 'yes' : 'no'} | ${entry.status} |`);
+    }
+
+    if (data.manifest.orphanedFiles && data.manifest.orphanedFiles.length > 0) {
+      lines.push('');
+      lines.push(`**Orphaned files** (in .synapse/ but not in manifest): ${data.manifest.orphanedFiles.join(', ')}`);
+    }
+  } else {
+    lines.push('*No manifest data collected*');
+  }
+  lines.push('');
+
+  // Section 4: Pipeline Simulation
+  lines.push(`## 4. Pipeline Simulation (${data.pipeline?.bracket || 'UNKNOWN'} bracket)`);
+  if (data.pipeline && data.pipeline.layers) {
+    lines.push('| Layer | Expected | Status |');
+    lines.push('|-------|----------|--------|');
+    for (const layer of data.pipeline.layers) {
+      lines.push(`| ${layer.layer} | ${layer.expected} | ${layer.status} |`);
+    }
+  } else {
+    lines.push('*No pipeline data collected*');
+  }
+  lines.push('');
+
+  // Section 5: UAP Bridge
+  lines.push('## 5. UAP Bridge');
+  if (data.uap && data.uap.checks) {
+    lines.push('| Check | Status | Detail |');
+    lines.push('|-------|--------|--------|');
+    for (const check of data.uap.checks) {
+      lines.push(`| ${check.name} | ${check.status} | ${check.detail} |`);
+    }
+  } else {
+    lines.push('*No UAP bridge data collected*');
+  }
+  lines.push('');
+
+  // Section 6: Memory Bridge
+  lines.push('## 6. Memory Bridge');
+  lines.push('| Check | Status | Detail |');
+  lines.push('|-------|--------|--------|');
+
+  // Memory bridge is Pro-only, so always report current state
+  lines.push('| Pro available | INFO | Check `pro/` submodule |');
+  lines.push(`| Bracket requires hints | ${_bracketNeedsMemory(data.pipeline?.bracket) ? 'YES' : 'NO'} | ${data.pipeline?.bracket || 'UNKNOWN'} bracket |`);
+  lines.push('');
+
+  // Section 7: Gaps & Recommendations
+  lines.push('## 7. Gaps & Recommendations');
+  const gaps = _collectGaps(data);
+
+  if (gaps.length === 0) {
+    lines.push('| # | Severity | Gap | Recommendation |');
+    lines.push('|---|----------|-----|----------------|');
+    lines.push('| - | - | None found | Pipeline operating correctly |');
+  } else {
+    lines.push('| # | Severity | Gap | Recommendation |');
+    lines.push('|---|----------|-----|----------------|');
+    for (let i = 0; i < gaps.length; i++) {
+      lines.push(`| ${i + 1} | ${gaps[i].severity} | ${gaps[i].gap} | ${gaps[i].recommendation} |`);
+    }
+  }
+  lines.push('');
+
+  // Section 8: Timing Analysis (SYN-14)
+  _formatTimingSection(lines, data.timing);
+
+  // Section 9: Context Quality Analysis (SYN-14)
+  _formatQualitySection(lines, data.quality);
+
+  // Section 10: Consistency Checks (SYN-14)
+  _formatConsistencySection(lines, data.consistency);
+
+  // Section 11: Output Quality (SYN-14)
+  _formatOutputSection(lines, data.outputAnalysis);
+
+  // Section 12: Relevance Matrix (SYN-14)
+  _formatRelevanceSection(lines, data.relevance);
+
+  return lines.join('\n');
+}
+
+/**
+ * Extract agent ID from collected data.
+ * @param {object} data
+ * @returns {string|null}
+ */
+function _extractAgentId(data) {
+  if (data.session?.raw?.bridgeData?.id) return data.session.raw.bridgeData.id;
+  if (data.session?.raw?.session?.active_agent?.id) return data.session.raw.session.active_agent.id;
+  return null;
+}
+
+/**
+ * Check if a bracket requires memory hints.
+ * @param {string} bracket
+ * @returns {boolean}
+ */
+function _bracketNeedsMemory(bracket) {
+  return bracket === 'DEPLETED' || bracket === 'CRITICAL';
+}
+
+/**
+ * Collect gaps from all collector results.
+ * @param {object} data
+ * @returns {Array<{ severity: string, gap: string, recommendation: string }>}
+ */
+function _collectGaps(data) {
+  const gaps = [];
+
+  // Check hook failures
+  const hookChecks = data.hook?.checks || [];
+  for (const check of hookChecks) {
+    if (check.status === 'FAIL') {
+      gaps.push({
+        severity: 'HIGH',
+        gap: `Hook: ${check.name} — ${check.detail}`,
+        recommendation: 'Run `npx aios-core install` to reinstall hooks',
+      });
+    }
+  }
+
+  // Check session issues
+  const sessionFields = data.session?.fields || [];
+  for (const field of sessionFields) {
+    if (field.status === 'FAIL') {
+      gaps.push({
+        severity: 'HIGH',
+        gap: `Session: ${field.field} — ${field.actual}`,
+        recommendation: 'Activate an agent with @agent to create session',
+      });
+    }
+  }
+
+  // Check manifest failures
+  const manifestEntries = data.manifest?.entries || [];
+  for (const entry of manifestEntries) {
+    if (entry.status === 'FAIL') {
+      gaps.push({
+        severity: 'MEDIUM',
+        gap: `Manifest: domain "${entry.domain}" file missing`,
+        recommendation: `Create .synapse/${entry.domain} domain file`,
+      });
+    }
+  }
+
+  // Check UAP bridge failures
+  const uapChecks = data.uap?.checks || [];
+  for (const check of uapChecks) {
+    if (check.status === 'FAIL') {
+      gaps.push({
+        severity: 'HIGH',
+        gap: `UAP Bridge: ${check.name} — ${check.detail}`,
+        recommendation: 'Activate an agent to trigger UAP bridge write',
+      });
+    }
+  }
+
+  // SYN-14 fix: Include gaps from new collectors (consistency, quality, relevance)
+
+  // Consistency check failures
+  const consistencyChecks = data.consistency?.checks || [];
+  for (const check of consistencyChecks) {
+    if (check.status === 'FAIL') {
+      gaps.push({
+        severity: 'MEDIUM',
+        gap: `Consistency: ${check.name} — ${check.detail}`,
+        recommendation: 'Re-activate agent to refresh metrics alignment',
+      });
+    }
+  }
+
+  // Quality grade below threshold
+  if (data.quality?.overall?.grade === 'F') {
+    gaps.push({
+      severity: 'HIGH',
+      gap: `Context quality: ${data.quality.overall.score}/100 (${data.quality.overall.grade})`,
+      recommendation: 'Re-activate agent to refresh UAP metrics',
+    });
+  }
+
+  // Relevance critical gaps
+  const relevanceGaps = data.relevance?.gaps || [];
+  for (const g of relevanceGaps) {
+    if (g.importance === 'critical') {
+      gaps.push({
+        severity: 'HIGH',
+        gap: `Relevance: ${g.component} (${g.importance}) missing`,
+        recommendation: 'Ensure critical context component is available for active agent',
+      });
+    }
+  }
+
+  // Sort by severity (HIGH first)
+  const severityOrder = { HIGH: 0, MEDIUM: 1, LOW: 2 };
+  gaps.sort((a, b) => {
+    const orderA = severityOrder[a.severity] !== undefined ? severityOrder[a.severity] : 3;
+    const orderB = severityOrder[b.severity] !== undefined ? severityOrder[b.severity] : 3;
+    return orderA - orderB;
+  });
+
+  return gaps;
+}
+
+/**
+ * Section 8: Timing Analysis.
+ * @param {string[]} lines
+ * @param {object} timing
+ */
+function _formatTimingSection(lines, timing) {
+  lines.push('## 8. Timing Analysis');
+  if (!timing || timing.error) {
+    lines.push('*No timing data available*');
+    lines.push('');
+    return;
+  }
+
+  // UAP Timing
+  if (timing.uap && timing.uap.available) {
+    const staleTag = timing.uap.stale ? ' **[STALE]**' : '';
+    lines.push(`### UAP Activation Pipeline (${timing.uap.totalDuration}ms total, quality: ${timing.uap.quality})${staleTag}`);
+    lines.push('| Loader | Duration | Status | Tier |');
+    lines.push('|--------|----------|--------|------|');
+    for (const loader of timing.uap.loaders) {
+      lines.push(`| ${loader.name} | ${loader.duration}ms | ${loader.status} | ${loader.tier} |`);
+    }
+    lines.push(`| **Total** | **${timing.uap.totalDuration}ms** | | |`);
+  } else {
+    lines.push('### UAP Activation Pipeline');
+    lines.push('*No UAP timing data — activate an agent first*');
+  }
+  lines.push('');
+
+  // Hook Timing
+  if (timing.hook && timing.hook.available) {
+    const staleTag = timing.hook.stale ? ' **[STALE]**' : '';
+    const bootInfo = timing.hook.hookBootMs ? ` boot: ${Math.round(timing.hook.hookBootMs)}ms,` : '';
+    lines.push(`### SYNAPSE Hook Pipeline (${timing.hook.totalDuration}ms total,${bootInfo} ${timing.hook.bracket} bracket)${staleTag}`);
+    lines.push('| Layer | Duration | Status | Rules |');
+    lines.push('|-------|----------|--------|-------|');
+    for (const layer of timing.hook.layers) {
+      lines.push(`| ${layer.name} | ${layer.duration}ms | ${layer.status} | ${layer.rules} |`);
+    }
+    const totalRules = timing.hook.layers.reduce((sum, l) => sum + (l.rules || 0), 0);
+    lines.push(`| **Total** | **${timing.hook.totalDuration}ms** | | **${totalRules}** |`);
+  } else {
+    lines.push('### SYNAPSE Hook Pipeline');
+    lines.push('*No Hook timing data — send a prompt first*');
+  }
+  lines.push('');
+
+  // Combined
+  lines.push(`**Combined pipeline time:** ${timing.combined ? timing.combined.totalMs : 0}ms`);
+  lines.push('');
+}
+
+/**
+ * Section 9: Context Quality Analysis.
+ * @param {string[]} lines
+ * @param {object} quality
+ */
+function _formatQualitySection(lines, quality) {
+  lines.push('## 9. Context Quality Analysis');
+  if (!quality || quality.error) {
+    lines.push('*No quality data available*');
+    lines.push('');
+    return;
+  }
+
+  const overall = quality.overall || { score: 0, grade: 'F', label: 'UNKNOWN' };
+  lines.push(`**Overall: ${overall.score}/100 (${overall.grade} — ${overall.label})**`);
+
+  const uapScore = quality.uap ? quality.uap.score : 0;
+  const hookScore = quality.hook ? quality.hook.score : 0;
+  const uapStale = quality.uap && quality.uap.stale ? ' [STALE]' : '';
+  const hookStale = quality.hook && quality.hook.stale ? ' [STALE]' : '';
+  lines.push(`UAP: ${uapScore}/100${uapStale} | Hook: ${hookScore}/100${hookStale}`);
+  lines.push('');
+
+  // UAP Loaders
+  if (quality.uap && quality.uap.loaders && quality.uap.loaders.length > 0) {
+    lines.push('### UAP Loaders');
+    lines.push('| Loader | Score | Criticality | Impact |');
+    lines.push('|--------|-------|-------------|--------|');
+    for (const loader of quality.uap.loaders) {
+      lines.push(`| ${loader.name} | ${loader.score}/${loader.maxScore} | ${loader.criticality} | ${loader.impact} |`);
+    }
+    lines.push('');
+  }
+
+  // Hook Layers
+  if (quality.hook && quality.hook.layers && quality.hook.layers.length > 0) {
+    lines.push('### Hook Layers');
+    lines.push('| Layer | Score | Criticality | Rules | Impact |');
+    lines.push('|-------|-------|-------------|-------|--------|');
+    for (const layer of quality.hook.layers) {
+      lines.push(`| ${layer.name} | ${layer.score}/${layer.maxScore} | ${layer.criticality} | ${layer.rules || '-'} | ${layer.impact} |`);
+    }
+    lines.push('');
+  }
+}
+
+/**
+ * Section 10: Consistency Checks.
+ * @param {string[]} lines
+ * @param {object} consistency
+ */
+function _formatConsistencySection(lines, consistency) {
+  lines.push('## 10. Consistency Checks');
+  if (!consistency || consistency.error || !consistency.available) {
+    lines.push('*No consistency data available*');
+    lines.push('');
+    return;
+  }
+
+  lines.push(`**Score:** ${consistency.score}/${consistency.maxScore}`);
+  lines.push('');
+  lines.push('| Check | Status | Detail |');
+  lines.push('|-------|--------|--------|');
+  for (const check of consistency.checks) {
+    lines.push(`| ${check.name} | ${check.status} | ${check.detail} |`);
+  }
+  lines.push('');
+}
+
+/**
+ * Section 11: Output Quality.
+ * @param {string[]} lines
+ * @param {object} outputAnalysis
+ */
+function _formatOutputSection(lines, outputAnalysis) {
+  lines.push('## 11. Output Quality');
+  if (!outputAnalysis || outputAnalysis.error || !outputAnalysis.available) {
+    lines.push('*No output analysis data available*');
+    lines.push('');
+    return;
+  }
+
+  const s = outputAnalysis.summary;
+  lines.push(`**UAP:** ${s.uapHealthy}/${s.uapTotal} healthy | **Hook:** ${s.hookHealthy}/${s.hookTotal} healthy`);
+  lines.push('');
+
+  if (outputAnalysis.uapAnalysis && outputAnalysis.uapAnalysis.length > 0) {
+    lines.push('### UAP Loaders');
+    lines.push('| Loader | Status | Quality | Detail |');
+    lines.push('|--------|--------|---------|--------|');
+    for (const a of outputAnalysis.uapAnalysis) {
+      lines.push(`| ${a.name} | ${a.status} | ${a.quality} | ${a.detail} |`);
+    }
+    lines.push('');
+  }
+
+  if (outputAnalysis.hookAnalysis && outputAnalysis.hookAnalysis.length > 0) {
+    lines.push('### Hook Layers');
+    lines.push('| Layer | Status | Rules | Quality | Detail |');
+    lines.push('|-------|--------|-------|---------|--------|');
+    for (const a of outputAnalysis.hookAnalysis) {
+      lines.push(`| ${a.name} | ${a.status} | ${a.rules} | ${a.quality} | ${a.detail} |`);
+    }
+    lines.push('');
+  }
+}
+
+/**
+ * Section 12: Relevance Matrix.
+ * @param {string[]} lines
+ * @param {object} relevance
+ */
+function _formatRelevanceSection(lines, relevance) {
+  lines.push('## 12. Relevance Matrix');
+  if (!relevance || relevance.error || !relevance.available) {
+    lines.push('*No relevance data available*');
+    lines.push('');
+    return;
+  }
+
+  lines.push(`**Agent:** @${relevance.agentId} | **Relevance Score:** ${relevance.score}/100`);
+  lines.push('');
+
+  if (relevance.matrix && relevance.matrix.length > 0) {
+    lines.push('| Component | Importance | Status | Gap |');
+    lines.push('|-----------|------------|--------|-----|');
+    for (const item of relevance.matrix) {
+      const gapFlag = item.gap ? 'YES' : '-';
+      lines.push(`| ${item.component} | ${item.importance} | ${item.status} | ${gapFlag} |`);
+    }
+    lines.push('');
+  }
+
+  if (relevance.gaps && relevance.gaps.length > 0) {
+    lines.push('### Critical Gaps');
+    for (const gap of relevance.gaps) {
+      lines.push(`- **${gap.component}** (${gap.importance}): missing or failed`);
+    }
+    lines.push('');
+  }
+}
+
+module.exports = { formatReport };

package/.aios-core/core/synapse/diagnostics/synapse-diagnostics.js

@@ -0,0 +1,95 @@
+/**
+ * SYNAPSE Diagnostics Orchestrator
+ *
+ * Coordinates all collectors and generates a comprehensive diagnostic report
+ * comparing expected vs. actual SYNAPSE pipeline state.
+ *
+ * Usage:
+ *   const { runDiagnostics } = require('.../synapse-diagnostics');
+ *   const report = runDiagnostics('/path/to/project');
+ *
+ * @module core/synapse/diagnostics/synapse-diagnostics
+ * @version 1.0.0
+ * @created Story SYN-13
+ */
+
+'use strict';
+
+const path = require('path');
+const { collectHookStatus } = require('./collectors/hook-collector');
+const { collectSessionStatus } = require('./collectors/session-collector');
+const { collectManifestIntegrity } = require('./collectors/manifest-collector');
+const { collectPipelineSimulation } = require('./collectors/pipeline-collector');
+const { collectUapBridgeStatus } = require('./collectors/uap-collector');
+const { formatReport } = require('./report-formatter');
+const { parseManifest } = require('../domain/domain-loader');
+
+/**
+ * Safely execute a collector, returning an error object on failure.
+ * Diagnostics must be resilient — a broken collector should not crash the entire run.
+ * @param {string} name - Collector name for error reporting
+ * @param {Function} fn - Collector function to execute
+ * @returns {*} Collector result or { error: true, collector, message, checks, fields, entries }
+ */
+function _safeCollect(name, fn) {
+  try {
+    return fn();
+  } catch (error) {
+    return { error: true, collector: name, message: error.message, checks: [], fields: [], entries: [] };
+  }
+}
+
+/**
+ * Run all collectors and return raw results.
+ * Shared orchestration logic used by both runDiagnostics and runDiagnosticsRaw.
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {object} options - Diagnostic options
+ * @returns {{ hook, session, manifest, pipeline, uap }} Collector results
+ */
+function _collectAll(projectRoot, options) {
+  if (!projectRoot || typeof projectRoot !== 'string') {
+    throw new Error('projectRoot is required and must be a string');
+  }
+
+  const synapsePath = path.join(projectRoot, '.synapse');
+  const manifestPath = path.join(synapsePath, 'manifest');
+
+  const hook = _safeCollect('hook', () => collectHookStatus(projectRoot));
+  const session = _safeCollect('session', () => collectSessionStatus(projectRoot, options.sessionId));
+  const manifest = _safeCollect('manifest', () => collectManifestIntegrity(projectRoot));
+  const parsedManifest = _safeCollect('parsedManifest', () => parseManifest(manifestPath));
+
+  const promptCount = session?.raw?.session?.prompt_count || 0;
+  const activeAgentId = session?.raw?.bridgeData?.id || session?.raw?.session?.active_agent?.id || null;
+
+  const pipeline = _safeCollect('pipeline', () => collectPipelineSimulation(promptCount, activeAgentId, parsedManifest));
+  const uap = _safeCollect('uap', () => collectUapBridgeStatus(projectRoot));
+
+  return { hook, session, manifest, pipeline, uap };
+}
+
+/**
+ * Run full SYNAPSE diagnostics and return formatted markdown report.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {object} [options] - Diagnostic options
+ * @param {string} [options.sessionId] - Session UUID for session-specific checks
+ * @returns {string} Formatted markdown diagnostic report
+ */
+function runDiagnostics(projectRoot, options = {}) {
+  const data = _collectAll(projectRoot, options);
+  return formatReport(data);
+}
+
+/**
+ * Run diagnostics and return raw collector data (for programmatic use).
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {object} [options] - Diagnostic options
+ * @returns {object} Raw collector results
+ */
+function runDiagnosticsRaw(projectRoot, options = {}) {
+  return _collectAll(projectRoot, options);
+}
+
+module.exports = { runDiagnostics, runDiagnosticsRaw };