@zhuan-ai/zhuanspec 1.3.0 → 2.1.0

package/dist/core/task-graph/mermaid-renderer.js

@@ -0,0 +1,128 @@
+/**
+ * Mermaid Renderer for Execution Plan
+ *
+ * Renders ExecutionPlan to Mermaid flowchart format for visualization in tasks.md.
+ */
+/**
+ * Escapes special Mermaid characters in a string.
+ * Mermaid uses quotes, brackets, and other characters that need escaping.
+ */
+function escapeMermaid(str) {
+    return str
+        .replace(/"/g, '#quot;')
+        .replace(/\[/g, '#91;')
+        .replace(/\]/g, '#93;')
+        .replace(/\(/g, '#40;')
+        .replace(/\)/g, '#41;')
+        .replace(/</g, '#lt;')
+        .replace(/>/g, '#gt;')
+        .replace(/\{/g, '#123;')
+        .replace(/\}/g, '#125;')
+        .replace(/\|/g, '#124;');
+}
+/**
+ * Converts a task ID to a valid Mermaid node ID.
+ * Mermaid node IDs cannot contain dots or hyphens.
+ *
+ * Example: "1.1" -> "T1_1", "2.3" -> "T2_3"
+ */
+function toNodeId(taskId) {
+    return 'T' + taskId.replace(/\./g, '_').replace(/-/g, '_');
+}
+/**
+ * Truncates a string to a maximum length, appending "..." if truncated.
+ */
+function truncate(str, maxLength) {
+    if (str.length <= maxLength) {
+        return str;
+    }
+    return str.slice(0, maxLength) + '...';
+}
+/**
+ * Generates the wave subtitle based on task count and max parallelism.
+ */
+function getWaveSubtitle(taskCount, maxParallelism) {
+    if (taskCount === 1) {
+        return '串行';
+    }
+    if (taskCount <= maxParallelism) {
+        return `并行度: ${taskCount}`;
+    }
+    // Calculate batch count: ceil(taskCount / maxParallelism)
+    const batchCount = Math.ceil(taskCount / maxParallelism);
+    return `并行度: ${taskCount}, 建议分批: ${batchCount}批`;
+}
+/**
+ * Renders a single task node label.
+ */
+function renderNodeLabel(task, showSkills) {
+    const truncatedDesc = truncate(task.description, 30);
+    let label = `${task.id} ${truncatedDesc}`;
+    if (showSkills && task.skills.length > 0) {
+        // Show first skill
+        label += `\\n@skill:${task.skills[0]}`;
+    }
+    return escapeMermaid(label);
+}
+/**
+ * Renders an ExecutionPlan to Mermaid flowchart format.
+ *
+ * @param plan - The execution plan to render
+ * @param tasks - The parsed tasks (used for task details)
+ * @param options - Render options
+ * @returns Complete markdown section with Mermaid diagram
+ */
+export function renderMermaidDiagram(plan, tasks, options) {
+    const maxParallelism = options?.maxParallelism ?? 3;
+    const showSkills = options?.showSkills ?? true;
+    // Handle error cases - return empty string for cycle
+    if (plan.hasCycle) {
+        return '';
+    }
+    // Handle empty plan (all tasks complete or no tasks)
+    if (plan.waves.length === 0) {
+        return '';
+    }
+    // Build task map for quick lookup
+    const taskMap = new Map();
+    for (const task of tasks) {
+        taskMap.set(task.id, task);
+    }
+    const lines = [];
+    // Markdown header with auto-generated notice
+    lines.push('## Workflow Diagram');
+    lines.push('');
+    lines.push('<!-- Auto-generated by zhuanspec validate. DO NOT edit manually. -->');
+    lines.push('');
+    lines.push('```mermaid');
+    lines.push('graph TD');
+    // Render each wave as a subgraph
+    for (const wave of plan.waves) {
+        const subtitle = getWaveSubtitle(wave.tasks.length, maxParallelism);
+        lines.push(`    subgraph Wave${wave.wave}["Wave ${wave.wave} (${subtitle})"]`);
+        for (const task of wave.tasks) {
+            const nodeId = toNodeId(task.id);
+            const label = renderNodeLabel(task, showSkills);
+            lines.push(`        ${nodeId}["${label}"]`);
+        }
+        lines.push('    end');
+    }
+    // Render dependency arrows after all subgraphs
+    // Arrow direction: from dependency -> to dependent (被依赖者 -> 依赖者)
+    for (const wave of plan.waves) {
+        for (const task of wave.tasks) {
+            for (const depId of task.depends) {
+                // Check if dependency exists in the plan (might be completed already)
+                const depTask = taskMap.get(depId);
+                if (depTask && !depTask.completed) {
+                    const fromNode = toNodeId(depId);
+                    const toNode = toNodeId(task.id);
+                    lines.push(`    ${fromNode} --> ${toNode}`);
+                }
+            }
+        }
+    }
+    lines.push('```');
+    return lines.join('\n');
+}
+//# sourceMappingURL=mermaid-renderer.js.map

package/dist/core/task-graph/task-graph.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Task Graph
+ *
+ * Builds a DAG from parsed tasks and provides graph operations.
+ * Uses Kahn's algorithm for topological sorting.
+ */
+import type { ParsedTask } from './types.js';
+/**
+ * Validation result for the task graph
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Represents a task dependency graph.
+ * Provides methods for querying build order, ready tasks, and completion status.
+ */
+export declare class TaskGraph {
+    private tasks;
+    private inDegree;
+    private dependents;
+    private dependencies;
+    private completedTasks;
+    constructor(tasks: ParsedTask[]);
+    /**
+     * Validates the task graph.
+     *
+     * Checks:
+     * - All depends references exist
+     * - No self-dependencies
+     * - No circular dependencies
+     */
+    validate(): ValidationResult;
+    /**
+     * Performs topological sort using Kahn's algorithm.
+     * Returns tasks in execution order.
+     */
+    topologicalSort(): ParsedTask[];
+    /**
+     * Detects circular dependencies in the graph.
+     * Returns an array of cycle paths.
+     */
+    detectCycles(): string[][];
+    /**
+     * Gets tasks that are ready to execute (in-degree 0 and not completed).
+     */
+    getReady(): ParsedTask[];
+    /**
+     * Marks a task as completed and updates graph state.
+     */
+    markCompleted(taskId: string): void;
+    /**
+     * Gets the direct dependencies of a task (tasks it depends on).
+     */
+    getDependencies(taskId: string): ParsedTask[];
+    /**
+     * Gets the direct dependents of a task (tasks that depend on it).
+     */
+    getDependents(taskId: string): ParsedTask[];
+    /**
+     * Gets a task by ID.
+     */
+    getTask(taskId: string): ParsedTask | undefined;
+    /**
+     * Gets all tasks in the graph.
+     */
+    getAllTasks(): ParsedTask[];
+    /**
+     * Checks if all tasks are completed.
+     */
+    isComplete(): boolean;
+}
+//# sourceMappingURL=task-graph.d.ts.map

package/dist/core/task-graph/task-graph.js

@@ -0,0 +1,219 @@
+/**
+ * Task Graph
+ *
+ * Builds a DAG from parsed tasks and provides graph operations.
+ * Uses Kahn's algorithm for topological sorting.
+ */
+/**
+ * Represents a task dependency graph.
+ * Provides methods for querying build order, ready tasks, and completion status.
+ */
+export class TaskGraph {
+    tasks;
+    inDegree;
+    dependents; // task -> tasks that depend on it
+    dependencies; // task -> tasks it depends on
+    completedTasks;
+    constructor(tasks) {
+        this.tasks = new Map(tasks.map(t => [t.id, t]));
+        this.inDegree = new Map();
+        this.dependents = new Map();
+        this.dependencies = new Map();
+        this.completedTasks = new Set();
+        // Initialize data structures
+        for (const task of tasks) {
+            this.inDegree.set(task.id, 0);
+            this.dependents.set(task.id, []);
+            this.dependencies.set(task.id, []);
+            // Mark already completed tasks
+            if (task.completed) {
+                this.completedTasks.add(task.id);
+            }
+        }
+        // Build graph edges
+        for (const task of tasks) {
+            // Filter depends to only include existing tasks
+            const validDepends = task.depends.filter(dep => this.tasks.has(dep));
+            this.dependencies.set(task.id, validDepends);
+            this.inDegree.set(task.id, validDepends.length);
+            for (const dep of validDepends) {
+                this.dependents.get(dep).push(task.id);
+            }
+        }
+    }
+    /**
+     * Validates the task graph.
+     *
+     * Checks:
+     * - All depends references exist
+     * - No self-dependencies
+     * - No circular dependencies
+     */
+    validate() {
+        const errors = [];
+        // Check for missing dependencies and self-dependencies
+        for (const task of this.tasks.values()) {
+            for (const dep of task.depends) {
+                if (!this.tasks.has(dep)) {
+                    errors.push(`Task ${task.id}: depends on non-existent task "${dep}"`);
+                }
+                if (dep === task.id) {
+                    errors.push(`Task ${task.id}: self-dependency not allowed`);
+                }
+            }
+            // Check for duplicate dependencies (warning, not error)
+            const uniqueDeps = new Set(task.depends);
+            if (uniqueDeps.size < task.depends.length) {
+                const duplicates = task.depends.filter((d, i) => task.depends.indexOf(d) !== i);
+                errors.push(`Task ${task.id}: duplicate dependencies detected: ${[...new Set(duplicates)].join(', ')}`);
+            }
+        }
+        // Check for cycles
+        const cycles = this.detectCycles();
+        if (cycles.length > 0) {
+            for (const cycle of cycles) {
+                errors.push(`Circular dependency detected: ${cycle.join(' → ')}`);
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+        };
+    }
+    /**
+     * Performs topological sort using Kahn's algorithm.
+     * Returns tasks in execution order.
+     */
+    topologicalSort() {
+        // Create a copy of in-degrees for this operation
+        const inDegree = new Map();
+        for (const [id, degree] of this.inDegree) {
+            inDegree.set(id, degree);
+        }
+        // Start with roots (in-degree 0), sorted for determinism
+        const queue = [...this.tasks.keys()]
+            .filter(id => inDegree.get(id) === 0)
+            .sort();
+        const result = [];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            result.push(this.tasks.get(current));
+            // Collect newly ready tasks, then sort before adding
+            const newlyReady = [];
+            for (const dep of this.dependents.get(current)) {
+                const newDegree = inDegree.get(dep) - 1;
+                inDegree.set(dep, newDegree);
+                if (newDegree === 0) {
+                    newlyReady.push(dep);
+                }
+            }
+            queue.push(...newlyReady.sort());
+        }
+        return result;
+    }
+    /**
+     * Detects circular dependencies in the graph.
+     * Returns an array of cycle paths.
+     */
+    detectCycles() {
+        const cycles = [];
+        const visited = new Set();
+        const recStack = new Set();
+        const path = [];
+        const dfs = (taskId) => {
+            visited.add(taskId);
+            recStack.add(taskId);
+            path.push(taskId);
+            const deps = this.dependencies.get(taskId) || [];
+            for (const dep of deps) {
+                if (!visited.has(dep)) {
+                    if (dfs(dep)) {
+                        return true;
+                    }
+                }
+                else if (recStack.has(dep)) {
+                    // Found a cycle - extract the cycle path
+                    const cycleStart = path.indexOf(dep);
+                    const cyclePath = [...path.slice(cycleStart), dep];
+                    cycles.push(cyclePath);
+                    return true;
+                }
+            }
+            path.pop();
+            recStack.delete(taskId);
+            return false;
+        };
+        for (const taskId of this.tasks.keys()) {
+            if (!visited.has(taskId)) {
+                dfs(taskId);
+            }
+        }
+        return cycles;
+    }
+    /**
+     * Gets tasks that are ready to execute (in-degree 0 and not completed).
+     */
+    getReady() {
+        const ready = [];
+        for (const task of this.tasks.values()) {
+            if (this.completedTasks.has(task.id)) {
+                continue; // Already completed
+            }
+            // Check if all dependencies are completed
+            const deps = this.dependencies.get(task.id) || [];
+            const allDepsCompleted = deps.every(dep => this.completedTasks.has(dep));
+            if (allDepsCompleted) {
+                ready.push(task);
+            }
+        }
+        // Sort for deterministic ordering
+        return ready.sort((a, b) => a.id.localeCompare(b.id));
+    }
+    /**
+     * Marks a task as completed and updates graph state.
+     */
+    markCompleted(taskId) {
+        if (!this.tasks.has(taskId)) {
+            throw new Error(`Task "${taskId}" not found in graph`);
+        }
+        this.completedTasks.add(taskId);
+    }
+    /**
+     * Gets the direct dependencies of a task (tasks it depends on).
+     */
+    getDependencies(taskId) {
+        const deps = this.dependencies.get(taskId) || [];
+        return deps.map(id => this.tasks.get(id)).filter(Boolean);
+    }
+    /**
+     * Gets the direct dependents of a task (tasks that depend on it).
+     */
+    getDependents(taskId) {
+        const deps = this.dependents.get(taskId) || [];
+        return deps.map(id => this.tasks.get(id)).filter(Boolean);
+    }
+    /**
+     * Gets a task by ID.
+     */
+    getTask(taskId) {
+        return this.tasks.get(taskId);
+    }
+    /**
+     * Gets all tasks in the graph.
+     */
+    getAllTasks() {
+        return Array.from(this.tasks.values());
+    }
+    /**
+     * Checks if all tasks are completed.
+     */
+    isComplete() {
+        for (const task of this.tasks.values()) {
+            if (!this.completedTasks.has(task.id)) {
+                return false;
+            }
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=task-graph.js.map

package/dist/core/task-graph/task-parser.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Task Parser
+ *
+ * Parses tasks.md content into structured ParsedTask array.
+ */
+import type { ParsedTask } from './types.js';
+/**
+ * Parse tasks.md content into an array of ParsedTask objects.
+ *
+ * @param content - The raw content of tasks.md
+ * @returns Array of parsed tasks
+ */
+export declare function parseTasks(content: string): ParsedTask[];
+//# sourceMappingURL=task-parser.d.ts.map

package/dist/core/task-graph/task-parser.js

@@ -0,0 +1,111 @@
+/**
+ * Task Parser
+ *
+ * Parses tasks.md content into structured ParsedTask array.
+ */
+// Regex patterns for parsing
+// Group header: ## N. Group Name
+const GROUP_HEADER_REGEX = /^##\s+(\d+)\.\s+(.+)$/;
+// Task line: - [ ] N.M description @skill:name1,name2 @depends:id1,id2
+// or: - [x] N.M description ...
+const TASK_LINE_REGEX = /^-\s+\[([ xX])\]\s+(\d+\.\d+)\s+(.*)$/;
+// Annotations (can be inside or outside HTML comments)
+const SKILL_REGEX = /@skill:([^\s@]+)/g;
+const DEPENDS_REGEX = /@depends:([^\s@]+)/g;
+// HTML comment pattern to extract content
+const HTML_COMMENT_REGEX = /<!--\s*(.*?)\s*-->/g;
+/**
+ * Extract annotations from text (handles both plain text and HTML comments)
+ */
+function extractAnnotations(text) {
+    const skills = [];
+    const depends = [];
+    // Collect all text to search (including content inside HTML comments)
+    let searchText = text;
+    // Extract content from HTML comments and add to search text
+    let match;
+    while ((match = HTML_COMMENT_REGEX.exec(text)) !== null) {
+        searchText += ' ' + match[1];
+    }
+    // Reset lastIndex for subsequent regex operations
+    HTML_COMMENT_REGEX.lastIndex = 0;
+    // Extract skills
+    let skillMatch;
+    while ((skillMatch = SKILL_REGEX.exec(searchText)) !== null) {
+        const skillList = skillMatch[1].split(',').filter(s => s.trim());
+        skills.push(...skillList);
+    }
+    SKILL_REGEX.lastIndex = 0;
+    // Extract depends
+    let dependsMatch;
+    while ((dependsMatch = DEPENDS_REGEX.exec(searchText)) !== null) {
+        const dependsList = dependsMatch[1].split(',').filter(d => d.trim());
+        depends.push(...dependsList);
+    }
+    DEPENDS_REGEX.lastIndex = 0;
+    return {
+        skills: [...new Set(skills)], // dedupe
+        depends: [...new Set(depends)], // dedupe
+    };
+}
+/**
+ * Clean description by removing annotations
+ */
+function cleanDescription(text) {
+    let cleaned = text
+        // Remove HTML comments with annotations
+        .replace(/<!--\s*@(?:skill|depends):[^\s]*(?:\s+@(?:skill|depends):[^\s]*)?\s*-->/g, '')
+        // Remove plain annotations
+        .replace(/@skill:[^\s@]+/g, '')
+        .replace(/@depends:[^\s@]+/g, '')
+        .trim();
+    return cleaned;
+}
+/**
+ * Parse tasks.md content into an array of ParsedTask objects.
+ *
+ * @param content - The raw content of tasks.md
+ * @returns Array of parsed tasks
+ */
+export function parseTasks(content) {
+    if (!content || !content.trim()) {
+        return [];
+    }
+    const lines = content.split('\n');
+    const tasks = [];
+    let currentGroup = '';
+    let currentGroupName = '';
+    for (const line of lines) {
+        // Check for group header
+        const groupMatch = line.match(GROUP_HEADER_REGEX);
+        if (groupMatch) {
+            currentGroup = groupMatch[1];
+            currentGroupName = groupMatch[2].trim();
+            continue;
+        }
+        // Check for task line
+        const taskMatch = line.match(TASK_LINE_REGEX);
+        if (taskMatch) {
+            const checkboxState = taskMatch[1];
+            const taskId = taskMatch[2];
+            const rest = taskMatch[3];
+            // Extract annotations
+            const { skills, depends } = extractAnnotations(rest);
+            // Clean description
+            const description = cleanDescription(rest);
+            // Parse group from task ID if not already set
+            const taskGroup = taskId.split('.')[0];
+            tasks.push({
+                id: taskId,
+                group: currentGroup || taskGroup,
+                groupName: currentGroupName,
+                description,
+                skills,
+                depends,
+                completed: checkboxState.toLowerCase() === 'x',
+            });
+        }
+    }
+    return tasks;
+}
+//# sourceMappingURL=task-parser.js.map

package/dist/core/task-graph/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Task Graph Types
+ *
+ * Type definitions for task dependency graph module.
+ */
+/**
+ * Represents a parsed task from tasks.md
+ */
+export interface ParsedTask {
+    /** Task ID, e.g., "1.1", "2.3" */
+    id: string;
+    /** Group number, e.g., "1", "2" */
+    group: string;
+    /** Group name */
+    groupName: string;
+    /** Task description text */
+    description: string;
+    /** Skills required, e.g., ["java-dao-standards"] */
+    skills: string[];
+    /** Task IDs this task depends on, e.g., ["1.1", "2.1"] */
+    depends: string[];
+    /** Whether the task is completed (checkbox state [x] vs [ ]) */
+    completed: boolean;
+}
+/**
+ * Represents a wave of tasks that can be executed together
+ */
+export interface ExecutionWave {
+    /** Wave number (starting from 1) */
+    wave: number;
+    /** Tasks in this wave */
+    tasks: ParsedTask[];
+    /** Whether tasks can run in parallel (tasks.length > 1) */
+    parallel: boolean;
+}
+/**
+ * Represents the complete execution plan
+ */
+export interface ExecutionPlan {
+    /** Waves of tasks to execute */
+    waves: ExecutionWave[];
+    /** Total number of tasks */
+    totalTasks: number;
+    /** Number of tasks that can be executed in parallel (tasks in multi-task waves) */
+    parallelTasks: number;
+    /** Number of tasks that must be executed serially (tasks in single-task waves) */
+    serialTasks: number;
+    /** Whether there is a cycle in the dependency graph */
+    hasCycle: boolean;
+    /** Validation errors */
+    errors: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/task-graph/types.js

@@ -0,0 +1,7 @@
+/**
+ * Task Graph Types
+ *
+ * Type definitions for task dependency graph module.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/task-graph/xml-renderer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * XML Renderer for Execution Plan
+ *
+ * Renders ExecutionPlan to XML format for injection into apply instructions.
+ */
+import type { ExecutionPlan, ParsedTask } from './types.js';
+/**
+ * Renders an ExecutionPlan to XML format.
+ *
+ * @param plan - The execution plan to render
+ * @returns XML string representation of the plan
+ */
+export declare function renderExecutionPlanXml(plan: ExecutionPlan): string;
+/**
+ * Checks if any task in the parsed tasks has @depends annotation.
+ *
+ * @param tasks - Array of parsed tasks
+ * @returns True if at least one task has dependencies
+ */
+export declare function hasDependsAnnotations(tasks: ParsedTask[]): boolean;
+//# sourceMappingURL=xml-renderer.d.ts.map