@eddacraft/anvil-adapters 0.1.0

package/src/generic/serializer.ts

@@ -0,0 +1,134 @@
+/**
+ * Generic Markdown Serializer
+ *
+ * Serializes APS plans to generic markdown format.
+ */
+
+import type { APSPlan } from '@eddacraft/anvil-core';
+
+/**
+ * Type guard to check if value is a string
+ */
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+/**
+ * Type guard to check if value is a string array
+ */
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
+/**
+ * Serialize APS plan to generic markdown format
+ */
+export function serializeToGeneric(plan: APSPlan): string {
+  const lines: string[] = [];
+
+  // Title (from intent or metadata) - safely check if title is a non-empty string
+  const metadataTitle = plan.metadata?.['title'];
+  const title = isString(metadataTitle) && metadataTitle ? metadataTitle : plan.intent;
+  lines.push(`# ${title}`);
+  lines.push('');
+
+  // Overview section - safely check if overview is a string
+  const metadataOverview = plan.metadata?.['overview'];
+  if (metadataOverview && isString(metadataOverview)) {
+    lines.push('## Overview');
+    lines.push('');
+    lines.push(metadataOverview);
+    lines.push('');
+  } else if (plan.intent) {
+    lines.push('## Purpose');
+    lines.push('');
+    lines.push(plan.intent);
+    lines.push('');
+  }
+
+  // Goals section - safely check if goals is a string array
+  const metadataGoals = plan.metadata?.['goals'];
+  if (metadataGoals && isStringArray(metadataGoals)) {
+    lines.push('## Goals');
+    lines.push('');
+    for (const goal of metadataGoals) {
+      lines.push(`- ${goal}`);
+    }
+    lines.push('');
+  }
+
+  // Changes section
+  if (plan.proposed_changes.length > 0) {
+    lines.push('## Changes');
+    lines.push('');
+
+    // Group changes by type
+    const creates = plan.proposed_changes.filter((c) => c.type === 'file_create');
+    const updates = plan.proposed_changes.filter((c) => c.type === 'file_update');
+    const deletes = plan.proposed_changes.filter((c) => c.type === 'file_delete');
+    const configs = plan.proposed_changes.filter((c) => c.type === 'config_update');
+
+    if (creates.length > 0) {
+      lines.push('### Files to Create');
+      lines.push('');
+      for (const change of creates) {
+        lines.push(`- **${change.path}**: ${change.description}`);
+      }
+      lines.push('');
+    }
+
+    if (updates.length > 0) {
+      lines.push('### Files to Update');
+      lines.push('');
+      for (const change of updates) {
+        lines.push(`- **${change.path}**: ${change.description}`);
+      }
+      lines.push('');
+    }
+
+    if (configs.length > 0) {
+      lines.push('### Configuration Changes');
+      lines.push('');
+      for (const change of configs) {
+        lines.push(`- **${change.path}**: ${change.description}`);
+      }
+      lines.push('');
+    }
+
+    if (deletes.length > 0) {
+      lines.push('### Files to Delete');
+      lines.push('');
+      for (const change of deletes) {
+        lines.push(`- **${change.path}**: ${change.description}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // Validation requirements
+  if (plan.validations.required_checks.length > 0) {
+    lines.push('## Validation Requirements');
+    lines.push('');
+    for (const check of plan.validations.required_checks) {
+      lines.push(`- ${check}`);
+    }
+    lines.push('');
+  }
+
+  // Metadata section
+  if (plan.provenance) {
+    lines.push('## Metadata');
+    lines.push('');
+    lines.push(`- **Author**: ${plan.provenance.author || 'Unknown'}`);
+    lines.push(`- **Created**: ${plan.provenance.timestamp}`);
+    if (plan.provenance.repository) {
+      lines.push(`- **Repository**: ${plan.provenance.repository}`);
+    }
+    if (plan.provenance.branch) {
+      lines.push(`- **Branch**: ${plan.provenance.branch}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/generic/types.ts

@@ -0,0 +1,53 @@
+/**
+ * Generic Adapter Types
+ *
+ * Types for the generic markdown adapter that handles common planning document formats.
+ */
+
+/**
+ * Parsed generic document structure
+ */
+export interface GenericDocument {
+  /** Document title (from first # heading) */
+  title?: string;
+  /** Intent/purpose extracted from intro or objective sections */
+  intent?: string;
+  /** Overview/description */
+  overview?: string;
+  /** Goals or objectives */
+  goals?: string[];
+  /** Requirements extracted from various sections */
+  requirements?: string[];
+  /** Tasks or action items */
+  tasks?: string[];
+  /** Features or capabilities */
+  features?: string[];
+  /** Metadata from document */
+  metadata?: Record<string, unknown>;
+  /** Raw content */
+  raw: string;
+}
+
+/**
+ * Detection indicators for generic markdown
+ */
+export interface GenericIndicators {
+  /** Has markdown headings */
+  hasHeadings: boolean;
+  /** Has lists (bullet or numbered) */
+  hasLists: boolean;
+  /** Has requirements-like content */
+  hasRequirementsSection: boolean;
+  /** Has goals/objectives section */
+  hasGoalsSection: boolean;
+  /** Has tasks/action items */
+  hasTasksSection: boolean;
+  /** Has features section */
+  hasFeaturesSection: boolean;
+  /** Has overview/description */
+  hasOverviewSection: boolean;
+  /** Document length */
+  wordCount: number;
+  /** Number of list items */
+  listItemCount: number;
+}

package/src/generic/utils.ts

@@ -0,0 +1,270 @@
+/**
+ * Generic Adapter Utilities
+ *
+ * Helper functions for parsing generic markdown documents.
+ */
+
+import type { GenericDocument, GenericIndicators } from './types.js';
+
+/**
+ * Extract document title from first heading
+ */
+export function extractTitle(content: string): string | undefined {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : undefined;
+}
+
+/**
+ * Extract intent from common sections
+ */
+export function extractIntent(content: string): string | undefined {
+  // Look for sections like: Purpose, Intent, Objective, Goal, Summary
+  const patterns = [
+    /##\s+(?:Purpose|Intent|Objective|Goal)\s*\n+([^\n#]+)/i,
+    /##\s+(?:Executive\s+)?Summary\s*\n+([^\n#]+)/i,
+    /^([^#\n]+?)(?=\n##|\n#|$)/m, // First paragraph as fallback
+  ];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match && match[1]) {
+      return match[1].trim().substring(0, 500); // Limit length
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract overview/description
+ */
+export function extractOverview(content: string): string | undefined {
+  const patterns = [/##\s+(?:Overview|Description|Background|Context)\s*\n+([\s\S]+?)(?=\n##|$)/i];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match && match[1]) {
+      return match[1].trim();
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract goals from lists under Goals/Objectives sections
+ */
+export function extractGoals(content: string): string[] {
+  const goals: string[] = [];
+
+  // Match Goals/Objectives section
+  const sectionMatch = content.match(/##\s+(?:Goals?|Objectives?)\s*\n+([\s\S]+?)(?=\n##|$)/i);
+
+  if (sectionMatch) {
+    const section = sectionMatch[1];
+    // Extract list items
+    const listItems = section.match(/^[-*]\s+(.+)$/gm);
+    if (listItems) {
+      goals.push(...listItems.map((item) => item.replace(/^[-*]\s+/, '').trim()));
+    }
+  }
+
+  return goals;
+}
+
+/**
+ * Extract requirements from various sections
+ */
+export function extractRequirements(content: string): string[] {
+  const requirements: string[] = [];
+
+  // Match Requirements/Needs/Must Have sections
+  const patterns = [
+    /##\s+(?:Requirements?|Needs?|Must\s+Have)\s*\n+([\s\S]+?)(?=\n##|$)/i,
+    /##\s+(?:Functional\s+)?Requirements?\s*\n+([\s\S]+?)(?=\n##|$)/i,
+  ];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match) {
+      const section = match[1];
+      // Extract list items
+      const listItems = section.match(/^[-*]\s+(.+)$/gm);
+      if (listItems) {
+        requirements.push(...listItems.map((item) => item.replace(/^[-*]\s+/, '').trim()));
+      }
+      // Extract numbered items
+      const numberedItems = section.match(/^\d+\.\s+(.+)$/gm);
+      if (numberedItems) {
+        requirements.push(...numberedItems.map((item) => item.replace(/^\d+\.\s+/, '').trim()));
+      }
+    }
+  }
+
+  return requirements;
+}
+
+/**
+ * Extract tasks from Tasks/Action Items sections
+ */
+export function extractTasks(content: string): string[] {
+  const tasks: string[] = [];
+
+  const patterns = [/##\s+(?:Tasks?|Action\s+Items?|To\s+Do|TODO)\s*\n+([\s\S]+?)(?=\n##|$)/i];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match) {
+      const section = match[1];
+      // Extract list items (including checkboxes)
+      const listItems = section.match(/^[-*]\s+(?:\[[ x]\]\s+)?(.+)$/gm);
+      if (listItems) {
+        tasks.push(...listItems.map((item) => item.replace(/^[-*]\s+(?:\[[ x]\]\s+)?/, '').trim()));
+      }
+    }
+  }
+
+  return tasks;
+}
+
+/**
+ * Extract features from Features/Capabilities sections
+ */
+export function extractFeatures(content: string): string[] {
+  const features: string[] = [];
+
+  const patterns = [/##\s+(?:Features?|Capabilities?|Functionality)\s*\n+([\s\S]+?)(?=\n##|$)/i];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match) {
+      const section = match[1];
+      const listItems = section.match(/^[-*]\s+(.+)$/gm);
+      if (listItems) {
+        features.push(...listItems.map((item) => item.replace(/^[-*]\s+/, '').trim()));
+      }
+    }
+  }
+
+  return features;
+}
+
+/**
+ * Analyze content for generic markdown indicators
+ */
+export function analyzeContent(content: string): GenericIndicators {
+  const headings = content.match(/^#{1,6}\s+.+$/gm) || [];
+  const listItems = content.match(/^[-*]\s+.+$/gm) || [];
+  const words = content.split(/\s+/).filter((w) => w.length > 0);
+
+  return {
+    hasHeadings: headings.length > 0,
+    hasLists: listItems.length > 0,
+    hasRequirementsSection: /##\s+(?:Requirements?|Needs?)/i.test(content),
+    hasGoalsSection: /##\s+(?:Goals?|Objectives?)/i.test(content),
+    hasTasksSection: /##\s+(?:Tasks?|Action\s+Items?|To\s+Do)/i.test(content),
+    hasFeaturesSection: /##\s+(?:Features?|Capabilities?)/i.test(content),
+    hasOverviewSection: /##\s+(?:Overview|Description|Background)/i.test(content),
+    wordCount: words.length,
+    listItemCount: listItems.length,
+  };
+}
+
+/**
+ * Calculate confidence score for generic markdown detection
+ */
+export function calculateConfidenceScore(indicators: GenericIndicators): number {
+  let score = 0;
+
+  // Basic markdown structure (10 points)
+  if (indicators.hasHeadings) {
+    score += 10;
+  }
+
+  // Has lists (10 points)
+  if (indicators.hasLists) {
+    score += 10;
+  }
+
+  // Planning-related sections (5 points each)
+  if (indicators.hasRequirementsSection) {
+    score += 5;
+  }
+  if (indicators.hasGoalsSection) {
+    score += 5;
+  }
+  if (indicators.hasTasksSection) {
+    score += 5;
+  }
+  if (indicators.hasFeaturesSection) {
+    score += 5;
+  }
+  if (indicators.hasOverviewSection) {
+    score += 5;
+  }
+
+  // Content density (up to 10 points)
+  if (indicators.wordCount >= 100) {
+    score += 5;
+  }
+  if (indicators.wordCount >= 500) {
+    score += 5;
+  }
+
+  // List items (up to 5 points)
+  if (indicators.listItemCount >= 3) {
+    score += 3;
+  }
+  if (indicators.listItemCount >= 10) {
+    score += 2;
+  }
+
+  return Math.min(100, score);
+}
+
+/**
+ * Build detection reason string
+ */
+export function buildDetectionReason(indicators: GenericIndicators): string {
+  const reasons: string[] = [];
+
+  if (indicators.hasHeadings) {
+    reasons.push('markdown-headings');
+  }
+  if (indicators.hasLists) {
+    reasons.push(`${indicators.listItemCount} list-items`);
+  }
+  if (indicators.hasRequirementsSection) {
+    reasons.push('requirements-section');
+  }
+  if (indicators.hasGoalsSection) {
+    reasons.push('goals-section');
+  }
+  if (indicators.hasTasksSection) {
+    reasons.push('tasks-section');
+  }
+  if (indicators.hasFeaturesSection) {
+    reasons.push('features-section');
+  }
+  if (indicators.hasOverviewSection) {
+    reasons.push('overview-section');
+  }
+
+  return reasons.length > 0 ? reasons.join(', ') : 'generic-markdown';
+}
+
+/**
+ * Parse generic markdown document
+ */
+export function parseGenericDocument(content: string): GenericDocument {
+  return {
+    title: extractTitle(content),
+    intent: extractIntent(content),
+    overview: extractOverview(content),
+    goals: extractGoals(content),
+    requirements: extractRequirements(content),
+    tasks: extractTasks(content),
+    features: extractFeatures(content),
+    raw: content,
+  };
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Anvil Adapters Package
+ *
+ * Provides format adapters for converting between external planning formats
+ * (SpecKit, BMAD, etc.) and the Anvil Plan Spec (APS).
+ */
+
+// Export base framework (types, registry, utils)
+export * from './base/index.js';
+
+// Export APS Markdown adapter (native format)
+export * from './aps-markdown/index.js';
+
+// Export SpecKit adapter
+export * from './speckit/index.js';
+
+// Export BMAD adapter
+export * from './bmad/index.js';
+
+// Export Generic adapter
+export * from './generic/index.js';
+
+// Export common types for backward compatibility
+export type {
+  SpecContext,
+  ExternalSpec,
+  ConversionResult,
+  ConversionError,
+  ConversionWarning,
+} from './common/types.js';
+
+// Auto-register adapters when module is imported
+import { registry as baseRegistry } from './base/index.js';
+import { APSMarkdownAdapter } from './aps-markdown/index.js';
+import { BMADFormatAdapter } from './bmad/index.js';
+import { SpecKitFormatAdapter } from './speckit/index.js';
+import { GenericMarkdownAdapter } from './generic/index.js';
+
+// Register adapters in priority order
+// APS adapter first (native format), then specific external formats
+// Generic adapter is registered last as fallback
+baseRegistry.register(new APSMarkdownAdapter());
+baseRegistry.register(new BMADFormatAdapter());
+baseRegistry.register(new SpecKitFormatAdapter());
+baseRegistry.register(new GenericMarkdownAdapter());
+
+// Export the registry instance as default export
+export { baseRegistry as registry };