@visulima/task-runner 0.0.1 → 1.0.0-alpha.1

package/dist/run-summary.d.ts

@@ -0,0 +1,89 @@
+import type { TaskGraph, TaskHashDetails, TaskResults } from "./types.d.ts";
+/**
+ * Summary of a single task execution.
+ */
+interface TaskSummary {
+    /** Whether the task was cacheable */
+    cacheable: boolean;
+    /** Cache status */
+    cacheStatus: "HIT" | "MISS" | "REMOTE_HIT" | "SKIPPED";
+    /** Dependencies on other tasks */
+    dependencies: string[];
+    /** Duration in milliseconds */
+    duration: number | undefined;
+    /** End time (ISO 8601) */
+    endTime: string | undefined;
+    /** Exit code */
+    exitCode: number | undefined;
+    /** The computed cache hash */
+    hash: string | undefined;
+    /** Detailed hash information */
+    hashDetails: TaskHashDetails | undefined;
+    /** The task's declared outputs */
+    outputs: string[];
+    /** Start time (ISO 8601) */
+    startTime: string | undefined;
+    /** The task target */
+    target: {
+        configuration?: string;
+        project: string;
+        target: string;
+    };
+    /** The task ID (e.g., "app:build") */
+    taskId: string;
+}
+/**
+ * Complete summary of a task runner execution.
+ */
+interface RunSummary {
+    /** Total duration in milliseconds */
+    duration: number;
+    /** Run end time (ISO 8601) */
+    endTime: string;
+    /** Environment info */
+    environment: {
+        /** Architecture */
+        arch: string;
+        /** Node.js version */
+        nodeVersion: string;
+        /** Platform */
+        platform: string;
+    };
+    /** Unique run ID */
+    id: string;
+    /** Run start time (ISO 8601) */
+    startTime: string;
+    /** Overall execution statistics */
+    stats: {
+        /** Number of cached tasks (local + remote) */
+        cached: number;
+        /** Number of failed tasks */
+        failed: number;
+        /** Number of skipped tasks */
+        skipped: number;
+        /** Number of successful tasks */
+        succeeded: number;
+        /** Total number of tasks */
+        total: number;
+    };
+    /** The task graph used for this run */
+    taskGraph: {
+        dependencies: Record<string, string[]>;
+        roots: string[];
+    };
+    /** Summary of each task */
+    tasks: TaskSummary[];
+}
+/**
+ * Generates a run summary from task results.
+ */
+declare const generateRunSummary: (results: TaskResults, taskGraph: TaskGraph, startTime: number) => RunSummary;
+/**
+ * Writes the run summary to a JSON file in the `.task-runner/runs/` directory.
+ * @param summary The run summary to write
+ * @param workspaceRoot The workspace root directory
+ * @returns The path to the written summary file
+ */
+declare const writeRunSummary: (summary: RunSummary, workspaceRoot: string) => Promise<string>;
+export type { RunSummary, TaskSummary };
+export { generateRunSummary, writeRunSummary };

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

@@ -0,0 +1,39 @@
+import type { TaskGraph } from "./types.d.ts";
+/**
+ * Finds a single cycle in the task graph, if one exists.
+ * Returns the cycle as an array of task IDs, or null if no cycle exists.
+ */
+export declare const findCycle: (taskGraph: TaskGraph) => string[] | undefined;
+/**
+ * Finds all cycles in the task graph.
+ */
+export declare const findCycles: (taskGraph: TaskGraph) => string[][];
+/**
+ * Walks the task graph in topological order (dependencies before dependents),
+ * calling the callback for each task.
+ *
+ * Note: If the graph contains cycles, tasks involved in cycles will not be visited.
+ * Use `findCycle` to detect cycles before walking if complete traversal is required.
+ */
+export declare const walkTaskGraph: (taskGraph: TaskGraph, callback: (taskId: string) => void) => void;
+/**
+ * Returns a reversed copy of the task graph (edges point in the opposite direction).
+ */
+export declare const reverseTaskGraph: (taskGraph: TaskGraph) => TaskGraph;
+/**
+ * Returns the leaf tasks (tasks with no dependencies of their own).
+ */
+export declare const getLeafTasks: (taskGraph: TaskGraph) => string[];
+/**
+ * Removes edges that form cycles, making the graph acyclic.
+ * Returns a new task graph without the cycle-forming edges.
+ */
+export declare const makeAcyclic: (taskGraph: TaskGraph) => TaskGraph;
+/**
+ * Gets all tasks that depend on the given task (directly or transitively).
+ */
+export declare const getDependentTasks: (taskGraph: TaskGraph, taskId: string) => string[];
+/**
+ * Gets all tasks that the given task depends on (directly or transitively).
+ */
+export declare const getTransitiveDependencies: (taskGraph: TaskGraph, taskId: string) => string[];

package/dist/task-graph.d.ts

@@ -0,0 +1,22 @@
+import type { ProjectGraph, TargetConfiguration, Task, TaskGraph, TaskTarget, WorkspaceConfiguration } from "./types.d.ts";
+interface CreateTaskGraphOptions {
+    /** The project graph */
+    projectGraph: ProjectGraph;
+    /** Target default configurations */
+    targetDefaults?: Record<string, Partial<TargetConfiguration>>;
+    /** The workspace configuration */
+    workspace: WorkspaceConfiguration;
+}
+/**
+ * Creates a unique task ID from a target.
+ */
+declare const getTaskId: (target: TaskTarget) => string;
+/**
+ * Parses a task ID into its component parts.
+ */
+declare const parseTaskId: (taskId: string) => TaskTarget;
+/**
+ * Creates a task graph from a list of tasks, resolving all dependencies.
+ */
+declare const createTaskGraph: (initialTasks: Task[], options: CreateTaskGraphOptions) => TaskGraph;
+export { createTaskGraph, getTaskId, parseTaskId };

package/dist/task-hasher.d.ts

@@ -0,0 +1,67 @@
+import type { NamedInputs, ProjectConfiguration, TargetConfiguration, Task, TaskHashDetails } from "./types.d.ts";
+/**
+ * Interface for task hashers.
+ */
+interface TaskHasher {
+    hashTask: (task: Task) => Promise<TaskHashDetails>;
+}
+/**
+ * Options for creating an InProcessTaskHasher.
+ */
+interface TaskHasherOptions {
+    /** Additional environment variables to include in hash */
+    envVars?: string[];
+    /**
+     * Enable framework environment variable inference.
+     * When true, auto-detects frameworks and includes their public
+     * env var prefixes in the task hash.
+     * @default false
+     */
+    frameworkInference?: boolean;
+    /**
+     * Global environment variables that invalidate all task hashes.
+     */
+    globalEnv?: string[];
+    /**
+     * Global input files that invalidate all task hashes when changed.
+     * These are workspace-root-relative paths (e.g., "pnpm-lock.yaml").
+     */
+    globalInputs?: string[];
+    /** Named input definitions */
+    namedInputs?: NamedInputs;
+    /** Project configurations keyed by project name */
+    projects: Record<string, ProjectConfiguration>;
+    /**
+     * Enable smart lockfile hashing.
+     * When true, instead of hashing the entire lockfile, only the resolved
+     * versions of a package's actual dependencies are hashed.
+     * This means changing the lockfile only busts cache for affected packages.
+     *
+     * Matches Turborepo's smart lockfile hashing behavior.
+     * @default false
+     */
+    smartLockfileHashing?: boolean;
+    /** Target default configurations */
+    targetDefaults?: Record<string, Partial<TargetConfiguration>>;
+    /** The workspace root directory */
+    workspaceRoot: string;
+}
+/**
+ * Computes hashes for tasks based on their inputs.
+ * Used to determine if a cached result can be reused.
+ */
+declare class InProcessTaskHasher implements TaskHasher {
+    #private;
+    constructor(options: TaskHasherOptions);
+    hashTask(task: Task): Promise<TaskHashDetails>;
+    clearCache(): void;
+}
+/**
+ * Computes the final hash for a task from its hash details.
+ * Uses native Rust xxh3-128 when available, otherwise pure TS xxh3-ts.
+ * Both produce identical xxh3-128 hashes, ensuring cache compatibility
+ * regardless of whether the native addon is loaded.
+ */
+declare const computeTaskHash: (hashDetails: TaskHashDetails) => string;
+export { computeTaskHash, InProcessTaskHasher };
+export type { TaskHasher, TaskHasherOptions };

package/dist/task-orchestrator.d.ts

@@ -0,0 +1,38 @@
+import type { Cache } from "./cache.d.ts";
+import type { RemoteCache } from "./remote-cache.d.ts";
+import type { TaskHasher } from "./task-hasher.d.ts";
+import type { TaskScheduler } from "./task-scheduler.d.ts";
+import type { LifeCycleInterface, Task, TaskExecutor, TaskResults } from "./types.d.ts";
+/**
+ * Options for the TaskOrchestrator.
+ */
+interface TaskOrchestratorOptions {
+    autoFingerprint?: boolean;
+    cache: Cache;
+    cacheDiagnostics?: boolean;
+    captureOutput?: boolean;
+    dryRun?: boolean;
+    fingerprintEnvPatterns?: string[];
+    lifeCycle: LifeCycleInterface;
+    remoteCache?: RemoteCache;
+    resolveCommand?: (task: Task) => string | undefined;
+    scheduler: TaskScheduler;
+    skipCache?: boolean;
+    summarize?: boolean;
+    taskExecutor: TaskExecutor;
+    taskGraph?: import("./types").TaskGraph;
+    taskHasher: TaskHasher;
+    untrackedEnvVars?: string[];
+    workspaceRoot: string;
+}
+/**
+ * Orchestrates the execution of tasks, handling caching,
+ * scheduling, and lifecycle events.
+ */
+declare class TaskOrchestrator {
+    #private;
+    constructor(options: TaskOrchestratorOptions);
+    run(): Promise<TaskResults>;
+}
+export { TaskOrchestrator };
+export type { TaskOrchestratorOptions };

package/dist/task-scheduler.d.ts

@@ -0,0 +1,18 @@
+import type { ProjectGraph, Task, TaskGraph } from "./types.d.ts";
+/**
+ * Manages the scheduling order of tasks based on dependencies,
+ * parallelism constraints, and estimated execution times.
+ */
+export declare class TaskScheduler {
+    #private;
+    constructor(taskGraph: TaskGraph, projectGraph: ProjectGraph, maxParallel?: number);
+    /**
+     * Returns the next batch of tasks that are ready to execute.
+     */
+    getNextBatch(): Task[];
+    startTask(taskId: string): void;
+    completeTask(taskId: string): void;
+    isComplete(): boolean;
+    get remainingCount(): number;
+    get runningCount(): number;
+}

package/dist/tracked-executor.d.ts

@@ -0,0 +1,46 @@
+import type { FileAccess } from "./file-access-tracker.d.ts";
+import type { Task, TaskExecutionOptions } from "./types.d.ts";
+/**
+ * Result of a tracked task execution.
+ */
+export interface TrackedExecutionResult {
+    /** File accesses recorded during execution */
+    accesses: FileAccess[];
+    /** The command exit code */
+    code: number;
+    /** The command stdout + stderr output */
+    terminalOutput: string;
+}
+/**
+ * A task executor that tracks file accesses during command execution.
+ *
+ * Tracking strategies (in priority order):
+ * 1. **Linux**: strace-based syscall interception (most complete)
+ * 2. **macOS/Windows**: Node.js preload script that patches `fs` module
+ * (works for Node.js processes, not native binaries)
+ * 3. **Fallback**: No tracking (accesses array will be empty)
+ */
+export declare class TrackedTaskExecutor {
+    #private;
+    constructor(workspaceRoot: string);
+    /**
+     * Returns true if file access tracking is supported on the current platform.
+     * strace tracking (Linux) or preload script (any Node.js process).
+     */
+    get isTrackingSupported(): boolean;
+    /**
+     * Returns true if the platform supports full syscall-level tracking (strace).
+     */
+    get isStraceSupported(): boolean;
+    /**
+     * Executes a task command and tracks all file system accesses.
+     *
+     * On Linux, uses strace for comprehensive tracking.
+     * On other platforms, uses a Node.js preload script (for Node processes).
+     */
+    execute(task: Task, options: TaskExecutionOptions, command: string): Promise<TrackedExecutionResult>;
+    /**
+     * Kills all active child processes. Called on abort/signal to prevent orphans.
+     */
+    killAll(): void;
+}