@eddacraft/anvil-adapters 0.1.0

package/src/base/testing.ts

@@ -0,0 +1,334 @@
+/**
+ * Adapter Testing Utilities
+ *
+ * Helpers for testing format adapters with common patterns and assertions.
+ */
+
+import type {
+  FormatAdapter,
+  ParseResult,
+  SerializeResult,
+  DetectionResult,
+  ParseContext,
+  AdapterOptions,
+} from './types.js';
+import type { APSPlan } from '@eddacraft/anvil-core';
+
+/**
+ * Test fixture for adapter testing
+ */
+export interface AdapterTestFixture {
+  /** Name of the test case */
+  name: string;
+  /** Raw content in external format */
+  content: string;
+  /** Expected detection result (optional) */
+  expectedDetection?: Partial<DetectionResult>;
+  /** Expected parse success (optional) */
+  expectParseSuccess?: boolean;
+  /** Context for parsing */
+  parseContext?: ParseContext;
+  /** Options for operations */
+  options?: AdapterOptions;
+  /** Expected values in parsed plan (optional) */
+  expectedPlan?: Partial<APSPlan>;
+  /** Expected error codes (if parse should fail) */
+  expectedErrors?: string[];
+  /** Expected warning codes */
+  expectedWarnings?: string[];
+}
+
+/**
+ * Test helper for adapter detection
+ */
+export class AdapterTester {
+  constructor(private adapter: FormatAdapter) {}
+
+  /**
+   * Test detection with a fixture
+   */
+  testDetection(fixture: AdapterTestFixture): DetectionResult {
+    const result = this.adapter.detect(fixture.content);
+
+    if (fixture.expectedDetection) {
+      if (fixture.expectedDetection.detected !== undefined) {
+        if (result.detected !== fixture.expectedDetection.detected) {
+          throw new Error(
+            `Detection mismatch for "${fixture.name}": expected ${fixture.expectedDetection.detected}, got ${result.detected}`
+          );
+        }
+      }
+
+      if (fixture.expectedDetection.confidence !== undefined) {
+        if (result.confidence < fixture.expectedDetection.confidence) {
+          throw new Error(
+            `Confidence too low for "${fixture.name}": expected >=${fixture.expectedDetection.confidence}, got ${result.confidence}`
+          );
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Test parsing with a fixture
+   */
+  async testParse(fixture: AdapterTestFixture): Promise<ParseResult> {
+    const result = await this.adapter.parse(fixture.content, fixture.parseContext, fixture.options);
+
+    if (fixture.expectParseSuccess !== undefined) {
+      if (result.success !== fixture.expectParseSuccess) {
+        throw new Error(
+          `Parse success mismatch for "${fixture.name}": expected ${fixture.expectParseSuccess}, got ${result.success}`
+        );
+      }
+    }
+
+    if (fixture.expectedErrors && fixture.expectedErrors.length > 0) {
+      if (!result.errors || result.errors.length === 0) {
+        throw new Error(`Expected errors for "${fixture.name}" but got none`);
+      }
+
+      const errorCodes = result.errors.map((e) => e.code);
+      for (const expectedCode of fixture.expectedErrors) {
+        if (!errorCodes.includes(expectedCode)) {
+          throw new Error(
+            `Expected error code "${expectedCode}" for "${fixture.name}" but found: ${errorCodes.join(', ')}`
+          );
+        }
+      }
+    }
+
+    if (fixture.expectedWarnings && fixture.expectedWarnings.length > 0) {
+      if (!result.warnings || result.warnings.length === 0) {
+        throw new Error(`Expected warnings for "${fixture.name}" but got none`);
+      }
+
+      const warningCodes = result.warnings.map((w) => w.code);
+      for (const expectedCode of fixture.expectedWarnings) {
+        if (!warningCodes.includes(expectedCode)) {
+          throw new Error(
+            `Expected warning code "${expectedCode}" for "${fixture.name}" but found: ${warningCodes.join(', ')}`
+          );
+        }
+      }
+    }
+
+    if (fixture.expectedPlan && result.data) {
+      this.assertPlanMatches(result.data, fixture.expectedPlan, fixture.name);
+    }
+
+    return result;
+  }
+
+  /**
+   * Test serialization
+   */
+  async testSerialize(plan: APSPlan, options?: AdapterOptions): Promise<SerializeResult> {
+    return this.adapter.serialize(plan, options);
+  }
+
+  /**
+   * Test round-trip: parse then serialize then parse again
+   */
+  async testRoundTrip(fixture: AdapterTestFixture): Promise<{
+    firstParse: ParseResult;
+    serialized: SerializeResult;
+    secondParse: ParseResult;
+    planMatches: boolean;
+  }> {
+    // First parse
+    const firstParse = await this.adapter.parse(
+      fixture.content,
+      fixture.parseContext,
+      fixture.options
+    );
+
+    if (!firstParse.success || !firstParse.data) {
+      throw new Error(`First parse failed for "${fixture.name}"`);
+    }
+
+    // Serialize
+    const serialized = await this.adapter.serialize(firstParse.data, fixture.options);
+
+    if (!serialized.success || !serialized.content) {
+      throw new Error(`Serialization failed for "${fixture.name}"`);
+    }
+
+    // Second parse
+    const secondParse = await this.adapter.parse(
+      serialized.content,
+      fixture.parseContext,
+      fixture.options
+    );
+
+    if (!secondParse.success || !secondParse.data) {
+      throw new Error(`Second parse failed for "${fixture.name}"`);
+    }
+
+    // Compare plans
+    const planMatches = this.plansEqual(firstParse.data, secondParse.data);
+
+    return {
+      firstParse,
+      serialized,
+      secondParse,
+      planMatches,
+    };
+  }
+
+  /**
+   * Assert that parsed plan matches expected values
+   */
+  private assertPlanMatches(actual: APSPlan, expected: Partial<APSPlan>, testName: string): void {
+    if (expected.intent !== undefined && actual.intent !== expected.intent) {
+      throw new Error(
+        `Intent mismatch for "${testName}": expected "${expected.intent}", got "${actual.intent}"`
+      );
+    }
+
+    if (expected.id !== undefined && actual.id !== expected.id) {
+      throw new Error(
+        `ID mismatch for "${testName}": expected "${expected.id}", got "${actual.id}"`
+      );
+    }
+
+    if (
+      expected.proposed_changes !== undefined &&
+      actual.proposed_changes.length !== expected.proposed_changes.length
+    ) {
+      throw new Error(
+        `Changes count mismatch for "${testName}": expected ${expected.proposed_changes.length}, got ${actual.proposed_changes.length}`
+      );
+    }
+  }
+
+  /**
+   * Compare two plans for equality (ignoring hash and timestamps)
+   */
+  private plansEqual(plan1: APSPlan, plan2: APSPlan): boolean {
+    // Compare intents
+    if (plan1.intent !== plan2.intent) return false;
+
+    // Compare changes count
+    if (plan1.proposed_changes.length !== plan2.proposed_changes.length) return false;
+
+    // Compare each change
+    for (let i = 0; i < plan1.proposed_changes.length; i++) {
+      const change1 = plan1.proposed_changes[i];
+      const change2 = plan2.proposed_changes[i];
+
+      if (change1.type !== change2.type) return false;
+      if (change1.path !== change2.path) return false;
+      if (change1.description !== change2.description) return false;
+    }
+
+    return true;
+  }
+}
+
+/**
+ * Create a test adapter tester
+ */
+export function createTester(adapter: FormatAdapter): AdapterTester {
+  return new AdapterTester(adapter);
+}
+
+/**
+ * Create a basic parse context for testing
+ */
+export function createTestContext(overrides?: Partial<ParseContext>): ParseContext {
+  return {
+    author: 'test-user',
+    repositoryPath: '/test/repo',
+    branch: 'main',
+    commit: 'abc123',
+    timestamp: '2024-01-01T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+/**
+ * Create basic adapter options for testing
+ */
+export function createTestOptions(overrides?: Partial<AdapterOptions>): AdapterOptions {
+  return {
+    preserveComments: true,
+    preserveMetadata: true,
+    strict: false,
+    ...overrides,
+  };
+}
+
+/**
+ * Assert detection result
+ */
+export function assertDetection(
+  result: DetectionResult,
+  expected: { detected: boolean; minConfidence?: number }
+): void {
+  if (result.detected !== expected.detected) {
+    throw new Error(
+      `Detection mismatch: expected ${expected.detected}, got ${result.detected}. Reason: ${result.reason}`
+    );
+  }
+
+  if (expected.minConfidence !== undefined && result.confidence < expected.minConfidence) {
+    throw new Error(
+      `Confidence too low: expected >=${expected.minConfidence}, got ${result.confidence}`
+    );
+  }
+}
+
+/**
+ * Assert parse success
+ */
+export function assertParseSuccess(
+  result: ParseResult
+): asserts result is ParseResult & { data: APSPlan } {
+  if (!result.success) {
+    const errorMsg =
+      result.errors?.map((e) => `${e.code}: ${e.message}`).join(', ') || 'Unknown error';
+    throw new Error(`Parse failed: ${errorMsg}`);
+  }
+
+  if (!result.data) {
+    throw new Error('Parse succeeded but no data returned');
+  }
+}
+
+/**
+ * Assert parse failure
+ */
+export function assertParseFailure(result: ParseResult, expectedErrorCode?: string): void {
+  if (result.success) {
+    throw new Error('Expected parse to fail but it succeeded');
+  }
+
+  if (expectedErrorCode && result.errors) {
+    const errorCodes = result.errors.map((e) => e.code);
+    if (!errorCodes.includes(expectedErrorCode)) {
+      throw new Error(
+        `Expected error code "${expectedErrorCode}" but found: ${errorCodes.join(', ')}`
+      );
+    }
+  }
+}
+
+/**
+ * Assert serialize success
+ */
+export function assertSerializeSuccess(
+  result: SerializeResult
+): asserts result is SerializeResult & { content: string } {
+  if (!result.success) {
+    const errorMsg =
+      result.errors?.map((e) => `${e.code}: ${e.message}`).join(', ') || 'Unknown error';
+    throw new Error(`Serialize failed: ${errorMsg}`);
+  }
+
+  if (!result.content) {
+    throw new Error('Serialize succeeded but no content returned');
+  }
+}

package/src/base/types.ts

@@ -0,0 +1,342 @@
+/**
+ * Base Adapter Framework Types
+ *
+ * Defines the core interfaces for format adapters that convert between
+ * external planning formats (SpecKit, BMAD, etc.) and APS.
+ */
+
+import type { APSPlan, ValidationResult } from '@eddacraft/anvil-core';
+
+/**
+ * Result of format detection
+ */
+export interface DetectionResult {
+  /** Whether this adapter can handle the content */
+  detected: boolean;
+  /** Confidence score (0-100) */
+  confidence: number;
+  /** Reason for detection result */
+  reason?: string;
+}
+
+/**
+ * Result of parsing external format to APS
+ */
+export interface ParseResult {
+  /** Whether parsing succeeded */
+  success: boolean;
+  /** Parsed APS plan (if successful) */
+  data?: APSPlan;
+  /** Errors encountered during parsing */
+  errors?: AdapterError[];
+  /** Non-fatal warnings */
+  warnings?: AdapterWarning[];
+}
+
+/**
+ * Result of serializing APS to external format
+ */
+export interface SerializeResult {
+  /** Whether serialization succeeded */
+  success: boolean;
+  /** Serialized content (if successful) */
+  content?: string;
+  /** Errors encountered during serialization */
+  errors?: AdapterError[];
+  /** Non-fatal warnings */
+  warnings?: AdapterWarning[];
+  /** Additional metadata about serialization */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Error encountered during adapter operation
+ */
+export interface AdapterError {
+  /** Error code for programmatic handling */
+  code: string;
+  /** Human-readable error message */
+  message: string;
+  /** Path to the problematic element (e.g., "changes[0].path") */
+  path?: string;
+  /** Line number in source content (if applicable) */
+  line?: number;
+  /** Column number in source content (if applicable) */
+  column?: number;
+  /** Additional error details */
+  details?: unknown;
+}
+
+/**
+ * Warning encountered during adapter operation
+ */
+export interface AdapterWarning {
+  /** Warning code for programmatic handling */
+  code: string;
+  /** Human-readable warning message */
+  message: string;
+  /** Path to the element (e.g., "changes[0].description") */
+  path?: string;
+  /** Line number in source content (if applicable) */
+  line?: number;
+  /** Column number in source content (if applicable) */
+  column?: number;
+  /** Additional warning details */
+  details?: unknown;
+}
+
+/**
+ * Context provided when parsing external formats
+ */
+export interface ParseContext {
+  /** Repository path or URL */
+  repositoryPath?: string;
+  /** Git branch */
+  branch?: string;
+  /** Git commit hash */
+  commit?: string;
+  /** Author information */
+  author?: string;
+  /** Timestamp for provenance */
+  timestamp?: string;
+  /** Additional context metadata */
+  metadata?: Record<string, unknown>;
+  /** Pre-generated plan ID (for deterministic parsing) */
+  planId?: string;
+}
+
+/**
+ * Hint for path-based format detection
+ *
+ * Provides file path and sibling file information to improve
+ * detection accuracy for formats that use folder conventions.
+ */
+export interface PathDetectionHint {
+  /** File path being analyzed */
+  filePath: string;
+  /** Sibling file names in the same directory */
+  siblingFiles?: string[];
+  /** Parent directory names (innermost first) */
+  parentDirs?: string[];
+}
+
+/**
+ * Options for adapter operations
+ */
+export interface AdapterOptions {
+  /** Preserve comments from source */
+  preserveComments?: boolean;
+  /** Preserve metadata from source */
+  preserveMetadata?: boolean;
+  /** Strict validation mode */
+  strict?: boolean;
+  /** Format-specific options */
+  formatOptions?: Record<string, unknown>;
+}
+
+/**
+ * Metadata about an adapter
+ */
+export interface AdapterMetadata {
+  /** Adapter name (e.g., "speckit", "bmad") */
+  name: string;
+  /** Adapter version */
+  version: string;
+  /** Human-readable display name */
+  displayName: string;
+  /** Short description of what this adapter handles */
+  description: string;
+  /** File extensions supported (e.g., [".md", ".spec.md"]) */
+  extensions: readonly string[];
+  /** Format identifiers (e.g., ["speckit", "spec"]) */
+  formats: readonly string[];
+}
+
+/**
+ * Core interface for format adapters
+ *
+ * Adapters convert between external planning formats and APS.
+ * Each adapter should handle one external format (e.g., SpecKit, BMAD).
+ */
+export interface FormatAdapter {
+  /** Adapter metadata */
+  readonly metadata: AdapterMetadata;
+
+  /**
+   * Detect if this adapter can handle the given content
+   *
+   * @param content - Raw content to analyze
+   * @returns Detection result with confidence score
+   */
+  detect(content: string): DetectionResult;
+
+  /**
+   * Parse external format content into APS
+   *
+   * @param content - Raw content in external format
+   * @param context - Context for provenance tracking
+   * @param options - Parsing options
+   * @returns Parse result with APS plan or errors
+   */
+  parse(content: string, context?: ParseContext, options?: AdapterOptions): Promise<ParseResult>;
+
+  /**
+   * Serialize APS plan to external format
+   *
+   * @param plan - APS plan to serialize
+   * @param options - Serialization options
+   * @returns Serialize result with content or errors
+   */
+  serialize(plan: APSPlan, options?: AdapterOptions): Promise<SerializeResult>;
+
+  /**
+   * Validate external format content
+   *
+   * Validates the content without full conversion to APS.
+   * Useful for fast validation feedback.
+   *
+   * @param content - Raw content to validate
+   * @param options - Validation options
+   * @returns Validation result
+   */
+  validate(content: string, options?: AdapterOptions): Promise<ValidationResult>;
+
+  /**
+   * Detect if this adapter can handle content using file path hints
+   *
+   * Optional method that uses folder structure and sibling files
+   * to improve detection accuracy. Falls back to content-only
+   * detection if not implemented.
+   *
+   * @param content - Raw content to analyze
+   * @param hint - Path and directory information
+   * @returns Detection result with confidence score
+   */
+  detectWithPath?(content: string, hint: PathDetectionHint): DetectionResult;
+
+  /**
+   * Check if this adapter can import from a given format
+   *
+   * @param format - Format identifier or file extension
+   * @returns True if adapter supports importing from this format
+   */
+  canImport(format: string): boolean;
+
+  /**
+   * Check if this adapter can export to a given format
+   *
+   * @param format - Format identifier or file extension
+   * @returns True if adapter supports exporting to this format
+   */
+  canExport(format: string): boolean;
+}
+
+/**
+ * Abstract base class for format adapters
+ *
+ * Provides common functionality and structure for concrete adapters.
+ */
+export abstract class BaseFormatAdapter implements FormatAdapter {
+  abstract readonly metadata: AdapterMetadata;
+
+  constructor(protected options: AdapterOptions = {}) {}
+
+  abstract detect(content: string): DetectionResult;
+  abstract parse(
+    content: string,
+    context?: ParseContext,
+    options?: AdapterOptions
+  ): Promise<ParseResult>;
+  abstract serialize(plan: APSPlan, options?: AdapterOptions): Promise<SerializeResult>;
+  abstract validate(content: string, options?: AdapterOptions): Promise<ValidationResult>;
+
+  canImport(format: string): boolean {
+    const normalized = format.toLowerCase().replace(/^\./, '');
+    return (
+      this.metadata.formats.includes(normalized) ||
+      this.metadata.extensions.some((ext) => ext.replace(/^\./, '') === normalized)
+    );
+  }
+
+  canExport(format: string): boolean {
+    return this.canImport(format);
+  }
+
+  /**
+   * Helper to create a successful parse result
+   */
+  protected createParseSuccess(data: APSPlan, warnings?: AdapterWarning[]): ParseResult {
+    return {
+      success: true,
+      data,
+      warnings: warnings && warnings.length > 0 ? warnings : undefined,
+    };
+  }
+
+  /**
+   * Helper to create a failed parse result
+   */
+  protected createParseError(errors: AdapterError[], warnings?: AdapterWarning[]): ParseResult {
+    return {
+      success: false,
+      errors,
+      warnings: warnings && warnings.length > 0 ? warnings : undefined,
+    };
+  }
+
+  /**
+   * Helper to create a successful serialize result
+   */
+  protected createSerializeSuccess(
+    content: string,
+    warnings?: AdapterWarning[],
+    metadata?: Record<string, unknown>
+  ): SerializeResult {
+    return {
+      success: true,
+      content,
+      warnings: warnings && warnings.length > 0 ? warnings : undefined,
+      metadata,
+    };
+  }
+
+  /**
+   * Helper to create a failed serialize result
+   */
+  protected createSerializeError(
+    errors: AdapterError[],
+    warnings?: AdapterWarning[]
+  ): SerializeResult {
+    return {
+      success: false,
+      errors,
+      warnings: warnings && warnings.length > 0 ? warnings : undefined,
+    };
+  }
+
+  /**
+   * Helper to add an error
+   */
+  protected addError(
+    errors: AdapterError[],
+    code: string,
+    message: string,
+    path?: string,
+    details?: unknown
+  ): void {
+    errors.push({ code, message, path, details });
+  }
+
+  /**
+   * Helper to add a warning
+   */
+  protected addWarning(
+    warnings: AdapterWarning[],
+    code: string,
+    message: string,
+    path?: string,
+    details?: unknown
+  ): void {
+    warnings.push({ code, message, path, details });
+  }
+}