@polymorphism-tech/morph-spec 8.1.2 → 8.2.0

package/src/lib/generators/mandate-generator.js

@@ -1,468 +0,0 @@
-/**
- * Implementation Mandate Generator
- *
- * Synthesizes the plan-phase outputs (spec.md, tasks.json, decisions.md) into
- * a single task-structured implementation mandate. Contracts are read from
- * spec.md (v5 keeps contracts inside the spec, not in separate files).
- *
- * The mandate is the primary context artifact for the implement phase —
- * each task section is self-contained with acceptance criteria, contracts,
- * file paths, and architectural constraints.
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-import { validateTasksJson } from '../tasks/tasks-json-parser.js';
-
-/**
- * Resolve a single task object from parsed tasks.json data.
- * FR references are extracted from the task `description` (v5 convention:
- * tasks reference their FR(s) inline in the description).
- *
- * @param {object} tasksData - Parsed tasks.json structure
- * @param {string} taskId - Task id (e.g. 'T1')
- * @returns {{ id: string, title: string, description: string, frs: string[] }|null}
- */
-function resolveTask(tasksData, taskId) {
-  const task = tasksData.tasks.find(t => t.id === taskId);
-  if (!task) return null;
-  const frRefs = [...(task.description || '').matchAll(/\bFR-?\d+\b/g)].map(m => m[0]);
-  return {
-    id: task.id,
-    title: task.title || '',
-    description: task.description || '',
-    frs: [...new Set(frRefs)],
-    files: Array.isArray(task.outputs) ? task.outputs : [],
-  };
-}
-
-/**
- * Extract all FR sections from spec.md.
- *
- * @param {string} specContent - Full spec.md content
- * @returns {Map<string, { title: string, content: string, criteria: string[] }>}
- */
-function parseFRSections(specContent) {
-  const sections = new Map();
-  const frPattern = /^##\s+(FR\d+)[:\s—–-]+(.+?)$/gm;
-  let match;
-  const matches = [];
-
-  while ((match = frPattern.exec(specContent)) !== null) {
-    matches.push({
-      id: match[1],
-      title: match[2].trim(),
-      start: match.index,
-      headerEnd: match.index + match[0].length,
-    });
-  }
-
-  for (let i = 0; i < matches.length; i++) {
-    const current = matches[i];
-    const nextStart = i + 1 < matches.length ? matches[i + 1].start : specContent.length;
-    const body = specContent.slice(current.headerEnd, nextStart).trim();
-
-    // Extract bullet points as acceptance criteria
-    const criteria = [];
-    const bulletPattern = /^[\s]*[-*]\s+(.+)/gm;
-    let bulletMatch;
-    while ((bulletMatch = bulletPattern.exec(body)) !== null) {
-      criteria.push(bulletMatch[1].trim());
-    }
-
-    sections.set(current.id, {
-      title: current.title,
-      content: body,
-      criteria,
-    });
-  }
-
-  return sections;
-}
-
-/**
- * Extract contract types/interfaces from content. Matches C# records, classes,
- * interfaces and TypeScript types/interfaces — v5 contracts are defined inside
- * spec.md, so this scans the spec content.
- *
- * @param {string} contractsContent - Content to scan for contract definitions
- * @returns {Map<string, string>} Map of type name → definition
- */
-function parseContracts(contractsContent) {
-  const types = new Map();
-
-  // C# sealed records: sealed record Foo(...)
-  const csRecordPattern = /^\s*((?:public\s+)?sealed\s+record\s+\w+\([^)]*\)\s*;)/gm;
-  let match;
-  while ((match = csRecordPattern.exec(contractsContent)) !== null) {
-    const nameMatch = match[1].match(/record\s+(\w+)/);
-    if (nameMatch) {
-      types.set(nameMatch[1], match[1].trim());
-    }
-  }
-
-  // C# interfaces: public interface IFoo { ... }
-  const csInterfacePattern = /^\s*((?:public\s+)?interface\s+\w+\s*\{[^}]*\})/gms;
-  while ((match = csInterfacePattern.exec(contractsContent)) !== null) {
-    const nameMatch = match[1].match(/interface\s+(\w+)/);
-    if (nameMatch) {
-      types.set(nameMatch[1], match[1].trim());
-    }
-  }
-
-  // TypeScript types/interfaces
-  const tsTypePattern = /^\s*(export\s+(?:type|interface)\s+\w+[\s\S]*?(?:\};?|=[^;]+;))/gm;
-  while ((match = tsTypePattern.exec(contractsContent)) !== null) {
-    const nameMatch = match[1].match(/(?:type|interface)\s+(\w+)/);
-    if (nameMatch) {
-      types.set(nameMatch[1], match[1].trim());
-    }
-  }
-
-  return types;
-}
-
-/**
- * Extract architectural constraints from decisions.md.
- *
- * @param {string} decisionsContent - Full decisions.md content
- * @returns {string[]} One-line constraint summaries
- */
-function parseDecisions(decisionsContent) {
-  const constraints = [];
-  const adrPattern = /^###?\s+(ADR-\d+)[:\s—–-]+(.+?)$/gm;
-  let match;
-
-  while ((match = adrPattern.exec(decisionsContent)) !== null) {
-    constraints.push(`${match[1]}: ${match[2].trim()}`);
-  }
-
-  return constraints;
-}
-
-/**
- * Extract all task IDs from parsed tasks.json data, in declared order.
- *
- * @param {object} tasksData - Parsed tasks.json structure
- * @returns {string[]} Task IDs in order (e.g., ['T1', 'T2', ...])
- */
-function extractTaskIds(tasksData) {
-  return tasksData.tasks.map(t => t.id);
-}
-
-/**
- * Find contract types relevant to an FR or task.
- * Matches by: type name in content, or FR title keywords in type name.
- *
- * @param {string} searchText - FR content + task title/description
- * @param {Map<string, string>} contracts - Parsed contracts
- * @returns {string[]} Matching contract definitions
- */
-function findRelevantContracts(searchText, contracts) {
-  const relevant = [];
-  const searchLower = searchText.toLowerCase();
-
-  for (const [typeName, definition] of contracts) {
-    // Direct match: type name appears in the search text
-    if (searchText.includes(typeName)) {
-      relevant.push(definition);
-      continue;
-    }
-    // Keyword match: split type name into words (e.g., UserRegisterRequest → user, register, request)
-    // and check if the significant words appear in the search text
-    const typeWords = typeName
-      .replace(/([a-z])([A-Z])/g, '$1 $2')
-      .toLowerCase()
-      .split(/\s+/)
-      .filter(w => w.length > 3 && !['request', 'response', 'result'].includes(w));
-    if (typeWords.length > 0 && typeWords.every(w => searchLower.includes(w))) {
-      relevant.push(definition);
-    }
-  }
-  return relevant;
-}
-
-/**
- * Generate an implementation mandate from spec phase outputs.
- *
- * @param {string} projectPath - Project root
- * @param {string} featureName - Feature name
- * @returns {{ mandate: string, stats: { frCount: number, taskCount: number, totalChars: number } }|null}
- */
-export function generateMandate(projectPath, featureName) {
-  const featureDir = join(projectPath, '.morph/features', featureName);
-
-  // Read required files
-  const tasksPath = join(featureDir, '2-plan/tasks.json');
-  const specPath = join(featureDir, '2-plan/spec.md');
-
-  if (!existsSync(tasksPath) || !existsSync(specPath)) return null;
-
-  let tasksData;
-  try {
-    tasksData = JSON.parse(readFileSync(tasksPath, 'utf-8'));
-  } catch {
-    return null;
-  }
-  if (!validateTasksJson(tasksData).valid) return null;
-  const specContent = readFileSync(specPath, 'utf-8');
-
-  // Read optional files
-  const decisionsPath = join(featureDir, '2-plan/decisions.md');
-  const decisionsContent = existsSync(decisionsPath) ? readFileSync(decisionsPath, 'utf-8') : '';
-
-  const proposalPath = join(featureDir, '0-proposal/proposal.md');
-  const proposalContent = existsSync(proposalPath) ? readFileSync(proposalPath, 'utf-8') : '';
-
-  // Read project config
-  let stack = '';
-  let architecture = '';
-  try {
-    const configPath = join(projectPath, '.morph/config/config.json');
-    if (existsSync(configPath)) {
-      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
-      stack = config?.project?.stack || '';
-      architecture = config?.architecture?.style || '';
-    }
-  } catch { /* ignore */ }
-
-  // Parse all inputs. v5: contracts live inside spec.md (no separate
-  // contracts.cs/.ts file) — parseContracts scans the spec content.
-  const frSections = parseFRSections(specContent);
-  const contracts = parseContracts(specContent);
-  const decisions = parseDecisions(decisionsContent);
-  const taskIds = extractTaskIds(tasksData);
-
-  // Build mandate
-  const lines = [];
-
-  // Header
-  lines.push(`# Implementation Mandate: ${featureName}`);
-  lines.push('');
-  lines.push(`**Generated:** ${new Date().toISOString().split('T')[0]} | **FRs:** ${frSections.size} | **Tasks:** ${taskIds.length}`);
-  if (stack || architecture) {
-    lines.push(`**Stack:** ${stack || 'unspecified'} | **Architecture:** ${architecture || 'unspecified'}`);
-  }
-
-  // Overview from proposal
-  if (proposalContent) {
-    lines.push('');
-    lines.push('## Overview');
-    // Extract first paragraph after the title
-    const paragraphs = proposalContent
-      .split(/\n\n+/)
-      .filter(p => p.trim() && !p.trim().startsWith('#'))
-      .slice(0, 1);
-    if (paragraphs.length > 0) {
-      lines.push(paragraphs[0].trim());
-    }
-  }
-
-  // Architectural constraints
-  if (decisions.length > 0) {
-    lines.push('');
-    lines.push('## Architectural Constraints');
-    for (const d of decisions) {
-      lines.push(`- ${d}`);
-    }
-  }
-
-  // Task sections
-  for (const taskId of taskIds) {
-    const task = resolveTask(tasksData, taskId);
-    if (!task) continue;
-
-    lines.push('');
-    lines.push('---');
-    lines.push('');
-    lines.push(`## ${taskId}: ${task.title}`);
-
-    // Metadata line
-    const metaParts = [];
-    if (task.frs.length > 0) metaParts.push(`**FRs:** ${task.frs.join(', ')}`);
-    if (task.files.length > 0) metaParts.push(`**Files:** ${task.files.join(', ')}`);
-    if (metaParts.length > 0) lines.push(metaParts.join(' | '));
-
-    // Acceptance criteria from FR sections
-    const allCriteria = [];
-    const allFRContracts = [];
-    for (const frId of task.frs) {
-      const fr = frSections.get(frId);
-      if (fr) {
-        allCriteria.push(...fr.criteria);
-        // Search for contracts in FR content + task title for broader matching
-        const searchText = `${fr.title} ${fr.content} ${task.title} ${task.description}`;
-        allFRContracts.push(...findRelevantContracts(searchText, contracts));
-      }
-    }
-
-    if (allCriteria.length > 0) {
-      lines.push('');
-      lines.push('### Acceptance Criteria');
-      for (const c of allCriteria) {
-        lines.push(`- [ ] ${c}`);
-      }
-    }
-
-    // Contracts
-    const uniqueContracts = [...new Set(allFRContracts)];
-    if (uniqueContracts.length > 0) {
-      lines.push('');
-      lines.push('### Contracts');
-      lines.push('```');
-      lines.push(uniqueContracts.join('\n'));
-      lines.push('```');
-    }
-
-    // Task description as notes
-    if (task.description) {
-      lines.push('');
-      lines.push('### Notes');
-      lines.push(task.description);
-    }
-  }
-
-  // Verification summary
-  lines.push('');
-  lines.push('---');
-  lines.push('');
-  lines.push('## Verification');
-  lines.push('```bash');
-  if (stack.includes('dotnet')) {
-    lines.push('dotnet build');
-    lines.push('dotnet test');
-  } else {
-    lines.push('npm run build');
-    lines.push('npm test');
-  }
-  lines.push('```');
-
-  const mandate = lines.join('\n');
-
-  return {
-    mandate,
-    stats: {
-      frCount: frSections.size,
-      taskCount: taskIds.length,
-      totalChars: mandate.length,
-    },
-  };
-}
-
-/**
- * Extract a single task's section from a generated mandate.
- *
- * @param {string} mandateContent - Full mandate.md content
- * @param {string} taskId - Task ID (e.g., 'T003')
- * @returns {string|null} Task section text or null if not found
- */
-export function extractTaskSection(mandateContent, taskId) {
-  // Find the start of this task's section
-  const headerPattern = new RegExp(`^## ${taskId}:`, 'm');
-  const headerMatch = headerPattern.exec(mandateContent);
-  if (!headerMatch) return null;
-
-  const start = headerMatch.index;
-
-  // Find the end: next task header, Verification section, or end of content
-  const rest = mandateContent.slice(start + 1);
-  const endPatterns = [
-    /\n## T\d+:/,
-    /\n## Verification/,
-  ];
-
-  let end = mandateContent.length;
-  for (const pattern of endPatterns) {
-    const endMatch = pattern.exec(rest);
-    if (endMatch) {
-      const candidate = start + 1 + endMatch.index;
-      if (candidate < end) end = candidate;
-    }
-  }
-
-  // Extract and trim, removing trailing --- separators
-  let section = mandateContent.slice(start, end).trim();
-  section = section.replace(/\n---\s*$/, '').trim();
-
-  return section;
-}
-
-/**
- * Extract multiple task sections (for agent dispatch).
- *
- * @param {string} mandateContent - Full mandate.md content
- * @param {string[]} taskIds - Task IDs (e.g., ['T001', 'T002', 'T003'])
- * @returns {string} Combined task sections
- */
-export function extractTaskSections(mandateContent, taskIds) {
-  const sections = [];
-  for (const taskId of taskIds) {
-    const section = extractTaskSection(mandateContent, taskId);
-    if (section) sections.push(section);
-  }
-  return sections.join('\n\n---\n\n');
-}
-
-/**
- * Generate a mandate overview (for session start injection).
- * Shows FR list with task mapping and completion status.
- *
- * @param {string} mandateContent - Full mandate.md content
- * @param {Object} taskStatus - Map of taskId → status ('completed'|'in_progress'|'pending')
- * @returns {string} Overview text
- */
-export function generateMandateOverview(mandateContent, taskStatus = {}) {
-  const lines = [];
-
-  // Extract task-to-FR mapping from mandate
-  const taskFRMap = new Map();
-  const frTaskMap = new Map();
-
-  const taskPattern = /^## (T\d+): .+$/gm;
-  const frLinePattern = /^\*\*FRs:\*\*\s+(.+?)(?:\s*\||$)/gm;
-
-  let match;
-  let lastTaskId = null;
-
-  while ((match = taskPattern.exec(mandateContent)) !== null) {
-    lastTaskId = match[1];
-    // Look for FRs line right after task header
-    const afterHeader = mandateContent.slice(match.index + match[0].length, match.index + match[0].length + 200);
-    const frMatch = afterHeader.match(/\*\*FRs:\*\*\s+([^\n|]+)/);
-    if (frMatch) {
-      const frs = frMatch[1].split(',').map(f => f.trim()).filter(Boolean);
-      taskFRMap.set(lastTaskId, frs);
-      for (const fr of frs) {
-        if (!frTaskMap.has(fr)) frTaskMap.set(fr, []);
-        frTaskMap.get(fr).push(lastTaskId);
-      }
-    }
-  }
-
-  // Build overview
-  lines.push('Implementation Mandate Overview:');
-
-  for (const [frId, taskIds] of frTaskMap) {
-    const taskStatuses = taskIds.map(tid => {
-      const status = taskStatus[tid] || 'pending';
-      if (status === 'completed') return `${tid} ✓`;
-      if (status === 'in_progress') return `${tid} →`;
-      return tid;
-    });
-    lines.push(`  ${frId} → ${taskStatuses.join(', ')}`);
-  }
-
-  // Next task
-  const allTaskIds = [...taskFRMap.keys()];
-  const nextTask = allTaskIds.find(tid => {
-    const status = taskStatus[tid];
-    return status === 'in_progress' || !status || status === 'pending';
-  });
-  if (nextTask) {
-    const status = taskStatus[nextTask];
-    const verb = status === 'in_progress' ? 'In progress' : 'Next';
-    lines.push(`  ${verb}: ${nextTask}`);
-  }
-
-  return lines.join('\n');
-}