jumpstart-mode 1.1.12 → 1.1.13

package/bin/lib/data-contracts.js

@@ -0,0 +1,129 @@
+/**
+ * data-contracts.js — Data Contract Governance (Item 84)
+ *
+ * Schema evolution, versioning, lineage, and producer-consumer compatibility.
+ *
+ * Usage:
+ *   node bin/lib/data-contracts.js register|validate|lineage|report [options]
+ *
+ * State file: .jumpstart/state/data-contracts.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'data-contracts.json');
+
+const COMPATIBILITY_MODES = ['backward', 'forward', 'full', 'none'];
+
+function defaultState() {
+  return { version: '1.0.0', contracts: [], lineage: [], last_updated: null };
+}
+
+function loadState(stateFile) {
+  const fp = stateFile || DEFAULT_STATE_FILE;
+  if (!fs.existsSync(fp)) return defaultState();
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); }
+  catch { return defaultState(); }
+}
+
+function saveState(state, stateFile) {
+  const fp = stateFile || DEFAULT_STATE_FILE;
+  const dir = path.dirname(fp);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  state.last_updated = new Date().toISOString();
+  fs.writeFileSync(fp, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+function registerContract(name, schema, options = {}) {
+  if (!name || !schema) return { success: false, error: 'name and schema are required' };
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const contract = {
+    id: `DC-${Date.now()}`,
+    name,
+    version: options.version || '1.0.0',
+    schema,
+    producer: options.producer || null,
+    consumers: options.consumers || [],
+    compatibility: options.compatibility || 'backward',
+    created_at: new Date().toISOString()
+  };
+
+  state.contracts.push(contract);
+  saveState(state, stateFile);
+
+  return { success: true, contract };
+}
+
+function validateCompatibility(contractId, newSchema, options = {}) {
+  if (!contractId || !newSchema) return { success: false, error: 'contractId and newSchema are required' };
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const contract = state.contracts.find(c => c.id === contractId);
+  if (!contract) return { success: false, error: `Contract ${contractId} not found` };
+
+  const oldFields = new Set(Object.keys(contract.schema));
+  const newFields = new Set(Object.keys(newSchema));
+
+  const added = [...newFields].filter(f => !oldFields.has(f));
+  const removed = [...oldFields].filter(f => !newFields.has(f));
+
+  let compatible = true;
+  const issues = [];
+
+  if (contract.compatibility === 'backward' && removed.length > 0) {
+    compatible = false;
+    issues.push({ type: 'breaking_removal', fields: removed });
+  }
+  if (contract.compatibility === 'forward' && added.length > 0) {
+    compatible = false;
+    issues.push({ type: 'forward_incompatible', fields: added });
+  }
+
+  return { success: true, compatible, issues, added, removed };
+}
+
+function trackLineage(sourceContract, targetContract, options = {}) {
+  if (!sourceContract || !targetContract) return { success: false, error: 'source and target contracts are required' };
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const entry = {
+    source: sourceContract,
+    target: targetContract,
+    transformation: options.transformation || 'direct',
+    created_at: new Date().toISOString()
+  };
+
+  state.lineage.push(entry);
+  saveState(state, stateFile);
+
+  return { success: true, lineage: entry };
+}
+
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  return {
+    success: true,
+    total_contracts: state.contracts.length,
+    total_lineage: state.lineage.length,
+    contracts: state.contracts.map(c => ({ id: c.id, name: c.name, version: c.version, compatibility: c.compatibility })),
+    lineage: state.lineage
+  };
+}
+
+module.exports = {
+  registerContract, validateCompatibility, trackLineage, generateReport,
+  loadState, saveState, defaultState,
+  COMPATIBILITY_MODES
+};

package/bin/lib/db-evolution.js

@@ -0,0 +1,158 @@
+/**
+ * db-evolution.js — Database Evolution Planner (Item 49)
+ *
+ * Generate migration strategy, backward compatibility plan,
+ * data validation, and rollback approach.
+ *
+ * Usage:
+ *   node bin/lib/db-evolution.js plan|validate|report [options]
+ *
+ * State file: .jumpstart/state/db-evolution.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'db-evolution.json');
+
+const MIGRATION_TYPES = ['add-column', 'drop-column', 'rename-column', 'add-table', 'drop-table',
+  'add-index', 'drop-index', 'modify-type', 'add-constraint', 'data-migration'];
+
+const RISK_LEVELS = {
+  'add-column': 'low', 'add-table': 'low', 'add-index': 'low',
+  'rename-column': 'medium', 'modify-type': 'medium', 'add-constraint': 'medium',
+  'drop-column': 'high', 'drop-table': 'high', 'drop-index': 'medium',
+  'data-migration': 'high'
+};
+
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    migrations: [],
+    rollback_scripts: []
+  };
+}
+
+function loadState(stateFile) {
+  const filePath = stateFile || DEFAULT_STATE_FILE;
+  if (!fs.existsSync(filePath)) return defaultState();
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }
+  catch { return defaultState(); }
+}
+
+function saveState(state, stateFile) {
+  const filePath = stateFile || DEFAULT_STATE_FILE;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  state.last_updated = new Date().toISOString();
+  fs.writeFileSync(filePath, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Plan a database migration.
+ *
+ * @param {object} migration - { name, type, description, table?, column?, backward_compatible? }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function planMigration(migration, options = {}) {
+  if (!migration || !migration.name || !migration.type) {
+    return { success: false, error: 'name and type are required' };
+  }
+
+  if (!MIGRATION_TYPES.includes(migration.type)) {
+    return { success: false, error: `Invalid type. Must be one of: ${MIGRATION_TYPES.join(', ')}` };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const risk = RISK_LEVELS[migration.type] || 'medium';
+
+  const mig = {
+    id: `DB-${(state.migrations.length + 1).toString().padStart(3, '0')}`,
+    name: migration.name,
+    type: migration.type,
+    description: migration.description || '',
+    table: migration.table || null,
+    column: migration.column || null,
+    risk_level: risk,
+    backward_compatible: migration.backward_compatible !== false,
+    rollback_strategy: migration.rollback_strategy || (risk === 'low' ? 'reverse-migration' : 'backup-restore'),
+    validation_steps: migration.validation_steps || ['row-count', 'schema-compare'],
+    status: 'planned',
+    created_at: new Date().toISOString()
+  };
+
+  state.migrations.push(mig);
+  saveState(state, stateFile);
+
+  return { success: true, migration: mig };
+}
+
+/**
+ * Validate migration plan for safety.
+ *
+ * @param {string} migrationId
+ * @param {object} [options]
+ * @returns {object}
+ */
+function validateMigration(migrationId, options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const mig = state.migrations.find(m => m.id === migrationId);
+  if (!mig) return { success: false, error: `Migration not found: ${migrationId}` };
+
+  const warnings = [];
+  if (!mig.backward_compatible) warnings.push('Migration is not backward compatible');
+  if (mig.risk_level === 'high') warnings.push('High-risk migration — requires explicit approval');
+  if (!mig.rollback_strategy) warnings.push('No rollback strategy defined');
+  if (mig.type === 'drop-table' || mig.type === 'drop-column') {
+    warnings.push('Destructive operation — ensure data backup exists');
+  }
+
+  return {
+    success: true,
+    migration_id: migrationId,
+    safe: warnings.length === 0,
+    warnings,
+    risk_level: mig.risk_level,
+    backward_compatible: mig.backward_compatible
+  };
+}
+
+/**
+ * Generate DB evolution report.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  return {
+    success: true,
+    total_migrations: state.migrations.length,
+    by_type: state.migrations.reduce((acc, m) => { acc[m.type] = (acc[m.type] || 0) + 1; return acc; }, {}),
+    by_risk: state.migrations.reduce((acc, m) => { acc[m.risk_level] = (acc[m.risk_level] || 0) + 1; return acc; }, {}),
+    high_risk: state.migrations.filter(m => m.risk_level === 'high'),
+    migrations: state.migrations
+  };
+}
+
+module.exports = {
+  defaultState,
+  loadState,
+  saveState,
+  planMigration,
+  validateMigration,
+  generateReport,
+  MIGRATION_TYPES,
+  RISK_LEVELS
+};

package/bin/lib/decision-conflicts.js

@@ -0,0 +1,299 @@
+/**
+ * decision-conflicts.js — Decision Conflict Detection
+ *
+ * Detect when ADRs, PRD decisions, architecture docs, and code
+ * choices contradict one another.
+ *
+ * Usage:
+ *   node bin/lib/decision-conflicts.js detect|report [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CONFLICT_TYPES = ['technology', 'pattern', 'constraint', 'requirement', 'terminology'];
+
+/**
+ * Extract decisions from ADR files.
+ * @param {string} decisionsDir - Path to specs/decisions/.
+ * @returns {object[]}
+ */
+function extractADRDecisions(decisionsDir) {
+  const decisions = [];
+
+  if (!fs.existsSync(decisionsDir)) return decisions;
+
+  const files = fs.readdirSync(decisionsDir).filter(f => f.endsWith('.md'));
+  for (const file of files) {
+    const content = fs.readFileSync(path.join(decisionsDir, file), 'utf8');
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    const statusMatch = content.match(/\*\*Status[:\s]*\*?\*?\s*(.+)/i) || content.match(/Status[:\s]+(.+)/i);
+    const decisionMatch = content.match(/##\s+Decision\s*\n([\s\S]*?)(?=\n##|\n$|$)/i);
+
+    decisions.push({
+      source: `specs/decisions/${file}`,
+      type: 'adr',
+      title: titleMatch ? titleMatch[1].trim() : file,
+      status: statusMatch ? statusMatch[1].trim().toLowerCase() : 'unknown',
+      decision_text: decisionMatch ? decisionMatch[1].trim() : '',
+      technologies: extractTechReferences(content),
+      patterns: extractPatternReferences(content)
+    });
+  }
+
+  return decisions;
+}
+
+/**
+ * Extract decisions from architecture doc.
+ * @param {string} archPath
+ * @returns {object[]}
+ */
+function extractArchDecisions(archPath) {
+  if (!fs.existsSync(archPath)) return [];
+
+  const content = fs.readFileSync(archPath, 'utf8');
+  const decisions = [];
+  const sections = content.split(/^##\s+/m);
+
+  for (const section of sections) {
+    if (section.trim().length === 0) continue;
+    const titleLine = section.split('\n')[0].trim();
+    const sectionContent = section.split('\n').slice(1).join('\n');
+
+    decisions.push({
+      source: 'specs/architecture.md',
+      type: 'architecture',
+      title: titleLine,
+      decision_text: sectionContent.trim().slice(0, 500),
+      technologies: extractTechReferences(sectionContent),
+      patterns: extractPatternReferences(sectionContent)
+    });
+  }
+
+  return decisions;
+}
+
+/**
+ * Extract decisions from PRD.
+ * @param {string} prdPath
+ * @returns {object[]}
+ */
+function extractPRDDecisions(prdPath) {
+  if (!fs.existsSync(prdPath)) return [];
+
+  const content = fs.readFileSync(prdPath, 'utf8');
+  const decisions = [];
+
+  // Extract NFRs and constraints
+  const nfrSection = content.match(/##\s+(?:Non-Functional|NFR|Constraints).*?\n([\s\S]*?)(?=\n##|\n$|$)/i);
+  if (nfrSection) {
+    decisions.push({
+      source: 'specs/prd.md',
+      type: 'prd',
+      title: 'Non-Functional Requirements',
+      decision_text: nfrSection[1].trim().slice(0, 500),
+      technologies: extractTechReferences(nfrSection[1]),
+      patterns: extractPatternReferences(nfrSection[1])
+    });
+  }
+
+  // Extract technology decisions mentioned in PRD
+  const techSection = content.match(/##\s+(?:Tech|Technology|Stack|Technical).*?\n([\s\S]*?)(?=\n##|\n$|$)/i);
+  if (techSection) {
+    decisions.push({
+      source: 'specs/prd.md',
+      type: 'prd',
+      title: 'Technology Decisions',
+      decision_text: techSection[1].trim().slice(0, 500),
+      technologies: extractTechReferences(techSection[1]),
+      patterns: extractPatternReferences(techSection[1])
+    });
+  }
+
+  return decisions;
+}
+
+/**
+ * Extract technology references from text.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractTechReferences(text) {
+  const techTerms = [
+    'react', 'vue', 'angular', 'svelte', 'next\\.js', 'nuxt',
+    'express', 'fastify', 'koa', 'hapi', 'nestjs',
+    'postgresql', 'mysql', 'mongodb', 'redis', 'sqlite', 'dynamodb',
+    'docker', 'kubernetes', 'aws', 'azure', 'gcp',
+    'graphql', 'rest', 'grpc', 'websocket',
+    'typescript', 'javascript', 'python', 'go', 'rust', 'java',
+    'kafka', 'rabbitmq', 'sqs', 'nats',
+    'openai', 'langchain', 'pinecone', 'chromadb'
+  ];
+
+  const found = [];
+  for (const tech of techTerms) {
+    const pattern = new RegExp(`\\b${tech}\\b`, 'gi');
+    if (pattern.test(text)) {
+      found.push(tech.replace(/\\\./g, '.'));
+    }
+  }
+  return [...new Set(found)];
+}
+
+/**
+ * Extract architectural pattern references from text.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractPatternReferences(text) {
+  const patternTerms = [
+    'microservice', 'monolith', 'serverless', 'event-driven', 'event sourcing',
+    'cqrs', 'saga', 'domain-driven', 'hexagonal', 'clean architecture',
+    'mvc', 'mvvm', 'repository pattern', 'factory', 'singleton',
+    'pub-sub', 'message queue', 'circuit breaker', 'api gateway',
+    'rag', 'agent', 'multi-agent'
+  ];
+
+  const found = [];
+  for (const pattern of patternTerms) {
+    const regex = new RegExp(`\\b${pattern}s?\\b`, 'gi');
+    if (regex.test(text)) {
+      found.push(pattern);
+    }
+  }
+  return [...new Set(found)];
+}
+
+/**
+ * Detect conflicts between decisions.
+ *
+ * @param {object[]} decisions - Array of extracted decisions.
+ * @returns {object[]}
+ */
+function findConflicts(decisions) {
+  const conflicts = [];
+
+  // Technology conflicts: same category but different choices
+  const techBySource = {};
+  for (const d of decisions) {
+    for (const tech of d.technologies) {
+      if (!techBySource[tech]) techBySource[tech] = [];
+      techBySource[tech].push(d);
+    }
+  }
+
+  // Check for competing technologies in the same category
+  const competing = {
+    frontend: ['react', 'vue', 'angular', 'svelte'],
+    backend: ['express', 'fastify', 'koa', 'hapi', 'nestjs'],
+    database: ['postgresql', 'mysql', 'mongodb', 'sqlite', 'dynamodb'],
+    messaging: ['kafka', 'rabbitmq', 'sqs', 'nats'],
+    cloud: ['aws', 'azure', 'gcp']
+  };
+
+  for (const [category, techs] of Object.entries(competing)) {
+    const usedTechs = techs.filter(t => techBySource[t]);
+    if (usedTechs.length > 1) {
+      const sources = usedTechs.flatMap(t => techBySource[t].map(d => d.source));
+      conflicts.push({
+        type: 'technology',
+        category,
+        description: `Competing ${category} technologies referenced: ${usedTechs.join(', ')}`,
+        technologies: usedTechs,
+        sources: [...new Set(sources)],
+        severity: 'warning'
+      });
+    }
+  }
+
+  // Pattern conflicts: contradictory patterns
+  const patternBySource = {};
+  for (const d of decisions) {
+    for (const pattern of d.patterns) {
+      if (!patternBySource[pattern]) patternBySource[pattern] = [];
+      patternBySource[pattern].push(d);
+    }
+  }
+
+  const contradictory = [
+    ['microservice', 'monolith'],
+    ['event sourcing', 'cqrs'],
+    ['serverless', 'kubernetes']
+  ];
+
+  for (const [p1, p2] of contradictory) {
+    if (patternBySource[p1] && patternBySource[p2]) {
+      const sources = [
+        ...patternBySource[p1].map(d => d.source),
+        ...patternBySource[p2].map(d => d.source)
+      ];
+      conflicts.push({
+        type: 'pattern',
+        description: `Potentially contradictory patterns: "${p1}" and "${p2}"`,
+        patterns: [p1, p2],
+        sources: [...new Set(sources)],
+        severity: 'warning'
+      });
+    }
+  }
+
+  return conflicts;
+}
+
+/**
+ * Detect decision conflicts across all project artifacts.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function detectConflicts(root, options = {}) {
+  const decisions = [];
+
+  // Collect decisions from all sources
+  const decisionsDir = path.join(root, 'specs', 'decisions');
+  decisions.push(...extractADRDecisions(decisionsDir));
+
+  const archPath = path.join(root, 'specs', 'architecture.md');
+  decisions.push(...extractArchDecisions(archPath));
+
+  const prdPath = path.join(root, 'specs', 'prd.md');
+  decisions.push(...extractPRDDecisions(prdPath));
+
+  if (decisions.length === 0) {
+    return { success: true, conflicts: [], message: 'No decisions found to analyze' };
+  }
+
+  const conflicts = findConflicts(decisions);
+
+  return {
+    success: true,
+    total_decisions: decisions.length,
+    decisions_by_source: {
+      adr: decisions.filter(d => d.type === 'adr').length,
+      architecture: decisions.filter(d => d.type === 'architecture').length,
+      prd: decisions.filter(d => d.type === 'prd').length
+    },
+    conflicts,
+    summary: {
+      total_conflicts: conflicts.length,
+      technology_conflicts: conflicts.filter(c => c.type === 'technology').length,
+      pattern_conflicts: conflicts.filter(c => c.type === 'pattern').length,
+      has_conflicts: conflicts.length > 0
+    }
+  };
+}
+
+module.exports = {
+  extractADRDecisions,
+  extractArchDecisions,
+  extractPRDDecisions,
+  extractTechReferences,
+  extractPatternReferences,
+  findConflicts,
+  detectConflicts,
+  CONFLICT_TYPES
+};