@eddacraft/anvil-adapters 0.1.0

package/src/common/types.ts

@@ -0,0 +1,84 @@
+import type { APSPlan, ValidationResult } from '@eddacraft/anvil-core';
+
+export interface SpecContext {
+  repositoryPath?: string;
+  branch?: string;
+  commit?: string;
+  author?: string;
+  timestamp?: string;
+  additionalContext?: Record<string, unknown>;
+}
+
+export interface ExternalSpec {
+  format: string;
+  version: string;
+  content: unknown;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ConversionResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  errors?: ConversionError[];
+  warnings?: ConversionWarning[];
+}
+
+export interface ConversionError {
+  code: string;
+  message: string;
+  path?: string;
+  line?: number;
+  column?: number;
+  details?: unknown;
+}
+
+export interface ConversionWarning {
+  code: string;
+  message: string;
+  path?: string;
+  line?: number;
+  column?: number;
+  details?: unknown;
+}
+
+export interface SpecToolAdapter {
+  readonly name: string;
+  readonly version: string;
+  readonly supportedFormats: readonly string[];
+
+  generateSpec(intent: string, context: SpecContext): Promise<APSPlan>;
+  validateSpec(spec: APSPlan): Promise<ValidationResult>;
+  convertToAPS(spec: ExternalSpec): Promise<ConversionResult<APSPlan>>;
+  convertFromAPS(spec: APSPlan): Promise<ConversionResult<ExternalSpec>>;
+
+  canImport(format: string): boolean;
+  canExport(format: string): boolean;
+}
+
+export interface AdapterConfig {
+  preserveComments?: boolean;
+  preserveMetadata?: boolean;
+  strictMode?: boolean;
+  formatOptions?: Record<string, unknown>;
+}
+
+export abstract class BaseAdapter implements SpecToolAdapter {
+  abstract readonly name: string;
+  abstract readonly version: string;
+  abstract readonly supportedFormats: readonly string[];
+
+  constructor(protected config: AdapterConfig = {}) {}
+
+  abstract generateSpec(intent: string, context: SpecContext): Promise<APSPlan>;
+  abstract validateSpec(spec: APSPlan): Promise<ValidationResult>;
+  abstract convertToAPS(spec: ExternalSpec): Promise<ConversionResult<APSPlan>>;
+  abstract convertFromAPS(spec: APSPlan): Promise<ConversionResult<ExternalSpec>>;
+
+  canImport(format: string): boolean {
+    return this.supportedFormats.includes(format);
+  }
+
+  canExport(format: string): boolean {
+    return this.supportedFormats.includes(format);
+  }
+}

package/src/generic/__tests__/serializer.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Generic Serializer Tests
+ * Tests for type-safe serialization of APS plans
+ */
+
+import { describe, it, expect } from 'vitest';
+import { serializeToGeneric } from '../serializer.js';
+import type { APSPlan } from '@eddacraft/anvil-core';
+
+describe('serializeToGeneric', () => {
+  const basePlan: APSPlan = {
+    id: 'aps-test123',
+    schema_version: '0.1.0',
+    hash: 'test-hash',
+    intent: 'Test plan',
+    proposed_changes: [],
+    provenance: {
+      timestamp: '2024-01-01T00:00:00Z',
+      author: 'test@example.com',
+      source: 'cli',
+      version: '1.0.0',
+    },
+    validations: {
+      required_checks: [],
+      skip_checks: [],
+    },
+    evidence: [],
+    executions: [],
+  };
+
+  it('should handle plan with no metadata', () => {
+    const result = serializeToGeneric(basePlan);
+
+    expect(result).toContain('# Test plan');
+    expect(result).toContain('## Purpose');
+  });
+
+  it('should handle plan with string title metadata', () => {
+    const plan = {
+      ...basePlan,
+      metadata: {
+        title: 'Custom Title',
+      },
+    };
+
+    const result = serializeToGeneric(plan);
+
+    expect(result).toContain('# Custom Title');
+  });
+
+  it('should handle plan with non-string title metadata gracefully', () => {
+    const plan = {
+      ...basePlan,
+      metadata: {
+        title: 123 as unknown as string, // Invalid type
+      },
+    };
+
+    const result = serializeToGeneric(plan);
+
+    // Should fall back to intent
+    expect(result).toContain('# Test plan');
+  });
+
+  it('should handle plan with string overview metadata', () => {
+    const plan = {
+      ...basePlan,
+      metadata: {
+        overview: 'This is an overview',
+      },
+    };
+
+    const result = serializeToGeneric(plan);
+
+    expect(result).toContain('## Overview');
+    expect(result).toContain('This is an overview');
+  });
+
+  it('should handle plan with non-string overview metadata gracefully', () => {
+    const plan = {
+      ...basePlan,
+      metadata: {
+        overview: { text: 'overview' } as unknown as string, // Invalid type
+      },
+    };
+
+    const result = serializeToGeneric(plan);
+
+    // Should fall back to purpose section
+    expect(result).toContain('## Purpose');
+    expect(result).not.toContain('## Overview');
+  });
+
+  it('should handle plan with string array goals', () => {
+    const plan = {
+      ...basePlan,
+      metadata: {
+        goals: ['Goal 1', 'Goal 2', 'Goal 3'],
+      },
+    };
+
+    const result = serializeToGeneric(plan);
+
+    expect(result).toContain('## Goals');
+    expect(result).toContain('- Goal 1');
+    expect(result).toContain('- Goal 2');
+    expect(result).toContain('- Goal 3');
+  });
+
+  it('should handle plan with non-string array goals gracefully', () => {
+    const plan = {
+      ...basePlan,
+      metadata: {
+        goals: [1, 2, 3] as unknown as string[], // Invalid type
+      },
+    };
+
+    const result = serializeToGeneric(plan);
+
+    // Should not include goals section
+    expect(result).not.toContain('## Goals');
+  });
+
+  it('should handle plan with mixed-type goals array gracefully', () => {
+    const plan = {
+      ...basePlan,
+      metadata: {
+        goals: ['Goal 1', 123, 'Goal 2'] as unknown as string[], // Mixed types
+      },
+    };
+
+    const result = serializeToGeneric(plan);
+
+    // Should not include goals section since not all elements are strings
+    expect(result).not.toContain('## Goals');
+  });
+
+  it('should handle plan with all metadata types', () => {
+    const plan = {
+      ...basePlan,
+      metadata: {
+        title: 'Full Plan',
+        overview: 'Complete overview',
+        goals: ['Goal A', 'Goal B'],
+      },
+      proposed_changes: [
+        {
+          type: 'file_create' as const,
+          path: 'test.ts',
+          description: 'Create test file',
+        },
+      ],
+    };
+
+    const result = serializeToGeneric(plan);
+
+    expect(result).toContain('# Full Plan');
+    expect(result).toContain('## Overview');
+    expect(result).toContain('Complete overview');
+    expect(result).toContain('## Goals');
+    expect(result).toContain('- Goal A');
+    expect(result).toContain('- Goal B');
+    expect(result).toContain('## Changes');
+    expect(result).toContain('### Files to Create');
+    expect(result).toContain('test.ts');
+  });
+});

package/src/generic/format-adapter.ts

@@ -0,0 +1,200 @@
+/**
+ * Generic Markdown Format Adapter
+ *
+ * FormatAdapter implementation for generic markdown planning documents.
+ * Serves as a fallback adapter for documents that don't match specific formats.
+ */
+
+import { generateHash, type APSPlan, type ValidationResult } from '@eddacraft/anvil-core';
+import {
+  BaseFormatAdapter,
+  type AdapterMetadata,
+  type DetectionResult,
+  type ParseResult,
+  type SerializeResult,
+  type ParseContext,
+  type AdapterOptions,
+} from '../base/types.js';
+import { createDetection } from '../base/utils.js';
+import { analyzeContent, calculateConfidenceScore, buildDetectionReason } from './utils.js';
+import { parseGeneric } from './parser.js';
+import { serializeToGeneric } from './serializer.js';
+
+const MIN_CONTENT_LENGTH = 50;
+const FALLBACK_DETECTION_THRESHOLD = 30;
+const MAX_FALLBACK_CONFIDENCE = 45;
+
+/**
+ * Generic Markdown FormatAdapter implementation
+ *
+ * Converts between generic markdown documents and APS plans.
+ * Designed to work as a fallback for documents that don't match
+ * specific formats like BMAD or SpecKit.
+ */
+export class GenericMarkdownAdapter extends BaseFormatAdapter {
+  readonly metadata: AdapterMetadata = {
+    name: 'generic-markdown',
+    version: '1.0.0',
+    displayName: 'Generic Markdown',
+    description: 'Generic markdown adapter for PRDs, plans, todos, and other planning documents',
+    formats: ['generic', 'markdown', 'prd', 'plan', 'todo', 'rfc', 'adr'],
+    extensions: ['.md', '.markdown'],
+  };
+
+  /**
+   * Detect if content is generic markdown planning document
+   *
+   * Uses lower confidence threshold (30-40%) to serve as fallback.
+   * This adapter should be registered last so specific adapters
+   * (BMAD, SpecKit) take precedence.
+   *
+   * @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);
+
+    const cappedConfidence = Math.min(MAX_FALLBACK_CONFIDENCE, confidence);
+
+    return createDetection(
+      cappedConfidence >= FALLBACK_DETECTION_THRESHOLD,
+      cappedConfidence,
+      reason
+    );
+  }
+
+  /**
+   * Parse generic markdown content to APS plan
+   *
+   * @param content - 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 = parseGeneric(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 generic markdown content',
+          details: error,
+        },
+      ]);
+    }
+  }
+
+  /**
+   * Serialize APS plan to generic markdown format
+   *
+   * @param plan - APS plan to serialize
+   * @param options - Adapter options
+   * @returns Serialize result with markdown content
+   */
+  async serialize(plan: APSPlan, _options?: AdapterOptions): Promise<SerializeResult> {
+    try {
+      const content = serializeToGeneric(plan);
+      return this.createSerializeSuccess(content);
+    } catch (error) {
+      return this.createSerializeError([
+        {
+          code: 'SERIALIZE_ERROR',
+          message:
+            error instanceof Error
+              ? error.message
+              : 'Failed to serialize to generic markdown format',
+          details: error,
+        },
+      ]);
+    }
+  }
+
+  /**
+   * Validate generic markdown content
+   *
+   * Checks for basic markdown structure without strict requirements.
+   *
+   * @param content - 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';
+    }> = [];
+
+    if (content.trim().length < MIN_CONTENT_LENGTH) {
+      issues.push({
+        code: 'CONTENT_TOO_SHORT',
+        path: 'content',
+        message: 'Content is too short to be a valid planning document',
+        severity: 'error',
+      });
+    }
+
+    const indicators = analyzeContent(content);
+    const confidence = calculateConfidenceScore(indicators);
+
+    if (confidence < FALLBACK_DETECTION_THRESHOLD) {
+      issues.push({
+        code: 'LOW_CONFIDENCE',
+        path: 'content',
+        message: `Content does not appear to be a planning document (confidence: ${confidence}%)`,
+        severity: 'error',
+      });
+    }
+
+    // Warn if missing common planning sections
+    if (
+      !indicators.hasRequirementsSection &&
+      !indicators.hasTasksSection &&
+      !indicators.hasFeaturesSection
+    ) {
+      issues.push({
+        code: 'NO_PLANNING_SECTIONS',
+        path: 'content',
+        message: 'Document lacks common planning sections (requirements, tasks, or features)',
+        severity: 'warning',
+      });
+    }
+
+    return {
+      valid: issues.filter((i) => i.severity === 'error').length === 0,
+      issues: issues.length > 0 ? issues : undefined,
+      summary:
+        issues.length === 0
+          ? 'Generic markdown document is valid'
+          : `Found ${issues.length} validation issue${issues.length > 1 ? 's' : ''}`,
+    };
+  }
+}
+
+/**
+ * Create a new generic markdown adapter instance
+ *
+ * @param options - Adapter options
+ * @returns Generic markdown adapter instance
+ */
+export function createGenericMarkdownAdapter(options?: AdapterOptions): GenericMarkdownAdapter {
+  return new GenericMarkdownAdapter(options);
+}

package/src/generic/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Generic Markdown Adapter
+ *
+ * Exports for generic markdown format adapter.
+ */
+
+export { GenericMarkdownAdapter, createGenericMarkdownAdapter } from './format-adapter.js';
+export type { GenericDocument, GenericIndicators } from './types.js';
+export { parseGeneric } from './parser.js';
+export { serializeToGeneric } from './serializer.js';
+// Note: Utils are not exported to avoid conflicts with BMAD utils

package/src/generic/parser.ts

@@ -0,0 +1,129 @@
+/**
+ * Generic Markdown Parser
+ *
+ * Parses generic markdown documents into APS plans.
+ */
+
+import { type APSPlan, type Change, validateRelativePath } from '@eddacraft/anvil-core';
+import type { ParseContext } from '../base/types.js';
+import type { GenericDocument } from './types.js';
+import { generateDeterministicPlanId } from '../base/utils.js';
+import { parseGenericDocument } from './utils.js';
+
+/**
+ * Convert generic document item to APS change
+ */
+function itemToChange(item: string, type: 'requirement' | 'task' | 'feature'): Change {
+  // Determine change type based on item type
+  let changeType: Change['type'] = 'file_create';
+  let pathPrefix = 'src';
+
+  switch (type) {
+    case 'requirement':
+      changeType = 'file_create';
+      pathPrefix = 'src/features';
+      break;
+    case 'task':
+      changeType = 'file_update';
+      pathPrefix = 'src/tasks';
+      break;
+    case 'feature':
+      changeType = 'file_create';
+      pathPrefix = 'src/features';
+      break;
+  }
+
+  // Generate a reasonable path from the item description
+  const slug = item
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, '')
+    .replace(/\s+/g, '-')
+    .substring(0, 50);
+
+  const rawPath = `${pathPrefix}/${slug}.ts`;
+  let safePath: string;
+  try {
+    safePath = validateRelativePath(rawPath);
+  } catch {
+    safePath = rawPath.replace(/\.{2,}/g, '');
+  }
+
+  return {
+    type: changeType,
+    path: safePath,
+    description: item,
+  };
+}
+
+export function genericToAPS(
+  document: GenericDocument,
+  context?: ParseContext,
+  originalContent?: string
+): APSPlan {
+  const planId =
+    context?.planId ??
+    (originalContent
+      ? generateDeterministicPlanId(originalContent)
+      : `aps-${Date.now().toString(16).substring(0, 8)}`);
+
+  // Collect all changes from requirements, tasks, and features
+  const changes: Change[] = [];
+
+  // Add requirements as changes
+  if (document.requirements && document.requirements.length > 0) {
+    changes.push(...document.requirements.map((req) => itemToChange(req, 'requirement')));
+  }
+
+  // Add tasks as changes
+  if (document.tasks && document.tasks.length > 0) {
+    changes.push(...document.tasks.map((task) => itemToChange(task, 'task')));
+  }
+
+  // Add features as changes
+  if (document.features && document.features.length > 0) {
+    changes.push(...document.features.map((feat) => itemToChange(feat, 'feature')));
+  }
+
+  // Build intent from document
+  const intent =
+    document.intent || document.title || document.overview?.substring(0, 200) || 'Generic plan';
+
+  // Build provenance
+  const timestamp = context?.timestamp || new Date().toISOString();
+  const author = context?.author || 'unknown';
+
+  // Create APS plan
+  const plan: APSPlan = {
+    id: planId,
+    schema_version: '0.1.0',
+    intent,
+    proposed_changes: changes,
+    provenance: {
+      timestamp,
+      author,
+      source: 'cli',
+      version: '1.0.0',
+      repository: context?.repositoryPath,
+      branch: context?.branch,
+      commit: context?.commit,
+    },
+    validations: {
+      required_checks: ['lint', 'test'],
+      skip_checks: [],
+    },
+    metadata: {
+      source_format: 'generic-markdown',
+      title: document.title,
+      overview: document.overview,
+      goals: document.goals,
+    },
+    hash: '0000000000000000000000000000000000000000000000000000000000000000',
+  };
+
+  return plan;
+}
+
+export function parseGeneric(content: string, context?: ParseContext): APSPlan {
+  const document = parseGenericDocument(content);
+  return genericToAPS(document, context, content);
+}