@eddacraft/anvil-adapters 0.1.0

package/dist/speckit/parsers/spec-parser.js

@@ -0,0 +1,255 @@
+/**
+ * Parser for official GitHub Spec-Kit spec.md format
+ *
+ * Spec.md focuses on WHAT and WHY (not HOW):
+ * - Feature metadata
+ * - User Scenarios & Testing (prioritized user stories)
+ * - Requirements (functional requirements, key entities)
+ * - Success Criteria (measurable outcomes)
+ */
+export class SpecParser {
+    parseSpec(content) {
+        const result = {
+            metadata: {},
+            userScenarios: [],
+            requirements: {
+                functional: [],
+                entities: [],
+            },
+            successCriteria: {
+                quantitative: [],
+                qualitative: [],
+            },
+            clarifications: [],
+        };
+        // Extract metadata from first section (before ## headers)
+        result.metadata = this.extractMetadata(content);
+        // Parse user scenarios section
+        result.userScenarios = this.parseUserScenarios(content);
+        // Parse requirements section
+        result.requirements = this.parseRequirements(content);
+        // Parse success criteria
+        result.successCriteria = this.parseSuccessCriteria(content);
+        // Extract all clarifications
+        result.clarifications = this.extractClarifications(content);
+        return result;
+    }
+    extractMetadata(content) {
+        const metadata = {};
+        // Extract title (# Feature: ...)
+        const titleMatch = content.match(/^#\s+Feature:\s+(.+)$/m);
+        if (titleMatch) {
+            metadata.feature = titleMatch[1].trim();
+        }
+        // Extract bold key-value pairs (** Key **: value)
+        // Stop at next ** or newline to handle multiple metadata on same line
+        const metadataRegex = /\*\*([^*]+)\*\*:\s*`?([^`*\n]+?)`?\s*(?=\*\*|\n|$)/g;
+        let match;
+        while ((match = metadataRegex.exec(content)) !== null) {
+            const key = match[1].trim().toLowerCase().replace(/\s+/g, '_');
+            const value = match[2].trim();
+            metadata[key] = value;
+        }
+        return metadata;
+    }
+    parseUserScenarios(content) {
+        const scenarios = [];
+        // Find "User Scenarios & Testing" section
+        const scenarioSectionMatch = content.match(/##\s+User Scenarios?\s*(?:&|and)?\s*Testing([\s\S]*?)(?=\n##\s|\n#\s|$)/i);
+        if (!scenarioSectionMatch) {
+            return scenarios;
+        }
+        const scenarioSection = scenarioSectionMatch[1];
+        // Split by ### headers (each scenario)
+        const scenarioBlocks = scenarioSection.split(/###\s+/).slice(1);
+        for (const block of scenarioBlocks) {
+            const scenario = this.parseUserScenario(block);
+            if (scenario) {
+                scenarios.push(scenario);
+            }
+        }
+        return scenarios;
+    }
+    parseUserScenario(block) {
+        // Extract priority and title from first line (P1: Title)
+        const titleMatch = block.match(/^(P\d+):\s+(.+)$/m);
+        if (!titleMatch) {
+            return null;
+        }
+        const priority = titleMatch[1];
+        const title = titleMatch[2].trim();
+        // Extract user story components (handle multiline with line breaks)
+        const asAMatch = block.match(/\*\*As a\*\*\s+(.+?)(?=\s*\*\*|\n\n|$)/is);
+        const iWantToMatch = block.match(/\*\*I want(?:\s+to)?\*\*\s+(.+?)(?=\s*\*\*|\n\n|$)/is);
+        const soThatMatch = block.match(/\*\*So(?:\s+|\n)that\*\*\s+(.+?)(?=\s*\n\n|$)/is);
+        // Extract acceptance scenarios
+        const acceptanceScenarios = [];
+        const acceptanceMatch = block.match(/\*\*Acceptance Scenarios:\*\*([\s\S]*?)(?=\*\*Edge Cases:|\*\*\[NEEDS|###|$)/i);
+        if (acceptanceMatch) {
+            const scenarios = acceptanceMatch[1]
+                .split(/\n[-*]\s+/)
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            acceptanceScenarios.push(...scenarios);
+        }
+        // Extract edge cases
+        const edgeCases = [];
+        const edgeCaseMatch = block.match(/\*\*Edge Cases:\*\*([\s\S]*?)(?=###|$)/i);
+        if (edgeCaseMatch) {
+            const cases = edgeCaseMatch[1]
+                .split(/\n[-*]\s+/)
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            edgeCases.push(...cases);
+        }
+        return {
+            priority,
+            title,
+            asA: asAMatch?.[1]?.trim() || '',
+            iWantTo: iWantToMatch?.[1]?.trim() || '',
+            soThat: soThatMatch?.[1]?.trim() || '',
+            acceptanceScenarios,
+            edgeCases,
+        };
+    }
+    parseRequirements(content) {
+        const requirements = {
+            functional: [],
+            entities: [],
+        };
+        // Find "Requirements" section
+        const reqSectionMatch = content.match(/##\s+Requirements([\s\S]*?)(?=\n##\s|\n#\s|$)/i);
+        if (!reqSectionMatch) {
+            return requirements;
+        }
+        const reqSection = reqSectionMatch[1];
+        // Parse functional requirements
+        requirements.functional = this.parseFunctionalRequirements(reqSection);
+        // Parse entity definitions
+        requirements.entities = this.parseEntities(reqSection);
+        return requirements;
+    }
+    parseFunctionalRequirements(section) {
+        const requirements = [];
+        // Find "Functional Requirements" subsection
+        const functionalMatch = section.match(/###\s+Functional Requirements([\s\S]*?)(?=\n###|$)/i);
+        if (!functionalMatch) {
+            return requirements;
+        }
+        const functionalSection = functionalMatch[1];
+        // Match FR-XXX: Description or [NEEDS CLARIFICATION: question]
+        const reqRegex = /\*\*(FR-\d+)\*\*:\s+(.+?)(?=\n\*\*FR-|\n###|$)/gs;
+        let match;
+        while ((match = reqRegex.exec(functionalSection)) !== null) {
+            const code = match[1];
+            const description = match[2].trim();
+            // Check if this is a clarification request
+            const clarificationMatch = description.match(/\[NEEDS CLARIFICATION:\s*(.+?)\]/);
+            requirements.push({
+                code,
+                description: clarificationMatch ? description : description,
+                needsClarification: !!clarificationMatch,
+                clarificationQuestion: clarificationMatch?.[1]?.trim(),
+            });
+        }
+        return requirements;
+    }
+    parseEntities(section) {
+        const entities = [];
+        // Find "Key Entities" subsection
+        const entitiesMatch = section.match(/###\s+Key Entities([\s\S]*?)(?=\n##|$)/i);
+        if (!entitiesMatch) {
+            return entities;
+        }
+        const entitiesSection = entitiesMatch[1];
+        // Split by ** EntityName **
+        const entityBlocks = entitiesSection.split(/\*\*([^*]+)\*\*/g).slice(1);
+        for (let i = 0; i < entityBlocks.length; i += 2) {
+            const entityName = entityBlocks[i].trim();
+            const entityContent = entityBlocks[i + 1] || '';
+            if (!entityName || !entityContent.trim()) {
+                continue;
+            }
+            const entity = this.parseEntity(entityName, entityContent);
+            if (entity) {
+                entities.push(entity);
+            }
+        }
+        return entities;
+    }
+    parseEntity(name, content) {
+        const representsMatch = content.match(/[-*]\s+Represents:\s+(.+)/i);
+        const attributesMatch = content.match(/[-*]\s+Key Attributes:\s+(.+)/i);
+        const relationshipsMatch = content.match(/[-*]\s+Relationships:\s+(.+)/i);
+        return {
+            name,
+            represents: representsMatch?.[1]?.trim() || '',
+            keyAttributes: attributesMatch?.[1]
+                ?.split(',')
+                .map((a) => a.trim())
+                .filter((a) => a.length > 0) || [],
+            relationships: relationshipsMatch?.[1]
+                ?.split(',')
+                .map((r) => r.trim())
+                .filter((r) => r.length > 0) || [],
+        };
+    }
+    parseSuccessCriteria(content) {
+        const criteria = {
+            quantitative: [],
+            qualitative: [],
+        };
+        // Find "Success Criteria" section
+        const criteriaSectionMatch = content.match(/##\s+Success Criteria([\s\S]*?)(?=\n##\s|\n#\s|$)/i);
+        if (!criteriaSectionMatch) {
+            return criteria;
+        }
+        const criteriaSection = criteriaSectionMatch[1];
+        // Parse quantitative metrics
+        const quantMatch = criteriaSection.match(/###\s+Quantitative Metrics([\s\S]*?)(?=\n###|$)/i);
+        if (quantMatch) {
+            const metrics = quantMatch[1]
+                .split(/\n[-*]\s+/)
+                .map((m) => m.trim())
+                .filter((m) => m.length > 0);
+            criteria.quantitative = metrics;
+        }
+        // Parse qualitative metrics
+        const qualMatch = criteriaSection.match(/###\s+Qualitative Metrics([\s\S]*?)(?=\n###|$)/i);
+        if (qualMatch) {
+            const metrics = qualMatch[1]
+                .split(/\n[-*]\s+/)
+                .map((m) => m.trim())
+                .filter((m) => m.length > 0);
+            criteria.qualitative = metrics;
+        }
+        // Parse security metrics (if present)
+        const securityMatch = criteriaSection.match(/###\s+Security Metrics([\s\S]*?)(?=\n###|$)/i);
+        if (securityMatch) {
+            const metrics = securityMatch[1]
+                .split(/\n[-*]\s+/)
+                .map((m) => m.trim())
+                .filter((m) => m.length > 0);
+            criteria.security = metrics;
+        }
+        // Parse performance metrics (if present)
+        const perfMatch = criteriaSection.match(/###\s+Performance Metrics([\s\S]*?)(?=\n###|$)/i);
+        if (perfMatch) {
+            const metrics = perfMatch[1]
+                .split(/\n[-*]\s+/)
+                .map((m) => m.trim())
+                .filter((m) => m.length > 0);
+            criteria.performance = metrics;
+        }
+        return criteria;
+    }
+    extractClarifications(content) {
+        const clarifications = [];
+        const clarificationRegex = /\[NEEDS CLARIFICATION:\s*([^\]]+)\]/g;
+        let match;
+        while ((match = clarificationRegex.exec(content)) !== null) {
+            clarifications.push(match[1].trim());
+        }
+        return clarifications;
+    }
+}

package/dist/speckit/parsers/tasks-parser.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Parser for official GitHub Spec-Kit tasks.md format
+ *
+ * Tasks.md breaks down work into executable tasks:
+ * - Tasks organized by phases
+ * - Task IDs for tracking
+ * - Parallel execution markers
+ * - Dependencies and execution order
+ * - Implementation strategies
+ */
+interface TasksMetadata {
+    feature?: string;
+    branch?: string;
+    date?: string;
+    spec?: string;
+    plan?: string;
+    [key: string]: unknown;
+}
+interface Task {
+    id: string;
+    parallel: boolean;
+    userStory?: string;
+    description: string;
+}
+interface Phase {
+    name: string;
+    order: number;
+    tasks: Task[];
+    checkpoint?: string;
+}
+interface Dependency {
+    description: string;
+    requiredBefore?: string[];
+    canRunInParallel?: boolean;
+}
+interface ImplementationStrategy {
+    name: string;
+    description: string;
+    recommended?: boolean;
+}
+export interface ParsedTasks {
+    metadata: TasksMetadata;
+    phases: Phase[];
+    dependencies: Dependency[];
+    strategies: ImplementationStrategy[];
+}
+export declare class TasksParser {
+    parseTasks(content: string): ParsedTasks;
+    private extractMetadata;
+    private parsePhases;
+    private parseTaskItems;
+    private extractCheckpoint;
+    private parseDependencies;
+    private parseStrategies;
+}
+export {};
+//# sourceMappingURL=tasks-parser.d.ts.map

package/dist/speckit/parsers/tasks-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks-parser.d.ts","sourceRoot":"","sources":["../../../src/speckit/parsers/tasks-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,UAAU,aAAa;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,UAAU,IAAI;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,UAAU;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,UAAU,EAAE,sBAAsB,EAAE,CAAC;CACtC;AAED,qBAAa,WAAW;IACtB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW;IAuBxC,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,cAAc;IA8BtB,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,iBAAiB;IAyCzB,OAAO,CAAC,eAAe;CA4CxB"}

package/dist/speckit/parsers/tasks-parser.js

@@ -0,0 +1,157 @@
+/**
+ * Parser for official GitHub Spec-Kit tasks.md format
+ *
+ * Tasks.md breaks down work into executable tasks:
+ * - Tasks organized by phases
+ * - Task IDs for tracking
+ * - Parallel execution markers
+ * - Dependencies and execution order
+ * - Implementation strategies
+ */
+export class TasksParser {
+    parseTasks(content) {
+        const result = {
+            metadata: {},
+            phases: [],
+            dependencies: [],
+            strategies: [],
+        };
+        // Extract metadata
+        result.metadata = this.extractMetadata(content);
+        // Parse phases and tasks
+        result.phases = this.parsePhases(content);
+        // Parse dependencies section
+        result.dependencies = this.parseDependencies(content);
+        // Parse implementation strategies
+        result.strategies = this.parseStrategies(content);
+        return result;
+    }
+    extractMetadata(content) {
+        const metadata = {};
+        // Extract title (# Tasks: ...)
+        const titleMatch = content.match(/^#\s+Tasks:\s+(.+)$/m);
+        if (titleMatch) {
+            metadata.feature = titleMatch[1].trim();
+        }
+        // Extract bold key-value pairs with links
+        const metadataRegex = /\*\*([^*]+)\*\*:\s*(?:`([^`\n]+)`|\[([^\]]+)\]\(([^)]+)\)|([^\n|]+))/g;
+        let match;
+        while ((match = metadataRegex.exec(content)) !== null) {
+            const key = match[1].trim().toLowerCase().replace(/\s+/g, '_');
+            const value = match[2] || match[3] || match[5] || '';
+            metadata[key] = value.trim();
+        }
+        return metadata;
+    }
+    parsePhases(content) {
+        const phases = [];
+        // Match ## Phase N: Name sections
+        const phaseRegex = /##\s+Phase\s+(\d+):\s+([^\n]+)([\s\S]*?)(?=\n##\s+(?:Phase|Dependencies)|$)/gi;
+        let match;
+        while ((match = phaseRegex.exec(content)) !== null) {
+            const order = parseInt(match[1], 10);
+            const name = match[2].trim();
+            const phaseContent = match[3];
+            const tasks = this.parseTaskItems(phaseContent);
+            const checkpoint = this.extractCheckpoint(phaseContent);
+            phases.push({
+                name,
+                order,
+                tasks,
+                checkpoint,
+            });
+        }
+        return phases;
+    }
+    parseTaskItems(content) {
+        const tasks = [];
+        // Match task lines: - [ID] [P?] [Story?] Description
+        // Format: - [001] Description
+        //     or: - [001] [P] Description
+        //     or: - [001] [P] [Story] Description
+        const taskRegex = /[-*]\s+\[(\d+)\](?:\s+\[P\])?(?:\s+\[([^\]]+)\])?\s+(.+)/g;
+        let match;
+        while ((match = taskRegex.exec(content)) !== null) {
+            const id = match[1];
+            const userStory = match[2]?.trim();
+            const description = match[3].trim();
+            // Check if [P] marker exists (for parallel execution)
+            const lineMatch = content.match(new RegExp(`\\[${id}\\]\\s+\\[P\\]`, 'i'));
+            const parallel = !!lineMatch;
+            tasks.push({
+                id,
+                parallel,
+                userStory,
+                description,
+            });
+        }
+        return tasks;
+    }
+    extractCheckpoint(content) {
+        const checkpointMatch = content.match(/\*\*Checkpoint\*\*:\s+(.+)/i);
+        return checkpointMatch?.[1]?.trim();
+    }
+    parseDependencies(content) {
+        const dependencies = [];
+        // Find "Dependencies & Execution Order" section
+        const depsMatch = content.match(/##\s+Dependencies\s*(?:&|and)?\s*Execution Order([\s\S]*?)(?=\n##\s|$)/i);
+        if (!depsMatch) {
+            return dependencies;
+        }
+        const depsSection = depsMatch[1];
+        // Parse subsections (### Required Sequential Order, ### Parallel Work Opportunities)
+        const subsections = depsSection.split(/###\s+/).slice(1);
+        for (const subsection of subsections) {
+            const lines = subsection.split('\n');
+            const title = lines[0].trim();
+            const items = [];
+            for (const line of lines.slice(1)) {
+                const itemMatch = line.match(/^[-*]\s+(.+)/);
+                if (itemMatch) {
+                    items.push(itemMatch[1].trim());
+                }
+            }
+            if (items.length > 0) {
+                dependencies.push({
+                    description: title,
+                    requiredBefore: title.toLowerCase().includes('sequential') ? items : undefined,
+                    canRunInParallel: title.toLowerCase().includes('parallel'),
+                });
+            }
+        }
+        return dependencies;
+    }
+    parseStrategies(content) {
+        const strategies = [];
+        // Find "Implementation Strategies" section
+        const strategiesMatch = content.match(/##\s+Implementation Strategies([\s\S]*?)$/i);
+        if (!strategiesMatch) {
+            return strategies;
+        }
+        const strategiesSection = strategiesMatch[1];
+        // Parse ### Strategy N: Name
+        const strategyRegex = /###\s+Strategy\s+\d+:\s+([^\n]+)([\s\S]*?)(?=\n###|$)/gi;
+        let match;
+        while ((match = strategyRegex.exec(strategiesSection)) !== null) {
+            const name = match[1].trim();
+            const description = match[2].trim();
+            // Check if recommended
+            const recommended = strategiesSection.toLowerCase().includes(`recommended`);
+            strategies.push({
+                name,
+                description,
+                recommended: recommended && match[0].toLowerCase().includes('recommended'),
+            });
+        }
+        // Extract recommended strategy
+        const recommendedMatch = strategiesSection.match(/\*\*Recommended\*\*:\s+([^.]+)/i);
+        if (recommendedMatch) {
+            const recommendedName = recommendedMatch[1].trim();
+            const strategy = strategies.find((s) => recommendedName.toLowerCase().includes(s.name.toLowerCase()));
+            if (strategy) {
+                strategy.recommended = true;
+            }
+        }
+        return strategies;
+    }
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@eddacraft/anvil-adapters",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "@eddacraft/anvil-aps": "0.1.0",
+    "@eddacraft/anvil-core": "0.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/project.json

@@ -0,0 +1,29 @@
+{
+  "name": "@eddacraft/anvil-adapters",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/adapters/src",
+  "projectType": "library",
+  "release": {
+    "version": {
+      "manifestRootsToUpdate": ["{projectRoot}/dist"],
+      "currentVersionResolver": "git-tag",
+      "fallbackCurrentVersionResolver": "disk"
+    }
+  },
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "nx:run-script",
+      "outputs": ["{projectRoot}/dist"],
+      "options": {
+        "script": "build"
+      },
+      "dependsOn": ["^build"]
+    },
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "{projectRoot}/dist"
+      }
+    }
+  }
+}