@weavelogic/knowledge-graph-agent 0.11.8 → 0.12.0

package/dist/sparc/sparc-planner.js

@@ -0,0 +1,757 @@
+import { existsSync, mkdirSync, writeFileSync, readdirSync, statSync, readFileSync } from "fs";
+import { join, extname, relative } from "path";
+import { createLogger } from "../utils/logger.js";
+import { createDecisionLogManager } from "./decision-log.js";
+import { createConsensusBuilder, ConsensusBuilder } from "./consensus.js";
+import { createReviewProcess } from "./review-process.js";
+const logger = createLogger("sparc-planner");
+class SPARCPlanner {
+  options;
+  plan;
+  decisionLog;
+  consensusBuilder;
+  constructor(options) {
+    this.options = {
+      outputDir: join(options.projectRoot, ".sparc"),
+      parallelResearch: true,
+      reviewPasses: 3,
+      autoConsensus: true,
+      kgEnabled: true,
+      vectorEnabled: true,
+      ...options
+    };
+    this.plan = this.initializePlan();
+    this.decisionLog = createDecisionLogManager({
+      outputDir: this.options.outputDir,
+      planId: this.plan.id
+    });
+    this.consensusBuilder = createConsensusBuilder({
+      defaultThreshold: 0.67,
+      method: "majority"
+    });
+    logger.info("SPARC Planner initialized", {
+      planId: this.plan.id,
+      projectRoot: this.options.projectRoot
+    });
+  }
+  /**
+   * Initialize a new plan
+   */
+  initializePlan() {
+    const now = /* @__PURE__ */ new Date();
+    const id = `plan_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+    return {
+      id,
+      name: this.options.name,
+      description: this.options.description,
+      status: "draft",
+      currentPhase: "specification",
+      projectRoot: this.options.projectRoot,
+      outputDir: this.options.outputDir,
+      tasks: [],
+      parallelGroups: [],
+      criticalPath: [],
+      executionOrder: [],
+      researchFindings: [],
+      decisionLog: {
+        id: `dlog_${id}`,
+        planId: id,
+        decisions: [],
+        statistics: {
+          total: 0,
+          approved: 0,
+          rejected: 0,
+          deferred: 0,
+          highConfidence: 0,
+          lowConfidence: 0,
+          consensusRequired: 0
+        },
+        createdAt: now,
+        updatedAt: now
+      },
+      createdAt: now,
+      updatedAt: now,
+      version: "1.0.0",
+      author: "sparc-planner",
+      statistics: {
+        totalTasks: 0,
+        completedTasks: 0,
+        parallelizableTasks: 0,
+        estimatedHours: 0,
+        researchFindings: 0,
+        decisions: 0,
+        kgNodes: 0
+      }
+    };
+  }
+  /**
+   * Execute the full planning process
+   */
+  async executePlanning() {
+    logger.info("Starting SPARC planning process", { planId: this.plan.id });
+    try {
+      this.plan.status = "researching";
+      await this.executeResearchPhase();
+      this.plan.status = "planning";
+      await this.executeSpecificationPhase();
+      await this.executePseudocodePhase();
+      await this.executeArchitecturePhase();
+      await this.executeRefinementPhase();
+      this.plan.status = "reviewing";
+      const reviewResult = await this.executeReviewPhase();
+      this.plan.reviewResult = reviewResult;
+      if (reviewResult.overallStatus === "approved") {
+        this.plan.status = "approved";
+      } else if (reviewResult.overallStatus === "rejected") {
+        this.plan.status = "failed";
+      } else {
+        this.plan.status = "planning";
+      }
+      this.updateStatistics();
+      this.savePlan();
+      logger.info("SPARC planning completed", {
+        planId: this.plan.id,
+        status: this.plan.status,
+        tasks: this.plan.tasks.length
+      });
+      return this.plan;
+    } catch (error) {
+      this.plan.status = "failed";
+      logger.error("SPARC planning failed", error instanceof Error ? error : new Error(String(error)));
+      throw error;
+    }
+  }
+  /**
+   * Execute research phase
+   */
+  async executeResearchPhase() {
+    logger.info("Executing research phase");
+    this.plan.currentPhase = "specification";
+    const srcPath = join(this.options.projectRoot, "src");
+    if (existsSync(srcPath)) {
+      this.plan.existingCode = await this.analyzeExistingCode(srcPath);
+      this.addDecision(
+        "Existing Code Integration",
+        "Integrate with existing codebase in src/",
+        "specification",
+        "high",
+        "Existing code found and analyzed for patterns and integration points",
+        ["Start from scratch", "Partial rewrite", "Full integration"]
+      );
+    }
+    const researchTasks = this.defineResearchTasks();
+    for (const task of researchTasks) {
+      const finding = await this.executeResearchTask(task);
+      this.plan.researchFindings.push(finding);
+    }
+    logger.info("Research phase completed", {
+      findings: this.plan.researchFindings.length,
+      hasExistingCode: !!this.plan.existingCode
+    });
+  }
+  /**
+   * Analyze existing code in src directory
+   */
+  async analyzeExistingCode(srcPath) {
+    const analysis = {
+      hasSrcDirectory: true,
+      srcPath,
+      fileCount: 0,
+      languages: {},
+      keyFiles: [],
+      patterns: [],
+      dependencies: [],
+      entryPoints: []
+    };
+    const analyzeDir = (dir) => {
+      const entries = readdirSync(dir);
+      for (const entry of entries) {
+        const fullPath = join(dir, entry);
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          if (!entry.startsWith(".") && entry !== "node_modules") {
+            analyzeDir(fullPath);
+          }
+        } else if (stat.isFile()) {
+          analysis.fileCount++;
+          const ext = extname(entry);
+          analysis.languages[ext] = (analysis.languages[ext] || 0) + 1;
+          if (entry === "index.ts" || entry === "index.js") {
+            analysis.entryPoints.push(relative(this.options.projectRoot, fullPath));
+          }
+          if (entry === "package.json") {
+            try {
+              const pkg = JSON.parse(readFileSync(fullPath, "utf-8"));
+              analysis.dependencies = Object.keys(pkg.dependencies || {});
+            } catch {
+            }
+          }
+        }
+      }
+    };
+    analyzeDir(srcPath);
+    if (analysis.languages[".ts"] > 0 || analysis.languages[".tsx"] > 0) {
+      analysis.patterns.push("TypeScript");
+    }
+    if (existsSync(join(this.options.projectRoot, "tests")) || existsSync(join(this.options.projectRoot, "__tests__"))) {
+      analysis.patterns.push("Test-Driven Development");
+      analysis.testCoverage = { hasTests: true };
+    }
+    return analysis;
+  }
+  /**
+   * Define research tasks
+   */
+  defineResearchTasks() {
+    return [
+      {
+        id: "research-requirements",
+        agentType: "researcher",
+        description: "Research and analyze project requirements",
+        topics: ["functional requirements", "non-functional requirements", "constraints"],
+        context: [this.options.description]
+      },
+      {
+        id: "research-patterns",
+        agentType: "researcher",
+        description: "Research applicable design patterns",
+        topics: ["design patterns", "architecture patterns", "best practices"],
+        context: this.plan.existingCode?.patterns || []
+      },
+      {
+        id: "research-technology",
+        agentType: "researcher",
+        description: "Research technology choices and alternatives",
+        topics: ["technology stack", "frameworks", "libraries"],
+        context: this.plan.existingCode?.dependencies || []
+      }
+    ];
+  }
+  /**
+   * Execute a research task (stub - would spawn agent)
+   */
+  async executeResearchTask(task) {
+    return {
+      id: `finding_${task.id}`,
+      agent: task.agentType,
+      topic: task.topics[0],
+      summary: `Research findings for ${task.description}`,
+      details: `Detailed research results for topics: ${task.topics.join(", ")}`,
+      confidence: "medium",
+      evidence: task.context,
+      relatedFindings: [],
+      kgReferences: [],
+      timestamp: /* @__PURE__ */ new Date()
+    };
+  }
+  /**
+   * Execute specification phase
+   */
+  async executeSpecificationPhase() {
+    logger.info("Executing specification phase");
+    this.plan.currentPhase = "specification";
+    const spec = {
+      id: `spec_${this.plan.id}`,
+      projectName: this.options.name,
+      version: "1.0.0",
+      createdAt: /* @__PURE__ */ new Date(),
+      updatedAt: /* @__PURE__ */ new Date(),
+      summary: this.options.description,
+      problemStatement: this.extractProblemStatement(),
+      goals: this.extractGoals(),
+      requirements: this.generateRequirements(),
+      features: this.generateFeatures(),
+      constraints: this.extractConstraints(),
+      assumptions: [],
+      outOfScope: [],
+      successMetrics: this.generateSuccessMetrics(),
+      kgReferences: []
+    };
+    this.plan.specification = spec;
+    this.addDecision(
+      "Requirements Definition",
+      `Defined ${spec.requirements.length} requirements and ${spec.features.length} features`,
+      "specification",
+      "high",
+      "Requirements derived from research findings and project description"
+    );
+    logger.info("Specification phase completed", {
+      requirements: spec.requirements.length,
+      features: spec.features.length
+    });
+  }
+  /**
+   * Execute pseudocode phase
+   */
+  async executePseudocodePhase() {
+    logger.info("Executing pseudocode phase");
+    this.plan.currentPhase = "pseudocode";
+    const algorithms = [];
+    for (const feature of this.plan.specification?.features || []) {
+      const algorithm = this.generateAlgorithmDesign(feature);
+      algorithms.push(algorithm);
+    }
+    this.plan.algorithms = algorithms;
+    logger.info("Pseudocode phase completed", {
+      algorithms: algorithms.length
+    });
+  }
+  /**
+   * Execute architecture phase
+   */
+  async executeArchitecturePhase() {
+    logger.info("Executing architecture phase");
+    this.plan.currentPhase = "architecture";
+    const arch = {
+      id: `arch_${this.plan.id}`,
+      version: "1.0.0",
+      createdAt: /* @__PURE__ */ new Date(),
+      overview: this.generateArchitectureOverview(),
+      patterns: this.identifyArchitecturePatterns(),
+      components: this.generateComponents(),
+      decisions: [],
+      dataFlow: this.describeDataFlow(),
+      securityConsiderations: this.identifySecurityConsiderations(),
+      scalabilityConsiderations: [],
+      diagrams: []
+    };
+    this.plan.architecture = arch;
+    this.addDecision(
+      "Architecture Design",
+      `Defined ${arch.components.length} components using ${arch.patterns.join(", ")} patterns`,
+      "architecture",
+      "medium",
+      "Architecture designed based on requirements and existing patterns",
+      ["Microservices", "Monolith", "Modular monolith"]
+    );
+    logger.info("Architecture phase completed", {
+      components: arch.components.length,
+      patterns: arch.patterns.length
+    });
+  }
+  /**
+   * Execute refinement phase (task breakdown)
+   */
+  async executeRefinementPhase() {
+    logger.info("Executing refinement phase");
+    this.plan.currentPhase = "refinement";
+    const tasks = [];
+    tasks.push(this.createTask(
+      "Research and Analysis",
+      "Comprehensive research on project requirements and patterns",
+      "specification",
+      "research",
+      "high",
+      4
+    ));
+    for (const component of this.plan.architecture?.components || []) {
+      tasks.push(this.createTask(
+        `Implement ${component.name}`,
+        `Implement the ${component.name} component: ${component.description}`,
+        "refinement",
+        "implementation",
+        this.getComponentPriority(component),
+        this.estimateComponentHours(component)
+      ));
+    }
+    tasks.push(this.createTask(
+      "Unit Testing",
+      "Create comprehensive unit tests for all components",
+      "refinement",
+      "testing",
+      "high",
+      8
+    ));
+    tasks.push(this.createTask(
+      "Integration Testing",
+      "Create integration tests for component interactions",
+      "refinement",
+      "testing",
+      "medium",
+      6
+    ));
+    tasks.push(this.createTask(
+      "API Documentation",
+      "Document all public APIs and interfaces",
+      "completion",
+      "documentation",
+      "medium",
+      4
+    ));
+    this.plan.tasks = tasks;
+    this.calculateParallelGroups();
+    this.calculateCriticalPath();
+    logger.info("Refinement phase completed", {
+      tasks: tasks.length,
+      parallelGroups: this.plan.parallelGroups.length
+    });
+  }
+  /**
+   * Execute review phase
+   */
+  async executeReviewPhase() {
+    logger.info("Executing review phase");
+    this.plan.currentPhase = "completion";
+    this.plan.decisionLog = this.decisionLog.getLog();
+    const reviewProcess = createReviewProcess({
+      plan: this.plan,
+      passes: this.options.reviewPasses,
+      autoFix: false,
+      strictMode: false
+    });
+    const result = await reviewProcess.executeReview();
+    logger.info("Review phase completed", {
+      status: result.overallStatus,
+      totalFindings: result.totalFindings,
+      criticalFindings: result.criticalFindings
+    });
+    return result;
+  }
+  /**
+   * Add a decision to the log
+   */
+  addDecision(title, description, phase, confidence, rationale, alternatives) {
+    const decision = this.decisionLog.addDecision({
+      title,
+      description,
+      phase,
+      confidence,
+      rationale,
+      alternatives,
+      decidedBy: "sparc-planner"
+    });
+    if (this.options.autoConsensus && ConsensusBuilder.needsConsensus(confidence)) {
+      logger.info("Building consensus for low-confidence decision", {
+        decisionId: decision.id,
+        confidence
+      });
+    }
+  }
+  /**
+   * Create a SPARC task
+   */
+  createTask(name, description, phase, type, priority, estimatedHours) {
+    return {
+      id: `task_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
+      name,
+      description,
+      phase,
+      type,
+      priority,
+      estimatedHours,
+      dependencies: [],
+      parallelizable: type === "implementation" || type === "testing",
+      status: "pending",
+      contextLinks: [],
+      kgReferences: []
+    };
+  }
+  /**
+   * Calculate parallel task groups
+   */
+  calculateParallelGroups() {
+    const parallelizable = this.plan.tasks.filter((t) => t.parallelizable);
+    const groups = [];
+    const phases = ["specification", "pseudocode", "architecture", "refinement", "completion"];
+    for (const phase of phases) {
+      const phaseTasks = parallelizable.filter((t) => t.phase === phase);
+      if (phaseTasks.length > 0) {
+        groups.push(phaseTasks.map((t) => t.id));
+      }
+    }
+    this.plan.parallelGroups = groups;
+  }
+  /**
+   * Calculate critical path
+   */
+  calculateCriticalPath() {
+    const critical = this.plan.tasks.filter((t) => t.priority === "critical" || t.priority === "high").sort((a, b) => {
+      const phaseOrder = ["specification", "pseudocode", "architecture", "refinement", "completion"];
+      return phaseOrder.indexOf(a.phase) - phaseOrder.indexOf(b.phase);
+    }).map((t) => t.id);
+    this.plan.criticalPath = critical;
+    this.plan.executionOrder = this.plan.tasks.map((t) => t.id);
+  }
+  /**
+   * Update plan statistics
+   */
+  updateStatistics() {
+    this.plan.statistics = {
+      totalTasks: this.plan.tasks.length,
+      completedTasks: this.plan.tasks.filter((t) => t.status === "completed").length,
+      parallelizableTasks: this.plan.tasks.filter((t) => t.parallelizable).length,
+      estimatedHours: this.plan.tasks.reduce((sum, t) => sum + t.estimatedHours, 0),
+      researchFindings: this.plan.researchFindings.length,
+      decisions: this.decisionLog.getDecisions().length,
+      kgNodes: this.plan.tasks.reduce((sum, t) => sum + (t.kgReferences?.length || 0), 0)
+    };
+    this.plan.updatedAt = /* @__PURE__ */ new Date();
+  }
+  /**
+   * Save plan to disk
+   */
+  savePlan() {
+    const dir = this.options.outputDir;
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const planPath = join(dir, "sparc-plan.json");
+    writeFileSync(planPath, JSON.stringify(this.plan, null, 2));
+    const mdPath = join(dir, "sparc-plan.md");
+    writeFileSync(mdPath, this.generateMarkdownSummary());
+    this.decisionLog.save();
+    this.decisionLog.saveMarkdown();
+    logger.info("Plan saved", { dir });
+  }
+  /**
+   * Generate markdown summary
+   */
+  generateMarkdownSummary() {
+    const lines = [
+      `# SPARC Plan: ${this.plan.name}`,
+      "",
+      `**Status:** ${this.plan.status}`,
+      `**Version:** ${this.plan.version}`,
+      `**Created:** ${this.plan.createdAt.toISOString()}`,
+      "",
+      "## Summary",
+      "",
+      this.plan.description,
+      "",
+      "## Statistics",
+      "",
+      `| Metric | Value |`,
+      `|--------|-------|`,
+      `| Total Tasks | ${this.plan.statistics.totalTasks} |`,
+      `| Parallelizable | ${this.plan.statistics.parallelizableTasks} |`,
+      `| Estimated Hours | ${this.plan.statistics.estimatedHours} |`,
+      `| Research Findings | ${this.plan.statistics.researchFindings} |`,
+      `| Decisions | ${this.plan.statistics.decisions} |`,
+      ""
+    ];
+    if (this.plan.specification) {
+      lines.push("## Specification");
+      lines.push("");
+      lines.push(`- **Requirements:** ${this.plan.specification.requirements.length}`);
+      lines.push(`- **Features:** ${this.plan.specification.features.length}`);
+      lines.push("");
+    }
+    if (this.plan.architecture) {
+      lines.push("## Architecture");
+      lines.push("");
+      lines.push(`- **Components:** ${this.plan.architecture.components.length}`);
+      lines.push(`- **Patterns:** ${this.plan.architecture.patterns.join(", ")}`);
+      lines.push("");
+    }
+    lines.push("## Tasks");
+    lines.push("");
+    for (const task of this.plan.tasks) {
+      lines.push(`### ${task.name}`);
+      lines.push("");
+      lines.push(`- **Phase:** ${task.phase}`);
+      lines.push(`- **Type:** ${task.type}`);
+      lines.push(`- **Priority:** ${task.priority}`);
+      lines.push(`- **Estimated:** ${task.estimatedHours}h`);
+      lines.push(`- **Parallelizable:** ${task.parallelizable ? "Yes" : "No"}`);
+      lines.push("");
+      lines.push(task.description);
+      lines.push("");
+    }
+    if (this.plan.reviewResult) {
+      lines.push("## Review Result");
+      lines.push("");
+      lines.push(`- **Status:** ${this.plan.reviewResult.overallStatus}`);
+      lines.push(`- **Total Findings:** ${this.plan.reviewResult.totalFindings}`);
+      lines.push(`- **Critical Findings:** ${this.plan.reviewResult.criticalFindings}`);
+      lines.push("");
+      if (this.plan.reviewResult.recommendations.length > 0) {
+        lines.push("### Recommendations");
+        lines.push("");
+        for (const rec of this.plan.reviewResult.recommendations) {
+          lines.push(`- ${rec}`);
+        }
+        lines.push("");
+      }
+    }
+    return lines.join("\n");
+  }
+  // Helper methods for content generation
+  extractProblemStatement() {
+    return `Problem to solve: ${this.options.description}`;
+  }
+  extractGoals() {
+    return [
+      "Implement all specified features",
+      "Ensure code quality and maintainability",
+      "Provide comprehensive documentation",
+      "Enable parallel development where possible"
+    ];
+  }
+  generateRequirements() {
+    return [
+      {
+        id: "req-001",
+        type: "functional",
+        description: "Core functionality as described",
+        priority: "must-have",
+        source: "User request",
+        acceptanceCriteria: ["Feature works as specified"],
+        relatedRequirements: []
+      },
+      {
+        id: "req-002",
+        type: "non-functional",
+        description: "Code must be well-documented",
+        priority: "should-have",
+        source: "Best practices",
+        acceptanceCriteria: ["API documentation exists"],
+        relatedRequirements: []
+      },
+      {
+        id: "req-003",
+        type: "non-functional",
+        description: "Test coverage must be adequate",
+        priority: "should-have",
+        source: "Best practices",
+        acceptanceCriteria: ["Unit tests exist for core functionality"],
+        relatedRequirements: []
+      }
+    ];
+  }
+  generateFeatures() {
+    return [
+      {
+        id: "feat-001",
+        name: "Core Implementation",
+        description: "Main feature implementation",
+        userStories: [`As a user, I want ${this.options.description}`],
+        requirements: ["req-001"],
+        complexity: "medium",
+        dependencies: [],
+        parallelizable: true
+      }
+    ];
+  }
+  extractConstraints() {
+    return [
+      "Must follow existing code patterns if present",
+      "Must maintain backwards compatibility"
+    ];
+  }
+  generateSuccessMetrics() {
+    return [
+      "All tests pass",
+      "Documentation is complete",
+      "Code review approved"
+    ];
+  }
+  generateAlgorithmDesign(feature) {
+    return {
+      id: `algo_${feature.id}`,
+      name: `${feature.name} Algorithm`,
+      purpose: feature.description,
+      steps: [
+        {
+          step: 1,
+          description: "Initialize",
+          pseudocode: "// Initialize component",
+          inputs: [],
+          outputs: []
+        },
+        {
+          step: 2,
+          description: "Process",
+          pseudocode: "// Process input",
+          inputs: ["input"],
+          outputs: ["result"]
+        },
+        {
+          step: 3,
+          description: "Return",
+          pseudocode: "// Return result",
+          inputs: ["result"],
+          outputs: ["output"]
+        }
+      ],
+      timeComplexity: "O(n)",
+      spaceComplexity: "O(1)",
+      edgeCases: ["Empty input", "Invalid input"],
+      relatedFeatures: [feature.id]
+    };
+  }
+  generateArchitectureOverview() {
+    return `Architecture for ${this.options.name}: ${this.options.description}`;
+  }
+  identifyArchitecturePatterns() {
+    const patterns = ["Modular"];
+    if (this.plan.existingCode?.patterns.includes("TypeScript")) {
+      patterns.push("Type-Safe");
+    }
+    if (this.plan.existingCode?.patterns.includes("Test-Driven Development")) {
+      patterns.push("TDD");
+    }
+    return patterns;
+  }
+  generateComponents() {
+    return [
+      {
+        id: "comp-core",
+        name: "Core Module",
+        type: "module",
+        description: "Core functionality module",
+        responsibilities: ["Main feature implementation"],
+        interfaces: [],
+        dependencies: [],
+        technologies: ["TypeScript"]
+      },
+      {
+        id: "comp-api",
+        name: "API Layer",
+        type: "api",
+        description: "Public API interface",
+        responsibilities: ["Expose public API"],
+        interfaces: [],
+        dependencies: ["comp-core"],
+        technologies: ["TypeScript"]
+      }
+    ];
+  }
+  describeDataFlow() {
+    return "Input -> API Layer -> Core Module -> Output";
+  }
+  identifySecurityConsiderations() {
+    return [
+      "Input validation",
+      "Error handling"
+    ];
+  }
+  getComponentPriority(component) {
+    if (component.dependencies.length === 0) return "high";
+    return "medium";
+  }
+  estimateComponentHours(component) {
+    const base = 4;
+    const depFactor = component.dependencies.length * 2;
+    return base + depFactor;
+  }
+  /**
+   * Get the current plan
+   */
+  getPlan() {
+    return this.plan;
+  }
+  /**
+   * Get decision log manager
+   */
+  getDecisionLog() {
+    return this.decisionLog;
+  }
+}
+function createSPARCPlanner(options) {
+  return new SPARCPlanner(options);
+}
+export {
+  SPARCPlanner,
+  createSPARCPlanner
+};
+//# sourceMappingURL=sparc-planner.js.map