@eddacraft/anvil-aps 0.1.0

package/src/parser/parse-document.ts

@@ -0,0 +1,262 @@
+/**
+ * Document parsing utilities
+ * Converts APS Markdown documents to structured data
+ */
+
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import { visit } from 'unist-util-visit';
+import type { Root, Heading, Paragraph, List, Strong } from 'mdast';
+import { parseTask } from './parse-task.js';
+import { ParseError, type Task, type ParsedDocument, type ModuleMetadata } from '../types/index.js';
+
+/**
+ * Parse an APS leaf spec document from Markdown content
+ *
+ * This function parses leaf specs (documents with tasks).
+ * For index files (documents with modules), use `parseIndex` instead.
+ *
+ * @param content - Markdown content of a leaf spec
+ * @param sourcePath - Optional source file path for error reporting
+ * @returns Parsed document with tasks
+ */
+export async function parseDocument(content: string, sourcePath?: string): Promise<ParsedDocument> {
+  // Parse Markdown to AST
+  const processor = unified().use(remarkParse);
+  const ast = processor.parse(content) as Root;
+
+  // Extract document structure
+  const structure = extractStructure(ast, sourcePath);
+
+  // Validate structure
+  if (!structure.title) {
+    throw new ParseError('Document must have an H1 title', sourcePath);
+  }
+
+  return {
+    title: structure.title,
+    metadata: structure.metadata,
+    tasks: structure.tasks,
+    sourcePath,
+  };
+}
+
+/**
+ * Extract document structure from AST
+ */
+interface DocumentStructure {
+  title: string | null;
+  metadata?: ModuleMetadata;
+  tasks: Task[];
+}
+
+type TaskHeading = { heading: Heading; lineNumber: number };
+
+function extractStructure(ast: Root, sourcePath?: string): DocumentStructure {
+  const structure: DocumentStructure = {
+    title: null,
+    tasks: [],
+  };
+
+  let currentSection: 'root' | 'tasks' = 'root';
+  let currentTaskHeading: TaskHeading | null = null;
+  let currentTaskContent: Array<Paragraph | List> = [];
+
+  visit(ast, (node, index, parent) => {
+    if (node.type === 'heading') {
+      const heading = node as Heading;
+
+      // H1: Document title
+      if (heading.depth === 1) {
+        structure.title = extractPlainText(heading);
+
+        // Check next sibling for metadata line
+        if (parent && index !== null && index !== undefined) {
+          const nextSibling = (parent as Root).children[index + 1];
+          if (nextSibling && nextSibling.type === 'paragraph') {
+            structure.metadata = parseMetadataLine(nextSibling as Paragraph);
+          }
+        }
+      }
+
+      // H2: Section headers
+      if (heading.depth === 2) {
+        // Save previous task if any
+        if (currentTaskHeading) {
+          saveTask(currentTaskHeading, currentTaskContent, sourcePath, structure);
+          currentTaskHeading = null;
+          currentTaskContent = [];
+        }
+
+        const sectionTitle = extractPlainText(heading).toLowerCase();
+        if (sectionTitle === 'tasks') {
+          currentSection = 'tasks';
+        } else {
+          currentSection = 'root';
+        }
+      }
+
+      // H3: Task headings
+      if (heading.depth === 3 && currentSection === 'tasks') {
+        // Save previous task if any
+        if (currentTaskHeading) {
+          saveTask(currentTaskHeading, currentTaskContent, sourcePath, structure);
+          currentTaskHeading = null;
+          currentTaskContent = [];
+        }
+
+        // Start new task
+        currentTaskHeading = {
+          heading,
+          lineNumber: node.position?.start.line ?? 0,
+        };
+        currentTaskContent = [];
+      }
+    }
+
+    // Collect content for current task
+    if (currentTaskHeading && (node.type === 'paragraph' || node.type === 'list')) {
+      currentTaskContent.push(node as Paragraph | List);
+    }
+  });
+
+  // Save last task if any
+  if (currentTaskHeading) {
+    saveTask(currentTaskHeading, currentTaskContent, sourcePath, structure);
+  }
+
+  return structure;
+}
+
+/**
+ * Helper to save a task from heading and content
+ */
+function saveTask(
+  taskHeading: TaskHeading,
+  taskContent: Array<Paragraph | List>,
+  sourcePath: string | undefined,
+  structure: DocumentStructure
+): void {
+  try {
+    const task = parseTask(taskHeading.heading, taskContent, sourcePath, taskHeading.lineNumber);
+    structure.tasks.push(task);
+  } catch (error) {
+    if (error instanceof ParseError) {
+      throw error;
+    }
+    throw new ParseError(
+      `Failed to parse task: ${error instanceof Error ? error.message : String(error)}`,
+      sourcePath
+    );
+  }
+}
+
+/**
+ * Extract plain text from heading or paragraph node
+ */
+function extractPlainText(node: Heading | Paragraph): string {
+  let text = '';
+
+  visit(node, 'text', (textNode) => {
+    text += (textNode as { value: string }).value;
+  });
+
+  return text;
+}
+
+/**
+ * Parse module metadata line (immediately after H1)
+ * Format: **Scope:** AUTH **Owner:** @alice **Priority:** high
+ */
+function parseMetadataLine(para: Paragraph): ModuleMetadata {
+  const metadata: ModuleMetadata = {};
+  let currentKey = '';
+  let currentValue = '';
+
+  for (const child of para.children) {
+    if (child.type === 'strong') {
+      // Save previous field (even if value is empty, so handlers like Packages can default)
+      if (currentKey) {
+        assignMetadataField(metadata, currentKey, currentValue.trim());
+      }
+
+      // Extract new field key
+      let strongText = '';
+      visit(child as Strong, 'text', (textNode) => {
+        strongText += (textNode as { value: string }).value;
+      });
+      const match = strongText.match(/^(\w+):$/);
+      if (match) {
+        currentKey = match[1];
+        currentValue = '';
+      }
+    } else if (child.type === 'text' && currentKey) {
+      currentValue += (child as { value: string }).value;
+    }
+  }
+
+  // Save last field (even if value is empty)
+  if (currentKey) {
+    assignMetadataField(metadata, currentKey, currentValue.trim());
+  }
+
+  return metadata;
+}
+
+/**
+ * Assign metadata field value
+ */
+function assignMetadataField(metadata: ModuleMetadata, key: string, value: string): void {
+  switch (key) {
+    case 'Scope':
+    case 'ID':
+      // Support both 'Scope:' and 'ID:' per current APS spec
+      metadata.scope = value;
+      break;
+    case 'Owner':
+      metadata.owner = value;
+      break;
+    case 'Status': {
+      // Normalise status values to match ModuleStatusSchema
+      // Legacy values are mapped to canonical equivalents: Draft→Proposed, Complete→Done
+      const statusMap: Record<string, ModuleMetadata['status']> = {
+        Draft: 'Proposed',
+        Proposed: 'Proposed',
+        Ready: 'Ready',
+        'In Progress': 'In Progress',
+        Complete: 'Done',
+        Done: 'Done',
+        Blocked: 'Blocked',
+      };
+      const mapped = statusMap[value.trim()];
+      if (mapped) {
+        metadata.status = mapped;
+      }
+      break;
+    }
+    case 'Priority':
+      if (value === 'low' || value === 'medium' || value === 'high') {
+        metadata.priority = value;
+      }
+      break;
+    case 'Tags':
+      metadata.tags = value.split(',').map((t) => t.trim());
+      break;
+    case 'Dependencies':
+      metadata.dependencies = value.split(',').map((d) => d.trim());
+      break;
+    case 'Packages': {
+      // Monorepo support: list of affected packages
+      const trimmed = value.trim();
+      if (!trimmed || trimmed.toLowerCase() === '(none)') {
+        metadata.packages = [];
+      } else {
+        metadata.packages = trimmed
+          .split(',')
+          .map((p) => p.trim())
+          .filter((p) => p.length > 0);
+      }
+      break;
+    }
+  }
+}

package/src/parser/parse-index.test.ts

@@ -0,0 +1,316 @@
+/**
+ * Tests for parse-index module
+ */
+
+import { describe, it, expect } from 'vitest';
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseIndex } from './parse-index.js';
+import { ParseError } from '../types/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXTURES_DIR = join(__dirname, '__fixtures__');
+const EXAMPLES_DIR = join(__dirname, '../../examples');
+
+async function loadFixture(filename: string): Promise<string> {
+  return fs.readFile(join(FIXTURES_DIR, filename), 'utf-8');
+}
+
+describe('parseIndex', () => {
+  describe('basic parsing', () => {
+    it('should parse a simple index file', async () => {
+      const content = await loadFixture('simple-index.aps.md');
+      const index = await parseIndex(content, 'simple-index.aps.md');
+
+      expect(index.title).toBe('Simple Plan');
+      expect(index.overview).toBe('A simple plan with two modules for testing.');
+      expect(index.modules).toHaveLength(2);
+      expect(index.sourcePath).toBe('simple-index.aps.md');
+    });
+
+    it('should parse module metadata correctly', async () => {
+      const content = await loadFixture('simple-index.aps.md');
+      const index = await parseIndex(content);
+
+      // First module (auth)
+      expect(index.modules[0]).toEqual({
+        id: 'auth',
+        path: './modules/auth.aps.md',
+        scope: 'AUTH',
+        owner: '@alice',
+        priority: 'high',
+        tags: ['security', 'core'],
+        dependencies: [],
+      });
+
+      // Second module (api)
+      expect(index.modules[1]).toEqual({
+        id: 'api',
+        path: './modules/api.aps.md',
+        scope: 'API',
+        owner: '@bob',
+        priority: 'medium',
+        tags: ['backend'],
+        dependencies: ['auth'],
+      });
+    });
+
+    it('should parse open questions', async () => {
+      const content = await loadFixture('simple-index.aps.md');
+      const index = await parseIndex(content);
+
+      expect(index.openQuestions).toEqual([
+        'Should we add rate limiting?',
+        'What authentication method to use?',
+      ]);
+    });
+
+    it('should parse decisions', async () => {
+      const content = await loadFixture('simple-index.aps.md');
+      const index = await parseIndex(content);
+
+      expect(index.decisions).toEqual([
+        'Using JWT tokens (decided 2025-01-15)',
+        'PostgreSQL database (decided 2025-01-10)',
+      ]);
+    });
+  });
+
+  describe('real examples', () => {
+    it('should parse system-ecommerce index file', async () => {
+      const content = await fs.readFile(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'), 'utf-8');
+      const index = await parseIndex(content, 'system-ecommerce/APS.md');
+
+      expect(index.title).toBe('E-commerce Platform MVP');
+      expect(index.modules).toHaveLength(4);
+
+      // Check module IDs
+      expect(index.modules.map((m) => m.id)).toEqual(['auth', 'products', 'cart', 'payments']);
+
+      // Check auth module
+      expect(index.modules[0]).toMatchObject({
+        id: 'auth',
+        path: './modules/auth.aps.md',
+        scope: 'AUTH',
+        owner: '@alice',
+        priority: 'high',
+        dependencies: [],
+      });
+
+      // Check payments module dependencies
+      expect(index.modules[3]).toMatchObject({
+        id: 'payments',
+        dependencies: ['auth', 'cart'],
+      });
+
+      // Check open questions exist
+      expect(index.openQuestions).toHaveLength(3);
+
+      // Check decisions exist
+      expect(index.decisions).toHaveLength(4);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should throw ParseError for index without title', async () => {
+      const content = '## Modules\n\n### auth\n- **Path:** ./auth.aps.md';
+
+      await expect(parseIndex(content, 'no-title.md')).rejects.toThrow(ParseError);
+      await expect(parseIndex(content, 'no-title.md')).rejects.toThrow(/must have an H1 title/);
+    });
+
+    it('should handle index with no modules', async () => {
+      const content = '# Empty Plan\n\n## Overview\n\nJust an overview.';
+
+      const index = await parseIndex(content);
+
+      expect(index.title).toBe('Empty Plan');
+      expect(index.modules).toHaveLength(0);
+    });
+  });
+
+  describe('ID field parsing', () => {
+    it('should parse ID field as alias for Scope', async () => {
+      const content = `# Test Plan
+
+## Modules
+
+### auth
+
+- **Path:** [./auth.aps.md](./auth.aps.md)
+- **ID:** AUTH
+`;
+
+      const index = await parseIndex(content);
+      expect(index.modules[0].scope).toBe('AUTH');
+    });
+
+    it('should parse Scope field (legacy) the same as ID', async () => {
+      const content = `# Test Plan
+
+## Modules
+
+### auth
+
+- **Path:** [./auth.aps.md](./auth.aps.md)
+- **Scope:** AUTH
+`;
+
+      const index = await parseIndex(content);
+      expect(index.modules[0].scope).toBe('AUTH');
+    });
+  });
+
+  describe('status normalization', () => {
+    it('should normalize legacy Draft to Proposed', async () => {
+      const content = `# Test Plan
+
+## Modules
+
+### auth
+
+- **Path:** [./auth.aps.md](./auth.aps.md)
+- **Status:** Draft
+`;
+
+      const index = await parseIndex(content);
+      expect(index.modules[0].status).toBe('Proposed');
+    });
+
+    it('should normalize legacy Complete to Done', async () => {
+      const content = `# Test Plan
+
+## Modules
+
+### auth
+
+- **Path:** [./auth.aps.md](./auth.aps.md)
+- **Status:** Complete
+`;
+
+      const index = await parseIndex(content);
+      expect(index.modules[0].status).toBe('Done');
+    });
+
+    it('should accept all valid status values', async () => {
+      for (const [input, expected] of [
+        ['Proposed', 'Proposed'],
+        ['Ready', 'Ready'],
+        ['In Progress', 'In Progress'],
+        ['Done', 'Done'],
+        ['Blocked', 'Blocked'],
+      ] as const) {
+        const content = `# Test Plan
+
+## Modules
+
+### mod
+
+- **Path:** [./mod.aps.md](./mod.aps.md)
+- **Status:** ${input}
+`;
+
+        const index = await parseIndex(content);
+        expect(index.modules[0].status).toBe(expected);
+      }
+    });
+  });
+
+  describe('packages parsing', () => {
+    it('should parse comma-separated Packages field', async () => {
+      const content = `# Test Plan
+
+## Modules
+
+### auth
+
+- **Path:** [./auth.aps.md](./auth.aps.md)
+- **Packages:** @app/core, @app/utils
+`;
+
+      const index = await parseIndex(content);
+      expect(index.modules[0].packages).toEqual(['@app/core', '@app/utils']);
+    });
+
+    it('should handle Packages: (none) as empty array', async () => {
+      const content = `# Test Plan
+
+## Modules
+
+### auth
+
+- **Path:** [./auth.aps.md](./auth.aps.md)
+- **Packages:** (none)
+`;
+
+      const index = await parseIndex(content);
+      expect(index.modules[0].packages).toEqual([]);
+    });
+
+    it('should handle empty Packages value as empty array', async () => {
+      const content = `# Test Plan
+
+## Modules
+
+### auth
+
+- **Path:** [./auth.aps.md](./auth.aps.md)
+- **Packages:**
+`;
+
+      const index = await parseIndex(content);
+      expect(index.modules[0].packages).toEqual([]);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle module with minimal metadata', async () => {
+      const content = `# Minimal
+
+## Modules
+
+### simple
+
+- **Path:** [./simple.aps.md](./simple.aps.md)
+`;
+
+      const index = await parseIndex(content);
+
+      expect(index.modules[0]).toEqual({
+        id: 'simple',
+        path: './simple.aps.md',
+      });
+    });
+
+    it('should handle empty dependencies', async () => {
+      const content = `# Test
+
+## Modules
+
+### mod
+
+- **Path:** [./mod.aps.md](./mod.aps.md)
+- **Dependencies:** (none)
+`;
+
+      const index = await parseIndex(content);
+      expect(index.modules[0].dependencies).toEqual([]);
+    });
+
+    it('should handle multiple tags', async () => {
+      const content = `# Test
+
+## Modules
+
+### mod
+
+- **Path:** [./mod.aps.md](./mod.aps.md)
+- **Tags:** one, two, three, four
+`;
+
+      const index = await parseIndex(content);
+      expect(index.modules[0].tags).toEqual(['one', 'two', 'three', 'four']);
+    });
+  });
+});