@plures/praxis 1.4.0 → 2.0.0

package/src/decision-ledger/report.ts

@@ -0,0 +1,378 @@
+/**
+ * Decision Ledger — Report Generation
+ *
+ * Generates the full analysis report, human-readable markdown,
+ * CI-friendly output, and diffs between analysis runs.
+ */
+
+import type { PraxisRegistry } from '../core/rules.js';
+import type { LogicEngine } from '../core/engine.js';
+import type { ExpectationSet } from '../expectations/expectations.js';
+import type {
+  AnalysisReport,
+  LedgerDiff,
+  LedgerDiffEntry,
+} from './analyzer-types.js';
+import {
+  findDeadRules,
+  findUnreachableStates,
+  findShadowedRules,
+  findContradictions,
+  findGaps,
+} from './analyzer.js';
+import { traceDerivation } from './derivation.js';
+import { suggestAll } from './suggestions.js';
+import { findContractGaps } from './contract-verification.js';
+
+/**
+ * Generate the full analysis report.
+ *
+ * This is the main entry point for the Decision Ledger analyzer.
+ * It runs all analyses and produces a comprehensive report.
+ */
+export function generateLedger<TContext = unknown>(
+  registry: PraxisRegistry<TContext>,
+  engine: LogicEngine<TContext>,
+  expectations?: ExpectationSet,
+): AnalysisReport {
+  // Collect all known event types from rules
+  const allEventTypes = new Set<string>();
+  for (const rule of registry.getAllRules()) {
+    if (rule.eventTypes) {
+      const types = Array.isArray(rule.eventTypes) ? rule.eventTypes : [rule.eventTypes];
+      for (const t of types) allEventTypes.add(t);
+    }
+  }
+
+  // Run analyses
+  const deadRules = findDeadRules(registry, [...allEventTypes]);
+  const unreachableStates = findUnreachableStates(registry);
+  const shadowedRules = findShadowedRules(registry);
+  const contradictions = findContradictions(registry);
+  const contractGaps = findContractGaps(registry);
+  const gaps = expectations ? findGaps(registry, expectations) : [];
+
+  // Build derivation chains for current facts
+  const currentFacts = engine.getFacts();
+  const factDerivationChains = currentFacts.map(fact =>
+    traceDerivation(fact.tag, engine, registry),
+  );
+
+  // Generate suggestions
+  const suggestions = suggestAll({
+    deadRules,
+    gaps,
+    contradictions,
+    unreachableStates,
+    shadowedRules,
+    contractGaps,
+  });
+
+  // Calculate health score
+  const totalRules = registry.getRuleIds().length;
+  const totalConstraints = registry.getConstraintIds().length;
+  const totalIssues =
+    deadRules.length +
+    unreachableStates.length +
+    shadowedRules.length +
+    contradictions.length +
+    gaps.length;
+
+  const maxIssues = Math.max(totalRules + totalConstraints, 1);
+  const healthScore = Math.max(0, Math.round(100 - (totalIssues / maxIssues) * 100));
+
+  return {
+    timestamp: new Date().toISOString(),
+    factDerivationChains,
+    deadRules,
+    unreachableStates,
+    shadowedRules,
+    contradictions,
+    gaps,
+    suggestions,
+    summary: {
+      totalRules,
+      totalConstraints,
+      deadRuleCount: deadRules.length,
+      unreachableStateCount: unreachableStates.length,
+      shadowedRuleCount: shadowedRules.length,
+      contradictionCount: contradictions.length,
+      gapCount: gaps.length,
+      suggestionCount: suggestions.length,
+      healthScore,
+    },
+  };
+}
+
+/**
+ * Format an analysis report as human-readable markdown.
+ */
+export function formatLedger(report: AnalysisReport): string {
+  const lines: string[] = [];
+
+  // Header
+  const icon = report.summary.healthScore >= 90 ? '✅' : report.summary.healthScore >= 70 ? '🟡' : '🔴';
+  lines.push(`# ${icon} Decision Ledger Analysis`);
+  lines.push('');
+  lines.push(`**Health Score:** ${report.summary.healthScore}/100`);
+  lines.push(`**Timestamp:** ${report.timestamp}`);
+  lines.push('');
+
+  // Summary
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`| Metric | Count |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Rules | ${report.summary.totalRules} |`);
+  lines.push(`| Constraints | ${report.summary.totalConstraints} |`);
+  lines.push(`| Dead Rules | ${report.summary.deadRuleCount} |`);
+  lines.push(`| Unreachable States | ${report.summary.unreachableStateCount} |`);
+  lines.push(`| Shadowed Rules | ${report.summary.shadowedRuleCount} |`);
+  lines.push(`| Contradictions | ${report.summary.contradictionCount} |`);
+  lines.push(`| Gaps | ${report.summary.gapCount} |`);
+  lines.push(`| Suggestions | ${report.summary.suggestionCount} |`);
+  lines.push('');
+
+  // Dead Rules
+  if (report.deadRules.length > 0) {
+    lines.push('## 💀 Dead Rules');
+    lines.push('');
+    for (const dr of report.deadRules) {
+      lines.push(`- **${dr.ruleId}**: ${dr.reason}`);
+    }
+    lines.push('');
+  }
+
+  // Unreachable States
+  if (report.unreachableStates.length > 0) {
+    lines.push('## 🚫 Unreachable States');
+    lines.push('');
+    for (const us of report.unreachableStates) {
+      lines.push(`- **[${us.factTags.join(', ')}]**: ${us.reason}`);
+    }
+    lines.push('');
+  }
+
+  // Shadowed Rules
+  if (report.shadowedRules.length > 0) {
+    lines.push('## 👻 Shadowed Rules');
+    lines.push('');
+    for (const sr of report.shadowedRules) {
+      lines.push(`- **${sr.ruleId}** shadowed by **${sr.shadowedBy}**: ${sr.reason}`);
+    }
+    lines.push('');
+  }
+
+  // Contradictions
+  if (report.contradictions.length > 0) {
+    lines.push('## ⚡ Contradictions');
+    lines.push('');
+    for (const c of report.contradictions) {
+      lines.push(`- **${c.ruleA}** ↔ **${c.ruleB}** on \`${c.conflictingTag}\`: ${c.reason}`);
+    }
+    lines.push('');
+  }
+
+  // Gaps
+  if (report.gaps.length > 0) {
+    lines.push('## 🕳️ Gaps');
+    lines.push('');
+    for (const g of report.gaps) {
+      lines.push(`- **${g.expectationName}** (${g.type}): ${g.description}`);
+    }
+    lines.push('');
+  }
+
+  // Derivation Chains
+  if (report.factDerivationChains.length > 0) {
+    lines.push('## 🔗 Fact Derivation Chains');
+    lines.push('');
+    for (const chain of report.factDerivationChains) {
+      if (chain.steps.length === 0) continue;
+      lines.push(`### \`${chain.targetFact}\` (depth: ${chain.depth})`);
+      for (const step of chain.steps) {
+        const icon = step.type === 'event' ? '⚡' : step.type === 'rule-fired' ? '⚙️' : step.type === 'fact-produced' ? '📦' : '📖';
+        lines.push(`  ${icon} ${step.description}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // Suggestions
+  if (report.suggestions.length > 0) {
+    lines.push('## 💡 Suggestions');
+    lines.push('');
+    for (const s of report.suggestions) {
+      const priorityIcon = s.priority >= 8 ? '🔴' : s.priority >= 5 ? '🟡' : '🟢';
+      lines.push(`${priorityIcon} **[${s.findingType}]** ${s.message}`);
+      if (s.skeleton) {
+        lines.push('```typescript');
+        lines.push(s.skeleton);
+        lines.push('```');
+      }
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format report as CI-friendly output with warnings and errors.
+ */
+export function formatBuildOutput(report: AnalysisReport): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push(`::group::Decision Ledger Analysis (Score: ${report.summary.healthScore}/100)`);
+
+  // Errors (contradictions, high-priority gaps)
+  for (const c of report.contradictions) {
+    lines.push(`::error title=Contradiction::Rules "${c.ruleA}" and "${c.ruleB}" both produce "${c.conflictingTag}"`);
+  }
+
+  for (const g of report.gaps) {
+    if (g.type === 'no-rule') {
+      lines.push(`::error title=Missing Rule::No rule covers expectation "${g.expectationName}"`);
+    }
+  }
+
+  // Warnings
+  for (const dr of report.deadRules) {
+    lines.push(`::warning title=Dead Rule::Rule "${dr.ruleId}" can never fire (requires [${dr.requiredEventTypes.join(', ')}])`);
+  }
+
+  for (const sr of report.shadowedRules) {
+    lines.push(`::warning title=Shadowed Rule::Rule "${sr.ruleId}" is always superseded by "${sr.shadowedBy}"`);
+  }
+
+  for (const us of report.unreachableStates) {
+    lines.push(`::warning title=Unreachable State::Facts [${us.factTags.join(', ')}] cannot be produced together`);
+  }
+
+  for (const g of report.gaps) {
+    if (g.type === 'partial-coverage') {
+      lines.push(`::warning title=Partial Coverage::Expectation "${g.expectationName}" is only partially covered`);
+    } else if (g.type === 'no-contract') {
+      lines.push(`::warning title=Missing Contract::Rules for "${g.expectationName}" lack contracts`);
+    }
+  }
+
+  // Summary
+  lines.push('');
+  lines.push(`Rules: ${report.summary.totalRules} | Constraints: ${report.summary.totalConstraints} | Health: ${report.summary.healthScore}/100`);
+  lines.push(`Dead: ${report.summary.deadRuleCount} | Unreachable: ${report.summary.unreachableStateCount} | Shadowed: ${report.summary.shadowedRuleCount} | Contradictions: ${report.summary.contradictionCount} | Gaps: ${report.summary.gapCount}`);
+
+  lines.push('::endgroup::');
+
+  return lines.join('\n');
+}
+
+/**
+ * Diff two analysis reports to find what changed between them.
+ */
+export function diffLedgers(before: AnalysisReport, after: AnalysisReport): LedgerDiff {
+  const changes: LedgerDiffEntry[] = [];
+
+  // Dead rules diff
+  diffItems(
+    before.deadRules,
+    after.deadRules,
+    dr => dr.ruleId,
+    dr => `Dead rule: ${dr.ruleId} — ${dr.reason}`,
+    'dead-rule',
+    changes,
+  );
+
+  // Unreachable states diff
+  diffItems(
+    before.unreachableStates,
+    after.unreachableStates,
+    us => us.factTags.join('+'),
+    us => `Unreachable state: [${us.factTags.join(', ')}]`,
+    'unreachable-state',
+    changes,
+  );
+
+  // Shadowed rules diff
+  diffItems(
+    before.shadowedRules,
+    after.shadowedRules,
+    sr => sr.ruleId,
+    sr => `Shadowed rule: ${sr.ruleId} by ${sr.shadowedBy}`,
+    'shadowed-rule',
+    changes,
+  );
+
+  // Contradictions diff
+  diffItems(
+    before.contradictions,
+    after.contradictions,
+    c => `${c.ruleA}↔${c.ruleB}`,
+    c => `Contradiction: ${c.ruleA} ↔ ${c.ruleB} on ${c.conflictingTag}`,
+    'contradiction',
+    changes,
+  );
+
+  // Gaps diff
+  diffItems(
+    before.gaps,
+    after.gaps,
+    g => g.expectationName,
+    g => `Gap: ${g.expectationName} (${g.type})`,
+    'gap',
+    changes,
+  );
+
+  const scoreDelta = after.summary.healthScore - before.summary.healthScore;
+  const scoreDirection = scoreDelta > 0 ? 'improved' : scoreDelta < 0 ? 'degraded' : 'unchanged';
+
+  return {
+    timestamp: new Date().toISOString(),
+    beforeTimestamp: before.timestamp,
+    afterTimestamp: after.timestamp,
+    changes,
+    scoreDelta,
+    summary: `Score ${scoreDirection} by ${Math.abs(scoreDelta)} points (${before.summary.healthScore} → ${after.summary.healthScore}). ${changes.length} changes: ${changes.filter(c => c.type === 'added').length} added, ${changes.filter(c => c.type === 'removed').length} removed, ${changes.filter(c => c.type === 'changed').length} changed.`,
+  };
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function diffItems<T>(
+  before: T[],
+  after: T[],
+  getKey: (item: T) => string,
+  describe: (item: T) => string,
+  category: LedgerDiffEntry['category'],
+  changes: LedgerDiffEntry[],
+): void {
+  const beforeKeys = new Set(before.map(getKey));
+  const afterKeys = new Set(after.map(getKey));
+
+  // Added
+  for (const item of after) {
+    const key = getKey(item);
+    if (!beforeKeys.has(key)) {
+      changes.push({
+        type: 'added',
+        category,
+        description: describe(item),
+        entityId: key,
+      });
+    }
+  }
+
+  // Removed
+  for (const item of before) {
+    const key = getKey(item);
+    if (!afterKeys.has(key)) {
+      changes.push({
+        type: 'removed',
+        category,
+        description: describe(item),
+        entityId: key,
+      });
+    }
+  }
+}

package/src/decision-ledger/suggestions.ts

@@ -0,0 +1,287 @@
+/**
+ * Decision Ledger — Actionable Fix Suggestions
+ *
+ * For each finding from the analyzer, generates concrete,
+ * actionable suggestions with optional code skeletons.
+ */
+
+import type {
+  DeadRule,
+  UnreachableState,
+  ShadowedRule,
+  Contradiction,
+  Gap,
+  ContractCoverageGap,
+  Suggestion,
+  FindingType,
+} from './analyzer-types.js';
+
+/**
+ * Generate a suggestion for any type of finding.
+ */
+export function suggest(
+  finding: DeadRule | UnreachableState | ShadowedRule | Contradiction | Gap | ContractCoverageGap,
+  type: FindingType,
+): Suggestion {
+  switch (type) {
+    case 'dead-rule':
+      return suggestForDeadRule(finding as DeadRule);
+    case 'gap':
+      return suggestForGap(finding as Gap);
+    case 'contradiction':
+      return suggestForContradiction(finding as Contradiction);
+    case 'unreachable-state':
+      return suggestForUnreachableState(finding as UnreachableState);
+    case 'shadowed-rule':
+      return suggestForShadowedRule(finding as ShadowedRule);
+    case 'contract-gap':
+      return suggestForContractGap(finding as ContractCoverageGap);
+    default:
+      return {
+        findingType: type,
+        entityId: 'unknown',
+        message: 'Unknown finding type',
+        action: 'modify',
+        priority: 1,
+      };
+  }
+}
+
+/**
+ * Generate suggestions for all findings at once.
+ */
+export function suggestAll(findings: {
+  deadRules?: DeadRule[];
+  gaps?: Gap[];
+  contradictions?: Contradiction[];
+  unreachableStates?: UnreachableState[];
+  shadowedRules?: ShadowedRule[];
+  contractGaps?: ContractCoverageGap[];
+}): Suggestion[] {
+  const suggestions: Suggestion[] = [];
+
+  if (findings.deadRules) {
+    for (const f of findings.deadRules) {
+      suggestions.push(suggestForDeadRule(f));
+    }
+  }
+  if (findings.gaps) {
+    for (const f of findings.gaps) {
+      suggestions.push(suggestForGap(f));
+    }
+  }
+  if (findings.contradictions) {
+    for (const f of findings.contradictions) {
+      suggestions.push(suggestForContradiction(f));
+    }
+  }
+  if (findings.unreachableStates) {
+    for (const f of findings.unreachableStates) {
+      suggestions.push(suggestForUnreachableState(f));
+    }
+  }
+  if (findings.shadowedRules) {
+    for (const f of findings.shadowedRules) {
+      suggestions.push(suggestForShadowedRule(f));
+    }
+  }
+  if (findings.contractGaps) {
+    for (const f of findings.contractGaps) {
+      suggestions.push(suggestForContractGap(f));
+    }
+  }
+
+  // Sort by priority (higher first)
+  suggestions.sort((a, b) => b.priority - a.priority);
+
+  return suggestions;
+}
+
+// ─── Individual Suggestion Generators ───────────────────────────────────────
+
+function suggestForDeadRule(finding: DeadRule): Suggestion {
+  const eventList = finding.requiredEventTypes.join(', ');
+  return {
+    findingType: 'dead-rule',
+    entityId: finding.ruleId,
+    message: `Remove rule "${finding.ruleId}" or add event type "${finding.requiredEventTypes[0]}" to your event sources. Rule requires [${eventList}] but none are emitted by the application.`,
+    action: finding.requiredEventTypes.length === 1 ? 'add-event-type' : 'remove',
+    priority: 5,
+    skeleton: `// Option 1: Remove the dead rule
+registry.removeRule('${finding.ruleId}');
+
+// Option 2: Add the missing event type
+engine.step([{ tag: '${finding.requiredEventTypes[0]}', payload: {} }]);`,
+  };
+}
+
+function suggestForGap(finding: Gap): Suggestion {
+  const ruleId = finding.expectationName
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '');
+
+  switch (finding.type) {
+    case 'no-rule':
+      return {
+        findingType: 'gap',
+        entityId: finding.expectationName,
+        message: `Add a rule covering: "${finding.expectationName}". No rules or constraints address this expected behavior.`,
+        action: 'add-rule',
+        priority: 8,
+        skeleton: `defineRule({
+  id: '${ruleId}',
+  description: '${finding.description}',
+  eventTypes: ['TODO_EVENT_TYPE'],
+  impl: (state, events) => {
+    // TODO: Implement logic for "${finding.expectationName}"
+    return RuleResult.noop('Not implemented');
+  },
+  contract: defineContract({
+    ruleId: '${ruleId}',
+    behavior: '${finding.expectationName}',
+    examples: [
+      { given: 'TODO', when: 'TODO', then: 'TODO' },
+    ],
+    invariants: [],
+  }),
+});`,
+      };
+
+    case 'partial-coverage':
+      return {
+        findingType: 'gap',
+        entityId: finding.expectationName,
+        message: `Expectation "${finding.expectationName}" is partially covered by rules [${finding.partialCoverage.join(', ')}]. Add contract examples or additional rules for uncovered conditions.`,
+        action: 'modify',
+        priority: 6,
+      };
+
+    case 'no-contract':
+      return {
+        findingType: 'gap',
+        entityId: finding.expectationName,
+        message: `Rules related to "${finding.expectationName}" ([${finding.partialCoverage.join(', ')}]) lack contracts. Add contracts with examples covering the expected behavior.`,
+        action: 'add-contract',
+        priority: 7,
+      };
+
+    default:
+      return {
+        findingType: 'gap',
+        entityId: finding.expectationName,
+        message: finding.description,
+        action: 'add-rule',
+        priority: 5,
+      };
+  }
+}
+
+function suggestForContradiction(finding: Contradiction): Suggestion {
+  return {
+    findingType: 'contradiction',
+    entityId: `${finding.ruleA}↔${finding.ruleB}`,
+    message: `Rules "${finding.ruleA}" and "${finding.ruleB}" both produce fact "${finding.conflictingTag}" with potentially different payloads. Add priority ordering, merge the rules, or add distinguishing conditions.`,
+    action: 'add-priority',
+    priority: 9,
+    skeleton: `// Option 1: Add priority via meta
+defineRule({
+  id: '${finding.ruleA}',
+  meta: { priority: 10 },  // Higher priority wins
+  // ...
+});
+
+// Option 2: Add distinguishing conditions
+defineRule({
+  id: '${finding.ruleA}',
+  impl: (state, events) => {
+    // Add condition to distinguish from "${finding.ruleB}"
+    if (/* specific condition */) {
+      return RuleResult.emit([{ tag: '${finding.conflictingTag}', payload: { /* ... */ } }]);
+    }
+    return RuleResult.skip('Deferred to ${finding.ruleB}');
+  },
+});`,
+  };
+}
+
+function suggestForUnreachableState(finding: UnreachableState): Suggestion {
+  const tags = finding.factTags.join(', ');
+  return {
+    findingType: 'unreachable-state',
+    entityId: finding.factTags.join('+'),
+    message: `No rule produces facts [${tags}] together. If this state combination is valid, add a composite rule that produces all required facts.`,
+    action: 'add-rule',
+    priority: 4,
+    skeleton: `defineRule({
+  id: 'composite-${finding.factTags[0]?.replace('.', '-') ?? 'unknown'}',
+  description: 'Produces facts [${tags}] together',
+  impl: (state, events) => {
+    return RuleResult.emit([
+${finding.factTags.map(t => `      { tag: '${t}', payload: {} },`).join('\n')}
+    ]);
+  },
+});`,
+  };
+}
+
+function suggestForShadowedRule(finding: ShadowedRule): Suggestion {
+  return {
+    findingType: 'shadowed-rule',
+    entityId: finding.ruleId,
+    message: `Rule "${finding.ruleId}" is always superseded by "${finding.shadowedBy}" for event types [${finding.sharedEventTypes.join(', ')}]. Consider merging the rules or adding a distinguishing condition to "${finding.ruleId}".`,
+    action: 'merge',
+    priority: 3,
+    skeleton: `// Option 1: Remove the shadowed rule
+registry.removeRule('${finding.ruleId}');
+
+// Option 2: Add unique behavior to the shadowed rule
+defineRule({
+  id: '${finding.ruleId}',
+  impl: (state, events) => {
+    // Add condition that "${finding.shadowedBy}" doesn't cover
+    if (/* unique condition */) {
+      return RuleResult.emit([/* unique facts */]);
+    }
+    return RuleResult.skip('Handled by ${finding.shadowedBy}');
+  },
+});`,
+  };
+}
+
+function suggestForContractGap(finding: ContractCoverageGap): Suggestion {
+  let message: string;
+  let action: Suggestion['action'] = 'add-contract';
+  let priority: number;
+
+  switch (finding.type) {
+    case 'missing-error-path':
+      message = `Rule "${finding.ruleId}" has no error/failure examples in its contract. Add examples showing what happens when preconditions fail, inputs are invalid, or the rule needs to skip.`;
+      priority = 6;
+      break;
+    case 'missing-edge-case':
+      message = `Rule "${finding.ruleId}": ${finding.description}. Add contract examples covering all declared event types.`;
+      priority = 5;
+      break;
+    case 'missing-boundary':
+      message = `Rule "${finding.ruleId}" has only 1 contract example. Add boundary condition examples (empty input, maximum values, concurrent events).`;
+      priority = 4;
+      break;
+    case 'cross-reference-broken':
+      message = `Rule "${finding.ruleId}": ${finding.description}. Verify the referenced fact producer exists.`;
+      action = 'modify';
+      priority = 7;
+      break;
+    default:
+      message = finding.description;
+      priority = 3;
+  }
+
+  return {
+    findingType: 'contract-gap',
+    entityId: finding.ruleId,
+    message,
+    action,
+    priority,
+  };
+}