jumpstart-mode 1.1.11 → 1.1.13

package/bin/lib/repo-graph.js

@@ -0,0 +1,262 @@
+/**
+ * repo-graph.js — Automated Repo Understanding Graph
+ *
+ * Builds and persists a semantic graph of domains, modules, APIs,
+ * ownership, decisions, and dependencies for a project repository.
+ *
+ * Usage:
+ *   node bin/lib/repo-graph.js build|query|export [options]
+ *
+ * Output file: .jumpstart/state/repo-graph.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_GRAPH_FILE = path.join('.jumpstart', 'state', 'repo-graph.json');
+
+/**
+ * Default empty graph structure.
+ * @returns {object}
+ */
+function defaultRepoGraph() {
+  return {
+    version: '1.0.0',
+    generated_at: new Date().toISOString(),
+    last_updated: null,
+    nodes: {},   // id → { id, type, name, metadata }
+    edges: []    // { from, to, relationship }
+  };
+}
+
+/**
+ * Load a repo graph from disk.
+ * @param {string} [graphFile]
+ * @returns {object}
+ */
+function loadRepoGraph(graphFile) {
+  const filePath = graphFile || DEFAULT_GRAPH_FILE;
+  if (!fs.existsSync(filePath)) {
+    return defaultRepoGraph();
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return defaultRepoGraph();
+  }
+}
+
+/**
+ * Save a repo graph to disk.
+ * @param {object} graph
+ * @param {string} [graphFile]
+ */
+function saveRepoGraph(graph, graphFile) {
+  const filePath = graphFile || DEFAULT_GRAPH_FILE;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  graph.last_updated = new Date().toISOString();
+  fs.writeFileSync(filePath, JSON.stringify(graph, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Add or update a node in the graph.
+ * @param {object} graph
+ * @param {string} id
+ * @param {string} type - domain|module|api|file|decision|owner|dependency
+ * @param {object} [metadata]
+ */
+function upsertNode(graph, id, type, metadata = {}) {
+  graph.nodes[id] = {
+    ...(graph.nodes[id] || {}),
+    id,
+    type,
+    ...metadata,
+    updated_at: new Date().toISOString()
+  };
+}
+
+/**
+ * Add an edge between two nodes (avoids duplicates).
+ * @param {object} graph
+ * @param {string} from
+ * @param {string} to
+ * @param {string} relationship
+ */
+function addEdge(graph, from, to, relationship) {
+  const exists = graph.edges.some(
+    e => e.from === from && e.to === to && e.relationship === relationship
+  );
+  if (!exists) {
+    graph.edges.push({ from, to, relationship });
+  }
+}
+
+/**
+ * Build the semantic graph from the project file system.
+ * Scans src/, specs/, and config files to auto-discover structure.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object} Populated graph.
+ */
+function buildRepoGraph(root, options = {}) {
+  const graph = defaultRepoGraph();
+  const srcDir = path.join(root, options.srcDir || 'src');
+  const specsDir = path.join(root, 'specs');
+  const graphFile = options.graphFile || path.join(root, DEFAULT_GRAPH_FILE);
+
+  // 1. Scan src directory for modules and files
+  if (fs.existsSync(srcDir)) {
+    upsertNode(graph, 'src', 'module', { name: 'Source Root', path: 'src' });
+
+    const walk = (dir, parentId) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        const rel = path.relative(root, full).replace(/\\/g, '/');
+        const nodeId = `file:${rel}`;
+
+        if (entry.isDirectory()) {
+          upsertNode(graph, nodeId, 'module', { name: entry.name, path: rel });
+          addEdge(graph, parentId, nodeId, 'contains');
+          walk(full, nodeId);
+        } else if (entry.isFile()) {
+          // Classify file type
+          let fileType = 'file';
+          const lower = entry.name.toLowerCase();
+          if (lower.includes('api') || lower.includes('route') || lower.includes('endpoint')) {
+            fileType = 'api';
+          } else if (lower.includes('model') || lower.includes('schema') || lower.includes('entity')) {
+            fileType = 'model';
+          } else if (lower.includes('service') || lower.includes('controller')) {
+            fileType = 'service';
+          }
+
+          upsertNode(graph, nodeId, fileType, { name: entry.name, path: rel });
+          addEdge(graph, parentId, nodeId, 'contains');
+
+          // Extract any ownership annotations (e.g., @owner comments)
+          try {
+            const content = fs.readFileSync(full, 'utf8');
+            const ownerMatch = content.match(/@owner[:\s]+(\S+)/i);
+            if (ownerMatch) {
+              const ownerId = `owner:${ownerMatch[1]}`;
+              upsertNode(graph, ownerId, 'owner', { name: ownerMatch[1] });
+              addEdge(graph, ownerId, nodeId, 'owns');
+            }
+          } catch {
+            // skip unreadable files
+          }
+        }
+      }
+    };
+
+    walk(srcDir, 'src');
+  }
+
+  // 2. Scan specs for decisions
+  const decisionsDir = path.join(specsDir, 'decisions');
+  if (fs.existsSync(decisionsDir)) {
+    upsertNode(graph, 'decisions', 'module', { name: 'Architecture Decisions', path: 'specs/decisions' });
+    for (const file of fs.readdirSync(decisionsDir)) {
+      if (file.endsWith('.md')) {
+        const nodeId = `decision:${file}`;
+        const adrPath = path.join(decisionsDir, file);
+        let title = file;
+        try {
+          const content = fs.readFileSync(adrPath, 'utf8');
+          const titleMatch = content.match(/^# (.+)/m);
+          if (titleMatch) title = titleMatch[1];
+        } catch {
+          // use filename as title
+        }
+        upsertNode(graph, nodeId, 'decision', { name: title, path: `specs/decisions/${file}` });
+        addEdge(graph, 'decisions', nodeId, 'contains');
+      }
+    }
+  }
+
+  // 3. Add spec files as nodes
+  const specFiles = ['challenger-brief.md', 'product-brief.md', 'prd.md', 'architecture.md', 'implementation-plan.md'];
+  upsertNode(graph, 'specs', 'module', { name: 'Specifications', path: 'specs' });
+  for (const sf of specFiles) {
+    const specPath = path.join(specsDir, sf);
+    if (fs.existsSync(specPath)) {
+      const nodeId = `spec:${sf}`;
+      upsertNode(graph, nodeId, 'spec', { name: sf, path: `specs/${sf}` });
+      addEdge(graph, 'specs', nodeId, 'contains');
+    }
+  }
+
+  const nodeCount = Object.keys(graph.nodes).length;
+  const edgeCount = graph.edges.length;
+
+  saveRepoGraph(graph, graphFile);
+
+  return {
+    success: true,
+    node_count: nodeCount,
+    edge_count: edgeCount,
+    graph_file: graphFile
+  };
+}
+
+/**
+ * Query the graph for nodes matching a type or name pattern.
+ *
+ * @param {object} graph
+ * @param {object} query - { type?, nameContains? }
+ * @returns {object[]} Matching nodes.
+ */
+function queryGraph(graph, query = {}) {
+  let nodes = Object.values(graph.nodes);
+
+  if (query.type) {
+    nodes = nodes.filter(n => n.type === query.type);
+  }
+
+  if (query.nameContains) {
+    const lower = query.nameContains.toLowerCase();
+    nodes = nodes.filter(n => n.name && n.name.toLowerCase().includes(lower));
+  }
+
+  if (query.id) {
+    nodes = nodes.filter(n => n.id === query.id);
+  }
+
+  return nodes;
+}
+
+/**
+ * Find all neighbours of a node (one-hop).
+ *
+ * @param {object} graph
+ * @param {string} nodeId
+ * @returns {{ incoming: object[], outgoing: object[] }}
+ */
+function getNeighbours(graph, nodeId) {
+  const outgoing = graph.edges
+    .filter(e => e.from === nodeId)
+    .map(e => ({ node: graph.nodes[e.to] || { id: e.to }, relationship: e.relationship }));
+
+  const incoming = graph.edges
+    .filter(e => e.to === nodeId)
+    .map(e => ({ node: graph.nodes[e.from] || { id: e.from }, relationship: e.relationship }));
+
+  return { incoming, outgoing };
+}
+
+module.exports = {
+  defaultRepoGraph,
+  loadRepoGraph,
+  saveRepoGraph,
+  upsertNode,
+  addEdge,
+  buildRepoGraph,
+  queryGraph,
+  getNeighbours
+};

package/bin/lib/requirements-baseline.js

@@ -0,0 +1,358 @@
+/**
+ * requirements-baseline.js — Requirements Baseline & Change Control
+ *
+ * Freezes approved requirements and forces impact assessment when
+ * downstream changes are proposed.
+ *
+ * Baseline file: .jumpstart/state/requirements-baseline.json
+ *
+ * Usage:
+ *   node bin/lib/requirements-baseline.js freeze|check|impact|status [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const DEFAULT_BASELINE_FILE = path.join('.jumpstart', 'state', 'requirements-baseline.json');
+
+const ARTIFACT_TYPES = ['challenger-brief', 'product-brief', 'prd', 'architecture', 'implementation-plan'];
+
+/**
+ * Default empty baseline registry.
+ * @returns {object}
+ */
+function defaultBaseline() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    frozen: false,
+    baselines: [],
+    change_requests: []
+  };
+}
+
+/**
+ * Load baseline from disk.
+ * @param {string} [baselineFile]
+ * @returns {object}
+ */
+function loadBaseline(baselineFile) {
+  const filePath = baselineFile || DEFAULT_BASELINE_FILE;
+  if (!fs.existsSync(filePath)) {
+    return defaultBaseline();
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return defaultBaseline();
+  }
+}
+
+/**
+ * Save baseline to disk.
+ * @param {object} baseline
+ * @param {string} [baselineFile]
+ */
+function saveBaseline(baseline, baselineFile) {
+  const filePath = baselineFile || DEFAULT_BASELINE_FILE;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  baseline.last_updated = new Date().toISOString();
+  fs.writeFileSync(filePath, JSON.stringify(baseline, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Compute SHA-256 hash of content.
+ * @param {string} content
+ * @returns {string}
+ */
+function hashContent(content) {
+  return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+/**
+ * Extract requirement IDs from content.
+ * Matches patterns like REQ-001, E01-S01, NFR-001, UC-001, etc.
+ * @param {string} content
+ * @returns {string[]}
+ */
+function extractRequirementIds(content) {
+  const patterns = [
+    /\b(REQ-\d+)\b/g,
+    /\b(E\d+-S\d+)\b/g,
+    /\b(NFR-\d+)\b/g,
+    /\b(UC-\d+)\b/g,
+    /\b(FR-\d+)\b/g,
+    /\b(AC-\d+)\b/g
+  ];
+  const ids = new Set();
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      ids.add(match[1]);
+    }
+  }
+  return [...ids].sort();
+}
+
+/**
+ * Freeze current requirements as baseline.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function freezeBaseline(root, options = {}) {
+  const baselineFile = options.baselineFile || path.join(root, DEFAULT_BASELINE_FILE);
+  const baseline = loadBaseline(baselineFile);
+
+  const specsDir = path.join(root, 'specs');
+  if (!fs.existsSync(specsDir)) {
+    return { success: false, error: 'specs/ directory not found' };
+  }
+
+  const snapshots = [];
+  const artifactMap = {
+    'challenger-brief': 'specs/challenger-brief.md',
+    'product-brief': 'specs/product-brief.md',
+    'prd': 'specs/prd.md',
+    'architecture': 'specs/architecture.md',
+    'implementation-plan': 'specs/implementation-plan.md'
+  };
+
+  for (const [type, relPath] of Object.entries(artifactMap)) {
+    const fullPath = path.join(root, relPath);
+    if (fs.existsSync(fullPath)) {
+      const content = fs.readFileSync(fullPath, 'utf8');
+      snapshots.push({
+        type,
+        path: relPath,
+        hash: hashContent(content),
+        requirement_ids: extractRequirementIds(content),
+        frozen_at: new Date().toISOString()
+      });
+    }
+  }
+
+  if (snapshots.length === 0) {
+    return { success: false, error: 'No spec artifacts found to freeze' };
+  }
+
+  const baselineEntry = {
+    id: `baseline-${Date.now()}`,
+    frozen_at: new Date().toISOString(),
+    frozen_by: options.approver || 'system',
+    snapshots,
+    total_requirements: snapshots.reduce((sum, s) => sum + s.requirement_ids.length, 0)
+  };
+
+  baseline.baselines.push(baselineEntry);
+  baseline.frozen = true;
+  saveBaseline(baseline, baselineFile);
+
+  return {
+    success: true,
+    baseline_id: baselineEntry.id,
+    artifacts_frozen: snapshots.length,
+    total_requirements: baselineEntry.total_requirements,
+    snapshots: snapshots.map(s => ({ type: s.type, path: s.path, requirements: s.requirement_ids.length }))
+  };
+}
+
+/**
+ * Check if any frozen artifacts have changed since the baseline.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function checkBaseline(root, options = {}) {
+  const baselineFile = options.baselineFile || path.join(root, DEFAULT_BASELINE_FILE);
+  const baseline = loadBaseline(baselineFile);
+
+  if (!baseline.frozen || baseline.baselines.length === 0) {
+    return { success: true, frozen: false, message: 'No frozen baseline found' };
+  }
+
+  const latestBaseline = baseline.baselines[baseline.baselines.length - 1];
+  const changes = [];
+  const unchanged = [];
+
+  for (const snapshot of latestBaseline.snapshots) {
+    const fullPath = path.join(root, snapshot.path);
+    if (!fs.existsSync(fullPath)) {
+      changes.push({
+        type: snapshot.type,
+        path: snapshot.path,
+        change: 'deleted',
+        severity: 'critical'
+      });
+      continue;
+    }
+
+    const content = fs.readFileSync(fullPath, 'utf8');
+    const currentHash = hashContent(content);
+
+    if (currentHash !== snapshot.hash) {
+      const currentIds = extractRequirementIds(content);
+      const addedIds = currentIds.filter(id => !snapshot.requirement_ids.includes(id));
+      const removedIds = snapshot.requirement_ids.filter(id => !currentIds.includes(id));
+
+      changes.push({
+        type: snapshot.type,
+        path: snapshot.path,
+        change: 'modified',
+        severity: removedIds.length > 0 ? 'critical' : addedIds.length > 0 ? 'warning' : 'info',
+        added_requirements: addedIds,
+        removed_requirements: removedIds
+      });
+    } else {
+      unchanged.push({ type: snapshot.type, path: snapshot.path });
+    }
+  }
+
+  const drifted = changes.length > 0;
+  return {
+    success: true,
+    frozen: true,
+    baseline_id: latestBaseline.id,
+    frozen_at: latestBaseline.frozen_at,
+    drifted,
+    changes,
+    unchanged,
+    summary: {
+      total_artifacts: latestBaseline.snapshots.length,
+      changed: changes.length,
+      unchanged: unchanged.length,
+      critical: changes.filter(c => c.severity === 'critical').length
+    }
+  };
+}
+
+/**
+ * Perform impact assessment for a proposed change.
+ *
+ * @param {string} artifactPath - Path to the changed artifact.
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function assessImpact(artifactPath, root, options = {}) {
+  const baselineFile = options.baselineFile || path.join(root, DEFAULT_BASELINE_FILE);
+  const baseline = loadBaseline(baselineFile);
+
+  if (!baseline.frozen || baseline.baselines.length === 0) {
+    return { success: true, impact: 'none', message: 'No frozen baseline — changes are unconstrained' };
+  }
+
+  const relPath = path.relative(root, path.resolve(root, artifactPath)).replace(/\\/g, '/');
+  const latestBaseline = baseline.baselines[baseline.baselines.length - 1];
+  const snapshot = latestBaseline.snapshots.find(s => s.path === relPath);
+
+  if (!snapshot) {
+    return { success: true, impact: 'none', message: `${relPath} is not part of the frozen baseline` };
+  }
+
+  const fullPath = path.join(root, relPath);
+  if (!fs.existsSync(fullPath)) {
+    return {
+      success: true,
+      impact: 'critical',
+      artifact: relPath,
+      assessment: {
+        change_type: 'deletion',
+        affected_requirements: snapshot.requirement_ids,
+        downstream_artifacts: ARTIFACT_TYPES.filter(t => t !== snapshot.type)
+      }
+    };
+  }
+
+  const content = fs.readFileSync(fullPath, 'utf8');
+  const currentHash = hashContent(content);
+
+  if (currentHash === snapshot.hash) {
+    return { success: true, impact: 'none', message: 'Artifact matches frozen baseline' };
+  }
+
+  const currentIds = extractRequirementIds(content);
+  const addedIds = currentIds.filter(id => !snapshot.requirement_ids.includes(id));
+  const removedIds = snapshot.requirement_ids.filter(id => !currentIds.includes(id));
+  const unchangedIds = currentIds.filter(id => snapshot.requirement_ids.includes(id));
+
+  const typeIndex = ARTIFACT_TYPES.indexOf(snapshot.type);
+  const downstreamTypes = ARTIFACT_TYPES.slice(typeIndex + 1);
+
+  const impactLevel = removedIds.length > 0 ? 'critical'
+    : addedIds.length > 3 ? 'high'
+    : addedIds.length > 0 ? 'medium'
+    : 'low';
+
+  const changeRequest = {
+    id: `cr-${Date.now()}`,
+    artifact: relPath,
+    artifact_type: snapshot.type,
+    requested_at: new Date().toISOString(),
+    impact_level: impactLevel,
+    added_requirements: addedIds,
+    removed_requirements: removedIds,
+    downstream_artifacts: downstreamTypes,
+    status: 'pending_review'
+  };
+
+  baseline.change_requests.push(changeRequest);
+  saveBaseline(baseline, baselineFile);
+
+  return {
+    success: true,
+    impact: impactLevel,
+    change_request_id: changeRequest.id,
+    artifact: relPath,
+    assessment: {
+      change_type: removedIds.length > 0 ? 'breaking' : 'additive',
+      added_requirements: addedIds,
+      removed_requirements: removedIds,
+      unchanged_requirements: unchangedIds.length,
+      downstream_artifacts: downstreamTypes,
+      requires_re_approval: impactLevel === 'critical' || impactLevel === 'high'
+    }
+  };
+}
+
+/**
+ * Get baseline status.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function getBaselineStatus(options = {}) {
+  const baselineFile = options.baselineFile || DEFAULT_BASELINE_FILE;
+  const baseline = loadBaseline(baselineFile);
+
+  return {
+    success: true,
+    frozen: baseline.frozen,
+    total_baselines: baseline.baselines.length,
+    total_change_requests: baseline.change_requests.length,
+    pending_change_requests: baseline.change_requests.filter(cr => cr.status === 'pending_review').length,
+    latest_baseline: baseline.baselines.length > 0 ? baseline.baselines[baseline.baselines.length - 1] : null
+  };
+}
+
+module.exports = {
+  defaultBaseline,
+  loadBaseline,
+  saveBaseline,
+  hashContent,
+  extractRequirementIds,
+  freezeBaseline,
+  checkBaseline,
+  assessImpact,
+  getBaselineStatus,
+  ARTIFACT_TYPES
+};