obsidian-accomplishments-mcp 0.1.10 → 0.1.12

package/dist/services/v2/cycle-detector.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Cycle Detector Service
+ *
+ * Detects cycles in entity dependency graphs using DFS.
+ * Operates in strict mode: rejects entity creation/update if cycle detected.
+ *
+ * Algorithm:
+ * 1. Build dependency graph from entities
+ * 2. Use DFS with coloring (white/gray/black) to detect back edges
+ * 3. If cycle detected, return the cycle path and suggestions for breaking it
+ */
+import { EntityId, Entity } from '../../models/v2-types.js';
+export interface CycleDetectionResult {
+    /** Whether a cycle was detected */
+    hasCycle: boolean;
+    /** The cycle path if detected (e.g., [A, B, C, A]) */
+    cyclePath?: EntityId[];
+    /** Human-readable message describing the cycle */
+    message?: string;
+    /** Suggestions for breaking the cycle */
+    suggestions?: CycleBreakSuggestion[];
+}
+export interface CycleBreakSuggestion {
+    /** The dependency to remove */
+    removeEdge: {
+        from: EntityId;
+        to: EntityId;
+    };
+    /** Priority of this suggestion (lower is better) */
+    priority: number;
+    /** Reason for this suggestion */
+    reason: string;
+}
+/**
+ * Detects cycles in dependency graphs using DFS.
+ */
+export declare class CycleDetector {
+    /**
+     * Check if adding a dependency would create a cycle.
+     *
+     * @param fromId - Entity that would depend on toId
+     * @param toId - Entity that fromId would depend on
+     * @param getDependencies - Function to get dependencies of an entity
+     * @returns CycleDetectionResult with cycle info if detected
+     */
+    wouldCreateCycle(fromId: EntityId, toId: EntityId, getDependencies: (id: EntityId) => EntityId[]): CycleDetectionResult;
+    /**
+     * Detect cycles in the entire dependency graph.
+     *
+     * @param entities - All entities to check
+     * @param getDependencies - Function to get dependencies of an entity
+     * @returns CycleDetectionResult with first cycle found, if any
+     */
+    detectCycles(entities: Entity[], getDependencies: (id: EntityId) => EntityId[]): CycleDetectionResult;
+    /**
+     * DFS to check if target is reachable from current.
+     */
+    private dfsCanReach;
+    /**
+     * DFS to find a cycle starting from the given node.
+     * Uses three-color algorithm (white/gray/black).
+     */
+    private dfsFindCycle;
+    /**
+     * Reconstruct the cycle path from parent pointers.
+     */
+    private reconstructCycle;
+    /**
+     * Generate suggestions for breaking a cycle.
+     * Uses priority rules based on entity types.
+     */
+    private generateBreakSuggestions;
+}
+/** Default detector instance */
+export declare const cycleDetector: CycleDetector;
+//# sourceMappingURL=cycle-detector.d.ts.map

package/dist/services/v2/cycle-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-detector.d.ts","sourceRoot":"","sources":["../../../src/services/v2/cycle-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAmC,MAAM,0BAA0B,CAAC;AAM7F,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,sDAAsD;IACtD,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,UAAU,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,EAAE,EAAE,QAAQ,CAAA;KAAE,CAAC;IAC7C,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAgBD;;GAEG;AACH,qBAAa,aAAa;IACxB;;;;;;;OAOG;IACH,gBAAgB,CACd,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,QAAQ,EACd,eAAe,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,QAAQ,EAAE,GAC5C,oBAAoB;IAqBvB;;;;;;OAMG;IACH,YAAY,CACV,QAAQ,EAAE,MAAM,EAAE,EAClB,eAAe,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,QAAQ,EAAE,GAC5C,oBAAoB;IA2BvB;;OAEG;IACH,OAAO,CAAC,WAAW;IA4BnB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAgCpB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAmBxB;;;OAGG;IACH,OAAO,CAAC,wBAAwB;CAuCjC;AAED,gCAAgC;AAChC,eAAO,MAAM,aAAa,eAAsB,CAAC"}

package/dist/services/v2/cycle-detector.js

@@ -0,0 +1,183 @@
+/**
+ * Cycle Detector Service
+ *
+ * Detects cycles in entity dependency graphs using DFS.
+ * Operates in strict mode: rejects entity creation/update if cycle detected.
+ *
+ * Algorithm:
+ * 1. Build dependency graph from entities
+ * 2. Use DFS with coloring (white/gray/black) to detect back edges
+ * 3. If cycle detected, return the cycle path and suggestions for breaking it
+ */
+import { getEntityTypeFromId } from '../../models/v2-types.js';
+// =============================================================================
+// Node Colors for DFS
+// =============================================================================
+var NodeColor;
+(function (NodeColor) {
+    NodeColor["WHITE"] = "white";
+    NodeColor["GRAY"] = "gray";
+    NodeColor["BLACK"] = "black";
+})(NodeColor || (NodeColor = {}));
+// =============================================================================
+// Cycle Detector
+// =============================================================================
+/**
+ * Detects cycles in dependency graphs using DFS.
+ */
+export class CycleDetector {
+    /**
+     * Check if adding a dependency would create a cycle.
+     *
+     * @param fromId - Entity that would depend on toId
+     * @param toId - Entity that fromId would depend on
+     * @param getDependencies - Function to get dependencies of an entity
+     * @returns CycleDetectionResult with cycle info if detected
+     */
+    wouldCreateCycle(fromId, toId, getDependencies) {
+        // Check if toId can reach fromId (which would create a cycle)
+        const visited = new Set();
+        const path = [];
+        const canReach = this.dfsCanReach(toId, fromId, getDependencies, visited, path);
+        if (canReach) {
+            // Cycle would be: fromId -> toId -> ... -> fromId
+            const cyclePath = [fromId, toId, ...path, fromId];
+            return {
+                hasCycle: true,
+                cyclePath,
+                message: `Adding dependency ${fromId} → ${toId} would create a cycle: ${cyclePath.join(' → ')}`,
+                suggestions: this.generateBreakSuggestions(cyclePath, getDependencies),
+            };
+        }
+        return { hasCycle: false };
+    }
+    /**
+     * Detect cycles in the entire dependency graph.
+     *
+     * @param entities - All entities to check
+     * @param getDependencies - Function to get dependencies of an entity
+     * @returns CycleDetectionResult with first cycle found, if any
+     */
+    detectCycles(entities, getDependencies) {
+        const colors = new Map();
+        const parent = new Map();
+        // Initialize all nodes as white
+        for (const entity of entities) {
+            colors.set(entity.id, NodeColor.WHITE);
+        }
+        // Run DFS from each unvisited node
+        for (const entity of entities) {
+            if (colors.get(entity.id) === NodeColor.WHITE) {
+                const cycle = this.dfsFindCycle(entity.id, getDependencies, colors, parent);
+                if (cycle) {
+                    return {
+                        hasCycle: true,
+                        cyclePath: cycle,
+                        message: `Cycle detected: ${cycle.join(' → ')}`,
+                        suggestions: this.generateBreakSuggestions(cycle, getDependencies),
+                    };
+                }
+            }
+        }
+        return { hasCycle: false };
+    }
+    /**
+     * DFS to check if target is reachable from current.
+     */
+    dfsCanReach(current, target, getDependencies, visited, path) {
+        if (current === target) {
+            return true;
+        }
+        if (visited.has(current)) {
+            return false;
+        }
+        visited.add(current);
+        path.push(current);
+        for (const dep of getDependencies(current)) {
+            if (this.dfsCanReach(dep, target, getDependencies, visited, path)) {
+                return true;
+            }
+        }
+        path.pop();
+        return false;
+    }
+    /**
+     * DFS to find a cycle starting from the given node.
+     * Uses three-color algorithm (white/gray/black).
+     */
+    dfsFindCycle(nodeId, getDependencies, colors, parent) {
+        colors.set(nodeId, NodeColor.GRAY);
+        for (const dep of getDependencies(nodeId)) {
+            // Ensure dep is in the color map
+            if (!colors.has(dep)) {
+                colors.set(dep, NodeColor.WHITE);
+            }
+            if (colors.get(dep) === NodeColor.GRAY) {
+                // Found a back edge - reconstruct cycle
+                return this.reconstructCycle(nodeId, dep, parent);
+            }
+            if (colors.get(dep) === NodeColor.WHITE) {
+                parent.set(dep, nodeId);
+                const cycle = this.dfsFindCycle(dep, getDependencies, colors, parent);
+                if (cycle) {
+                    return cycle;
+                }
+            }
+        }
+        colors.set(nodeId, NodeColor.BLACK);
+        return null;
+    }
+    /**
+     * Reconstruct the cycle path from parent pointers.
+     */
+    reconstructCycle(from, to, parent) {
+        const cycle = [to];
+        let current = from;
+        while (current !== to) {
+            cycle.unshift(current);
+            const p = parent.get(current);
+            if (!p)
+                break;
+            current = p;
+        }
+        cycle.push(to); // Complete the cycle
+        return cycle;
+    }
+    /**
+     * Generate suggestions for breaking a cycle.
+     * Uses priority rules based on entity types.
+     */
+    generateBreakSuggestions(cyclePath, _getDependencies) {
+        const suggestions = [];
+        // Priority order for breaking: task > story > milestone > decision > document
+        const typePriority = {
+            task: 1,
+            story: 2,
+            milestone: 3,
+            decision: 4,
+            document: 5,
+            feature: 6,
+        };
+        // For each edge in the cycle, suggest removing it
+        for (let i = 0; i < cyclePath.length - 1; i++) {
+            const from = cyclePath[i];
+            const to = cyclePath[i + 1];
+            const fromType = getEntityTypeFromId(from);
+            const toType = getEntityTypeFromId(to);
+            // Calculate priority based on types
+            const fromPriority = fromType ? typePriority[fromType] : 10;
+            const toPriority = toType ? typePriority[toType] : 10;
+            suggestions.push({
+                removeEdge: { from, to },
+                priority: fromPriority + toPriority,
+                reason: `Remove dependency from ${from} (${fromType || 'unknown'}) to ${to} (${toType || 'unknown'})`,
+            });
+        }
+        // Sort by priority (lower is better)
+        suggestions.sort((a, b) => a.priority - b.priority);
+        return suggestions;
+    }
+}
+/** Default detector instance */
+export const cycleDetector = new CycleDetector();
+//# sourceMappingURL=cycle-detector.js.map

package/dist/services/v2/cycle-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-detector.js","sourceRoot":"","sources":["../../../src/services/v2/cycle-detector.ts"],"names":[],"mappings":"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"}

package/dist/services/v2/cycle-detector.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tests for Cycle Detector Service
+ *
+ * Tests cycle detection algorithm as specified in MCP_PLUGIN_ALIGNMENT.md Section 9.
+ */
+export {};
+//# sourceMappingURL=cycle-detector.test.d.ts.map

package/dist/services/v2/cycle-detector.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-detector.test.d.ts","sourceRoot":"","sources":["../../../src/services/v2/cycle-detector.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/services/v2/cycle-detector.test.js

@@ -0,0 +1,125 @@
+/**
+ * Tests for Cycle Detector Service
+ *
+ * Tests cycle detection algorithm as specified in MCP_PLUGIN_ALIGNMENT.md Section 9.
+ */
+import { describe, it, expect } from 'vitest';
+import { cycleDetector } from './cycle-detector.js';
+// Helper to create a minimal story entity for testing
+function createStory(id, dependsOn = []) {
+    return {
+        id: id,
+        type: 'story',
+        title: `Story ${id}`,
+        workstream: 'default',
+        status: 'Not Started',
+        priority: 'Medium',
+        depends_on: dependsOn,
+        archived: false,
+        canvas_source: '',
+        vault_path: '',
+        cssclasses: [],
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+    };
+}
+describe('CycleDetector', () => {
+    describe('wouldCreateCycle', () => {
+        it('should detect cycle when adding A→B would create A→B→A', () => {
+            // B already depends on A
+            // Adding A→B would create a cycle
+            const getDependencies = (id) => {
+                if (id === 'S-002')
+                    return ['S-001'];
+                return [];
+            };
+            const result = cycleDetector.wouldCreateCycle('S-001', 'S-002', getDependencies);
+            expect(result.hasCycle).toBe(true);
+            expect(result.cyclePath).toBeDefined();
+            expect(result.cyclePath).toContain('S-001');
+            expect(result.cyclePath).toContain('S-002');
+            expect(result.message).toContain('cycle');
+        });
+        it('should not detect cycle when no cycle would be created', () => {
+            // A→B, B→C (no cycle)
+            const getDependencies = (id) => {
+                if (id === 'S-002')
+                    return ['S-003'];
+                return [];
+            };
+            const result = cycleDetector.wouldCreateCycle('S-001', 'S-002', getDependencies);
+            expect(result.hasCycle).toBe(false);
+            expect(result.cyclePath).toBeUndefined();
+        });
+        it('should detect longer cycles A→B→C→A', () => {
+            // B→C, C→A
+            // Adding A→B would create A→B→C→A
+            const getDependencies = (id) => {
+                if (id === 'S-002')
+                    return ['S-003'];
+                if (id === 'S-003')
+                    return ['S-001'];
+                return [];
+            };
+            const result = cycleDetector.wouldCreateCycle('S-001', 'S-002', getDependencies);
+            expect(result.hasCycle).toBe(true);
+            expect(result.cyclePath.length).toBeGreaterThan(2);
+        });
+        it('should provide suggestions for breaking the cycle', () => {
+            const getDependencies = (id) => {
+                if (id === 'S-002')
+                    return ['S-001'];
+                return [];
+            };
+            const result = cycleDetector.wouldCreateCycle('S-001', 'S-002', getDependencies);
+            expect(result.suggestions).toBeDefined();
+            expect(result.suggestions.length).toBeGreaterThan(0);
+            expect(result.suggestions[0].removeEdge).toBeDefined();
+        });
+    });
+    describe('detectCycles', () => {
+        it('should detect cycle in entity graph', () => {
+            const entities = [
+                createStory('S-001', ['S-002']),
+                createStory('S-002', ['S-003']),
+                createStory('S-003', ['S-001']), // Creates cycle
+            ];
+            const getDependencies = (id) => {
+                const entity = entities.find((e) => e.id === id);
+                return entity?.depends_on || [];
+            };
+            const result = cycleDetector.detectCycles(entities, getDependencies);
+            expect(result.hasCycle).toBe(true);
+            expect(result.cyclePath).toBeDefined();
+        });
+        it('should not detect cycle in DAG (directed acyclic graph)', () => {
+            const entities = [
+                createStory('S-001', ['S-002', 'S-003']),
+                createStory('S-002', ['S-004']),
+                createStory('S-003', ['S-004']),
+                createStory('S-004', []),
+            ];
+            const getDependencies = (id) => {
+                const entity = entities.find((e) => e.id === id);
+                return entity?.depends_on || [];
+            };
+            const result = cycleDetector.detectCycles(entities, getDependencies);
+            expect(result.hasCycle).toBe(false);
+        });
+        it('should handle empty entity list', () => {
+            const result = cycleDetector.detectCycles([], () => []);
+            expect(result.hasCycle).toBe(false);
+        });
+        it('should handle entities with no dependencies', () => {
+            const entities = [
+                createStory('S-001', []),
+                createStory('S-002', []),
+                createStory('S-003', []),
+            ];
+            const getDependencies = (_id) => [];
+            const result = cycleDetector.detectCycles(entities, getDependencies);
+            expect(result.hasCycle).toBe(false);
+        });
+    });
+});
+//# sourceMappingURL=cycle-detector.test.js.map

package/dist/services/v2/cycle-detector.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-detector.test.js","sourceRoot":"","sources":["../../../src/services/v2/cycle-detector.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,sDAAsD;AACtD,SAAS,WAAW,CAAC,EAAU,EAAE,YAAsB,EAAE;IACvD,OAAO;QACL,EAAE,EAAE,EAAa;QACjB,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,SAAS,EAAE,EAAE;QACpB,UAAU,EAAE,SAAS;QACrB,MAAM,EAAE,aAAa;QACrB,QAAQ,EAAE,QAAQ;QAClB,UAAU,EAAE,SAAuB;QACnC,QAAQ,EAAE,KAAK;QACf,aAAa,EAAE,EAAE;QACjB,UAAU,EAAE,EAAE;QACd,UAAU,EAAE,EAAE;QACd,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KAC3B,CAAC;AACd,CAAC;AAED,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;QAChC,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;YAChE,yBAAyB;YACzB,kCAAkC;YAClC,MAAM,eAAe,GAAG,CAAC,EAAY,EAAc,EAAE;gBACnD,IAAI,EAAE,KAAK,OAAO;oBAAE,OAAO,CAAC,OAAmB,CAAC,CAAC;gBACjD,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YAEF,MAAM,MAAM,GAAG,aAAa,CAAC,gBAAgB,CAC3C,OAAmB,EACnB,OAAmB,EACnB,eAAe,CAChB,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;YACvC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAC5C,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAC5C,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;YAChE,sBAAsB;YACtB,MAAM,eAAe,GAAG,CAAC,EAAY,EAAc,EAAE;gBACnD,IAAI,EAAE,KAAK,OAAO;oBAAE,OAAO,CAAC,OAAmB,CAAC,CAAC;gBACjD,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YAEF,MAAM,MAAM,GAAG,aAAa,CAAC,gBAAgB,CAC3C,OAAmB,EACnB,OAAmB,EACnB,eAAe,CAChB,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,aAAa,EAAE,CAAC;QAC3C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;YAC7C,WAAW;YACX,kCAAkC;YAClC,MAAM,eAAe,GAAG,CAAC,EAAY,EAAc,EAAE;gBACnD,IAAI,EAAE,KAAK,OAAO;oBAAE,OAAO,CAAC,OAAmB,CAAC,CAAC;gBACjD,IAAI,EAAE,KAAK,OAAO;oBAAE,OAAO,CAAC,OAAmB,CAAC,CAAC;gBACjD,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YAEF,MAAM,MAAM,GAAG,aAAa,CAAC,gBAAgB,CAC3C,OAAmB,EACnB,OAAmB,EACnB,eAAe,CAChB,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,SAAU,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QACtD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;YAC3D,MAAM,eAAe,GAAG,CAAC,EAAY,EAAc,EAAE;gBACnD,IAAI,EAAE,KAAK,OAAO;oBAAE,OAAO,CAAC,OAAmB,CAAC,CAAC;gBACjD,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YAEF,MAAM,MAAM,GAAG,aAAa,CAAC,gBAAgB,CAC3C,OAAmB,EACnB,OAAmB,EACnB,eAAe,CAChB,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,WAAW,EAAE,CAAC;YACzC,MAAM,CAAC,MAAM,CAAC,WAAY,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;YACtD,MAAM,CAAC,MAAM,CAAC,WAAY,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;QAC1D,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;QAC5B,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;YAC7C,MAAM,QAAQ,GAAG;gBACf,WAAW,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;gBAC/B,WAAW,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;gBAC/B,WAAW,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,gBAAgB;aAClD,CAAC;YAEF,MAAM,eAAe,GAAG,CAAC,EAAY,EAAc,EAAE;gBACnD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;gBACjD,OAAQ,MAAc,EAAE,UAAU,IAAI,EAAE,CAAC;YAC3C,CAAC,CAAC;YAEF,MAAM,MAAM,GAAG,aAAa,CAAC,YAAY,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;YAErE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;QACzC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;YACjE,MAAM,QAAQ,GAAG;gBACf,WAAW,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACxC,WAAW,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;gBAC/B,WAAW,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;gBAC/B,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC;aACzB,CAAC;YAEF,MAAM,eAAe,GAAG,CAAC,EAAY,EAAc,EAAE;gBACnD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;gBACjD,OAAQ,MAAc,EAAE,UAAU,IAAI,EAAE,CAAC;YAC3C,CAAC,CAAC;YAEF,MAAM,MAAM,GAAG,aAAa,CAAC,YAAY,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;YAErE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;YACzC,MAAM,MAAM,GAAG,aAAa,CAAC,YAAY,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAExD,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;YACrD,MAAM,QAAQ,GAAG;gBACf,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC;gBACxB,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC;gBACxB,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC;aACzB,CAAC;YAEF,MAAM,eAAe,GAAG,CAAC,GAAa,EAAc,EAAE,CAAC,EAAE,CAAC;YAE1D,MAAM,MAAM,GAAG,aAAa,CAAC,YAAY,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;YAErE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/services/v2/entity-parser.d.ts

@@ -0,0 +1,54 @@
+/**
+ * V2 Entity Parser
+ *
+ * Parses markdown files into Entity objects.
+ */
+import { Entity, VaultPath } from '../../models/v2-types.js';
+export interface ParseResult<T extends Entity = Entity> {
+    entity: T;
+    frontmatter: Record<string, any>;
+    content: string;
+    errors: string[];
+}
+export interface FrontmatterData {
+    [key: string]: any;
+}
+/**
+ * Parses markdown files with YAML frontmatter into Entity objects.
+ */
+export declare class EntityParser {
+    /** Parse markdown content into an Entity */
+    parse(content: string, filePath: VaultPath): ParseResult;
+    /** Extract YAML frontmatter from markdown content */
+    private extractFrontmatter;
+    /** Parse a YAML value */
+    private parseValue;
+    /** Parse an inline YAML array like [M-001, M-002] */
+    private parseInlineArray;
+    /** Extract valid entity IDs from an array of strings */
+    private extractValidEntityIds;
+    /** Extract entity ID from frontmatter (ID is required in frontmatter) */
+    private extractId;
+    private parseMilestone;
+    private parseStory;
+    private parseTask;
+    private parseDecision;
+    private parseDocument;
+    private parseFeature;
+    private validateStatus;
+    private validatePriority;
+    private validateTier;
+    private validatePhase;
+    private extractTitleFromBody;
+    /**
+     * Extract content from a markdown section (## SectionName).
+     * Returns the content between this section header and the next section header (or end of file).
+     */
+    private extractSection;
+    /**
+     * Extract body content before any section headers.
+     * Used for milestone objective which is written directly to body without a section header.
+     */
+    private extractBodyContent;
+}
+//# sourceMappingURL=entity-parser.d.ts.map

package/dist/services/v2/entity-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-parser.d.ts","sourceRoot":"","sources":["../../../src/services/v2/entity-parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,MAAM,EAiBN,SAAS,EAGV,MAAM,0BAA0B,CAAC;AAMlC,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACpD,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAMD;;GAEG;AACH,qBAAa,YAAY;IAKvB,4CAA4C;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,GAAG,WAAW;IAkDxD,qDAAqD;IACrD,OAAO,CAAC,kBAAkB;IA0D1B,yBAAyB;IACzB,OAAO,CAAC,UAAU;IA4BlB,qDAAqD;IACrD,OAAO,CAAC,gBAAgB;IAqBxB,wDAAwD;IACxD,OAAO,CAAC,qBAAqB;IA0B7B,yEAAyE;IACzE,OAAO,CAAC,SAAS;IAYjB,OAAO,CAAC,cAAc;IAkCtB,OAAO,CAAC,UAAU;IAqClB,OAAO,CAAC,SAAS;IAoCjB,OAAO,CAAC,aAAa;IAyCrB,OAAO,CAAC,aAAa;IA8BrB,OAAO,CAAC,YAAY;IAkCpB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,oBAAoB;IAK5B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CAc3B"}