@eddacraft/anvil-adapters 0.1.0

package/src/speckit/parsers/plan-parser.ts

@@ -0,0 +1,342 @@
+/**
+ * Parser for official GitHub Spec-Kit plan.md format
+ *
+ * Plan.md focuses on HOW (technical implementation):
+ * - Summary
+ * - Technical Context (stack, dependencies, constraints)
+ * - Constitution Check (compliance with project principles)
+ * - Project Structure (directories, files)
+ * - Implementation Details (API endpoints, database schema, etc.)
+ * - Complexity Tracking (design decisions)
+ */
+
+interface PlanMetadata {
+  feature?: string;
+  branch?: string;
+  date?: string;
+  spec?: string;
+  [key: string]: unknown;
+}
+
+interface TechnicalContext {
+  language?: string;
+  dependencies?: string[];
+  storage?: string;
+  testing?: string;
+  target?: string;
+  type?: string;
+  performanceGoals?: string[];
+  constraints?: string[];
+  scale?: string;
+}
+
+interface ConstitutionCheck {
+  modularity?: boolean | string;
+  testability?: boolean | string;
+  security?: boolean | string;
+  performance?: boolean | string;
+  maintainability?: boolean | string;
+  documentation?: boolean | string;
+  [key: string]: boolean | string | undefined;
+}
+
+interface ProjectStructure {
+  documentation?: string;
+  sourceCode?: string;
+  selectedOption?: string;
+}
+
+interface ComplexityDecision {
+  title: string;
+  problem: string;
+  solution: string;
+  justification: string;
+}
+
+export interface ParsedPlan {
+  metadata: PlanMetadata;
+  summary: string;
+  technicalContext: TechnicalContext;
+  constitutionCheck: ConstitutionCheck;
+  projectStructure: ProjectStructure;
+  implementationDetails: Map<string, string>; // Section title -> content
+  complexityDecisions: ComplexityDecision[];
+}
+
+export class PlanParser {
+  parsePlan(content: string): ParsedPlan {
+    const result: ParsedPlan = {
+      metadata: {},
+      summary: '',
+      technicalContext: {},
+      constitutionCheck: {},
+      projectStructure: {},
+      implementationDetails: new Map(),
+      complexityDecisions: [],
+    };
+
+    // Extract metadata from first section
+    result.metadata = this.extractMetadata(content);
+
+    // Parse summary section
+    result.summary = this.extractSummary(content);
+
+    // Parse technical context
+    result.technicalContext = this.parseTechnicalContext(content);
+
+    // Parse constitution check
+    result.constitutionCheck = this.parseConstitutionCheck(content);
+
+    // Parse project structure
+    result.projectStructure = this.parseProjectStructure(content);
+
+    // Parse implementation details (flexible sections)
+    result.implementationDetails = this.parseImplementationDetails(content);
+
+    // Parse complexity tracking
+    result.complexityDecisions = this.parseComplexityDecisions(content);
+
+    return result;
+  }
+
+  private extractMetadata(content: string): PlanMetadata {
+    const metadata: PlanMetadata = {};
+
+    // Extract title (# Implementation Plan: ...)
+    const titleMatch = content.match(/^#\s+Implementation Plan:\s+(.+)$/m);
+    if (titleMatch) {
+      metadata.feature = titleMatch[1].trim();
+    }
+
+    // Extract bold key-value pairs
+    const metadataRegex = /\*\*([^*]+)\*\*:\s*(?:`([^`\n]+)`|\[([^\]]+)\]\(([^)]+)\)|([^\n]+))/g;
+    let match;
+    while ((match = metadataRegex.exec(content)) !== null) {
+      const key = match[1].trim().toLowerCase().replace(/\s+/g, '_');
+      const value = match[2] || match[3] || match[5] || '';
+      metadata[key] = value.trim();
+    }
+
+    return metadata;
+  }
+
+  private extractSummary(content: string): string {
+    const summaryMatch = content.match(/##\s+Summary\s+([\s\S]*?)(?=\n##\s|$)/i);
+    return summaryMatch?.[1]?.trim() || '';
+  }
+
+  private parseTechnicalContext(content: string): TechnicalContext {
+    const context: TechnicalContext = {};
+
+    const contextMatch = content.match(/##\s+Technical Context([\s\S]*?)(?=\n##\s|$)/i);
+
+    if (!contextMatch) {
+      return context;
+    }
+
+    const contextSection = contextMatch[1];
+
+    // Parse bullet points with key-value pairs
+    const languageMatch = contextSection.match(/[-*]\s+\*\*Language\/Version\*\*:\s+(.+)/i);
+    if (languageMatch) {
+      context.language = languageMatch[1].trim();
+    }
+
+    const storageMatch = contextSection.match(/[-*]\s+\*\*Storage\*\*:\s+(.+)/i);
+    if (storageMatch) {
+      context.storage = storageMatch[1].trim();
+    }
+
+    const testingMatch = contextSection.match(/[-*]\s+\*\*Testing\*\*:\s+(.+)/i);
+    if (testingMatch) {
+      context.testing = testingMatch[1].trim();
+    }
+
+    const targetMatch = contextSection.match(/[-*]\s+\*\*Target\*\*:\s+(.+)/i);
+    if (targetMatch) {
+      context.target = targetMatch[1].trim();
+    }
+
+    const typeMatch = contextSection.match(/[-*]\s+\*\*Type\*\*:\s+(.+)/i);
+    if (typeMatch) {
+      context.type = typeMatch[1].trim();
+    }
+
+    const scaleMatch = contextSection.match(/[-*]\s+\*\*Scale\*\*:\s+(.+)/i);
+    if (scaleMatch) {
+      context.scale = scaleMatch[1].trim();
+    }
+
+    // Parse dependencies (multi-line list)
+    const depsMatch = contextSection.match(
+      /[-*]\s+\*\*Dependencies\*\*:\s+([\s\S]*?)(?=\n[-*]\s+\*\*|$)/i
+    );
+    if (depsMatch) {
+      const deps = depsMatch[1]
+        .split(/\n\s*[-*]\s+/)
+        .map((d) => d.trim())
+        .filter((d) => d.length > 0);
+      context.dependencies = deps;
+    }
+
+    // Parse performance goals
+    const perfMatch = contextSection.match(
+      /[-*]\s+\*\*Performance Goals\*\*:\s+([\s\S]*?)(?=\n[-*]\s+\*\*|$)/i
+    );
+    if (perfMatch) {
+      const goals = perfMatch[1]
+        .split(/\n\s*[-*]\s+/)
+        .map((g) => g.trim())
+        .filter((g) => g.length > 0);
+      context.performanceGoals = goals;
+    }
+
+    // Parse constraints
+    const constraintsMatch = contextSection.match(
+      /[-*]\s+\*\*Constraints\*\*:\s+([\s\S]*?)(?=\n[-*]\s+\*\*|$)/i
+    );
+    if (constraintsMatch) {
+      const constraints = constraintsMatch[1]
+        .split(/\n\s*[-*]\s+/)
+        .map((c) => c.trim())
+        .filter((c) => c.length > 0);
+      context.constraints = constraints;
+    }
+
+    return context;
+  }
+
+  private parseConstitutionCheck(content: string): ConstitutionCheck {
+    const check: ConstitutionCheck = {};
+
+    const checkMatch = content.match(/##\s+Constitution Check([\s\S]*?)(?=\n##\s|$)/i);
+
+    if (!checkMatch) {
+      return check;
+    }
+
+    const checkSection = checkMatch[1];
+
+    // Parse ✅ or ❌ followed by **Key**: Description
+    const checkRegex = /([✅❌✓✗×])\s+\*\*([^*]+)\*\*:\s+(.+)/g;
+    let match;
+
+    while ((match = checkRegex.exec(checkSection)) !== null) {
+      const status = match[1];
+      const key = match[2].trim().toLowerCase().replace(/\s+/g, '_');
+      const description = match[3].trim();
+
+      // Check if it passes or fails
+      const passes = status === '✅' || status === '✓';
+      check[key] = passes ? description : `FAIL: ${description}`;
+    }
+
+    return check;
+  }
+
+  private parseProjectStructure(content: string): ProjectStructure {
+    const structure: ProjectStructure = {};
+
+    const structureMatch = content.match(/##\s+Project Structure([\s\S]*?)(?=\n##\s|$)/i);
+
+    if (!structureMatch) {
+      return structure;
+    }
+
+    const structureSection = structureMatch[1];
+
+    // Extract documentation structure (code block)
+    const docsMatch = structureSection.match(
+      /###\s+Documentation[\s\S]*?```[\s\S]*?\n([\s\S]*?)```/i
+    );
+    if (docsMatch) {
+      structure.documentation = docsMatch[1].trim();
+    }
+
+    // Extract source code structure
+    const sourceMatch = structureSection.match(
+      /###\s+Source Code Structure[\s\S]*?```[\s\S]*?\n([\s\S]*?)```/i
+    );
+    if (sourceMatch) {
+      structure.sourceCode = sourceMatch[1].trim();
+    }
+
+    // Check for "Selected" or "(Selected)" marker
+    const selectedMatch = structureSection.match(/####\s+Option \d+:([^(]+)\(Selected\)/i);
+    if (selectedMatch) {
+      structure.selectedOption = selectedMatch[1].trim();
+    }
+
+    return structure;
+  }
+
+  private parseImplementationDetails(content: string): Map<string, string> {
+    const details = new Map<string, string>();
+
+    // Find "Implementation Details" section
+    const detailsMatch = content.match(
+      /##\s+Implementation Details([\s\S]*?)(?=\n##\s+Complexity|$)/i
+    );
+
+    if (!detailsMatch) {
+      return details;
+    }
+
+    const detailsSection = detailsMatch[1];
+
+    // Split by ### headers
+    const subsectionRegex = /###\s+([^\n]+)\n([\s\S]*?)(?=\n###|$)/g;
+    let match;
+
+    while ((match = subsectionRegex.exec(detailsSection)) !== null) {
+      const title = match[1].trim();
+      const content = match[2].trim();
+      details.set(title, content);
+    }
+
+    return details;
+  }
+
+  private parseComplexityDecisions(content: string): ComplexityDecision[] {
+    const decisions: ComplexityDecision[] = [];
+
+    // Find "Complexity Tracking" section
+    const complexityMatch = content.match(/##\s+Complexity Tracking([\s\S]*?)$/i);
+
+    if (!complexityMatch) {
+      return decisions;
+    }
+
+    const complexitySection = complexityMatch[1];
+
+    // Split by ### headers (each decision)
+    const decisionBlocks = complexitySection.split(/###\s+/).slice(1);
+
+    for (const block of decisionBlocks) {
+      const decision = this.parseComplexityDecision(block);
+      if (decision) {
+        decisions.push(decision);
+      }
+    }
+
+    return decisions;
+  }
+
+  private parseComplexityDecision(block: string): ComplexityDecision | null {
+    const titleMatch = block.match(/^([^\n]+)/);
+    const problemMatch = block.match(/\*\*Problem\*\*:\s+(.+?)(?=\n\*\*|$)/s);
+    const solutionMatch = block.match(/\*\*Solution\*\*:\s+([\s\S]+?)(?=\n\*\*|$)/);
+    const justificationMatch = block.match(/\*\*Justification\*\*:\s+([\s\S]+?)(?=\n###|$)/);
+
+    if (!titleMatch) {
+      return null;
+    }
+
+    return {
+      title: titleMatch[1].trim(),
+      problem: problemMatch?.[1]?.trim() || '',
+      solution: solutionMatch?.[1]?.trim() || '',
+      justification: justificationMatch?.[1]?.trim() || '',
+    };
+  }
+}

package/src/speckit/parsers/spec-parser.ts

@@ -0,0 +1,379 @@
+/**
+ * Parser for official GitHub Spec-Kit spec.md format
+ *
+ * Spec.md focuses on WHAT and WHY (not HOW):
+ * - Feature metadata
+ * - User Scenarios & Testing (prioritized user stories)
+ * - Requirements (functional requirements, key entities)
+ * - Success Criteria (measurable outcomes)
+ */
+
+interface SpecMetadata {
+  feature?: string;
+  branch?: string;
+  date?: string;
+  status?: string;
+  [key: string]: unknown;
+}
+
+interface UserScenario {
+  priority: 'P1' | 'P2' | 'P3' | string;
+  title: string;
+  asA: string;
+  iWantTo: string;
+  soThat: string;
+  acceptanceScenarios: string[];
+  edgeCases: string[];
+}
+
+interface FunctionalRequirement {
+  code: string;
+  description: string;
+  needsClarification: boolean;
+  clarificationQuestion?: string;
+}
+
+interface EntityDefinition {
+  name: string;
+  represents: string;
+  keyAttributes: string[];
+  relationships: string[];
+}
+
+interface SuccessCriteria {
+  quantitative: string[];
+  qualitative: string[];
+  security?: string[];
+  performance?: string[];
+}
+
+export interface ParsedSpec {
+  metadata: SpecMetadata;
+  userScenarios: UserScenario[];
+  requirements: {
+    functional: FunctionalRequirement[];
+    entities: EntityDefinition[];
+  };
+  successCriteria: SuccessCriteria;
+  clarifications: string[]; // All [NEEDS CLARIFICATION] markers
+}
+
+export class SpecParser {
+  parseSpec(content: string): ParsedSpec {
+    const result: ParsedSpec = {
+      metadata: {},
+      userScenarios: [],
+      requirements: {
+        functional: [],
+        entities: [],
+      },
+      successCriteria: {
+        quantitative: [],
+        qualitative: [],
+      },
+      clarifications: [],
+    };
+
+    // Extract metadata from first section (before ## headers)
+    result.metadata = this.extractMetadata(content);
+
+    // Parse user scenarios section
+    result.userScenarios = this.parseUserScenarios(content);
+
+    // Parse requirements section
+    result.requirements = this.parseRequirements(content);
+
+    // Parse success criteria
+    result.successCriteria = this.parseSuccessCriteria(content);
+
+    // Extract all clarifications
+    result.clarifications = this.extractClarifications(content);
+
+    return result;
+  }
+
+  private extractMetadata(content: string): SpecMetadata {
+    const metadata: SpecMetadata = {};
+
+    // Extract title (# Feature: ...)
+    const titleMatch = content.match(/^#\s+Feature:\s+(.+)$/m);
+    if (titleMatch) {
+      metadata.feature = titleMatch[1].trim();
+    }
+
+    // Extract bold key-value pairs (** Key **: value)
+    // Stop at next ** or newline to handle multiple metadata on same line
+    const metadataRegex = /\*\*([^*]+)\*\*:\s*`?([^`*\n]+?)`?\s*(?=\*\*|\n|$)/g;
+    let match;
+    while ((match = metadataRegex.exec(content)) !== null) {
+      const key = match[1].trim().toLowerCase().replace(/\s+/g, '_');
+      const value = match[2].trim();
+      metadata[key] = value;
+    }
+
+    return metadata;
+  }
+
+  private parseUserScenarios(content: string): UserScenario[] {
+    const scenarios: UserScenario[] = [];
+
+    // Find "User Scenarios & Testing" section
+    const scenarioSectionMatch = content.match(
+      /##\s+User Scenarios?\s*(?:&|and)?\s*Testing([\s\S]*?)(?=\n##\s|\n#\s|$)/i
+    );
+
+    if (!scenarioSectionMatch) {
+      return scenarios;
+    }
+
+    const scenarioSection = scenarioSectionMatch[1];
+
+    // Split by ### headers (each scenario)
+    const scenarioBlocks = scenarioSection.split(/###\s+/).slice(1);
+
+    for (const block of scenarioBlocks) {
+      const scenario = this.parseUserScenario(block);
+      if (scenario) {
+        scenarios.push(scenario);
+      }
+    }
+
+    return scenarios;
+  }
+
+  private parseUserScenario(block: string): UserScenario | null {
+    // Extract priority and title from first line (P1: Title)
+    const titleMatch = block.match(/^(P\d+):\s+(.+)$/m);
+    if (!titleMatch) {
+      return null;
+    }
+
+    const priority = titleMatch[1];
+    const title = titleMatch[2].trim();
+
+    // Extract user story components (handle multiline with line breaks)
+    const asAMatch = block.match(/\*\*As a\*\*\s+(.+?)(?=\s*\*\*|\n\n|$)/is);
+    const iWantToMatch = block.match(/\*\*I want(?:\s+to)?\*\*\s+(.+?)(?=\s*\*\*|\n\n|$)/is);
+    const soThatMatch = block.match(/\*\*So(?:\s+|\n)that\*\*\s+(.+?)(?=\s*\n\n|$)/is);
+
+    // Extract acceptance scenarios
+    const acceptanceScenarios: string[] = [];
+    const acceptanceMatch = block.match(
+      /\*\*Acceptance Scenarios:\*\*([\s\S]*?)(?=\*\*Edge Cases:|\*\*\[NEEDS|###|$)/i
+    );
+    if (acceptanceMatch) {
+      const scenarios = acceptanceMatch[1]
+        .split(/\n[-*]\s+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+      acceptanceScenarios.push(...scenarios);
+    }
+
+    // Extract edge cases
+    const edgeCases: string[] = [];
+    const edgeCaseMatch = block.match(/\*\*Edge Cases:\*\*([\s\S]*?)(?=###|$)/i);
+    if (edgeCaseMatch) {
+      const cases = edgeCaseMatch[1]
+        .split(/\n[-*]\s+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+      edgeCases.push(...cases);
+    }
+
+    return {
+      priority,
+      title,
+      asA: asAMatch?.[1]?.trim() || '',
+      iWantTo: iWantToMatch?.[1]?.trim() || '',
+      soThat: soThatMatch?.[1]?.trim() || '',
+      acceptanceScenarios,
+      edgeCases,
+    };
+  }
+
+  private parseRequirements(content: string): {
+    functional: FunctionalRequirement[];
+    entities: EntityDefinition[];
+  } {
+    const requirements = {
+      functional: [] as FunctionalRequirement[],
+      entities: [] as EntityDefinition[],
+    };
+
+    // Find "Requirements" section
+    const reqSectionMatch = content.match(/##\s+Requirements([\s\S]*?)(?=\n##\s|\n#\s|$)/i);
+
+    if (!reqSectionMatch) {
+      return requirements;
+    }
+
+    const reqSection = reqSectionMatch[1];
+
+    // Parse functional requirements
+    requirements.functional = this.parseFunctionalRequirements(reqSection);
+
+    // Parse entity definitions
+    requirements.entities = this.parseEntities(reqSection);
+
+    return requirements;
+  }
+
+  private parseFunctionalRequirements(section: string): FunctionalRequirement[] {
+    const requirements: FunctionalRequirement[] = [];
+
+    // Find "Functional Requirements" subsection
+    const functionalMatch = section.match(/###\s+Functional Requirements([\s\S]*?)(?=\n###|$)/i);
+
+    if (!functionalMatch) {
+      return requirements;
+    }
+
+    const functionalSection = functionalMatch[1];
+
+    // Match FR-XXX: Description or [NEEDS CLARIFICATION: question]
+    const reqRegex = /\*\*(FR-\d+)\*\*:\s+(.+?)(?=\n\*\*FR-|\n###|$)/gs;
+    let match;
+
+    while ((match = reqRegex.exec(functionalSection)) !== null) {
+      const code = match[1];
+      const description = match[2].trim();
+
+      // Check if this is a clarification request
+      const clarificationMatch = description.match(/\[NEEDS CLARIFICATION:\s*(.+?)\]/);
+
+      requirements.push({
+        code,
+        description: clarificationMatch ? description : description,
+        needsClarification: !!clarificationMatch,
+        clarificationQuestion: clarificationMatch?.[1]?.trim(),
+      });
+    }
+
+    return requirements;
+  }
+
+  private parseEntities(section: string): EntityDefinition[] {
+    const entities: EntityDefinition[] = [];
+
+    // Find "Key Entities" subsection
+    const entitiesMatch = section.match(/###\s+Key Entities([\s\S]*?)(?=\n##|$)/i);
+
+    if (!entitiesMatch) {
+      return entities;
+    }
+
+    const entitiesSection = entitiesMatch[1];
+
+    // Split by ** EntityName **
+    const entityBlocks = entitiesSection.split(/\*\*([^*]+)\*\*/g).slice(1);
+
+    for (let i = 0; i < entityBlocks.length; i += 2) {
+      const entityName = entityBlocks[i].trim();
+      const entityContent = entityBlocks[i + 1] || '';
+
+      if (!entityName || !entityContent.trim()) {
+        continue;
+      }
+
+      const entity = this.parseEntity(entityName, entityContent);
+      if (entity) {
+        entities.push(entity);
+      }
+    }
+
+    return entities;
+  }
+
+  private parseEntity(name: string, content: string): EntityDefinition | null {
+    const representsMatch = content.match(/[-*]\s+Represents:\s+(.+)/i);
+    const attributesMatch = content.match(/[-*]\s+Key Attributes:\s+(.+)/i);
+    const relationshipsMatch = content.match(/[-*]\s+Relationships:\s+(.+)/i);
+
+    return {
+      name,
+      represents: representsMatch?.[1]?.trim() || '',
+      keyAttributes:
+        attributesMatch?.[1]
+          ?.split(',')
+          .map((a) => a.trim())
+          .filter((a) => a.length > 0) || [],
+      relationships:
+        relationshipsMatch?.[1]
+          ?.split(',')
+          .map((r) => r.trim())
+          .filter((r) => r.length > 0) || [],
+    };
+  }
+
+  private parseSuccessCriteria(content: string): SuccessCriteria {
+    const criteria: SuccessCriteria = {
+      quantitative: [],
+      qualitative: [],
+    };
+
+    // Find "Success Criteria" section
+    const criteriaSectionMatch = content.match(
+      /##\s+Success Criteria([\s\S]*?)(?=\n##\s|\n#\s|$)/i
+    );
+
+    if (!criteriaSectionMatch) {
+      return criteria;
+    }
+
+    const criteriaSection = criteriaSectionMatch[1];
+
+    // Parse quantitative metrics
+    const quantMatch = criteriaSection.match(/###\s+Quantitative Metrics([\s\S]*?)(?=\n###|$)/i);
+    if (quantMatch) {
+      const metrics = quantMatch[1]
+        .split(/\n[-*]\s+/)
+        .map((m) => m.trim())
+        .filter((m) => m.length > 0);
+      criteria.quantitative = metrics;
+    }
+
+    // Parse qualitative metrics
+    const qualMatch = criteriaSection.match(/###\s+Qualitative Metrics([\s\S]*?)(?=\n###|$)/i);
+    if (qualMatch) {
+      const metrics = qualMatch[1]
+        .split(/\n[-*]\s+/)
+        .map((m) => m.trim())
+        .filter((m) => m.length > 0);
+      criteria.qualitative = metrics;
+    }
+
+    // Parse security metrics (if present)
+    const securityMatch = criteriaSection.match(/###\s+Security Metrics([\s\S]*?)(?=\n###|$)/i);
+    if (securityMatch) {
+      const metrics = securityMatch[1]
+        .split(/\n[-*]\s+/)
+        .map((m) => m.trim())
+        .filter((m) => m.length > 0);
+      criteria.security = metrics;
+    }
+
+    // Parse performance metrics (if present)
+    const perfMatch = criteriaSection.match(/###\s+Performance Metrics([\s\S]*?)(?=\n###|$)/i);
+    if (perfMatch) {
+      const metrics = perfMatch[1]
+        .split(/\n[-*]\s+/)
+        .map((m) => m.trim())
+        .filter((m) => m.length > 0);
+      criteria.performance = metrics;
+    }
+
+    return criteria;
+  }
+
+  private extractClarifications(content: string): string[] {
+    const clarifications: string[] = [];
+    const clarificationRegex = /\[NEEDS CLARIFICATION:\s*([^\]]+)\]/g;
+    let match;
+
+    while ((match = clarificationRegex.exec(content)) !== null) {
+      clarifications.push(match[1].trim());
+    }
+
+    return clarifications;
+  }
+}