jumpstart-mode 1.1.12 → 1.1.13

package/bin/lib/semantic-diff.js

@@ -0,0 +1,335 @@
+/**
+ * semantic-diff.js — Cross-artifact Semantic Diffing
+ *
+ * Detects meaning changes, not just text changes, across PRD,
+ * architecture, APIs, and tests.
+ *
+ * Usage:
+ *   node bin/lib/semantic-diff.js compare <path1> <path2> [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const SECTION_HEADING = /^(#{1,6})\s+(.+)$/gm;
+const REQUIREMENT_PATTERN = /\b(REQ-\d+|E\d+-S\d+|NFR-\d+|UC-\d+|FR-\d+|AC-\d+|M\d+-T\d+)\b/g;
+const API_ENDPOINT = /\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(\S+)/g;
+const TABLE_ROW = /^\|(.+)\|$/gm;
+
+/**
+ * Extract structural sections from markdown.
+ * @param {string} content
+ * @returns {object[]}
+ */
+function extractSections(content) {
+  const sections = [];
+  const lines = content.split('\n');
+  let currentSection = { heading: '(preamble)', level: 0, content: [], startLine: 0 };
+
+  for (let i = 0; i < lines.length; i++) {
+    const headingMatch = lines[i].match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      if (currentSection.content.length > 0 || currentSection.heading !== '(preamble)') {
+        currentSection.content = currentSection.content.join('\n').trim();
+        sections.push(currentSection);
+      }
+      currentSection = {
+        heading: headingMatch[2].trim(),
+        level: headingMatch[1].length,
+        content: [],
+        startLine: i + 1
+      };
+    } else {
+      currentSection.content.push(lines[i]);
+    }
+  }
+  currentSection.content = currentSection.content.join('\n').trim();
+  sections.push(currentSection);
+
+  return sections;
+}
+
+/**
+ * Extract requirement references from content.
+ * @param {string} content
+ * @returns {string[]}
+ */
+function extractRequirements(content) {
+  const matches = content.match(REQUIREMENT_PATTERN) || [];
+  return [...new Set(matches)].sort();
+}
+
+/**
+ * Extract API endpoints from content.
+ * @param {string} content
+ * @returns {object[]}
+ */
+function extractApiEndpoints(content) {
+  const endpoints = [];
+  let match;
+  const pattern = new RegExp(API_ENDPOINT.source, 'g');
+  while ((match = pattern.exec(content)) !== null) {
+    endpoints.push({ method: match[1], path: match[2] });
+  }
+  return endpoints;
+}
+
+/**
+ * Extract key-value pairs from table rows.
+ * @param {string} content
+ * @returns {string[][]}
+ */
+function extractTableData(content) {
+  const rows = [];
+  let match;
+  const pattern = new RegExp(TABLE_ROW.source, 'gm');
+  while ((match = pattern.exec(content)) !== null) {
+    const cells = match[1].split('|').map(c => c.trim()).filter(c => c.length > 0);
+    if (cells.some(c => /^[-:]+$/.test(c))) continue; // skip separator rows
+    rows.push(cells);
+  }
+  return rows;
+}
+
+/**
+ * Normalize text for comparison: lowercase, collapse whitespace, strip punctuation.
+ * @param {string} text
+ * @returns {string}
+ */
+function normalizeText(text) {
+  return text.toLowerCase()
+    .replace(/[^\w\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Compute simple similarity ratio between two strings (0-1).
+ * Uses set-based word overlap (Jaccard-like).
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function textSimilarity(a, b) {
+  const wordsA = new Set(normalizeText(a).split(' ').filter(w => w.length > 2));
+  const wordsB = new Set(normalizeText(b).split(' ').filter(w => w.length > 2));
+  if (wordsA.size === 0 && wordsB.size === 0) return 1;
+  if (wordsA.size === 0 || wordsB.size === 0) return 0;
+
+  let intersection = 0;
+  for (const w of wordsA) {
+    if (wordsB.has(w)) intersection++;
+  }
+  const union = new Set([...wordsA, ...wordsB]).size;
+  return union === 0 ? 1 : intersection / union;
+}
+
+/**
+ * Compare two artifacts and find semantic differences.
+ *
+ * @param {string} contentA - Original content.
+ * @param {string} contentB - Modified content.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function compareArtifacts(contentA, contentB, options = {}) {
+  const sectionsA = extractSections(contentA);
+  const sectionsB = extractSections(contentB);
+
+  const sectionChanges = [];
+  const headingsA = sectionsA.map(s => s.heading);
+  const headingsB = sectionsB.map(s => s.heading);
+
+  // Detect added sections
+  for (const sec of sectionsB) {
+    if (!headingsA.includes(sec.heading)) {
+      sectionChanges.push({
+        type: 'section_added',
+        heading: sec.heading,
+        severity: 'info'
+      });
+    }
+  }
+
+  // Detect removed sections
+  for (const sec of sectionsA) {
+    if (!headingsB.includes(sec.heading)) {
+      sectionChanges.push({
+        type: 'section_removed',
+        heading: sec.heading,
+        severity: 'warning'
+      });
+    }
+  }
+
+  // Detect modified sections
+  for (const secA of sectionsA) {
+    const secB = sectionsB.find(s => s.heading === secA.heading);
+    if (secB) {
+      const similarity = textSimilarity(secA.content, secB.content);
+      if (similarity < 0.95) {
+        sectionChanges.push({
+          type: 'section_modified',
+          heading: secA.heading,
+          similarity: Math.round(similarity * 100),
+          severity: similarity < 0.5 ? 'critical' : similarity < 0.8 ? 'warning' : 'info'
+        });
+      }
+    }
+  }
+
+  // Requirement changes
+  const reqsA = extractRequirements(contentA);
+  const reqsB = extractRequirements(contentB);
+  const addedReqs = reqsB.filter(r => !reqsA.includes(r));
+  const removedReqs = reqsA.filter(r => !reqsB.includes(r));
+
+  // API endpoint changes
+  const apisA = extractApiEndpoints(contentA);
+  const apisB = extractApiEndpoints(contentB);
+  const apiKeysA = apisA.map(a => `${a.method} ${a.path}`);
+  const apiKeysB = apisB.map(a => `${a.method} ${a.path}`);
+  const addedApis = apiKeysB.filter(k => !apiKeysA.includes(k));
+  const removedApis = apiKeysA.filter(k => !apiKeysB.includes(k));
+
+  // Table changes
+  const tablesA = extractTableData(contentA);
+  const tablesB = extractTableData(contentB);
+
+  const overallSimilarity = textSimilarity(contentA, contentB);
+  const hasBreakingChanges = removedReqs.length > 0 || removedApis.length > 0
+    || sectionChanges.some(c => c.severity === 'critical');
+
+  return {
+    success: true,
+    overall_similarity: Math.round(overallSimilarity * 100),
+    has_breaking_changes: hasBreakingChanges,
+    section_changes: sectionChanges,
+    requirement_changes: {
+      added: addedReqs,
+      removed: removedReqs,
+      total_before: reqsA.length,
+      total_after: reqsB.length
+    },
+    api_changes: {
+      added: addedApis,
+      removed: removedApis,
+      total_before: apisA.length,
+      total_after: apisB.length
+    },
+    table_changes: {
+      rows_before: tablesA.length,
+      rows_after: tablesB.length
+    },
+    summary: {
+      sections_added: sectionChanges.filter(c => c.type === 'section_added').length,
+      sections_removed: sectionChanges.filter(c => c.type === 'section_removed').length,
+      sections_modified: sectionChanges.filter(c => c.type === 'section_modified').length,
+      requirements_added: addedReqs.length,
+      requirements_removed: removedReqs.length,
+      apis_added: addedApis.length,
+      apis_removed: removedApis.length
+    }
+  };
+}
+
+/**
+ * Compare two artifact files on disk.
+ *
+ * @param {string} pathA - Path to original artifact.
+ * @param {string} pathB - Path to modified artifact.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function compareFiles(pathA, pathB, options = {}) {
+  if (!fs.existsSync(pathA)) {
+    return { success: false, error: `File not found: ${pathA}` };
+  }
+  if (!fs.existsSync(pathB)) {
+    return { success: false, error: `File not found: ${pathB}` };
+  }
+
+  const contentA = fs.readFileSync(pathA, 'utf8');
+  const contentB = fs.readFileSync(pathB, 'utf8');
+
+  const result = compareArtifacts(contentA, contentB, options);
+  result.file_a = pathA;
+  result.file_b = pathB;
+  return result;
+}
+
+/**
+ * Detect cross-artifact consistency issues across multiple spec files.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function crossArtifactDiff(root, options = {}) {
+  const specsDir = path.join(root, 'specs');
+  if (!fs.existsSync(specsDir)) {
+    return { success: false, error: 'specs/ directory not found' };
+  }
+
+  const artifacts = {};
+  const artifactFiles = ['challenger-brief.md', 'product-brief.md', 'prd.md', 'architecture.md', 'implementation-plan.md'];
+
+  for (const file of artifactFiles) {
+    const fullPath = path.join(specsDir, file);
+    if (fs.existsSync(fullPath)) {
+      const content = fs.readFileSync(fullPath, 'utf8');
+      artifacts[file] = {
+        content,
+        requirements: extractRequirements(content),
+        apis: extractApiEndpoints(content),
+        sections: extractSections(content)
+      };
+    }
+  }
+
+  const inconsistencies = [];
+
+  // Check requirement coverage flow (upstream → downstream)
+  const orderedKeys = Object.keys(artifacts);
+  for (let i = 0; i < orderedKeys.length - 1; i++) {
+    const upstream = artifacts[orderedKeys[i]];
+    const downstream = artifacts[orderedKeys[i + 1]];
+    if (!upstream || !downstream) continue;
+
+    const missingDownstream = upstream.requirements.filter(r => !downstream.requirements.includes(r));
+    if (missingDownstream.length > 0) {
+      inconsistencies.push({
+        type: 'requirement_gap',
+        upstream: orderedKeys[i],
+        downstream: orderedKeys[i + 1],
+        missing_requirements: missingDownstream,
+        severity: 'warning'
+      });
+    }
+  }
+
+  return {
+    success: true,
+    artifacts_analyzed: Object.keys(artifacts).length,
+    inconsistencies,
+    summary: {
+      total_inconsistencies: inconsistencies.length,
+      requirement_gaps: inconsistencies.filter(i => i.type === 'requirement_gap').length
+    }
+  };
+}
+
+module.exports = {
+  extractSections,
+  extractRequirements,
+  extractApiEndpoints,
+  extractTableData,
+  normalizeText,
+  textSimilarity,
+  compareArtifacts,
+  compareFiles,
+  crossArtifactDiff
+};

package/bin/lib/sla-slo.js

@@ -0,0 +1,210 @@
+/**
+ * sla-slo.js — SLA & SLO Specification Support (Item 28)
+ *
+ * Make operational expectations first-class citizens in the PRD
+ * and architecture.
+ *
+ * Usage:
+ *   node bin/lib/sla-slo.js define|check|report [options]
+ *
+ * State file: .jumpstart/state/sla-slo.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'sla-slo.json');
+
+const SLO_TYPES = ['availability', 'latency', 'throughput', 'error-rate', 'durability', 'freshness'];
+
+const DEFAULT_SLO_TEMPLATES = {
+  'web-api': [
+    { type: 'availability', target: 99.9, unit: 'percent', window: '30d' },
+    { type: 'latency', target: 200, unit: 'ms', percentile: 'p99', window: '30d' },
+    { type: 'error-rate', target: 0.1, unit: 'percent', window: '30d' }
+  ],
+  'batch-processing': [
+    { type: 'availability', target: 99.5, unit: 'percent', window: '30d' },
+    { type: 'throughput', target: 1000, unit: 'records/sec', window: '1h' },
+    { type: 'freshness', target: 60, unit: 'minutes', window: '24h' }
+  ],
+  'data-pipeline': [
+    { type: 'availability', target: 99.0, unit: 'percent', window: '30d' },
+    { type: 'freshness', target: 15, unit: 'minutes', window: '24h' },
+    { type: 'durability', target: 99.999, unit: 'percent', window: '30d' }
+  ]
+};
+
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    slos: [],
+    slas: [],
+    error_budgets: []
+  };
+}
+
+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');
+}
+
+/**
+ * Define an SLO.
+ *
+ * @param {object} slo - { name, service, type, target, unit, window, description? }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function defineSLO(slo, options = {}) {
+  if (!slo || !slo.name || !slo.service || !slo.target) {
+    return { success: false, error: 'name, service, and target are required' };
+  }
+
+  const type = (slo.type || 'availability').toLowerCase();
+  if (!SLO_TYPES.includes(type)) {
+    return { success: false, error: `Invalid type. Must be one of: ${SLO_TYPES.join(', ')}` };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const newSLO = {
+    id: `SLO-${Date.now().toString(36).toUpperCase()}`,
+    name: slo.name,
+    service: slo.service,
+    type,
+    target: slo.target,
+    unit: slo.unit || 'percent',
+    window: slo.window || '30d',
+    description: slo.description || '',
+    created_at: new Date().toISOString()
+  };
+
+  state.slos.push(newSLO);
+  saveState(state, stateFile);
+
+  return { success: true, slo: newSLO };
+}
+
+/**
+ * Apply an SLO template by service type.
+ *
+ * @param {string} serviceName
+ * @param {string} templateType - 'web-api' | 'batch-processing' | 'data-pipeline'
+ * @param {object} [options]
+ * @returns {object}
+ */
+function applyTemplate(serviceName, templateType, options = {}) {
+  const template = DEFAULT_SLO_TEMPLATES[templateType];
+  if (!template) {
+    return { success: false, error: `Unknown template: ${templateType}. Available: ${Object.keys(DEFAULT_SLO_TEMPLATES).join(', ')}` };
+  }
+
+  const results = [];
+  for (const t of template) {
+    const result = defineSLO({
+      name: `${serviceName} ${t.type}`,
+      service: serviceName,
+      ...t
+    }, options);
+    results.push(result);
+  }
+
+  return { success: true, service: serviceName, template: templateType, slos_created: results.length };
+}
+
+/**
+ * Check SLO coverage in specs.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function checkSLOCoverage(root, options = {}) {
+  const stateFile = options.stateFile || path.join(root, DEFAULT_STATE_FILE);
+  const state = loadState(stateFile);
+
+  const archFile = path.join(root, 'specs', 'architecture.md');
+  const prdFile = path.join(root, 'specs', 'prd.md');
+
+  let archHasSLO = false;
+  let prdHasSLO = false;
+
+  if (fs.existsSync(archFile)) {
+    try {
+      const content = fs.readFileSync(archFile, 'utf8');
+      archHasSLO = /\bSL[OA]\b|service.level|availability|latency.target/i.test(content);
+    } catch { /* ignore */ }
+  }
+
+  if (fs.existsSync(prdFile)) {
+    try {
+      const content = fs.readFileSync(prdFile, 'utf8');
+      prdHasSLO = /\bSL[OA]\b|service.level|availability|uptime/i.test(content);
+    } catch { /* ignore */ }
+  }
+
+  return {
+    success: true,
+    defined_slos: state.slos.length,
+    architecture_mentions_slo: archHasSLO,
+    prd_mentions_slo: prdHasSLO,
+    coverage: state.slos.length > 0 ? 'defined' : 'missing',
+    recommendations: state.slos.length === 0 ? ['Define SLOs using `jumpstart-mode sla-slo define`'] : []
+  };
+}
+
+/**
+ * Generate SLO report.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  return {
+    success: true,
+    slos: state.slos,
+    slas: state.slas,
+    total_slos: state.slos.length,
+    total_slas: state.slas.length,
+    by_service: state.slos.reduce((acc, s) => {
+      acc[s.service] = acc[s.service] || [];
+      acc[s.service].push(s);
+      return acc;
+    }, {}),
+    by_type: state.slos.reduce((acc, s) => {
+      acc[s.type] = (acc[s.type] || 0) + 1;
+      return acc;
+    }, {})
+  };
+}
+
+module.exports = {
+  defaultState,
+  loadState,
+  saveState,
+  defineSLO,
+  applyTemplate,
+  checkSLOCoverage,
+  generateReport,
+  SLO_TYPES,
+  DEFAULT_SLO_TEMPLATES
+};

package/bin/lib/spec-comments.js

@@ -0,0 +1,147 @@
+/**
+ * spec-comments.js — Inline Spec Review Comments (Item 63)
+ *
+ * Comment, resolve, assign, and approve within artifact sections.
+ *
+ * Usage:
+ *   node bin/lib/spec-comments.js add|resolve|list|assign [options]
+ *
+ * State file: .jumpstart/state/spec-comments.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'spec-comments.json');
+
+const COMMENT_STATUSES = ['open', 'resolved', 'wontfix', 'deferred'];
+
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    comments: []
+  };
+}
+
+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');
+}
+
+/**
+ * Add a review comment to a spec artifact.
+ */
+function addComment(artifact, section, text, options = {}) {
+  if (!artifact || !text) return { success: false, error: 'artifact and text are required' };
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const comment = {
+    id: `C-${Date.now()}`,
+    artifact,
+    section: section || null,
+    text,
+    author: options.author || 'anonymous',
+    assignee: options.assignee || null,
+    status: 'open',
+    created_at: new Date().toISOString(),
+    resolved_at: null,
+    replies: []
+  };
+
+  state.comments.push(comment);
+  saveState(state, stateFile);
+
+  return { success: true, comment };
+}
+
+/**
+ * Resolve a comment.
+ */
+function resolveComment(commentId, resolution, options = {}) {
+  if (!commentId) return { success: false, error: 'commentId is required' };
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const comment = state.comments.find(c => c.id === commentId);
+  if (!comment) return { success: false, error: `Comment ${commentId} not found` };
+
+  comment.status = 'resolved';
+  comment.resolution = resolution || 'Resolved';
+  comment.resolved_at = new Date().toISOString();
+  comment.resolved_by = options.author || 'anonymous';
+  saveState(state, stateFile);
+
+  return { success: true, comment };
+}
+
+/**
+ * List comments, optionally filtered.
+ */
+function listComments(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  let comments = state.comments;
+
+  if (options.artifact) {
+    comments = comments.filter(c => c.artifact === options.artifact);
+  }
+  if (options.status) {
+    comments = comments.filter(c => c.status === options.status);
+  }
+  if (options.assignee) {
+    comments = comments.filter(c => c.assignee === options.assignee);
+  }
+
+  return {
+    success: true,
+    total: comments.length,
+    comments
+  };
+}
+
+/**
+ * Assign a comment to a reviewer.
+ */
+function assignComment(commentId, assignee, options = {}) {
+  if (!commentId || !assignee) return { success: false, error: 'commentId and assignee are required' };
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const comment = state.comments.find(c => c.id === commentId);
+  if (!comment) return { success: false, error: `Comment ${commentId} not found` };
+
+  comment.assignee = assignee;
+  saveState(state, stateFile);
+
+  return { success: true, comment };
+}
+
+module.exports = {
+  addComment,
+  resolveComment,
+  listComments,
+  assignComment,
+  loadState,
+  saveState,
+  defaultState,
+  COMMENT_STATUSES
+};