@eddacraft/anvil-aps 0.1.0

package/dist/parser/parse-document.js

@@ -0,0 +1,219 @@
+/**
+ * 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 { parseTask } from './parse-task.js';
+import { ParseError } 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, sourcePath) {
+    // Parse Markdown to AST
+    const processor = unified().use(remarkParse);
+    const ast = processor.parse(content);
+    // 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,
+    };
+}
+function extractStructure(ast, sourcePath) {
+    const structure = {
+        title: null,
+        tasks: [],
+    };
+    let currentSection = 'root';
+    let currentTaskHeading = null;
+    let currentTaskContent = [];
+    visit(ast, (node, index, parent) => {
+        if (node.type === 'heading') {
+            const heading = node;
+            // 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.children[index + 1];
+                    if (nextSibling && nextSibling.type === 'paragraph') {
+                        structure.metadata = parseMetadataLine(nextSibling);
+                    }
+                }
+            }
+            // 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);
+        }
+    });
+    // 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, taskContent, sourcePath, structure) {
+    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) {
+    let text = '';
+    visit(node, 'text', (textNode) => {
+        text += textNode.value;
+    });
+    return text;
+}
+/**
+ * Parse module metadata line (immediately after H1)
+ * Format: **Scope:** AUTH **Owner:** @alice **Priority:** high
+ */
+function parseMetadataLine(para) {
+    const metadata = {};
+    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, 'text', (textNode) => {
+                strongText += textNode.value;
+            });
+            const match = strongText.match(/^(\w+):$/);
+            if (match) {
+                currentKey = match[1];
+                currentValue = '';
+            }
+        }
+        else if (child.type === 'text' && currentKey) {
+            currentValue += child.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, key, value) {
+    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 = {
+                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/dist/parser/parse-index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Index file parsing utilities
+ * Parses APS index files that organise multiple leaf specs
+ */
+import { type ModuleMetadata } from '../types/index.js';
+/**
+ * Parsed index file result
+ */
+export interface ParsedIndex {
+    /** Plan title from H1 */
+    title: string;
+    /** Overview text (optional) */
+    overview?: string;
+    /** Module definitions */
+    modules: ModuleMetadata[];
+    /** Open questions (optional) */
+    openQuestions?: string[];
+    /** Decisions with dates (optional) */
+    decisions?: string[];
+    /** Source file path */
+    sourcePath?: string;
+}
+/**
+ * Parse an APS index file from Markdown content
+ *
+ * @param content - Markdown content
+ * @param sourcePath - Optional source file path for error reporting
+ * @returns Parsed index with modules
+ */
+export declare function parseIndex(content: string, sourcePath?: string): Promise<ParsedIndex>;
+//# sourceMappingURL=parse-index.d.ts.map

package/dist/parser/parse-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-index.d.ts","sourceRoot":"","sources":["../../src/parser/parse-index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAAc,KAAK,cAAc,EAAiB,MAAM,mBAAmB,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IAEd,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,yBAAyB;IACzB,OAAO,EAAE,cAAc,EAAE,CAAC;IAE1B,gCAAgC;IAChC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAErB,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA0F3F"}

package/dist/parser/parse-index.js

@@ -0,0 +1,251 @@
+/**
+ * Index file parsing utilities
+ * Parses APS index files that organise multiple leaf specs
+ */
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import { visit } from 'unist-util-visit';
+import { ParseError } from '../types/index.js';
+/**
+ * Parse an APS index file from Markdown content
+ *
+ * @param content - Markdown content
+ * @param sourcePath - Optional source file path for error reporting
+ * @returns Parsed index with modules
+ */
+export async function parseIndex(content, sourcePath) {
+    const processor = unified().use(remarkParse);
+    const ast = processor.parse(content);
+    const result = {
+        title: '',
+        modules: [],
+        sourcePath,
+    };
+    let currentSection = 'root';
+    let currentModuleId = null;
+    let currentModuleContent = [];
+    visit(ast, (node) => {
+        // H1: Plan title
+        if (node.type === 'heading' && node.depth === 1) {
+            result.title = extractPlainText(node);
+        }
+        // H2: Section headers
+        if (node.type === 'heading' && node.depth === 2) {
+            // Save previous module if any
+            if (currentModuleId && currentModuleContent.length > 0) {
+                const moduleMetadata = parseModuleMetadata(currentModuleId, currentModuleContent);
+                result.modules.push(moduleMetadata);
+                currentModuleId = null;
+                currentModuleContent = [];
+            }
+            const sectionTitle = extractPlainText(node).toLowerCase();
+            if (sectionTitle === 'overview') {
+                currentSection = 'overview';
+            }
+            else if (sectionTitle === 'modules') {
+                currentSection = 'modules';
+            }
+            else if (sectionTitle === 'open questions') {
+                currentSection = 'questions';
+            }
+            else if (sectionTitle === 'decisions') {
+                currentSection = 'decisions';
+            }
+            else {
+                currentSection = 'root';
+            }
+        }
+        // H3: Module headings (within Modules section)
+        if (node.type === 'heading' && node.depth === 3 && currentSection === 'modules') {
+            // Save previous module if any
+            if (currentModuleId && currentModuleContent.length > 0) {
+                const moduleMetadata = parseModuleMetadata(currentModuleId, currentModuleContent);
+                result.modules.push(moduleMetadata);
+            }
+            currentModuleId = extractPlainText(node);
+            currentModuleContent = [];
+        }
+        // Collect lists for current module
+        if (node.type === 'list' && currentSection === 'modules' && currentModuleId) {
+            currentModuleContent.push(node);
+        }
+        // Collect overview paragraph
+        if (node.type === 'paragraph' && currentSection === 'overview') {
+            result.overview = extractPlainText(node);
+        }
+        // Collect open questions from list
+        if (node.type === 'list' && currentSection === 'questions') {
+            result.openQuestions = extractListItemsAsStrings(node);
+        }
+        // Collect decisions from list
+        if (node.type === 'list' && currentSection === 'decisions') {
+            result.decisions = extractListItemsAsStrings(node);
+        }
+    });
+    // Save last module if any
+    if (currentModuleId && currentModuleContent.length > 0) {
+        const moduleMetadata = parseModuleMetadata(currentModuleId, currentModuleContent);
+        result.modules.push(moduleMetadata);
+    }
+    // Validate
+    if (!result.title) {
+        throw new ParseError('Index file must have an H1 title', sourcePath);
+    }
+    return result;
+}
+/**
+ * Parse module metadata from list items
+ * Format: - **Field:** value
+ */
+function parseModuleMetadata(moduleId, lists) {
+    const metadata = {
+        id: moduleId,
+    };
+    for (const list of lists) {
+        for (const item of list.children) {
+            if (item.type !== 'listItem')
+                continue;
+            const { key, value } = extractFieldFromListItem(item);
+            if (!key)
+                continue;
+            switch (key) {
+                case 'Path':
+                    metadata.path = value;
+                    break;
+                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 - legacy values mapped to canonical equivalents
+                    const statusMap = {
+                        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 = parseCommaSeparated(value);
+                    break;
+                case 'Dependencies':
+                    if (value.toLowerCase() === '(none)' || value === '') {
+                        metadata.dependencies = [];
+                    }
+                    else {
+                        metadata.dependencies = parseCommaSeparated(value);
+                    }
+                    break;
+                case 'Packages':
+                    // Monorepo support: list of affected packages
+                    if (value.toLowerCase() === '(none)' || value === '') {
+                        metadata.packages = [];
+                    }
+                    else {
+                        metadata.packages = parseCommaSeparated(value);
+                    }
+                    break;
+            }
+        }
+    }
+    return metadata;
+}
+/**
+ * Extract field key and value from a list item
+ * Format: **Key:** value or **Key:** [link](url)
+ */
+function extractFieldFromListItem(item) {
+    let key = '';
+    let value = '';
+    for (const child of item.children) {
+        if (child.type !== 'paragraph')
+            continue;
+        const para = child;
+        let foundKey = false;
+        for (const node of para.children) {
+            if (node.type === 'strong') {
+                const strongText = extractPlainTextFromNode(node);
+                const match = strongText.match(/^(\w+):$/);
+                if (match) {
+                    key = match[1];
+                    foundKey = true;
+                }
+            }
+            else if (foundKey) {
+                if (node.type === 'text') {
+                    value += node.value;
+                }
+                else if (node.type === 'link') {
+                    // For Path field, extract the URL from the link
+                    const link = node;
+                    value += link.url;
+                }
+            }
+        }
+    }
+    return { key, value: value.trim() };
+}
+/**
+ * Extract plain text from a heading or paragraph
+ */
+function extractPlainText(node) {
+    let text = '';
+    visit(node, 'text', (textNode) => {
+        text += textNode.value;
+    });
+    return text;
+}
+/**
+ * Extract plain text from any node
+ */
+function extractPlainTextFromNode(node) {
+    let text = '';
+    visit(node, 'text', (textNode) => {
+        text += textNode.value;
+    });
+    return text;
+}
+/**
+ * Extract list items as strings
+ */
+function extractListItemsAsStrings(list) {
+    const items = [];
+    for (const item of list.children) {
+        if (item.type !== 'listItem')
+            continue;
+        let text = '';
+        visit(item, 'text', (textNode) => {
+            text += textNode.value;
+        });
+        if (text.trim()) {
+            items.push(text.trim());
+        }
+    }
+    return items;
+}
+/**
+ * Parse comma-separated list
+ */
+function parseCommaSeparated(value) {
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}

package/dist/parser/parse-task.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Task parsing utilities
+ * Extracts task information from Markdown AST nodes
+ */
+import type { Heading, Paragraph, List } from 'mdast';
+import { type Task } from '../types/index.js';
+/**
+ * Extract task ID and title from H3 heading text
+ * Format: "SCOPE-NUMBER: Task title"
+ * - Scope: 1-10 uppercase alphanumeric characters
+ * - Number: 3-digit zero-padded (001-999)
+ */
+export declare function parseTaskHeading(heading: Heading): {
+    id: string;
+    title: string;
+};
+/**
+ * Parse task fields from paragraph and list nodes
+ * Fields are in format: **FieldName:** value
+ */
+export declare function parseTaskFields(paragraphs: Paragraph[], lists: List[]): Partial<Task>;
+/**
+ * Parse a complete task from AST nodes
+ * @param heading - H3 heading node with task ID and title
+ * @param content - Array of paragraph and list nodes containing task fields
+ * @param sourcePath - Optional source file path
+ * @param lineNumber - Optional line number where task starts
+ */
+export declare function parseTask(heading: Heading, content: Array<Paragraph | List>, sourcePath?: string, lineNumber?: number): Task;
+//# sourceMappingURL=parse-task.d.ts.map

package/dist/parser/parse-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-task.d.ts","sourceRoot":"","sources":["../../src/parser/parse-task.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAU,IAAI,EAAmB,MAAM,OAAO,CAAC;AAC/E,OAAO,EAAc,KAAK,IAAI,EAAoC,MAAM,mBAAmB,CAAC;AAE5F;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA2BhF;AAiBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCrF;AA+KD;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,EAChC,UAAU,CAAC,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,IAAI,CAqCN"}