@eddacraft/anvil-adapters 0.1.0

package/src/base/file-discovery.ts

@@ -0,0 +1,305 @@
+/**
+ * File Discovery Utility
+ *
+ * Discovers planning documents in repositories by searching for common patterns.
+ */
+
+import { readdir, stat } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+
+/**
+ * Discovered planning file
+ */
+export interface DiscoveredFile {
+  /** Full path to file */
+  path: string;
+  /** File name */
+  name: string;
+  /** File size in bytes */
+  size: number;
+  /** Last modified timestamp */
+  modified: Date;
+  /** Confidence score that this is a planning document (0-100) */
+  confidence: number;
+  /** Reason for detection */
+  reason: string;
+}
+
+/**
+ * Search options
+ */
+export interface SearchOptions {
+  /** Root directory to search from */
+  rootPath: string;
+  /** Maximum depth to search */
+  maxDepth?: number;
+  /** Directories to exclude */
+  excludeDirs?: string[];
+  /** File patterns to search for */
+  patterns?: string[];
+}
+
+/**
+ * Maximum file size to consider (2MB)
+ */
+const MAX_FILE_SIZE_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Maximum directory depth for recursive search
+ */
+const MAX_DEPTH = 20;
+
+/**
+ * Default directories to exclude
+ */
+const DEFAULT_EXCLUDE_DIRS = [
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'coverage',
+  '.next',
+  '.nuxt',
+  'out',
+  'target',
+  'vendor',
+];
+
+/**
+ * Default file patterns for planning documents
+ */
+const DEFAULT_PATTERNS = [
+  'prd',
+  'plan',
+  'todo',
+  'tasks',
+  'spec',
+  'requirements',
+  'rfc',
+  'adr',
+  'design',
+  'proposal',
+  'roadmap',
+];
+
+/**
+ * Calculate confidence score for a file name
+ */
+function calculateFileConfidence(filename: string): { confidence: number; reason: string } {
+  const lower = filename.toLowerCase();
+  let confidence = 0;
+  const reasons: string[] = [];
+
+  // Exact matches (high confidence)
+  const exactMatches = ['prd.md', 'plan.md', 'todo.md', 'tasks.md', 'spec.md', 'requirements.md'];
+  if (exactMatches.some((pattern) => lower === pattern)) {
+    confidence += 80;
+    reasons.push('exact-match');
+  }
+
+  // Pattern matches (medium-high confidence)
+  if (lower.includes('prd')) {
+    confidence += 60;
+    reasons.push('prd-pattern');
+  }
+  if (lower.includes('plan')) {
+    confidence += 55;
+    reasons.push('plan-pattern');
+  }
+  if (lower.includes('todo')) {
+    confidence += 50;
+    reasons.push('todo-pattern');
+  }
+  if (lower.includes('spec')) {
+    confidence += 50;
+    reasons.push('spec-pattern');
+  }
+  if (lower.includes('requirements')) {
+    confidence += 55;
+    reasons.push('requirements-pattern');
+  }
+  if (lower.includes('task')) {
+    confidence += 45;
+    reasons.push('task-pattern');
+  }
+  if (lower.includes('rfc')) {
+    confidence += 50;
+    reasons.push('rfc-pattern');
+  }
+  if (lower.includes('adr')) {
+    confidence += 50;
+    reasons.push('adr-pattern');
+  }
+  if (lower.includes('design')) {
+    confidence += 40;
+    reasons.push('design-pattern');
+  }
+  if (lower.includes('proposal')) {
+    confidence += 45;
+    reasons.push('proposal-pattern');
+  }
+
+  // Check for common planning directories
+  if (lower.includes('docs/') || lower.includes('/docs/')) {
+    confidence += 10;
+    reasons.push('in-docs-dir');
+  }
+  if (lower.includes('.anvil/') || lower.includes('/.anvil/')) {
+    confidence += 15;
+    reasons.push('in-anvil-dir');
+  }
+
+  // Markdown extension
+  if (lower.endsWith('.md') || lower.endsWith('.markdown')) {
+    confidence += 5;
+    reasons.push('markdown');
+  }
+
+  return {
+    confidence: Math.min(100, confidence),
+    reason: reasons.join(', ') || 'no-match',
+  };
+}
+
+/**
+ * Search directory recursively for planning files
+ */
+async function searchDirectory(
+  dirPath: string,
+  options: Required<SearchOptions>,
+  currentDepth: number = 0,
+  results: DiscoveredFile[] = []
+): Promise<DiscoveredFile[]> {
+  // Stop if max depth reached (clamped to safety limit)
+  const effectiveMaxDepth = Math.min(options.maxDepth, MAX_DEPTH);
+  if (currentDepth > effectiveMaxDepth) {
+    return results;
+  }
+
+  try {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dirPath, entry.name);
+
+      if (entry.isDirectory()) {
+        // Skip excluded directories
+        if (options.excludeDirs.includes(entry.name)) {
+          continue;
+        }
+
+        // Recurse into directory
+        await searchDirectory(fullPath, options, currentDepth + 1, results);
+      } else if (entry.isFile()) {
+        // Check if file matches patterns
+        const lower = entry.name.toLowerCase();
+        const matchesPattern = options.patterns.some((pattern) => lower.includes(pattern));
+
+        if (matchesPattern && (lower.endsWith('.md') || lower.endsWith('.markdown'))) {
+          try {
+            const stats = await stat(fullPath);
+
+            // Skip files exceeding size limit
+            if (stats.size > MAX_FILE_SIZE_BYTES) {
+              continue;
+            }
+
+            const { confidence, reason } = calculateFileConfidence(fullPath);
+
+            if (confidence >= 40) {
+              // Threshold for inclusion
+              results.push({
+                path: fullPath,
+                name: entry.name,
+                size: stats.size,
+                modified: stats.mtime,
+                confidence,
+                reason,
+              });
+            }
+          } catch (statError) {
+            console.error(`[FileDiscovery] Failed to stat file ${fullPath}:`, statError);
+          }
+        }
+      }
+    }
+  } catch (readError) {
+    console.error(`[FileDiscovery] Failed to read directory ${dirPath}:`, readError);
+  }
+
+  return results;
+}
+
+/**
+ * Discover planning documents in a directory
+ *
+ * Searches for common planning document patterns like prd.md, plan.md, todo.md, etc.
+ *
+ * @param options - Search options
+ * @returns Array of discovered files, sorted by confidence
+ */
+export async function discoverPlanningFiles(options: SearchOptions): Promise<DiscoveredFile[]> {
+  const searchOptions: Required<SearchOptions> = {
+    rootPath: options.rootPath,
+    maxDepth: options.maxDepth ?? 5,
+    excludeDirs: options.excludeDirs ?? DEFAULT_EXCLUDE_DIRS,
+    patterns: options.patterns ?? DEFAULT_PATTERNS,
+  };
+
+  const results = await searchDirectory(searchOptions.rootPath, searchOptions);
+
+  // Sort by confidence (descending), then by modified date (newest first)
+  return results.sort((a, b) => {
+    if (a.confidence !== b.confidence) {
+      return b.confidence - a.confidence;
+    }
+    return b.modified.getTime() - a.modified.getTime();
+  });
+}
+
+/**
+ * Find the most likely planning document
+ *
+ * Returns the single most likely planning document based on confidence and recency.
+ *
+ * @param options - Search options
+ * @returns The most likely planning document, or undefined if none found
+ */
+export async function findBestPlanningFile(
+  options: SearchOptions
+): Promise<DiscoveredFile | undefined> {
+  const files = await discoverPlanningFiles(options);
+  return files[0];
+}
+
+/**
+ * Group discovered files by name pattern
+ *
+ * Groups files like "prd.md", "plan.md" etc. for easier selection.
+ *
+ * @param files - Discovered files
+ * @returns Map of pattern to files
+ */
+export function groupFilesByPattern(files: DiscoveredFile[]): Map<string, DiscoveredFile[]> {
+  const groups = new Map<string, DiscoveredFile[]>();
+
+  for (const file of files) {
+    const lower = basename(file.name).toLowerCase();
+
+    let pattern = 'other';
+    if (lower.includes('prd')) pattern = 'prd';
+    else if (lower.includes('plan')) pattern = 'plan';
+    else if (lower.includes('todo')) pattern = 'todo';
+    else if (lower.includes('spec')) pattern = 'spec';
+    else if (lower.includes('requirements')) pattern = 'requirements';
+    else if (lower.includes('rfc')) pattern = 'rfc';
+    else if (lower.includes('adr')) pattern = 'adr';
+
+    if (!groups.has(pattern)) {
+      groups.set(pattern, []);
+    }
+    groups.get(pattern)!.push(file);
+  }
+
+  return groups;
+}

package/src/base/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Base Adapter Framework
+ *
+ * Core types, interfaces, and registry for format adapters.
+ */
+
+export * from './types.js';
+export * from './registry.js';
+export * from './utils.js';
+export * from './file-discovery.js';

package/src/base/registry.ts

@@ -0,0 +1,263 @@
+/**
+ * Adapter Registry
+ *
+ * Central registry for format adapters with auto-detection and lookup capabilities.
+ */
+
+import type { FormatAdapter, DetectionResult, PathDetectionHint } from './types.js';
+
+/**
+ * Registry for managing format adapters
+ *
+ * Provides:
+ * - Adapter registration and lookup
+ * - Auto-detection of formats from content
+ * - Extension-based adapter selection
+ */
+export class AdapterRegistry {
+  private static instance: AdapterRegistry | null = null;
+  private adapters: Map<string, FormatAdapter> = new Map();
+
+  private constructor() {}
+
+  /**
+   * Get singleton instance
+   */
+  static getInstance(): AdapterRegistry {
+    if (!AdapterRegistry.instance) {
+      AdapterRegistry.instance = new AdapterRegistry();
+    }
+    return AdapterRegistry.instance;
+  }
+
+  /**
+   * Reset singleton instance (useful for testing)
+   */
+  static resetInstance(): void {
+    AdapterRegistry.instance = null;
+  }
+
+  /**
+   * Register an adapter
+   *
+   * @param adapter - Adapter to register
+   * @throws Error if adapter with same name already registered
+   */
+  register(adapter: FormatAdapter): void {
+    if (this.adapters.has(adapter.metadata.name)) {
+      throw new Error(`Adapter '${adapter.metadata.name}' is already registered`);
+    }
+    this.adapters.set(adapter.metadata.name, adapter);
+  }
+
+  /**
+   * Unregister an adapter by name
+   *
+   * @param name - Name of adapter to unregister
+   * @returns True if adapter was removed, false if not found
+   */
+  unregister(name: string): boolean {
+    return this.adapters.delete(name);
+  }
+
+  /**
+   * Get adapter by name
+   *
+   * @param name - Adapter name
+   * @returns Adapter instance or undefined
+   */
+  getAdapter(name: string): FormatAdapter | undefined {
+    return this.adapters.get(name);
+  }
+
+  /**
+   * Get adapter for a specific format identifier or extension
+   *
+   * @param format - Format identifier (e.g., "speckit") or extension (e.g., ".md")
+   * @returns First matching adapter or undefined
+   */
+  getAdapterForFormat(format: string): FormatAdapter | undefined {
+    for (const adapter of this.adapters.values()) {
+      if (adapter.canImport(format)) {
+        return adapter;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Detect adapter from content
+   *
+   * Runs detection on all registered adapters and returns the best match.
+   *
+   * @param content - Content to analyze
+   * @param minConfidence - Minimum confidence score (0-100) to accept
+   * @returns Best matching adapter and detection result, or undefined
+   */
+  detectAdapter(
+    content: string,
+    minConfidence: number = 50
+  ): { adapter: FormatAdapter; detection: DetectionResult } | undefined {
+    let bestMatch: { adapter: FormatAdapter; detection: DetectionResult } | undefined;
+    let bestConfidence = minConfidence - 1;
+
+    for (const adapter of this.adapters.values()) {
+      const detection = adapter.detect(content);
+      if (detection.detected && detection.confidence > bestConfidence) {
+        bestConfidence = detection.confidence;
+        bestMatch = { adapter, detection };
+      }
+    }
+
+    return bestMatch;
+  }
+
+  /**
+   * Detect adapter from content with path hints
+   *
+   * Like detectAdapter but passes file path information to adapters
+   * that implement detectWithPath for improved accuracy.
+   *
+   * @param content - Content to analyze
+   * @param hint - File path and directory information
+   * @param minConfidence - Minimum confidence score (0-100) to accept
+   * @returns Best matching adapter and detection result, or undefined
+   */
+  detectAdapterWithPath(
+    content: string,
+    hint: PathDetectionHint,
+    minConfidence: number = 50
+  ): { adapter: FormatAdapter; detection: DetectionResult } | undefined {
+    let bestMatch: { adapter: FormatAdapter; detection: DetectionResult } | undefined;
+    let bestConfidence = minConfidence - 1;
+
+    for (const adapter of this.adapters.values()) {
+      const detection = adapter.detectWithPath
+        ? adapter.detectWithPath(content, hint)
+        : adapter.detect(content);
+
+      if (detection.detected && detection.confidence > bestConfidence) {
+        bestConfidence = detection.confidence;
+        bestMatch = { adapter, detection };
+      }
+    }
+
+    return bestMatch;
+  }
+
+  /**
+   * Get all detection results for content
+   *
+   * Useful for debugging or showing user multiple format possibilities.
+   *
+   * @param content - Content to analyze
+   * @returns Array of detection results for all adapters, sorted by confidence
+   */
+  detectAll(content: string): Array<{ adapter: FormatAdapter; detection: DetectionResult }> {
+    const results = Array.from(this.adapters.values()).map((adapter) => ({
+      adapter,
+      detection: adapter.detect(content),
+    }));
+
+    return results.sort((a, b) => b.detection.confidence - a.detection.confidence);
+  }
+
+  /**
+   * List all registered adapters
+   *
+   * @returns Array of all adapters
+   */
+  listAdapters(): ReadonlyArray<FormatAdapter> {
+    return Array.from(this.adapters.values());
+  }
+
+  /**
+   * List all adapter names
+   *
+   * @returns Array of adapter names
+   */
+  listAdapterNames(): ReadonlyArray<string> {
+    return Array.from(this.adapters.keys());
+  }
+
+  /**
+   * List all supported formats across all adapters
+   *
+   * @returns Array of unique format identifiers
+   */
+  listSupportedFormats(): ReadonlyArray<string> {
+    const formats = new Set<string>();
+    for (const adapter of this.adapters.values()) {
+      for (const format of adapter.metadata.formats) {
+        formats.add(format);
+      }
+    }
+    return Array.from(formats).sort();
+  }
+
+  /**
+   * List all supported extensions across all adapters
+   *
+   * @returns Array of unique file extensions
+   */
+  listSupportedExtensions(): ReadonlyArray<string> {
+    const extensions = new Set<string>();
+    for (const adapter of this.adapters.values()) {
+      for (const ext of adapter.metadata.extensions) {
+        extensions.add(ext);
+      }
+    }
+    return Array.from(extensions).sort();
+  }
+
+  /**
+   * Get adapters that can import a specific format
+   *
+   * @param format - Format identifier or extension
+   * @returns Array of adapters that support this format for import
+   */
+  getImportAdapters(format: string): ReadonlyArray<FormatAdapter> {
+    return Array.from(this.adapters.values()).filter((adapter) => adapter.canImport(format));
+  }
+
+  /**
+   * Get adapters that can export to a specific format
+   *
+   * @param format - Format identifier or extension
+   * @returns Array of adapters that support this format for export
+   */
+  getExportAdapters(format: string): ReadonlyArray<FormatAdapter> {
+    return Array.from(this.adapters.values()).filter((adapter) => adapter.canExport(format));
+  }
+
+  /**
+   * Check if any adapter supports a format
+   *
+   * @param format - Format identifier or extension
+   * @returns True if at least one adapter supports this format
+   */
+  isFormatSupported(format: string): boolean {
+    return this.getAdapterForFormat(format) !== undefined;
+  }
+
+  /**
+   * Clear all registered adapters
+   *
+   * Mainly useful for testing.
+   */
+  clear(): void {
+    this.adapters.clear();
+  }
+
+  /**
+   * Get number of registered adapters
+   */
+  get size(): number {
+    return this.adapters.size;
+  }
+}
+
+/**
+ * Default singleton instance
+ */
+export const registry = AdapterRegistry.getInstance();