@girardmedia/bootspring 2.5.0 → 2.5.2

package/generators/decisions.js

@@ -1,655 +0,0 @@
-/**
- * Bootspring DECISIONS.md Generator
- *
- * Generates Architecture Decision Record (ADR) documentation
- * with decisions, rationale, trade-offs, outcomes, and lessons learned.
- *
- * @package bootspring
- * @module generators/decisions
- */
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Decision status values
- */
-const DECISION_STATUS = {
-  PROPOSED: 'proposed',
-  ACCEPTED: 'accepted',
-  DEPRECATED: 'deprecated',
-  SUPERSEDED: 'superseded',
-  REJECTED: 'rejected'
-};
-
-/**
- * Decision categories
- */
-const DECISION_CATEGORIES = {
-  ARCHITECTURE: { label: 'Architecture', emoji: '🏗️' },
-  TECHNOLOGY: { label: 'Technology', emoji: '⚙️' },
-  DESIGN: { label: 'Design', emoji: '🎨' },
-  SECURITY: { label: 'Security', emoji: '🔐' },
-  PERFORMANCE: { label: 'Performance', emoji: '⚡' },
-  INFRASTRUCTURE: { label: 'Infrastructure', emoji: '☁️' },
-  PROCESS: { label: 'Process', emoji: '📋' },
-  API: { label: 'API', emoji: '🔌' },
-  DATA: { label: 'Data', emoji: '💾' },
-  UI_UX: { label: 'UI/UX', emoji: '🖥️' }
-};
-
-/**
- * Impact levels
- */
-const IMPACT_LEVELS = {
-  HIGH: { label: 'High', emoji: '🔴', description: 'Affects core architecture or many components' },
-  MEDIUM: { label: 'Medium', emoji: '🟡', description: 'Affects specific features or modules' },
-  LOW: { label: 'Low', emoji: '🟢', description: 'Localized impact, easily reversible' }
-};
-
-/**
- * Decisions Document Generator
- */
-class DecisionsGenerator {
-  constructor(options = {}) {
-    this.projectRoot = options.projectRoot || process.cwd();
-    this.decisionsPath = path.join(this.projectRoot, '.bootspring', 'decisions.json');
-  }
-
-  /**
-   * Load decisions data
-   */
-  loadDecisions() {
-    try {
-      if (fs.existsSync(this.decisionsPath)) {
-        return JSON.parse(fs.readFileSync(this.decisionsPath, 'utf-8'));
-      }
-    } catch (_err) {
-      // Return default
-    }
-
-    return {
-      project: this.getProjectName(),
-      decisions: [],
-      metadata: {
-        created: new Date().toISOString(),
-        lastUpdated: new Date().toISOString(),
-        totalDecisions: 0
-      }
-    };
-  }
-
-  /**
-   * Save decisions data
-   */
-  saveDecisions(data) {
-    data.metadata.lastUpdated = new Date().toISOString();
-    data.metadata.totalDecisions = data.decisions.length;
-
-    const dir = path.dirname(this.decisionsPath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-    fs.writeFileSync(this.decisionsPath, JSON.stringify(data, null, 2));
-  }
-
-  /**
-   * Get project name from package.json
-   */
-  getProjectName() {
-    try {
-      const pkgPath = path.join(this.projectRoot, 'package.json');
-      if (fs.existsSync(pkgPath)) {
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-        return pkg.name || 'Project';
-      }
-    } catch (_err) {
-      // Default
-    }
-    return 'Project';
-  }
-
-  /**
-   * Generate a new decision ID
-   */
-  generateDecisionId(decisions) {
-    const maxId = decisions.reduce((max, d) => {
-      const num = parseInt(d.id.replace('ADR-', ''), 10);
-      return num > max ? num : max;
-    }, 0);
-    return `ADR-${String(maxId + 1).padStart(4, '0')}`;
-  }
-
-  /**
-   * Add a new decision
-   */
-  addDecision(data, decision) {
-    const id = this.generateDecisionId(data.decisions);
-
-    const newDecision = {
-      id,
-      title: decision.title,
-      status: decision.status || DECISION_STATUS.PROPOSED,
-      category: decision.category || 'ARCHITECTURE',
-      impact: decision.impact || 'MEDIUM',
-      date: new Date().toISOString().split('T')[0],
-
-      // Context
-      context: decision.context || '',
-      problem: decision.problem || '',
-
-      // Decision
-      decision: decision.decision || '',
-      rationale: decision.rationale || '',
-
-      // Options considered
-      options: decision.options || [],
-
-      // Consequences
-      consequences: {
-        positive: decision.consequences?.positive || [],
-        negative: decision.consequences?.negative || [],
-        risks: decision.consequences?.risks || []
-      },
-
-      // Related
-      relatedDecisions: decision.relatedDecisions || [],
-      supersedes: decision.supersedes || null,
-      supersededBy: null,
-
-      // Tracking
-      outcome: null,
-      lessonsLearned: [],
-      reviewDate: decision.reviewDate || null,
-
-      // Metadata
-      authors: decision.authors || [],
-      tags: decision.tags || [],
-      links: decision.links || []
-    };
-
-    data.decisions.push(newDecision);
-
-    // If this supersedes another decision, update that one
-    if (decision.supersedes) {
-      const superseded = data.decisions.find(d => d.id === decision.supersedes);
-      if (superseded) {
-        superseded.status = DECISION_STATUS.SUPERSEDED;
-        superseded.supersededBy = id;
-      }
-    }
-
-    return newDecision;
-  }
-
-  /**
-   * Update decision status
-   */
-  updateDecisionStatus(data, decisionId, status, notes = null) {
-    const decision = data.decisions.find(d => d.id === decisionId);
-    if (decision) {
-      decision.status = status;
-      if (notes) {
-        decision.statusNotes = notes;
-      }
-      decision.lastUpdated = new Date().toISOString();
-    }
-    return decision;
-  }
-
-  /**
-   * Record outcome for a decision
-   */
-  recordOutcome(data, decisionId, outcome) {
-    const decision = data.decisions.find(d => d.id === decisionId);
-    if (decision) {
-      decision.outcome = {
-        status: outcome.status, // 'success', 'partial', 'failure'
-        description: outcome.description,
-        metrics: outcome.metrics || {},
-        date: new Date().toISOString().split('T')[0]
-      };
-    }
-    return decision;
-  }
-
-  /**
-   * Add lessons learned
-   */
-  addLessonLearned(data, decisionId, lesson) {
-    const decision = data.decisions.find(d => d.id === decisionId);
-    if (decision) {
-      decision.lessonsLearned.push({
-        lesson,
-        date: new Date().toISOString().split('T')[0]
-      });
-    }
-    return decision;
-  }
-
-  /**
-   * Generate DECISIONS.md content
-   */
-  generate(data = null) {
-    if (!data) {
-      data = this.loadDecisions();
-    }
-
-    const sections = [];
-    const now = new Date().toISOString().split('T')[0];
-
-    // Header
-    sections.push(`# Architecture Decision Records
-
-**Project:** ${data.project}
-**Last Updated:** ${now}
-**Total Decisions:** ${data.decisions.length}
-
----
-
-## Overview
-
-This document tracks significant architecture and design decisions made during the development of this project. Each decision is recorded as an Architecture Decision Record (ADR).
-
-### Status Legend
-
-| Status | Meaning |
-|--------|---------|
-| 📝 Proposed | Under discussion, not yet accepted |
-| ✅ Accepted | Decision has been approved and is in effect |
-| ⚠️ Deprecated | Decision is being phased out |
-| 🔄 Superseded | Replaced by a newer decision |
-| ❌ Rejected | Decision was considered but not adopted |
-
----`);
-
-    // Summary Table
-    const activeDecisions = data.decisions.filter(d =>
-      d.status === DECISION_STATUS.ACCEPTED || d.status === DECISION_STATUS.PROPOSED
-    );
-
-    if (data.decisions.length > 0) {
-      sections.push(`## Decision Index
-
-| ID | Title | Category | Status | Impact | Date |
-|----|-------|----------|--------|--------|------|
-${data.decisions.map(d => {
-    const category = DECISION_CATEGORIES[d.category] || { emoji: '📋', label: d.category };
-    const impact = IMPACT_LEVELS[d.impact] || { emoji: '🟡', label: d.impact };
-    return `| [${d.id}](#${d.id.toLowerCase()}) | ${d.title} | ${category.emoji} ${category.label} | ${this.formatStatus(d.status)} | ${impact.emoji} ${impact.label} | ${d.date} |`;
-  }).join('\n')}
-
----`);
-    }
-
-    // Individual Decisions
-    if (data.decisions.length > 0) {
-      sections.push('## Decisions\n');
-
-      for (const decision of data.decisions) {
-        sections.push(this.formatDecision(decision));
-      }
-    } else {
-      sections.push(`## Decisions
-
-_No decisions recorded yet._
-
-To add a decision, use:
-\`\`\`bash
-bootspring docs decisions add "Decision Title"
-\`\`\`
-
----`);
-    }
-
-    // Statistics
-    const stats = this.calculateStatistics(data);
-    sections.push(`## Statistics
-
-| Metric | Value |
-|--------|-------|
-| Total Decisions | ${stats.total} |
-| Accepted | ${stats.accepted} |
-| Proposed | ${stats.proposed} |
-| Superseded | ${stats.superseded} |
-| With Outcomes | ${stats.withOutcomes} |
-| Success Rate | ${stats.successRate}% |
-
-### By Category
-
-${Object.entries(stats.byCategory).map(([cat, count]) => {
-    const category = DECISION_CATEGORIES[cat] || { emoji: '📋', label: cat };
-    return `- ${category.emoji} **${category.label}:** ${count}`;
-  }).join('\n')}
-
-### By Impact
-
-${Object.entries(stats.byImpact).map(([imp, count]) => {
-    const impact = IMPACT_LEVELS[imp] || { emoji: '🟡', label: imp };
-    return `- ${impact.emoji} **${impact.label}:** ${count}`;
-  }).join('\n')}
-
----`);
-
-    // Lessons Learned Summary
-    const lessonsLearned = data.decisions
-      .filter(d => d.lessonsLearned && d.lessonsLearned.length > 0)
-      .flatMap(d => d.lessonsLearned.map(l => ({ ...l, decisionId: d.id, title: d.title })));
-
-    if (lessonsLearned.length > 0) {
-      sections.push(`## Lessons Learned
-
-${lessonsLearned.slice(0, 10).map(l => `- **[${l.decisionId}]** ${l.lesson}
-  _From: ${l.title} (${l.date})_`).join('\n\n')}
-
----`);
-    }
-
-    // Footer
-    sections.push(`---
-
-*Generated by [Bootspring](https://bootspring.com) Decisions Generator*
-
-### Adding New Decisions
-
-\`\`\`bash
-# Add a new decision interactively
-bootspring docs decisions add
-
-# Add with title
-bootspring docs decisions add "Use PostgreSQL for Primary Database"
-
-# View decision details
-bootspring docs decisions show ADR-0001
-\`\`\`
-`);
-
-    return sections.join('\n\n');
-  }
-
-  /**
-   * Format status with emoji
-   */
-  formatStatus(status) {
-    const statusMap = {
-      [DECISION_STATUS.PROPOSED]: '📝 Proposed',
-      [DECISION_STATUS.ACCEPTED]: '✅ Accepted',
-      [DECISION_STATUS.DEPRECATED]: '⚠️ Deprecated',
-      [DECISION_STATUS.SUPERSEDED]: '🔄 Superseded',
-      [DECISION_STATUS.REJECTED]: '❌ Rejected'
-    };
-    return statusMap[status] || status;
-  }
-
-  /**
-   * Format a single decision as markdown
-   */
-  formatDecision(decision) {
-    const category = DECISION_CATEGORIES[decision.category] || { emoji: '📋', label: decision.category };
-    const impact = IMPACT_LEVELS[decision.impact] || { emoji: '🟡', label: decision.impact };
-
-    let md = `### ${decision.id}
-
-# ${decision.title}
-
-**Date:** ${decision.date}
-**Status:** ${this.formatStatus(decision.status)}
-**Category:** ${category.emoji} ${category.label}
-**Impact:** ${impact.emoji} ${impact.label}
-${decision.authors.length > 0 ? `**Authors:** ${decision.authors.join(', ')}` : ''}
-${decision.tags.length > 0 ? `**Tags:** ${decision.tags.map(t => `\`${t}\``).join(' ')}` : ''}
-
-#### Context
-
-${decision.context || '_No context provided._'}
-
-#### Problem
-
-${decision.problem || '_No problem statement provided._'}
-
-#### Decision
-
-${decision.decision || '_No decision recorded._'}
-
-#### Rationale
-
-${decision.rationale || '_No rationale provided._'}
-`;
-
-    // Options considered
-    if (decision.options && decision.options.length > 0) {
-      md += `
-#### Options Considered
-
-${decision.options.map((opt, i) => {
-    const chosen = opt.chosen ? ' ✅ **CHOSEN**' : '';
-    return `**Option ${i + 1}: ${opt.name}**${chosen}
-
-${opt.description || ''}
-
-- Pros: ${(opt.pros || []).join(', ') || 'None listed'}
-- Cons: ${(opt.cons || []).join(', ') || 'None listed'}`;
-  }).join('\n\n')}
-`;
-    }
-
-    // Consequences
-    md += `
-#### Consequences
-
-**Positive:**
-${decision.consequences.positive.length > 0 ? decision.consequences.positive.map(c => `- ✅ ${c}`).join('\n') : '- _None identified_'}
-
-**Negative:**
-${decision.consequences.negative.length > 0 ? decision.consequences.negative.map(c => `- ⚠️ ${c}`).join('\n') : '- _None identified_'}
-
-**Risks:**
-${decision.consequences.risks.length > 0 ? decision.consequences.risks.map(c => `- 🔴 ${c}`).join('\n') : '- _None identified_'}
-`;
-
-    // Related decisions
-    if (decision.relatedDecisions.length > 0) {
-      md += `
-#### Related Decisions
-
-${decision.relatedDecisions.map(r => `- [${r}](#${r.toLowerCase()})`).join('\n')}
-`;
-    }
-
-    // Supersedes
-    if (decision.supersedes) {
-      md += `
-#### Supersedes
-
-This decision supersedes [${decision.supersedes}](#${decision.supersedes.toLowerCase()}).
-`;
-    }
-
-    // Superseded by
-    if (decision.supersededBy) {
-      md += `
-#### Superseded By
-
-This decision has been superseded by [${decision.supersededBy}](#${decision.supersededBy.toLowerCase()}).
-`;
-    }
-
-    // Outcome
-    if (decision.outcome) {
-      const outcomeEmoji = decision.outcome.status === 'success' ? '✅' :
-        decision.outcome.status === 'partial' ? '🟡' : '❌';
-
-      md += `
-#### Outcome
-
-**Status:** ${outcomeEmoji} ${decision.outcome.status.charAt(0).toUpperCase() + decision.outcome.status.slice(1)}
-**Date:** ${decision.outcome.date}
-
-${decision.outcome.description || ''}
-`;
-
-      if (decision.outcome.metrics && Object.keys(decision.outcome.metrics).length > 0) {
-        md += `
-**Metrics:**
-${Object.entries(decision.outcome.metrics).map(([k, v]) => `- ${k}: ${v}`).join('\n')}
-`;
-      }
-    }
-
-    // Lessons learned
-    if (decision.lessonsLearned && decision.lessonsLearned.length > 0) {
-      md += `
-#### Lessons Learned
-
-${decision.lessonsLearned.map(l => `- ${l.lesson} _(${l.date})_`).join('\n')}
-`;
-    }
-
-    // Links
-    if (decision.links && decision.links.length > 0) {
-      md += `
-#### References
-
-${decision.links.map(l => `- [${l.title || l.url}](${l.url})`).join('\n')}
-`;
-    }
-
-    md += '\n---\n';
-
-    return md;
-  }
-
-  /**
-   * Calculate statistics
-   */
-  calculateStatistics(data) {
-    const decisions = data.decisions;
-
-    const stats = {
-      total: decisions.length,
-      accepted: decisions.filter(d => d.status === DECISION_STATUS.ACCEPTED).length,
-      proposed: decisions.filter(d => d.status === DECISION_STATUS.PROPOSED).length,
-      superseded: decisions.filter(d => d.status === DECISION_STATUS.SUPERSEDED).length,
-      deprecated: decisions.filter(d => d.status === DECISION_STATUS.DEPRECATED).length,
-      rejected: decisions.filter(d => d.status === DECISION_STATUS.REJECTED).length,
-      withOutcomes: decisions.filter(d => d.outcome).length,
-      byCategory: {},
-      byImpact: {}
-    };
-
-    // Success rate
-    const withOutcomes = decisions.filter(d => d.outcome);
-    const successful = withOutcomes.filter(d => d.outcome.status === 'success');
-    stats.successRate = withOutcomes.length > 0 ? Math.round((successful.length / withOutcomes.length) * 100) : 0;
-
-    // By category
-    for (const d of decisions) {
-      stats.byCategory[d.category] = (stats.byCategory[d.category] || 0) + 1;
-    }
-
-    // By impact
-    for (const d of decisions) {
-      stats.byImpact[d.impact] = (stats.byImpact[d.impact] || 0) + 1;
-    }
-
-    return stats;
-  }
-
-  /**
-   * Import decisions from decision intelligence module
-   */
-  async importFromDecisionIntelligence(data) {
-    try {
-      const { DecisionIntelligence } = require('../intelligence/decision-intelligence');
-      const di = new DecisionIntelligence(this.projectRoot);
-      const recentDecisions = await di.getRecentDecisions(50);
-
-      for (const d of recentDecisions) {
-        // Check if already exists
-        const exists = data.decisions.some(existing =>
-          existing.title.toLowerCase() === d.context?.toLowerCase() ||
-          existing.decision === d.chosen
-        );
-
-        if (!exists && d.type && d.chosen) {
-          this.addDecision(data, {
-            title: d.context || d.type,
-            category: this.mapTypeToCategory(d.type),
-            decision: d.chosen,
-            rationale: d.rationale || '',
-            status: DECISION_STATUS.ACCEPTED,
-            tags: d.tags || []
-          });
-        }
-      }
-    } catch (_err) {
-      // Decision intelligence not available
-    }
-
-    return data;
-  }
-
-  /**
-   * Map decision type to category
-   */
-  mapTypeToCategory(type) {
-    const mapping = {
-      architecture: 'ARCHITECTURE',
-      technology: 'TECHNOLOGY',
-      database: 'DATA',
-      api: 'API',
-      security: 'SECURITY',
-      performance: 'PERFORMANCE',
-      ui: 'UI_UX',
-      deployment: 'INFRASTRUCTURE'
-    };
-    return mapping[type] || 'ARCHITECTURE';
-  }
-}
-
-/**
- * Generate DECISIONS.md
- */
-function generate(options = {}) {
-  const generator = new DecisionsGenerator(options);
-  const data = generator.loadDecisions();
-  return generator.generate(data);
-}
-
-/**
- * Load decisions data
- */
-function loadDecisions(options = {}) {
-  const generator = new DecisionsGenerator(options);
-  return generator.loadDecisions();
-}
-
-/**
- * Save decisions data
- */
-function saveDecisions(data, options = {}) {
-  const generator = new DecisionsGenerator(options);
-  generator.saveDecisions(data);
-}
-
-/**
- * Add a new decision
- */
-function addDecision(decision, options = {}) {
-  const generator = new DecisionsGenerator(options);
-  const data = generator.loadDecisions();
-  const newDecision = generator.addDecision(data, decision);
-  generator.saveDecisions(data);
-  return newDecision;
-}
-
-module.exports = {
-  DecisionsGenerator,
-  generate,
-  loadDecisions,
-  saveDecisions,
-  addDecision,
-  DECISION_STATUS,
-  DECISION_CATEGORIES,
-  IMPACT_LEVELS
-};