@eddacraft/anvil-adapters 0.1.0

package/src/base/utils.ts

@@ -0,0 +1,306 @@
+import { createHash } from 'node:crypto';
+
+import type {
+  AdapterError,
+  AdapterWarning,
+  ParseResult,
+  SerializeResult,
+  DetectionResult,
+} from './types.js';
+
+export function generateDeterministicPlanId(content: string): string {
+  const hash = createHash('sha256').update(content, 'utf8').digest('hex');
+  return `aps-${hash.substring(0, 8)}`;
+}
+
+/**
+ * Create a detection result
+ *
+ * @param detected - Whether format was detected
+ * @param confidence - Confidence score (0-100)
+ * @param reason - Optional reason
+ * @returns Detection result
+ */
+export function createDetection(
+  detected: boolean,
+  confidence: number,
+  reason?: string
+): DetectionResult {
+  return {
+    detected,
+    confidence: Math.max(0, Math.min(100, confidence)),
+    reason,
+  };
+}
+
+/**
+ * Create an adapter error
+ *
+ * @param code - Error code
+ * @param message - Error message
+ * @param options - Additional options
+ * @returns Adapter error
+ */
+export function createError(
+  code: string,
+  message: string,
+  options?: {
+    path?: string;
+    line?: number;
+    column?: number;
+    details?: unknown;
+  }
+): AdapterError {
+  return {
+    code,
+    message,
+    ...options,
+  };
+}
+
+/**
+ * Create an adapter warning
+ *
+ * @param code - Warning code
+ * @param message - Warning message
+ * @param options - Additional options
+ * @returns Adapter warning
+ */
+export function createWarning(
+  code: string,
+  message: string,
+  options?: {
+    path?: string;
+    line?: number;
+    column?: number;
+    details?: unknown;
+  }
+): AdapterWarning {
+  return {
+    code,
+    message,
+    ...options,
+  };
+}
+
+/**
+ * Check if content matches a pattern
+ *
+ * Useful for format detection.
+ *
+ * @param content - Content to check
+ * @param patterns - Array of regex patterns or strings
+ * @returns Number of patterns matched (0 to patterns.length)
+ */
+export function matchesPatterns(content: string, patterns: Array<string | RegExp>): number {
+  let matches = 0;
+  for (const pattern of patterns) {
+    if (typeof pattern === 'string') {
+      if (content.includes(pattern)) {
+        matches++;
+      }
+    } else {
+      if (pattern.test(content)) {
+        matches++;
+      }
+    }
+  }
+  return matches;
+}
+
+/**
+ * Calculate confidence score based on pattern matches
+ *
+ * @param matchCount - Number of patterns matched
+ * @param totalPatterns - Total number of patterns checked
+ * @param requiredMatches - Minimum matches for 100% confidence
+ * @returns Confidence score (0-100)
+ */
+export function calculateConfidence(
+  matchCount: number,
+  totalPatterns: number,
+  requiredMatches: number = totalPatterns
+): number {
+  if (matchCount === 0) return 0;
+  if (matchCount >= requiredMatches) return 100;
+
+  // Linear interpolation
+  return Math.round((matchCount / requiredMatches) * 100);
+}
+
+/**
+ * Extract file extension from filename or path
+ *
+ * @param filename - Filename or path
+ * @returns Extension (including dot) or empty string
+ */
+export function getExtension(filename: string): string {
+  const match = filename.match(/\.[^.]+$/);
+  return match ? match[0] : '';
+}
+
+/**
+ * Normalize format identifier
+ *
+ * Removes leading dot and converts to lowercase.
+ *
+ * @param format - Format identifier or extension
+ * @returns Normalized format
+ */
+export function normalizeFormat(format: string): string {
+  return format.toLowerCase().replace(/^\./, '');
+}
+
+/**
+ * Format errors for display
+ *
+ * @param errors - Array of errors
+ * @returns Formatted error string
+ */
+export function formatErrors(errors: AdapterError[]): string {
+  return errors
+    .map((error) => {
+      let msg = `[${error.code}] ${error.message}`;
+      if (error.path) {
+        msg += ` (at ${error.path}`;
+        if (error.line !== undefined) {
+          msg += `:${error.line}`;
+          if (error.column !== undefined) {
+            msg += `:${error.column}`;
+          }
+        }
+        msg += ')';
+      }
+      return msg;
+    })
+    .join('\n');
+}
+
+/**
+ * Format warnings for display
+ *
+ * @param warnings - Array of warnings
+ * @returns Formatted warning string
+ */
+export function formatWarnings(warnings: AdapterWarning[]): string {
+  return warnings
+    .map((warning) => {
+      let msg = `[${warning.code}] ${warning.message}`;
+      if (warning.path) {
+        msg += ` (at ${warning.path}`;
+        if (warning.line !== undefined) {
+          msg += `:${warning.line}`;
+          if (warning.column !== undefined) {
+            msg += `:${warning.column}`;
+          }
+        }
+        msg += ')';
+      }
+      return msg;
+    })
+    .join('\n');
+}
+
+/**
+ * Merge parse results
+ *
+ * Useful when parsing composite formats.
+ *
+ * @param results - Array of parse results
+ * @returns Merged result
+ */
+export function mergeParseResults(results: ParseResult[]): ParseResult {
+  if (results.length === 0) {
+    return {
+      success: false,
+      errors: [createError('NO_RESULTS', 'No parse results to merge')],
+    };
+  }
+
+  if (results.length === 1) {
+    return results[0];
+  }
+
+  const allErrors: AdapterError[] = [];
+  const allWarnings: AdapterWarning[] = [];
+  let finalData = results[0].data;
+
+  for (const result of results) {
+    if (!result.success) {
+      if (result.errors) {
+        allErrors.push(...result.errors);
+      }
+    }
+    if (result.warnings) {
+      allWarnings.push(...result.warnings);
+    }
+    if (result.data) {
+      finalData = result.data;
+    }
+  }
+
+  if (allErrors.length > 0) {
+    return {
+      success: false,
+      errors: allErrors,
+      warnings: allWarnings.length > 0 ? allWarnings : undefined,
+    };
+  }
+
+  return {
+    success: true,
+    data: finalData,
+    warnings: allWarnings.length > 0 ? allWarnings : undefined,
+  };
+}
+
+/**
+ * Check if result has errors
+ *
+ * @param result - Parse or serialize result
+ * @returns True if result has errors
+ */
+export function hasErrors(result: ParseResult | SerializeResult): boolean {
+  return !result.success || (result.errors !== undefined && result.errors.length > 0);
+}
+
+/**
+ * Check if result has warnings
+ *
+ * @param result - Parse or serialize result
+ * @returns True if result has warnings
+ */
+export function hasWarnings(result: ParseResult | SerializeResult): boolean {
+  return result.warnings !== undefined && result.warnings.length > 0;
+}
+
+/**
+ * Extract first line from content (useful for format detection)
+ *
+ * @param content - Content string
+ * @returns First non-empty line or empty string
+ */
+export function getFirstLine(content: string): string {
+  const lines = content.split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed) {
+      return trimmed;
+    }
+  }
+  return '';
+}
+
+/**
+ * Count occurrences of pattern in content
+ *
+ * @param content - Content to search
+ * @param pattern - Pattern to count
+ * @returns Number of occurrences
+ */
+export function countOccurrences(content: string, pattern: string | RegExp): number {
+  if (typeof pattern === 'string') {
+    return (content.match(new RegExp(pattern, 'g')) || []).length;
+  }
+  return (content.match(new RegExp(pattern.source, 'g')) || []).length;
+}

package/src/bmad/format-adapter.ts

@@ -0,0 +1,227 @@
+/**
+ * BMAD Format Adapter
+ *
+ * FormatAdapter implementation for BMAD (Breakthrough Method for Agile AI-Driven Development) format.
+ * Handles PRD, Architecture, Epic, Story, and Agent documents.
+ */
+
+import { generateHash, type APSPlan, type ValidationResult } from '@eddacraft/anvil-core';
+import {
+  BaseFormatAdapter,
+  type AdapterMetadata,
+  type DetectionResult,
+  type ParseResult,
+  type SerializeResult,
+  type ParseContext,
+  type AdapterOptions,
+  type PathDetectionHint,
+} from '../base/types.js';
+import { createDetection } from '../base/utils.js';
+import {
+  analyzeContent,
+  calculateConfidenceScore,
+  buildDetectionReason,
+  extractFrontMatter,
+  identifyDocumentType,
+} from './utils.js';
+import { BMADDocumentType } from './types.js';
+import { parseBMAD } from './parser.js';
+import { serializeToBMAD } from './serializer.js';
+
+/**
+ * BMAD FormatAdapter implementation
+ *
+ * Converts between BMAD format documents and APS plans.
+ */
+export class BMADFormatAdapter extends BaseFormatAdapter {
+  readonly metadata: AdapterMetadata = {
+    name: 'bmad',
+    version: '1.0.0',
+    displayName: 'BMAD (Breakthrough Method for Agile AI-Driven Development)',
+    description: 'BMAD PRD and architecture document adapter',
+    formats: ['bmad', 'prd', 'architecture'],
+    extensions: ['.md'],
+  };
+
+  /**
+   * Detect if content is BMAD format
+   *
+   * Uses confidence scoring based on multiple indicators:
+   * - YAML front-matter (30 points)
+   * - Requirement identifiers FR/NFR/US (25 points)
+   * - User story format (20 points)
+   * - Change log table (15 points)
+   * - Document title (10 points)
+   *
+   * @param content - Document content to analyze
+   * @returns Detection result with confidence score
+   */
+  detect(content: string): DetectionResult {
+    const indicators = analyzeContent(content);
+    const confidence = calculateConfidenceScore(indicators);
+    const reason = buildDetectionReason(indicators);
+
+    // Detection threshold: 50% confidence
+    return createDetection(confidence >= 50, confidence, reason);
+  }
+
+  /**
+   * Detect with file path hints for improved accuracy
+   *
+   * Uses folder structure (e.g., `_bmad/`, `.bmad/`, `_config/`)
+   * to boost detection confidence.
+   *
+   * @param content - Document content to analyze
+   * @param hint - Path and directory information
+   * @returns Detection result with confidence score
+   */
+  detectWithPath(content: string, hint: PathDetectionHint): DetectionResult {
+    const indicators = analyzeContent(content, hint);
+    const confidence = calculateConfidenceScore(indicators);
+    const reason = buildDetectionReason(indicators);
+
+    return createDetection(confidence >= 50, confidence, reason);
+  }
+
+  /**
+   * Parse BMAD content to APS plan
+   *
+   * @param content - BMAD markdown content
+   * @param context - Parse context for provenance
+   * @param options - Adapter options
+   * @returns Parse result with APS plan
+   */
+  async parse(
+    content: string,
+    context?: ParseContext,
+    _options?: AdapterOptions
+  ): Promise<ParseResult> {
+    try {
+      // Parse content to APS plan
+      const plan = parseBMAD(content, context);
+
+      // Generate hash for the plan
+      const planWithHash = {
+        ...plan,
+        hash: generateHash(plan),
+      };
+
+      return this.createParseSuccess(planWithHash);
+    } catch (error) {
+      return this.createParseError([
+        {
+          code: 'PARSE_ERROR',
+          message: error instanceof Error ? error.message : 'Failed to parse BMAD content',
+          details: error,
+        },
+      ]);
+    }
+  }
+
+  /**
+   * Serialize APS plan to BMAD format
+   *
+   * @param plan - APS plan to serialize
+   * @param options - Adapter options
+   * @returns Serialize result with BMAD markdown
+   */
+  async serialize(plan: APSPlan, _options?: AdapterOptions): Promise<SerializeResult> {
+    try {
+      const content = serializeToBMAD(plan);
+      return this.createSerializeSuccess(content);
+    } catch (error) {
+      return this.createSerializeError([
+        {
+          code: 'SERIALIZE_ERROR',
+          message: error instanceof Error ? error.message : 'Failed to serialize to BMAD format',
+          details: error,
+        },
+      ]);
+    }
+  }
+
+  /**
+   * Validate BMAD content
+   *
+   * Checks for required BMAD elements without full conversion.
+   *
+   * @param content - BMAD content to validate
+   * @param options - Validation options
+   * @returns Validation result
+   */
+  async validate(content: string, _options?: AdapterOptions): Promise<ValidationResult> {
+    const issues: Array<{
+      path: string;
+      message: string;
+      code: string;
+      severity: 'error' | 'warning';
+    }> = [];
+
+    // Check for minimum content length
+    if (content.trim().length < 100) {
+      issues.push({
+        code: 'CONTENT_TOO_SHORT',
+        path: 'content',
+        message: 'Content is too short to be a valid BMAD document',
+        severity: 'error',
+      });
+    }
+
+    // Analyze content for BMAD indicators
+    const indicators = analyzeContent(content);
+    const confidence = calculateConfidenceScore(indicators);
+
+    // Low confidence suggests invalid BMAD format
+    if (confidence < 50) {
+      issues.push({
+        code: 'LOW_CONFIDENCE',
+        path: 'content',
+        message: `Content does not appear to be a valid BMAD document (confidence: ${confidence}%)`,
+        severity: 'error',
+      });
+    }
+
+    // Check for at least some requirements or stories
+    if (indicators.requirementCount === 0) {
+      issues.push({
+        code: 'NO_REQUIREMENTS',
+        path: 'content',
+        message: 'No requirements (FR/NFR/US) found in document',
+        severity: 'warning',
+      });
+    }
+
+    // v6: Warn on agent docs missing hasSidecar
+    const frontMatter = extractFrontMatter(content);
+    const docType = identifyDocumentType(content, frontMatter);
+    if (docType === BMADDocumentType.AGENT && frontMatter?.hasSidecar === undefined) {
+      issues.push({
+        code: 'MISSING_HAS_SIDECAR',
+        path: 'frontMatter.hasSidecar',
+        message: 'Agent document is missing the hasSidecar field (expected for BMAD v6)',
+        severity: 'warning',
+      });
+    }
+
+    return {
+      valid: issues.filter((i) => i.severity === 'error').length === 0,
+      issues: issues.length > 0 ? issues : undefined,
+      summary:
+        issues.filter((i) => i.severity === 'error').length === 0 && issues.length === 0
+          ? 'BMAD document is valid'
+          : issues.filter((i) => i.severity === 'error').length === 0
+            ? `Valid with ${issues.length} warning${issues.length > 1 ? 's' : ''}`
+            : `Found ${issues.filter((i) => i.severity === 'error').length} error${issues.filter((i) => i.severity === 'error').length > 1 ? 's' : ''}`,
+    };
+  }
+}
+
+/**
+ * Create a new BMAD format adapter instance
+ *
+ * @param options - Adapter options
+ * @returns BMAD adapter instance
+ */
+export function createBMADAdapter(options?: AdapterOptions): BMADFormatAdapter {
+  return new BMADFormatAdapter(options);
+}

package/src/bmad/index.ts

@@ -0,0 +1,21 @@
+/**
+ * BMAD Adapter Module
+ *
+ * Export all BMAD adapter functionality.
+ */
+
+export { BMADFormatAdapter, createBMADAdapter } from './format-adapter.js';
+export { BMAD_FOLDERS } from './types.js';
+export type {
+  BMADDocument,
+  BMADDocumentType,
+  BMADRequirement,
+  BMADUserStory,
+  BMADFrontMatter,
+  BMADChangeLogEntry,
+  RequirementType,
+  DetectionIndicators,
+} from './types.js';
+export { parseBMAD, parseBMADDocument, bmadToAPS } from './parser.js';
+export { serializeToBMAD } from './serializer.js';
+export * from './utils.js';