jettypod 3.0.1

package/lib/decisions-helpers.test.js

@@ -0,0 +1,310 @@
+const decisionsHelpers = require('./decisions-helpers');
+const { createTestEnvironment } = require('./test-helpers');
+const { getDb, closeDb, resetDb } = require('./database');
+const config = require('./config');
+
+describe('Decisions Helpers', () => {
+  let testEnv;
+  let db;
+
+  beforeEach(() => {
+    resetDb();
+    testEnv = createTestEnvironment();
+    process.chdir(testEnv.testDir);
+    db = getDb();
+  });
+
+  afterEach(async () => {
+    
+    
+    await closeDb();
+    testEnv.cleanup();
+    resetDb();
+  });
+
+  describe('getProjectDecision', () => {
+    test('returns null when no project decision exists', () => {
+      const decision = decisionsHelpers.getProjectDecision();
+      expect(decision).toBeNull();
+    });
+
+    test('returns project decision when it exists', () => {
+      // Mock config with decision
+      const originalRead = config.read;
+      config.read = () => ({
+        project_discovery: {
+          winner: 'prototypes/test',
+          rationale: 'Testing approach',
+          started_date: '2025-10-31T00:00:00.000Z'
+        }
+      });
+
+      const decision = decisionsHelpers.getProjectDecision();
+
+      expect(decision).toEqual({
+        winner: 'prototypes/test',
+        rationale: 'Testing approach',
+        started_date: '2025-10-31T00:00:00.000Z'
+      });
+
+      config.read = originalRead;
+    });
+
+    test('handles missing rationale and date gracefully', () => {
+      const originalRead = config.read;
+      config.read = () => ({
+        project_discovery: {
+          winner: 'prototypes/test'
+        }
+      });
+
+      const decision = decisionsHelpers.getProjectDecision();
+
+      expect(decision).toEqual({
+        winner: 'prototypes/test',
+        rationale: null,
+        started_date: null
+      });
+
+      config.read = originalRead;
+    });
+
+    test('returns null on config read error', () => {
+      const originalRead = config.read;
+      config.read = () => {
+        throw new Error('Config error');
+      };
+
+      const decision = decisionsHelpers.getProjectDecision();
+
+      expect(decision).toBeNull();
+
+      config.read = originalRead;
+    });
+  });
+
+  describe('getDecisionsForEpic', () => {
+    test('returns empty array when epic has no decisions', async () => {
+      // Create epic without decisions
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      const decisions = await decisionsHelpers.getDecisionsForEpic(1);
+
+      expect(decisions).toEqual([]);
+    });
+
+    test('returns decisions for specific epic', async () => {
+      // Create epic
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      // Add decisions
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple and widely understood'],
+          resolve
+        );
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Database', 'PostgreSQL', 'Robust and feature-rich'],
+          resolve
+        );
+      });
+
+      const decisions = await decisionsHelpers.getDecisionsForEpic(1);
+
+      expect(decisions).toHaveLength(2);
+      expect(decisions[0].aspect).toBe('Architecture');
+      expect(decisions[0].decision).toBe('REST API');
+      expect(decisions[1].aspect).toBe('Database');
+      expect(decisions[1].decision).toBe('PostgreSQL');
+    });
+
+    test('only returns decisions for specified epic', async () => {
+      // Create two epics
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Epic 1'], resolve);
+      });
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Epic 2'], resolve);
+      });
+
+      // Add decision to epic 1
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple'],
+          resolve
+        );
+      });
+
+      // Add decision to epic 2
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [2, 'Architecture', 'GraphQL', 'Flexible'],
+          resolve
+        );
+      });
+
+      const decisions = await decisionsHelpers.getDecisionsForEpic(1);
+
+      expect(decisions).toHaveLength(1);
+      expect(decisions[0].decision).toBe('REST API');
+    });
+  });
+
+  describe('getAllEpicDecisions', () => {
+    test('returns empty array when no decisions exist', async () => {
+      // Ensure db is ready
+      await new Promise((resolve) => {
+        db.get('SELECT 1', [], resolve);
+      });
+
+      const decisions = await decisionsHelpers.getAllEpicDecisions();
+      expect(decisions).toEqual([]);
+    });
+
+    test('returns all epic decisions across all epics', async () => {
+      // Create two epics
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Epic 1'], resolve);
+      });
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Epic 2'], resolve);
+      });
+
+      // Add decisions
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple'],
+          resolve
+        );
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [2, 'Architecture', 'GraphQL', 'Flexible'],
+          resolve
+        );
+      });
+
+      const decisions = await decisionsHelpers.getAllEpicDecisions();
+
+      expect(decisions).toHaveLength(2);
+      expect(decisions[0].epic_id).toBe(1);
+      expect(decisions[1].epic_id).toBe(2);
+    });
+  });
+
+  describe('getAllDecisions', () => {
+    test('returns structured object with project and epic decisions', async () => {
+      // Mock project decision
+      const originalRead = config.read;
+      config.read = () => ({
+        project_discovery: {
+          winner: 'prototypes/test',
+          rationale: 'Testing'
+        }
+      });
+
+      // Create epic with decision
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple'],
+          resolve
+        );
+      });
+
+      const allDecisions = await decisionsHelpers.getAllDecisions();
+
+      expect(allDecisions.project).toEqual({
+        winner: 'prototypes/test',
+        rationale: 'Testing',
+        started_date: null
+      });
+
+      expect(allDecisions.epics).toHaveLength(1);
+      expect(allDecisions.epics[0].id).toBe(1);
+      expect(allDecisions.epics[0].title).toBe('Test Epic');
+      expect(allDecisions.epics[0].decisions).toHaveLength(1);
+      expect(allDecisions.epics[0].decisions[0].aspect).toBe('Architecture');
+
+      config.read = originalRead;
+    });
+
+    test('groups decisions by epic', async () => {
+      // Create epic with multiple decisions
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple'],
+          resolve
+        );
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Database', 'PostgreSQL', 'Robust'],
+          resolve
+        );
+      });
+
+      const allDecisions = await decisionsHelpers.getAllDecisions();
+
+      expect(allDecisions.epics).toHaveLength(1);
+      expect(allDecisions.epics[0].decisions).toHaveLength(2);
+    });
+  });
+
+  describe('hasDecisions', () => {
+    test('returns false when epic has no decisions', async () => {
+      // Create epic without decisions
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      const result = await decisionsHelpers.hasDecisions(1);
+
+      expect(result).toBe(false);
+    });
+
+    test('returns true when epic has decisions', async () => {
+      // Create epic with decision
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple'],
+          resolve
+        );
+      });
+
+      const result = await decisionsHelpers.hasDecisions(1);
+
+      expect(result).toBe(true);
+    });
+  });
+});

package/lib/discovery-checkpoint.js

@@ -0,0 +1,83 @@
+const config = require('./config');
+
+/**
+ * Update discovery checkpoint with current progress
+ * @param {number} step - Current discovery step (1-7)
+ * @param {Object} data - Checkpoint data (user_journey, ux_approach, epics_created)
+ */
+function updateCheckpoint(step, data = {}) {
+  const currentConfig = config.read();
+
+  // Ensure project_discovery exists
+  if (!currentConfig.project_discovery) {
+    currentConfig.project_discovery = config.getDefaultProjectDiscovery();
+  }
+
+  // Update checkpoint
+  currentConfig.project_discovery.checkpoint = {
+    step,
+    user_journey: data.user_journey || currentConfig.project_discovery.checkpoint?.user_journey || null,
+    ux_approach: data.ux_approach || currentConfig.project_discovery.checkpoint?.ux_approach || null,
+    epics_created: data.epics_created !== undefined ? data.epics_created : (currentConfig.project_discovery.checkpoint?.epics_created || false)
+  };
+
+  // Update status to in_progress if not already completed
+  if (currentConfig.project_discovery.status === 'not_started') {
+    currentConfig.project_discovery.status = 'in_progress';
+    currentConfig.project_discovery.started_date = new Date().toISOString();
+  }
+
+  config.write(currentConfig);
+}
+
+/**
+ * Get current discovery checkpoint
+ * @returns {Object|null} Checkpoint data or null if not started
+ */
+function getCheckpoint() {
+  const currentConfig = config.read();
+
+  if (!currentConfig.project_discovery || currentConfig.project_discovery.status === 'not_started') {
+    return null;
+  }
+
+  return currentConfig.project_discovery.checkpoint || null;
+}
+
+/**
+ * Clear discovery checkpoint (when discovery is completed)
+ */
+function clearCheckpoint() {
+  const currentConfig = config.read();
+
+  if (currentConfig.project_discovery) {
+    currentConfig.project_discovery.checkpoint = config.getDefaultProjectDiscovery().checkpoint;
+    config.write(currentConfig);
+  }
+}
+
+/**
+ * Get human-readable description of current checkpoint step
+ * @param {number} step - Step number
+ * @returns {string} Step description
+ */
+function getStepDescription(step) {
+  const steps = {
+    1: 'Starting discovery - define user journey',
+    2: 'User journey defined - present UX approaches',
+    3: 'UX approach selected - build prototypes',
+    4: 'Prototypes tested - break into epics',
+    5: 'Epics created - choose tech stack',
+    6: 'Tech stack chosen - record decision',
+    7: 'Discovery complete'
+  };
+
+  return steps[step] || 'Unknown step';
+}
+
+module.exports = {
+  updateCheckpoint,
+  getCheckpoint,
+  clearCheckpoint,
+  getStepDescription
+};

package/lib/docs-generator.js

@@ -0,0 +1,280 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse all .feature files in a directory recursively
+ */
+function parseFeatureFiles(dir) {
+  const features = [];
+
+  if (!fs.existsSync(dir)) {
+    return features;
+  }
+
+  const files = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const file of files) {
+    const fullPath = path.join(dir, file.name);
+
+    if (file.isDirectory()) {
+      features.push(...parseFeatureFiles(fullPath));
+    } else if (file.name.endsWith('.feature')) {
+      const content = fs.readFileSync(fullPath, 'utf-8');
+      features.push(parseFeature(content, fullPath));
+    }
+  }
+
+  return features;
+}
+
+/**
+ * Parse a single Gherkin feature file
+ */
+function parseFeature(content, filepath) {
+  const lines = content.split('\n');
+  let featureName = '';
+  let featureDescription = [];
+  const scenarios = [];
+  let currentScenario = null;
+  let inDescription = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith('Feature:')) {
+      featureName = trimmed.replace('Feature:', '').trim();
+      inDescription = true;
+    } else if (trimmed.startsWith('Scenario:')) {
+      inDescription = false;
+      if (currentScenario) {
+        scenarios.push(currentScenario);
+      }
+      currentScenario = {
+        name: trimmed.replace('Scenario:', '').trim(),
+        given: [],
+        when: [],
+        then: []
+      };
+    } else if (currentScenario) {
+      if (trimmed.startsWith('Given')) {
+        currentScenario.given.push(trimmed.replace(/^Given\s+/, ''));
+      } else if (trimmed.startsWith('When')) {
+        currentScenario.when.push(trimmed.replace(/^When\s+/, ''));
+      } else if (trimmed.startsWith('Then')) {
+        currentScenario.then.push(trimmed.replace(/^Then\s+/, ''));
+      } else if (trimmed.startsWith('And')) {
+        // Add to the last category
+        const cleaned = trimmed.replace(/^And\s+/, '');
+        if (currentScenario.then.length > 0) {
+          currentScenario.then.push(cleaned);
+        } else if (currentScenario.when.length > 0) {
+          currentScenario.when.push(cleaned);
+        } else if (currentScenario.given.length > 0) {
+          currentScenario.given.push(cleaned);
+        }
+      }
+    } else if (inDescription && trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('Background:')) {
+      featureDescription.push(trimmed);
+    }
+  }
+
+  if (currentScenario) {
+    scenarios.push(currentScenario);
+  }
+
+  return {
+    filepath,
+    featureName,
+    description: featureDescription.join(' '),
+    scenarios
+  };
+}
+
+/**
+ * Generate a human-readable behavior description from a scenario
+ */
+function generateBehaviorDescription(scenario) {
+  let desc = '';
+
+  // Context
+  if (scenario.given.length > 0) {
+    const context = scenario.given.join(', ');
+    desc += `When ${context}, `;
+  }
+
+  // Action
+  if (scenario.when.length > 0) {
+    const action = scenario.when.join(' and ');
+    desc += `${action} `;
+  }
+
+  // Outcome
+  if (scenario.then.length > 0) {
+    const outcome = scenario.then.join(' and ');
+    desc += `→ ${outcome}`;
+  }
+
+  return desc;
+}
+
+/**
+ * Group scenarios by theme (extracted from feature name)
+ */
+function groupScenariosByTheme(features) {
+  const themes = {};
+
+  for (const feature of features) {
+    // Extract theme from feature name
+    const themeName = feature.featureName.split(/\s+(protection|removal|tracking|generation|commands)/i)[0].trim() || feature.featureName;
+
+    if (!themes[themeName]) {
+      themes[themeName] = {
+        features: [],
+        behaviors: []
+      };
+    }
+
+    themes[themeName].features.push(feature);
+
+    for (const scenario of feature.scenarios) {
+      themes[themeName].behaviors.push({
+        name: scenario.name,
+        description: generateBehaviorDescription(scenario),
+        feature: feature.featureName
+      });
+    }
+  }
+
+  return themes;
+}
+
+/**
+ * Convert text to markdown anchor
+ */
+function toAnchor(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+/**
+ * Generate markdown documentation from parsed features
+ */
+function generateMarkdown(features) {
+  let md = '# JettyPod System Behaviors\n\n';
+  md += `*Auto-generated from test scenarios on ${new Date().toISOString().split('T')[0]}*\n\n`;
+
+  // Summary stats
+  const totalScenarios = features.reduce((sum, f) => sum + f.scenarios.length, 0);
+  const totalSteps = features.reduce((sum, f) => {
+    return sum + f.scenarios.reduce((s, sc) => {
+      return s + sc.given.length + sc.when.length + sc.then.length;
+    }, 0);
+  }, 0);
+
+  md += '## Summary\n\n';
+  md += `- **${features.length}** features\n`;
+  md += `- **${totalScenarios}** test scenarios\n`;
+  md += `- **${totalSteps}** test steps\n\n`;
+
+  // Table of Contents
+  md += '## Table of Contents\n\n';
+  for (const feature of features) {
+    const anchor = toAnchor(feature.featureName);
+    md += `- [${feature.featureName}](#${anchor}) (${feature.scenarios.length} scenarios)\n`;
+  }
+  md += '\n---\n\n';
+
+  md += '## What JettyPod Does\n\n';
+  md += 'This documentation is derived from actual passing tests. It describes the verified behaviors of the system.\n\n';
+
+  const themes = groupScenariosByTheme(features);
+
+  for (const [themeName, theme] of Object.entries(themes)) {
+    md += `### ${themeName}\n\n`;
+
+    // Show which features contribute to this theme
+    const featureNames = theme.features.map(f => f.featureName).join(', ');
+    md += `*Related features: ${featureNames}*\n\n`;
+
+    md += '**Verified behaviors:**\n\n';
+
+    for (const behavior of theme.behaviors) {
+      md += `- **${behavior.name}**\n`;
+      md += `  ${behavior.description}\n\n`;
+    }
+
+    md += '---\n\n';
+  }
+
+  // Add a detailed section per feature
+  md += '## Detailed Feature Specifications\n\n';
+
+  for (const feature of features) {
+    md += `### ${feature.featureName}\n\n`;
+
+    if (feature.description) {
+      md += `${feature.description}\n\n`;
+    }
+
+    for (const scenario of feature.scenarios) {
+      md += `#### ${scenario.name}\n\n`;
+
+      if (scenario.given.length > 0) {
+        md += '**Context:**\n';
+        for (const g of scenario.given) {
+          md += `- ${g}\n`;
+        }
+        md += '\n';
+      }
+
+      if (scenario.when.length > 0) {
+        md += '**Action:**\n';
+        for (const w of scenario.when) {
+          md += `- ${w}\n`;
+        }
+        md += '\n';
+      }
+
+      if (scenario.then.length > 0) {
+        md += '**Expected outcome:**\n';
+        for (const t of scenario.then) {
+          md += `- ${t}\n`;
+        }
+        md += '\n';
+      }
+    }
+
+    md += '---\n\n';
+  }
+
+  return md;
+}
+
+/**
+ * Main function: generate documentation from feature files
+ */
+function generate(options = {}) {
+  const featuresDir = options.featuresDir || path.join(process.cwd(), 'features');
+  const outputPath = options.outputPath || path.join(process.cwd(), 'SYSTEM-BEHAVIOR.md');
+
+  const features = parseFeatureFiles(featuresDir);
+
+  if (features.length === 0) {
+    throw new Error(`No feature files found in ${featuresDir}`);
+  }
+
+  const markdown = generateMarkdown(features);
+  fs.writeFileSync(outputPath, markdown);
+
+  return {
+    outputPath,
+    featureCount: features.length,
+    scenarioCount: features.reduce((sum, f) => sum + f.scenarios.length, 0)
+  };
+}
+
+module.exports = {
+  generate,
+  parseFeatureFiles,
+  parseFeature,
+  generateMarkdown
+};