musubi-sdd 5.1.0 → 5.6.1

package/src/converters/writers/speckit-writer.js

@@ -1,8 +1,8 @@
 /**
  * Spec Kit Writer
- * 
+ *
  * Writes Intermediate Representation (IR) to Spec Kit project structure
- * 
+ *
  * Spec Kit structure:
  * .specify/
  * ├── memory/
@@ -36,22 +36,22 @@ async function writeSpeckitProject(ir, outputPath, options = {}) {
   const { dryRun = false, force = false, preserveRaw = false, verbose = false } = options;
   const warnings = [];
   let filesWritten = 0;
-  
+
   const specifyPath = path.join(outputPath, '.specify');
-  
+
   // Create base directories
   const dirs = [
     path.join(specifyPath, 'memory'),
     path.join(specifyPath, 'specs'),
     path.join(specifyPath, 'templates'),
   ];
-  
+
   if (!dryRun) {
     for (const dir of dirs) {
       await fs.ensureDir(dir);
     }
   }
-  
+
   // Write constitution
   const constitutionPath = path.join(specifyPath, 'memory', 'constitution.md');
   const constitution = generateConstitution(ir.constitution, preserveRaw);
@@ -60,17 +60,22 @@ async function writeSpeckitProject(ir, outputPath, options = {}) {
     filesWritten++;
   }
   if (verbose) console.log(`  Writing: ${constitutionPath}`);
-  
+
   // Write features
   for (let i = 0; i < ir.features.length; i++) {
     const feature = ir.features[i];
     const featureId = formatFeatureId(i + 1, feature.id);
     const featurePath = path.join(specifyPath, 'specs', featureId);
-    const result = await writeFeature(feature, featurePath, { dryRun, force, preserveRaw, verbose });
+    const result = await writeFeature(feature, featurePath, {
+      dryRun,
+      force,
+      preserveRaw,
+      verbose,
+    });
     filesWritten += result.filesWritten;
     warnings.push(...result.warnings);
   }
-  
+
   // Write templates
   for (const template of ir.templates) {
     const templatePath = path.join(specifyPath, 'templates', `${template.name}.md`);
@@ -80,18 +85,18 @@ async function writeSpeckitProject(ir, outputPath, options = {}) {
     }
     if (verbose) console.log(`  Writing: ${templatePath}`);
   }
-  
+
   return { filesWritten, warnings };
 }
 
 /**
  * Write file with optional force overwrite
- * @param {string} filePath 
- * @param {string} content 
- * @param {boolean} force 
+ * @param {string} filePath
+ * @param {string} content
+ * @param {boolean} force
  */
 async function writeFile(filePath, content, force = false) {
-  if (await fs.pathExists(filePath) && !force) {
+  if ((await fs.pathExists(filePath)) && !force) {
     throw new Error(`File exists: ${filePath} (use --force to overwrite)`);
   }
   await fs.writeFile(filePath, content, 'utf-8');
@@ -99,8 +104,8 @@ async function writeFile(filePath, content, force = false) {
 
 /**
  * Format feature ID with leading zeros (e.g., "001-photo-albums")
- * @param {number} index 
- * @param {string} originalId 
+ * @param {number} index
+ * @param {string} originalId
  * @returns {string}
  */
 function formatFeatureId(index, originalId) {
@@ -108,45 +113,45 @@ function formatFeatureId(index, originalId) {
   if (/^\d{3}-/.test(originalId)) {
     return originalId;
   }
-  
+
   // Convert to kebab-case
   const kebabName = originalId
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-|-$/g, '');
-  
+
   return `${String(index).padStart(3, '0')}-${kebabName}`;
 }
 
 /**
  * Generate constitution.md content (Spec Kit format)
- * @param {import('../ir/types').ConstitutionIR} constitution 
- * @param {boolean} preserveRaw 
+ * @param {import('../ir/types').ConstitutionIR} constitution
+ * @param {boolean} preserveRaw
  * @returns {string}
  */
 function generateConstitution(constitution, preserveRaw = false) {
   const lines = [];
-  
+
   lines.push('# Project Constitution');
   lines.push('');
   lines.push('The core principles and guidelines that govern this project.');
   lines.push('');
-  
+
   // Write Core Principles (converted from MUSUBI articles)
   lines.push('## Core Principles');
   lines.push('');
-  
+
   // Map articles to principles
   if (constitution.articles && constitution.articles.length > 0) {
     for (const article of constitution.articles) {
       lines.push(`### ${article.name}`);
       lines.push('');
-      
+
       if (article.description) {
         lines.push(article.description);
         lines.push('');
       }
-      
+
       if (article.rules && article.rules.length > 0) {
         for (const rule of article.rules) {
           lines.push(`- ${rule}`);
@@ -163,14 +168,14 @@ function generateConstitution(constitution, preserveRaw = false) {
       lines.push('');
     }
   }
-  
+
   // Write Governance
   if (constitution.governance) {
     lines.push('## Governance');
     lines.push('');
     lines.push(`**Version**: ${constitution.governance.version}`);
     lines.push('');
-    
+
     if (constitution.governance.rules && constitution.governance.rules.length > 0) {
       for (const rule of constitution.governance.rules) {
         lines.push(`- ${rule}`);
@@ -178,7 +183,7 @@ function generateConstitution(constitution, preserveRaw = false) {
       lines.push('');
     }
   }
-  
+
   // Preserve raw content if requested
   if (preserveRaw && constitution.rawContent) {
     lines.push('---');
@@ -189,26 +194,26 @@ function generateConstitution(constitution, preserveRaw = false) {
     lines.push(constitution.rawContent);
     lines.push('```');
   }
-  
+
   return lines.join('\n');
 }
 
 /**
  * Write a feature to Spec Kit format
- * @param {import('../ir/types').FeatureIR} feature 
- * @param {string} featurePath 
- * @param {Object} options 
+ * @param {import('../ir/types').FeatureIR} feature
+ * @param {string} featurePath
+ * @param {Object} options
  * @returns {Promise<{filesWritten: number, warnings: string[]}>}
  */
 async function writeFeature(feature, featurePath, options = {}) {
   const { dryRun = false, force = false, preserveRaw = false, verbose = false } = options;
   const warnings = [];
   let filesWritten = 0;
-  
+
   if (!dryRun) {
     await fs.ensureDir(featurePath);
   }
-  
+
   // Write spec.md
   const specPath = path.join(featurePath, 'spec.md');
   const specContent = generateSpec(feature, preserveRaw);
@@ -217,7 +222,7 @@ async function writeFeature(feature, featurePath, options = {}) {
     filesWritten++;
   }
   if (verbose) console.log(`  Writing: ${specPath}`);
-  
+
   // Write plan.md
   if (feature.plan) {
     const planPath = path.join(featurePath, 'plan.md');
@@ -228,7 +233,7 @@ async function writeFeature(feature, featurePath, options = {}) {
     }
     if (verbose) console.log(`  Writing: ${planPath}`);
   }
-  
+
   // Write tasks.md
   if (feature.tasks && feature.tasks.length > 0) {
     const tasksPath = path.join(featurePath, 'tasks.md');
@@ -239,7 +244,7 @@ async function writeFeature(feature, featurePath, options = {}) {
     }
     if (verbose) console.log(`  Writing: ${tasksPath}`);
   }
-  
+
   // Write research.md
   if (feature.research) {
     const researchPath = path.join(featurePath, 'research.md');
@@ -250,7 +255,7 @@ async function writeFeature(feature, featurePath, options = {}) {
     }
     if (verbose) console.log(`  Writing: ${researchPath}`);
   }
-  
+
   // Write data-model.md
   if (feature.dataModel) {
     const dataModelPath = path.join(featurePath, 'data-model.md');
@@ -261,14 +266,14 @@ async function writeFeature(feature, featurePath, options = {}) {
     }
     if (verbose) console.log(`  Writing: ${dataModelPath}`);
   }
-  
+
   // Write contracts
   if (feature.contracts && feature.contracts.length > 0) {
     const contractsPath = path.join(featurePath, 'contracts');
     if (!dryRun) {
       await fs.ensureDir(contractsPath);
     }
-    
+
     for (const contract of feature.contracts) {
       const contractFile = path.join(contractsPath, `${contract.name}.md`);
       const contractContent = contract.rawContent || generateContract(contract);
@@ -279,7 +284,7 @@ async function writeFeature(feature, featurePath, options = {}) {
       if (verbose) console.log(`  Writing: ${contractFile}`);
     }
   }
-  
+
   // Write quickstart.md
   if (feature.quickstart) {
     const quickstartPath = path.join(featurePath, 'quickstart.md');
@@ -290,47 +295,49 @@ async function writeFeature(feature, featurePath, options = {}) {
     }
     if (verbose) console.log(`  Writing: ${quickstartPath}`);
   }
-  
+
   return { filesWritten, warnings };
 }
 
 /**
  * Generate spec.md content (Spec Kit format with User Scenarios)
- * @param {import('../ir/types').FeatureIR} feature 
- * @param {boolean} preserveRaw 
+ * @param {import('../ir/types').FeatureIR} feature
+ * @param {boolean} preserveRaw
  * @returns {string}
  */
 function generateSpec(feature, preserveRaw = false) {
   const lines = [];
   const spec = feature.specification;
-  
+
   lines.push(`# ${spec.title || feature.name}`);
   lines.push('');
-  
+
   if (spec.description) {
     lines.push(spec.description);
     lines.push('');
   }
-  
+
   // Convert EARS requirements to User Scenarios
   if (spec.requirements && spec.requirements.length > 0) {
     lines.push('## User Scenarios');
     lines.push('');
-    
+
     let storyIndex = 1;
     for (const req of spec.requirements) {
       // Convert requirement to user scenario if needed
       const storyId = `US${storyIndex++}`;
-      const scenario = spec.userScenarios?.find(s => s.id === storyId) 
-        || requirementToUserScenario(req, storyId);
-      
+      const scenario =
+        spec.userScenarios?.find(s => s.id === storyId) || requirementToUserScenario(req, storyId);
+
       lines.push(`### ${scenario.title || req.title || `User Story ${storyIndex}`}`);
       lines.push('');
-      lines.push(`As a ${scenario.actor}, I want to ${scenario.action} so that ${scenario.benefit}.`);
+      lines.push(
+        `As a ${scenario.actor}, I want to ${scenario.action} so that ${scenario.benefit}.`
+      );
       lines.push('');
       lines.push(`**Priority**: ${scenario.priority || req.priority}`);
       lines.push('');
-      
+
       if (scenario.acceptanceCriteria && scenario.acceptanceCriteria.length > 0) {
         lines.push('**Acceptance Criteria**:');
         for (const ac of scenario.acceptanceCriteria) {
@@ -338,7 +345,7 @@ function generateSpec(feature, preserveRaw = false) {
         }
         lines.push('');
       }
-      
+
       // Add original EARS statement as note
       if (req.statement && !req.mappedFromUserStory) {
         lines.push(`> Original EARS: ${req.statement}`);
@@ -349,15 +356,17 @@ function generateSpec(feature, preserveRaw = false) {
     // Use original user scenarios
     lines.push('## User Scenarios');
     lines.push('');
-    
+
     for (const scenario of spec.userScenarios) {
       lines.push(`### ${scenario.title}`);
       lines.push('');
-      lines.push(`As a ${scenario.actor}, I want to ${scenario.action} so that ${scenario.benefit}.`);
+      lines.push(
+        `As a ${scenario.actor}, I want to ${scenario.action} so that ${scenario.benefit}.`
+      );
       lines.push('');
       lines.push(`**Priority**: ${scenario.priority}`);
       lines.push('');
-      
+
       if (scenario.acceptanceCriteria && scenario.acceptanceCriteria.length > 0) {
         lines.push('**Acceptance Criteria**:');
         for (const ac of scenario.acceptanceCriteria) {
@@ -367,7 +376,7 @@ function generateSpec(feature, preserveRaw = false) {
       }
     }
   }
-  
+
   // Write success criteria
   if (spec.successCriteria && spec.successCriteria.length > 0) {
     lines.push('## Success Criteria');
@@ -377,7 +386,7 @@ function generateSpec(feature, preserveRaw = false) {
     }
     lines.push('');
   }
-  
+
   // Preserve raw content if requested
   if (preserveRaw && spec.rawContent) {
     lines.push('---');
@@ -388,33 +397,33 @@ function generateSpec(feature, preserveRaw = false) {
     lines.push(spec.rawContent);
     lines.push('```');
   }
-  
+
   return lines.join('\n');
 }
 
 /**
  * Generate plan.md content
- * @param {import('../ir/types').PlanIR} plan 
- * @param {boolean} preserveRaw 
+ * @param {import('../ir/types').PlanIR} plan
+ * @param {boolean} preserveRaw
  * @returns {string}
  */
 function generatePlan(plan, preserveRaw = false) {
   const lines = [];
-  
+
   lines.push('# Implementation Plan');
   lines.push('');
-  
+
   if (plan.summary) {
     lines.push(plan.summary);
     lines.push('');
   }
-  
+
   // Technical Stack
   const tech = plan.technicalContext;
   if (tech && (tech.language || tech.framework)) {
     lines.push('## Technical Stack');
     lines.push('');
-    
+
     if (tech.language) {
       lines.push(`- **Language**: ${tech.language}${tech.version ? ` ${tech.version}` : ''}`);
     }
@@ -429,21 +438,21 @@ function generatePlan(plan, preserveRaw = false) {
     }
     lines.push('');
   }
-  
+
   // Implementation Phases
   if (plan.phases && plan.phases.length > 0) {
     lines.push('## Implementation Phases');
     lines.push('');
-    
+
     for (const phase of plan.phases) {
       lines.push(`### Phase ${phase.number}: ${phase.name}`);
       lines.push('');
-      
+
       if (phase.purpose) {
         lines.push(phase.purpose);
         lines.push('');
       }
-      
+
       if (phase.outputs && phase.outputs.length > 0) {
         lines.push('**Outputs**:');
         for (const output of phase.outputs) {
@@ -453,7 +462,7 @@ function generatePlan(plan, preserveRaw = false) {
       }
     }
   }
-  
+
   // Preserve raw content if requested
   if (preserveRaw && plan.rawContent) {
     lines.push('---');
@@ -464,21 +473,21 @@ function generatePlan(plan, preserveRaw = false) {
     lines.push(plan.rawContent);
     lines.push('```');
   }
-  
+
   return lines.join('\n');
 }
 
 /**
  * Generate tasks.md content (Spec Kit format)
- * @param {import('../ir/types').TaskIR[]} tasks 
+ * @param {import('../ir/types').TaskIR[]} tasks
  * @returns {string}
  */
 function generateTasks(tasks) {
   const lines = [];
-  
+
   lines.push('# Tasks');
   lines.push('');
-  
+
   // Group by phase
   const phases = {};
   for (const task of tasks) {
@@ -488,43 +497,45 @@ function generateTasks(tasks) {
     }
     phases[phase].push(task);
   }
-  
+
   for (const [phaseNum, phaseTasks] of Object.entries(phases)) {
     lines.push(`## Phase ${phaseNum}`);
     lines.push('');
-    
+
     for (const task of phaseTasks) {
       const checkbox = task.completed ? '[x]' : '[ ]';
       const parallelMarker = task.parallel ? '[P] ' : '';
       const storyMarker = task.userStory ? `[${task.userStory}] ` : '';
       const pathSuffix = task.filePath ? ` at ${task.filePath}` : '';
-      
+
       // Spec Kit format: - [ ] T001 [P] [US1] Description at path/
-      lines.push(`- ${checkbox} ${task.id} ${parallelMarker}${storyMarker}${task.description}${pathSuffix}`);
+      lines.push(
+        `- ${checkbox} ${task.id} ${parallelMarker}${storyMarker}${task.description}${pathSuffix}`
+      );
     }
     lines.push('');
   }
-  
+
   return lines.join('\n');
 }
 
 /**
  * Generate research.md content
- * @param {import('../ir/types').ResearchIR} research 
- * @param {boolean} preserveRaw 
+ * @param {import('../ir/types').ResearchIR} research
+ * @param {boolean} preserveRaw
  * @returns {string}
  */
 function generateResearch(research, preserveRaw = false) {
   const lines = [];
-  
+
   lines.push('# Research');
   lines.push('');
-  
+
   // Decisions
   if (research.decisions && research.decisions.length > 0) {
     lines.push('## Decisions');
     lines.push('');
-    
+
     for (const decision of research.decisions) {
       lines.push(`### ${decision.topic}`);
       lines.push('');
@@ -535,16 +546,16 @@ function generateResearch(research, preserveRaw = false) {
       lines.push('');
     }
   }
-  
+
   // Alternatives Considered
   if (research.alternatives && research.alternatives.length > 0) {
     lines.push('## Alternatives Considered');
     lines.push('');
-    
+
     for (const alt of research.alternatives) {
       lines.push(`### ${alt.name}`);
       lines.push('');
-      
+
       if (alt.pros && alt.pros.length > 0) {
         lines.push('**Pros**:');
         for (const pro of alt.pros) {
@@ -552,7 +563,7 @@ function generateResearch(research, preserveRaw = false) {
         }
         lines.push('');
       }
-      
+
       if (alt.cons && alt.cons.length > 0) {
         lines.push('**Cons**:');
         for (const con of alt.cons) {
@@ -560,7 +571,7 @@ function generateResearch(research, preserveRaw = false) {
         }
         lines.push('');
       }
-      
+
       if (alt.rejected) {
         lines.push(`**Status**: Rejected`);
         if (alt.reason) {
@@ -570,7 +581,7 @@ function generateResearch(research, preserveRaw = false) {
       }
     }
   }
-  
+
   // Preserve raw content if requested
   if (preserveRaw && research.rawContent) {
     lines.push('---');
@@ -581,36 +592,36 @@ function generateResearch(research, preserveRaw = false) {
     lines.push(research.rawContent);
     lines.push('```');
   }
-  
+
   return lines.join('\n');
 }
 
 /**
  * Generate data-model.md content
- * @param {import('../ir/types').DataModelIR} dataModel 
- * @param {boolean} preserveRaw 
+ * @param {import('../ir/types').DataModelIR} dataModel
+ * @param {boolean} preserveRaw
  * @returns {string}
  */
 function generateDataModel(dataModel, preserveRaw = false) {
   const lines = [];
-  
+
   lines.push('# Data Model');
   lines.push('');
-  
+
   // Entities
   if (dataModel.entities && dataModel.entities.length > 0) {
     lines.push('## Entities');
     lines.push('');
-    
+
     for (const entity of dataModel.entities) {
       lines.push(`### Entity: ${entity.name}`);
       lines.push('');
-      
+
       if (entity.description) {
         lines.push(entity.description);
         lines.push('');
       }
-      
+
       if (entity.fields && entity.fields.length > 0) {
         for (const field of entity.fields) {
           let fieldLine = `- ${field.name}: ${field.type}`;
@@ -621,19 +632,19 @@ function generateDataModel(dataModel, preserveRaw = false) {
       }
     }
   }
-  
+
   // Relationships
   if (dataModel.relationships && dataModel.relationships.length > 0) {
     lines.push('## Relationships');
     lines.push('');
-    
+
     for (const rel of dataModel.relationships) {
       const relType = rel.type === 'one-to-many' ? 'has many' : 'has one';
       lines.push(`- ${rel.from} ${relType} ${rel.to}`);
     }
     lines.push('');
   }
-  
+
   // Preserve raw content if requested
   if (preserveRaw && dataModel.rawContent) {
     lines.push('---');
@@ -644,44 +655,44 @@ function generateDataModel(dataModel, preserveRaw = false) {
     lines.push(dataModel.rawContent);
     lines.push('```');
   }
-  
+
   return lines.join('\n');
 }
 
 /**
  * Generate contract content
- * @param {import('../ir/types').ContractIR} contract 
+ * @param {import('../ir/types').ContractIR} contract
  * @returns {string}
  */
 function generateContract(contract) {
   const lines = [];
-  
+
   lines.push(`# ${contract.name}`);
   lines.push('');
   lines.push(`**Type**: ${contract.type.toUpperCase()}`);
   lines.push('');
-  
+
   if (contract.rawContent) {
     lines.push(contract.rawContent);
   } else {
     lines.push('> Contract details to be defined.');
   }
-  
+
   return lines.join('\n');
 }
 
 /**
  * Generate quickstart.md content
- * @param {import('../ir/types').QuickstartIR} quickstart 
- * @param {boolean} preserveRaw 
+ * @param {import('../ir/types').QuickstartIR} quickstart
+ * @param {boolean} preserveRaw
  * @returns {string}
  */
 function generateQuickstart(quickstart, preserveRaw = false) {
   const lines = [];
-  
+
   lines.push('# Quickstart');
   lines.push('');
-  
+
   if (quickstart.steps && quickstart.steps.length > 0) {
     for (let i = 0; i < quickstart.steps.length; i++) {
       const step = quickstart.steps[i];
@@ -689,7 +700,7 @@ function generateQuickstart(quickstart, preserveRaw = false) {
     }
     lines.push('');
   }
-  
+
   // Preserve raw content if requested
   if (preserveRaw && quickstart.rawContent) {
     lines.push('---');
@@ -700,7 +711,7 @@ function generateQuickstart(quickstart, preserveRaw = false) {
     lines.push(quickstart.rawContent);
     lines.push('```');
   }
-  
+
   return lines.join('\n');
 }