@webpresso/agent-kit 0.21.0

package/dist/esm/blueprint/dag/local/independence.js

@@ -0,0 +1,231 @@
+import { PackageGraph } from './package-graph.js';
+/**
+ * IndependenceDetector analyzes tasks to find false dependencies.
+ *
+ * Uses file and package analysis to determine if tasks can run in parallel,
+ * even when the plan declares a dependency between them.
+ *
+ * Accepts IPackageGraph interface for testability - package structure can be mocked.
+ */
+export class IndependenceDetector {
+    packageGraph;
+    /**
+     * Create a new IndependenceDetector.
+     * @param rootOrPackageGraph - Either a root path (creates real PackageGraph) or an IPackageGraph for testing
+     */
+    constructor(rootOrPackageGraph) {
+        if (typeof rootOrPackageGraph === 'string') {
+            this.packageGraph = new PackageGraph(rootOrPackageGraph);
+        }
+        else {
+            this.packageGraph = rootOrPackageGraph;
+        }
+    }
+    /**
+     * Determine if two tasks can run in parallel based on their file access.
+     *
+     * Algorithm:
+     * 1. Get package for each file (walk up to package.json)
+     * 2. IF different packages AND no cross-package deps → PARALLEL
+     * 3. IF same package but no file overlap → PARALLEL
+     * 4. IF file overlap but both read-only → PARALLEL
+     * 5. ELSE → SERIAL
+     */
+    canParallelize(taskA, taskB) {
+        if (!taskA.files.length || !taskB.files.length) {
+            return { canParallelize: true, reason: 'one or both tasks have no files' };
+        }
+        const packagesA = this.getPackagesForFiles(taskA.files);
+        const packagesB = this.getPackagesForFiles(taskB.files);
+        return this.analyzePackageLocation(taskA, taskB, packagesA, packagesB);
+    }
+    analyzePackageLocation(taskA, taskB, packagesA, packagesB) {
+        // If one has packages and the other doesn't, they're in different locations
+        if (packagesA.size === 0 && packagesB.size > 0) {
+            return { canParallelize: true, reason: 'different locations (packaged vs unpackaged)' };
+        }
+        if (packagesB.size === 0 && packagesA.size > 0) {
+            return { canParallelize: true, reason: 'different locations (packaged vs unpackaged)' };
+        }
+        // If both are outside packages, check file overlap
+        if (packagesA.size === 0 && packagesB.size === 0) {
+            return this.analyzeFilesOutsidePackages(taskA, taskB);
+        }
+        if (!this.hasOverlap(packagesA, packagesB)) {
+            return this.analyzeDifferentPackages(packagesA, packagesB);
+        }
+        return this.analyzeSamePackage(taskA, taskB);
+    }
+    analyzeFilesOutsidePackages(taskA, taskB) {
+        const overlappingFiles = this.getOverlappingFiles(taskA.files, taskB.files);
+        if (!overlappingFiles.length) {
+            return { canParallelize: true, reason: 'files outside packages, no overlap' };
+        }
+        if (taskA.readOnly && taskB.readOnly) {
+            return { canParallelize: true, reason: 'files outside packages, overlap but read-only' };
+        }
+        return {
+            canParallelize: false,
+            reason: 'files outside packages with write conflict',
+            conflictingFiles: overlappingFiles,
+        };
+    }
+    analyzeDifferentPackages(packagesA, packagesB) {
+        // If one is the root package and the other is not, they can parallelize
+        // Root package is a meta/dev package and its dependencies don't create real conflicts
+        const hasRoot = packagesA.has('') || packagesB.has('');
+        const hasNonRoot = Array.from(packagesA).some((p) => p !== '') || Array.from(packagesB).some((p) => p !== '');
+        if (hasRoot && hasNonRoot) {
+            return { canParallelize: true, reason: 'root package vs workspace package, no conflict' };
+        }
+        const hasCrossDep = this.hasCrossPackageDep(packagesA, packagesB);
+        if (!hasCrossDep) {
+            return { canParallelize: true, reason: 'different packages, no cross-dep' };
+        }
+        return { canParallelize: false, reason: 'cross-package dependency exists' };
+    }
+    analyzeSamePackage(taskA, taskB) {
+        const overlappingFiles = this.getOverlappingFiles(taskA.files, taskB.files);
+        if (!overlappingFiles.length) {
+            return { canParallelize: true, reason: 'same package, no file overlap' };
+        }
+        if (taskA.readOnly && taskB.readOnly) {
+            return { canParallelize: true, reason: 'file overlap but both read-only' };
+        }
+        return {
+            canParallelize: false,
+            reason: `file overlap with write conflict: ${overlappingFiles.join(', ')}`,
+            conflictingFiles: overlappingFiles,
+        };
+    }
+    /**
+     * Analyze a pair of tasks in detail.
+     * Useful for debugging why tasks can or cannot be parallelized.
+     */
+    analyzeTaskPair(taskA, taskB) {
+        const packagesA = this.getPackagesForFiles(taskA.files);
+        const packagesB = this.getPackagesForFiles(taskB.files);
+        const overlappingFiles = this.getOverlappingFiles(taskA.files, taskB.files);
+        const hasCrossDep = this.hasCrossPackageDep(packagesA, packagesB);
+        const result = this.canParallelize(taskA, taskB);
+        return {
+            taskA: taskA.id,
+            taskB: taskB.id,
+            canParallelize: result.canParallelize,
+            reason: result.reason,
+            packagesA: Array.from(packagesA),
+            packagesB: Array.from(packagesB),
+            overlappingFiles,
+            hasCrossPackageDependency: hasCrossDep,
+        };
+    }
+    /**
+     * Find all false dependencies in a task graph.
+     *
+     * @param tasks - List of tasks with their file information
+     * @param edges - List of declared dependencies (from → to)
+     * @returns List of edges that can be safely removed
+     */
+    findFalseDependencies(tasks, edges) {
+        const taskMap = new Map(tasks.map((t) => [t.id, t]));
+        const falseDeps = [];
+        for (const edge of edges) {
+            const taskA = taskMap.get(edge.from);
+            const taskB = taskMap.get(edge.to);
+            if (!taskA || !taskB)
+                continue;
+            const result = this.canParallelize(taskA, taskB);
+            if (result.canParallelize) {
+                falseDeps.push({
+                    from: edge.from,
+                    to: edge.to,
+                    reason: result.reason,
+                });
+            }
+        }
+        return falseDeps;
+    }
+    /**
+     * Analyze all task pairs and return detailed analysis.
+     * Useful for understanding the parallelization potential of a task set.
+     */
+    analyzeAllPairs(tasks) {
+        const analyses = [];
+        for (let i = 0; i < tasks.length; i++) {
+            for (let j = i + 1; j < tasks.length; j++) {
+                // Safe: loop conditions ensure i and j are within bounds
+                const taskA = tasks[i];
+                const taskB = tasks[j];
+                if (!taskA || !taskB)
+                    continue;
+                analyses.push(this.analyzeTaskPair(taskA, taskB));
+            }
+        }
+        return {
+            totalPairs: analyses.length,
+            parallelizablePairs: analyses.filter((a) => a.canParallelize).length,
+            analyses,
+        };
+    }
+    getPackagesForFiles(files) {
+        const packages = new Set();
+        for (const file of files) {
+            const pkg = this.packageGraph.findPackageRoot(file);
+            if (pkg !== null) {
+                packages.add(pkg);
+            }
+        }
+        return packages;
+    }
+    hasOverlap(setA, setB) {
+        for (const item of setA) {
+            if (setB.has(item))
+                return true;
+        }
+        return false;
+    }
+    hasCrossPackageDep(packagesA, packagesB) {
+        // Check if any package in A depends on any package in B (or vice versa)
+        for (const pkgA of packagesA) {
+            if (this.anyDependsOn(pkgA, packagesB))
+                return true;
+        }
+        for (const pkgB of packagesB) {
+            if (this.anyDependsOn(pkgB, packagesA))
+                return true;
+        }
+        return false;
+    }
+    anyDependsOn(pkg, targets) {
+        for (const target of targets) {
+            if (this.packageGraph.hasCrossPackageDependency(pkg, target))
+                return true;
+        }
+        return false;
+    }
+    getOverlappingFiles(filesA, filesB) {
+        const setB = new Set(filesB);
+        return filesA.filter((f) => setB.has(f));
+    }
+}
+/**
+ * Create a mock package graph for testing.
+ * @param packages - Map of file paths to package roots
+ * @param dependencies - Map of package roots to their dependencies
+ */
+export function createMockPackageGraph(packages, dependencies = new Map()) {
+    return {
+        findPackageRoot: (filePath) => packages.get(filePath) ?? null,
+        getPackageName: (packageRoot) => packageRoot,
+        hasCrossPackageDependency: (pkgA, pkgB) => {
+            const deps = dependencies.get(pkgA) ?? [];
+            return deps.includes(pkgB);
+        },
+        areInSamePackage: (filePathA, filePathB) => {
+            const pkgA = packages.get(filePathA);
+            const pkgB = packages.get(filePathB);
+            return pkgA !== null && pkgA === pkgB;
+        },
+    };
+}
+//# sourceMappingURL=independence.js.map

package/dist/esm/blueprint/dag/local/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * webpresso blueprint/dag/local
+ *
+ * Node.js-only DAG utilities for local CLI execution.
+ * These modules use `node:fs` and `node:path` — DO NOT import in Workers bundles.
+ *
+ * For workers-safe DAG utilities, use the parent `dag` subpath instead.
+ *
+ * @packageDocumentation
+ */
+export type { FalseDependency, ParallelizeResult, TaskFiles, TaskPairAnalysis, } from './independence.js';
+export { createMockPackageGraph, IndependenceDetector } from './independence.js';
+export { createMockFileSystem, PackageGraph, realFileSystem } from './package-graph.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/blueprint/dag/local/index.js

@@ -0,0 +1,14 @@
+/**
+ * webpresso blueprint/dag/local
+ *
+ * Node.js-only DAG utilities for local CLI execution.
+ * These modules use `node:fs` and `node:path` — DO NOT import in Workers bundles.
+ *
+ * For workers-safe DAG utilities, use the parent `dag` subpath instead.
+ *
+ * @packageDocumentation
+ */
+export { createMockPackageGraph, IndependenceDetector } from './independence.js';
+// Package Graph
+export { createMockFileSystem, PackageGraph, realFileSystem } from './package-graph.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/blueprint/dag/local/package-graph.d.ts

@@ -0,0 +1,66 @@
+import type { IFileSystem, IPackageGraph } from '#dag/interfaces';
+/**
+ * Default filesystem implementation using Node.js fs module.
+ */
+export declare const realFileSystem: IFileSystem;
+/**
+ * PackageGraph analyzes monorepo package structure for dependency detection.
+ *
+ * Used by the false dependency detector to determine if tasks can run in parallel
+ * based on package boundaries and cross-package dependencies.
+ *
+ * Implements IPackageGraph interface for testability - filesystem can be mocked.
+ */
+export declare class PackageGraph implements IPackageGraph {
+    private readonly root;
+    private readonly fs;
+    private readonly packageCache;
+    private readonly packageJsonCache;
+    constructor(root: string, fs?: IFileSystem);
+    /**
+     * Find the package root (directory containing package.json) for a file path.
+     * Walks up the directory tree until package.json is found.
+     *
+     * @param filePath - Relative path from monorepo root
+     * @returns Relative path to package root, or null if not found
+     */
+    findPackageRoot(filePath: string): string | null;
+    /**
+     * Get the package name from package.json.
+     *
+     * @param packageRoot - Relative path to package root
+     * @returns Package name or null if not found
+     */
+    getPackageName(packageRoot: string): string | null;
+    /**
+     * Check if package A has a dependency on package B.
+     *
+     * @param packageRootA - Relative path to first package
+     * @param packageRootB - Relative path to second package
+     * @returns True if A depends on B (directly)
+     */
+    hasCrossPackageDependency(packageRootA: string, packageRootB: string): boolean;
+    /**
+     * Check if two file paths belong to the same package.
+     *
+     * @param filePathA - First file path (relative)
+     * @param filePathB - Second file path (relative)
+     * @returns True if both files are in the same package
+     */
+    areInSamePackage(filePathA: string, filePathB: string): boolean;
+    /**
+     * Clear all caches. Useful for testing or when package structure changes.
+     */
+    clearCache(): void;
+    /**
+     * Get all cached package roots.
+     */
+    getCachedPackageRoots(): string[];
+    private loadPackageJson;
+}
+/**
+ * Create a mock filesystem for testing.
+ * @param files - Map of file paths to contents (or null for non-existent)
+ */
+export declare function createMockFileSystem(files: Map<string, string | null>): IFileSystem;
+//# sourceMappingURL=package-graph.d.ts.map

package/dist/esm/blueprint/dag/local/package-graph.js

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+/**
+ * Default filesystem implementation using Node.js fs module.
+ */
+export const realFileSystem = {
+    existsSync,
+    readFileSync: (path, encoding) => readFileSync(path, encoding),
+};
+/**
+ * PackageGraph analyzes monorepo package structure for dependency detection.
+ *
+ * Used by the false dependency detector to determine if tasks can run in parallel
+ * based on package boundaries and cross-package dependencies.
+ *
+ * Implements IPackageGraph interface for testability - filesystem can be mocked.
+ */
+export class PackageGraph {
+    root;
+    fs;
+    packageCache = new Map();
+    packageJsonCache = new Map();
+    constructor(root, fs = realFileSystem) {
+        this.root = root;
+        this.fs = fs;
+    }
+    /**
+     * Find the package root (directory containing package.json) for a file path.
+     * Walks up the directory tree until package.json is found.
+     *
+     * @param filePath - Relative path from monorepo root
+     * @returns Relative path to package root, or null if not found
+     */
+    findPackageRoot(filePath) {
+        if (this.packageCache.has(filePath)) {
+            return this.packageCache.get(filePath) ?? null;
+        }
+        let currentDir = dirname(join(this.root, filePath));
+        const rootAbs = this.root;
+        while (currentDir.length >= rootAbs.length) {
+            const pkgJsonPath = join(currentDir, 'package.json');
+            if (this.fs.existsSync(pkgJsonPath)) {
+                const result = relative(this.root, currentDir);
+                this.packageCache.set(filePath, result);
+                return result;
+            }
+            const parentDir = dirname(currentDir);
+            if (parentDir === currentDir)
+                break;
+            currentDir = parentDir;
+        }
+        this.packageCache.set(filePath, null);
+        return null;
+    }
+    /**
+     * Get the package name from package.json.
+     *
+     * @param packageRoot - Relative path to package root
+     * @returns Package name or null if not found
+     */
+    getPackageName(packageRoot) {
+        const pkgJson = this.loadPackageJson(packageRoot);
+        return pkgJson?.name ?? null;
+    }
+    /**
+     * Check if package A has a dependency on package B.
+     *
+     * @param packageRootA - Relative path to first package
+     * @param packageRootB - Relative path to second package
+     * @returns True if A depends on B (directly)
+     */
+    hasCrossPackageDependency(packageRootA, packageRootB) {
+        const pkgA = this.loadPackageJson(packageRootA);
+        const pkgB = this.loadPackageJson(packageRootB);
+        if (!pkgA || !pkgB)
+            return false;
+        const bName = pkgB.name;
+        const aDeps = {
+            ...pkgA.dependencies,
+            ...pkgA.devDependencies,
+        };
+        return bName in aDeps;
+    }
+    /**
+     * Check if two file paths belong to the same package.
+     *
+     * @param filePathA - First file path (relative)
+     * @param filePathB - Second file path (relative)
+     * @returns True if both files are in the same package
+     */
+    areInSamePackage(filePathA, filePathB) {
+        const pkgA = this.findPackageRoot(filePathA);
+        const pkgB = this.findPackageRoot(filePathB);
+        if (pkgA === null || pkgB === null)
+            return false;
+        return pkgA === pkgB;
+    }
+    /**
+     * Clear all caches. Useful for testing or when package structure changes.
+     */
+    clearCache() {
+        this.packageCache.clear();
+        this.packageJsonCache.clear();
+    }
+    /**
+     * Get all cached package roots.
+     */
+    getCachedPackageRoots() {
+        return Array.from(this.packageCache.values()).filter((v) => v !== null);
+    }
+    loadPackageJson(packageRoot) {
+        if (this.packageJsonCache.has(packageRoot)) {
+            return this.packageJsonCache.get(packageRoot) ?? null;
+        }
+        const pkgJsonPath = join(this.root, packageRoot, 'package.json');
+        if (!this.fs.existsSync(pkgJsonPath)) {
+            this.packageJsonCache.set(packageRoot, null);
+            return null;
+        }
+        try {
+            const content = this.fs.readFileSync(pkgJsonPath, 'utf-8');
+            const parsed = JSON.parse(content);
+            this.packageJsonCache.set(packageRoot, parsed);
+            return parsed;
+        }
+        catch {
+            this.packageJsonCache.set(packageRoot, null);
+            return null;
+        }
+    }
+}
+/**
+ * Create a mock filesystem for testing.
+ * @param files - Map of file paths to contents (or null for non-existent)
+ */
+export function createMockFileSystem(files) {
+    return {
+        existsSync: (path) => files.has(path) && files.get(path) !== null,
+        readFileSync: (path, _encoding) => {
+            const content = files.get(path);
+            if (content === null || content === undefined) {
+                throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+            }
+            return content;
+        },
+    };
+}
+//# sourceMappingURL=package-graph.js.map

package/dist/esm/blueprint/dag/plan-parser.d.ts

@@ -0,0 +1,54 @@
+import type { Task } from './types.js';
+/**
+ * Parsed task from an implementation plan
+ */
+export interface PlanTask {
+    id: string;
+    title: string;
+    description: string;
+    type: 'lint-fix' | 'typecheck-fix' | 'test-fix' | 'implement' | 'research' | 'verify';
+    package?: string;
+    file?: string;
+    dependsOn: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Plan parsing result
+ */
+export interface ParsedPlan {
+    title: string;
+    tasks: PlanTask[];
+    metadata: {
+        totalTasks: number;
+        maxParallelism: number;
+        criticalPathLength: number;
+    };
+}
+/**
+ * Parse implementation plan markdown into structured tasks.
+ *
+ * Supports formats:
+ * - Numbered lists with dependencies: `1. [depends: 2,3] Task description`
+ * - Task blocks with metadata
+ * - Checkbox lists: `- [ ] Task description`
+ *
+ * @example
+ * ```markdown
+ * # Implementation Plan
+ *
+ * ## Tasks
+ * 1. Fix lint errors in cli2
+ * 2. [depends: 1] Fix typecheck errors in cli2
+ * 3. [depends: 1] Fix typecheck errors in schema-engine
+ * 4. [depends: 2,3] Run full test suite
+ * ```
+ */
+export declare function parsePlan(markdown: string): ParsedPlan;
+/**
+ * Convert parsed plan tasks to Task format for executor
+ */
+export declare function planTasksToGraphTasks(planTasks: PlanTask[]): Array<{
+    task: Task<PlanTask>;
+    dependsOn?: string[];
+}>;
+//# sourceMappingURL=plan-parser.d.ts.map