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

package/dist/file-access-tracker.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Represents a file access recorded during task execution.
+ */
+export interface FileAccess {
+    /** The absolute path of the file */
+    path: string;
+    /** The type of access */
+    type: "read" | "stat" | "readdir" | "missing";
+}
+/**
+ * Result of tracking file accesses during a command execution.
+ */
+export interface TrackingResult {
+    /** All file accesses recorded */
+    accesses: FileAccess[];
+    /** The command exit code */
+    code: number;
+    /** The command stdout + stderr output */
+    output: string;
+}
+/**
+ * Tracks which files a child process accesses during execution.
+ *
+ * Uses `strace` on Linux to intercept syscalls (open, openat, stat, lstat, access, getdents).
+ * Falls back to no tracking on unsupported platforms.
+ */
+export declare class FileAccessTracker {
+    #private;
+    constructor(workspaceRoot: string, excludePatterns?: RegExp[]);
+    /**
+     * Returns true if file access tracking is supported on the current platform.
+     */
+    isSupported(): boolean;
+    /**
+     * Runs a command and tracks all file system accesses.
+     * On unsupported platforms, runs the command without tracking.
+     */
+    track(command: string, options?: {
+        cwd?: string;
+        env?: Record<string, string | undefined>;
+    }): Promise<TrackingResult>;
+    /**
+     * Kills all active child processes. Called on abort/signal to prevent orphans.
+     */
+    killAll(): void;
+}
+/**
+ * Generates a preload script that can be used with NODE_OPTIONS to
+ * track file accesses in Node.js child processes.
+ *
+ * This is an alternative to strace that works cross-platform for Node.js processes.
+ */
+export declare const generatePreloadScript: (outputPath: string) => string;

package/dist/fingerprint.d.ts

@@ -0,0 +1,45 @@
+import type { FileAccess } from "./file-access-tracker.d.ts";
+/**
+ * Represents a stored fingerprint for a task execution.
+ */
+export interface TaskFingerprint {
+    /** Hash of the command arguments */
+    commandHash: string;
+    /** Directory listings recorded during execution (path -> sorted entries) */
+    directoryListings: Record<string, string[]>;
+    /** Hashes of fingerprinted environment variables */
+    envHashes: Record<string, string>;
+    /** Content hashes of files that were read during execution */
+    fileHashes: Record<string, string>;
+    /** Paths of files that were probed but didn't exist (ENOENT) */
+    missingFiles: string[];
+}
+/**
+ * Describes why a cache miss occurred.
+ */
+export interface CacheMissReason {
+    currentHash?: string;
+    detail: string;
+    previousHash?: string;
+    type: "file-changed" | "file-created" | "file-deleted" | "directory-changed" | "env-changed" | "args-changed" | "no-fingerprint";
+}
+/**
+ * Manages task fingerprints for auto-detection caching.
+ *
+ * Records which files a task accesses during execution, stores content
+ * hashes, and on subsequent runs checks if any accessed file has changed.
+ */
+export declare class FingerprintManager {
+    #private;
+    constructor(workspaceRoot: string);
+    createFingerprint(accesses: FileAccess[], command: string, args: Record<string, unknown>, envVariables: Record<string, string | undefined>, envPatterns?: string[], untrackedEnvVariables?: string[]): Promise<TaskFingerprint>;
+    /**
+     * Validates a stored fingerprint against the current state.
+     * Returns null if valid (cache hit), or an array of reasons (cache miss).
+     *
+     * Does NOT use the file hash cache — validation must see current disk state.
+     */
+    validate(fingerprint: TaskFingerprint): Promise<CacheMissReason[] | undefined>;
+    validateCommand(fingerprint: TaskFingerprint, command: string, args: Record<string, unknown>): CacheMissReason | undefined;
+    formatMissReasons(reasons: CacheMissReason[]): string;
+}

package/dist/framework-inference.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Detected framework information.
+ */
+interface DetectedFramework {
+    /** The env var prefix(es) that should be included in task hashes */
+    envPrefixes: string[];
+    /** The framework name */
+    name: string;
+}
+/**
+ * Detects frameworks used in a project by inspecting its package.json dependencies.
+ * @param packageJsonPath Absolute path to the package.json file
+ * @returns Array of detected frameworks with their env prefixes
+ */
+declare const detectFrameworks: (packageJsonPath: string) => Promise<DetectedFramework[]>;
+/**
+ * Detects frameworks across all projects in a workspace and returns
+ * the env var patterns that should be included in task hashes.
+ * @param workspaceRoot The workspace root directory
+ * @param projects Map of project name to project configuration with root paths
+ * @returns Array of env var wildcard patterns (e.g., ["NEXT_PUBLIC_*", "VITE_*"])
+ */
+declare const inferFrameworkEnvPatterns: (workspaceRoot: string, projects: Record<string, {
+    root: string;
+}>) => Promise<string[]>;
+/**
+ * For a specific project, detects frameworks and returns the matching
+ * env vars from the current environment.
+ * @param packageJsonPath Absolute path to the project's package.json
+ * @param env The current environment variables
+ * @returns Map of env var name to value for matching framework env vars
+ */
+declare const getFrameworkEnvVariables: (packageJsonPath: string, env?: Record<string, string | undefined>) => Promise<Record<string, string>>;
+export type { DetectedFramework };
+export { detectFrameworks, getFrameworkEnvVariables, inferFrameworkEnvPatterns };

package/dist/graph-visualizer.d.ts

@@ -0,0 +1,74 @@
+import type { ProjectGraph, TaskGraph } from "./types.d.ts";
+/**
+ * Graph visualization output formats.
+ */
+type GraphFormat = "dot" | "json" | "html" | "ascii";
+/**
+ * Options for graph visualization.
+ */
+interface GraphVisualizerOptions {
+    /** Show only affected/filtered tasks (highlight subset) */
+    focusedTasks?: string[];
+    /** Group tasks by project (default: true) */
+    groupByProject?: boolean;
+    /** Show task status colors (requires results) */
+    taskStatuses?: Map<string, "success" | "failure" | "skipped" | "local-cache" | "local-cache-kept-existing" | "remote-cache" | "running" | "pending">;
+}
+/**
+ * Exports a task graph in DOT format for Graphviz rendering.
+ * @example
+ * ```ts
+ * const dot = toGraphvizDot(taskGraph);
+ * // Render: dot -Tsvg -o graph.svg <<< "$dot"
+ * ```
+ */
+declare const toGraphvizDot: (taskGraph: TaskGraph, options?: GraphVisualizerOptions) => string;
+/**
+ * Exports the task graph as a JSON object suitable for visualization tools.
+ */
+interface GraphJson {
+    edges: {
+        source: string;
+        target: string;
+    }[];
+    nodes: {
+        configuration?: string;
+        id: string;
+        project: string;
+        status?: string;
+        target: string;
+    }[];
+    roots: string[];
+}
+declare const toGraphJson: (taskGraph: TaskGraph, taskStatuses?: Map<string, string>) => {
+    edges: GraphJson["edges"];
+    nodes: GraphJson["nodes"];
+    roots: string[];
+};
+/**
+ * Generates a self-contained HTML file with an interactive task graph visualization.
+ * Uses a simple force-directed layout with SVG rendering (no external dependencies).
+ */
+declare const toGraphHtml: (taskGraph: TaskGraph, options?: GraphVisualizerOptions) => string;
+/**
+ * Renders the task graph as ASCII art for terminal display.
+ * @example
+ * ```
+ * Task Graph (6 tasks, 5 dependencies)
+ *
+ * app:build
+ * ├── lib-a:build
+ * │   └── lib-core:build
+ * └── lib-b:build
+ *     └── lib-core:build (*)
+ *
+ * (*) = already shown above
+ * ```
+ */
+declare const toGraphAscii: (taskGraph: TaskGraph, options?: GraphVisualizerOptions) => string;
+/**
+ * Exports a project graph in DOT format.
+ */
+declare const projectGraphToDot: (projectGraph: ProjectGraph) => string;
+export type { GraphFormat, GraphJson, GraphVisualizerOptions };
+export { projectGraphToDot, toGraphAscii, toGraphHtml, toGraphJson, toGraphvizDot };

package/dist/incremental-hasher.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Incremental file hasher that only re-hashes files that have changed
+ * since the last run, based on mtime comparison.
+ *
+ * This is the key performance optimization used by Nx's daemon and
+ * Turborepo's daemon — on subsequent runs, only files whose mtime
+ * changed need to be re-read and re-hashed.
+ *
+ * The snapshot (path → { mtime, hash }) is kept in memory and can
+ * optionally be persisted to disk for cross-process reuse.
+ */
+interface FileSnapshot {
+    /** xxh3-128 hash of file contents */
+    hash: string;
+    /** Last modification time in milliseconds */
+    mtimeMs: number;
+    /** File size in bytes (fast pre-check) */
+    size: number;
+}
+interface IncrementalHasherOptions {
+    /** Directories to skip (default: node_modules, .git, dist, coverage, .cache) */
+    ignoredDirs?: Set<string>;
+    /** File to persist the snapshot to (for cross-run reuse) */
+    snapshotPath?: string;
+    workspaceRoot: string;
+}
+declare class IncrementalFileHasher {
+    #private;
+    constructor(options: IncrementalHasherOptions);
+    /**
+     * Loads the snapshot from disk if available.
+     * Called automatically on first use.
+     */
+    load(): Promise<void>;
+    /**
+     * Persists the current snapshot to disk for cross-run reuse.
+     */
+    save(): Promise<void>;
+    /**
+     * Incrementally hashes all files in a directory.
+     *
+     * Only files whose mtime or size changed since the last snapshot
+     * are re-read and re-hashed. Unchanged files reuse the cached hash.
+     *
+     * Returns a map of relative paths → hashes.
+     */
+    hashDirectory(directoryPath: string): Promise<Record<string, string>>;
+    /**
+     * Returns how many files are in the snapshot (for diagnostics).
+     */
+    get snapshotSize(): number;
+    /**
+     * Clears the in-memory snapshot.
+     */
+    clear(): void;
+}
+export type { FileSnapshot, IncrementalHasherOptions };
+export { IncrementalFileHasher };

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+export type { AffectedOptions, AffectedResult } from "./affected.d.ts";
+export { filterAffectedTasks, getAffectedProjects, getChangedFiles } from "./affected.d.ts";
+export type { CachedResult, CacheOptions } from "./cache.d.ts";
+export { Cache, formatCacheSize, parseCacheSize } from "./cache.d.ts";
+export { defaultTaskRunner } from "./default-task-runner.d.ts";
+export type { FileAccess, TrackingResult } from "./file-access-tracker.d.ts";
+export { FileAccessTracker, generatePreloadScript } from "./file-access-tracker.d.ts";
+export type { CacheMissReason, TaskFingerprint } from "./fingerprint.d.ts";
+export { FingerprintManager } from "./fingerprint.d.ts";
+export type { DetectedFramework } from "./framework-inference.d.ts";
+export { detectFrameworks, getFrameworkEnvVariables, inferFrameworkEnvPatterns } from "./framework-inference.d.ts";
+export type { GraphFormat, GraphJson, GraphVisualizerOptions } from "./graph-visualizer.d.ts";
+export { projectGraphToDot, toGraphAscii, toGraphHtml, toGraphJson, toGraphvizDot } from "./graph-visualizer.d.ts";
+export type { FileSnapshot, IncrementalHasherOptions } from "./incremental-hasher.d.ts";
+export { IncrementalFileHasher } from "./incremental-hasher.d.ts";
+export { CompositeLifeCycle, ConsoleLifeCycle, EmptyLifeCycle } from "./life-cycle.d.ts";
+export type { PackageLockfileHash, ResolvedDependency } from "./lockfile-hasher.d.ts";
+export { extractPackageName, LockfileHasher, parseNpmLockfile, parsePnpmLockfile, parseYarnLockfile } from "./lockfile-hasher.d.ts";
+export { isNativeAvailable, loadNativeBindings } from "./native-binding.d.ts";
+export type { RemoteCacheOptions } from "./remote-cache.d.ts";
+export { RemoteCache } from "./remote-cache.d.ts";
+export type { RunSummary, TaskSummary } from "./run-summary.d.ts";
+export { generateRunSummary, writeRunSummary } from "./run-summary.d.ts";
+export { createTaskGraph, getTaskId, parseTaskId } from "./task-graph.d.ts";
+export { findCycle, findCycles, getDependentTasks, getLeafTasks, getTransitiveDependencies, makeAcyclic, reverseTaskGraph, walkTaskGraph, } from "./task-graph-utils.d.ts";
+export type { TaskHasher, TaskHasherOptions } from "./task-hasher.d.ts";
+export { computeTaskHash, InProcessTaskHasher } from "./task-hasher.d.ts";
+export type { TaskOrchestratorOptions } from "./task-orchestrator.d.ts";
+export { TaskOrchestrator } from "./task-orchestrator.d.ts";
+export { TaskScheduler } from "./task-scheduler.d.ts";
+export type { TrackedExecutionResult } from "./tracked-executor.d.ts";
+export { TrackedTaskExecutor } from "./tracked-executor.d.ts";
+export type { EnvironmentInput, ExternalDependencyInput, FileSetInput, InputDefinition, LifeCycleInterface, NamedInputs, ProjectConfiguration, ProjectGraph, ProjectGraphDependency, ProjectGraphProjectNode, RuntimeInput, TargetConfiguration, TargetDependencyConfig, Task, TaskExecutionOptions, TaskExecutor, TaskGraph, TaskHashDetails, TaskResult, TaskResults, TaskRunnerContext, TaskRunnerOptions, TasksRunner, TaskStatus, TaskTarget, WorkspaceConfiguration, } from "./types.d.ts";
+export { collectFiles, createFailureResult, hashFile, hashStrings, readPackageDeps, resolveTaskCwd, sortObjectKeys, uniqueId } from "./utils.d.ts";

package/dist/index.js

@@ -0,0 +1,20 @@
+export { filterAffectedTasks, getAffectedProjects, getChangedFiles } from './packem_shared/filterAffectedTasks-I-18zPg6.js';
+export { Cache, formatCacheSize, parseCacheSize } from './packem_shared/Cache-IYpTYVUC.js';
+export { defaultTaskRunner } from './packem_shared/defaultTaskRunner-CrW4v5Ye.js';
+export { FileAccessTracker, generatePreloadScript } from './packem_shared/FileAccessTracker-CrtBAt5D.js';
+export { FingerprintManager } from './packem_shared/FingerprintManager-D6Y0erg-.js';
+export { detectFrameworks, getFrameworkEnvVariables, inferFrameworkEnvPatterns } from './packem_shared/detectFrameworks-CeFzKE6J.js';
+export { projectGraphToDot, toGraphAscii, toGraphHtml, toGraphJson, toGraphvizDot } from './packem_shared/projectGraphToDot-VdTjHcVp.js';
+export { IncrementalFileHasher } from './packem_shared/IncrementalFileHasher-Ds3J6dgb.js';
+export { CompositeLifeCycle, ConsoleLifeCycle, EmptyLifeCycle } from './packem_shared/CompositeLifeCycle-7AtYw1dv.js';
+export { LockfileHasher, extractPackageName, parseNpmLockfile, parsePnpmLockfile, parseYarnLockfile } from './packem_shared/extractPackageName-CbVNW-dr.js';
+export { isNativeAvailable, loadNativeBindings } from './packem_shared/isNativeAvailable-BWhnZ4ES.js';
+export { RemoteCache } from './packem_shared/RemoteCache-BDqrnDEi.js';
+export { generateRunSummary, writeRunSummary } from './packem_shared/generateRunSummary-qn-_jKwt.js';
+export { createTaskGraph, getTaskId, parseTaskId } from './packem_shared/createTaskGraph-CcsFaSrz.js';
+export { findCycle, findCycles, getDependentTasks, getLeafTasks, getTransitiveDependencies, makeAcyclic, reverseTaskGraph, walkTaskGraph } from './packem_shared/findCycle-DF4_BRdO.js';
+export { InProcessTaskHasher, computeTaskHash } from './packem_shared/computeTaskHash-BoCnnvIJ.js';
+export { TaskOrchestrator } from './packem_shared/TaskOrchestrator-BvYs3ONw.js';
+export { TaskScheduler } from './packem_shared/TaskScheduler-CJilHDta.js';
+export { TrackedTaskExecutor } from './packem_shared/TrackedTaskExecutor-BGUKFE-7.js';
+export { c as collectFiles, a as createFailureResult, h as hashFile, b as hashStrings, r as readPackageDeps, d as resolveTaskCwd, s as sortObjectKeys, u as uniqueId } from './packem_shared/utils-zO0ZRgtf.js';

package/dist/life-cycle.d.ts

@@ -0,0 +1,36 @@
+import type { LifeCycleInterface, Task, TaskResult, TaskStatus } from "./types.d.ts";
+/**
+ * Combines multiple lifecycle handlers into one.
+ * Each event is forwarded to all registered handlers.
+ */
+declare class CompositeLifeCycle implements LifeCycleInterface {
+    #private;
+    constructor(lifeCycles: LifeCycleInterface[]);
+    startCommand(): void;
+    endCommand(): void;
+    scheduleTask(task: Task): void;
+    startTasks(tasks: Task[]): void;
+    endTasks(taskResults: TaskResult[]): void;
+    printTaskTerminalOutput(task: Task, status: TaskStatus, terminalOutput: string): void;
+    printCacheMiss(task: Task, reasons: string): void;
+}
+/**
+ * A lifecycle handler that logs task progress to the console.
+ */
+declare class ConsoleLifeCycle implements LifeCycleInterface {
+    #private;
+    constructor(verbose?: boolean);
+    startCommand(): void;
+    endCommand(): void;
+    scheduleTask(task: Task): void;
+    startTasks(tasks: Task[]): void;
+    endTasks(taskResults: TaskResult[]): void;
+    printTaskTerminalOutput(_task: Task, _status: TaskStatus, terminalOutput: string): void;
+    printCacheMiss(task: Task, reasons: string): void;
+}
+/**
+ * A no-op lifecycle handler. Useful as a default.
+ */
+declare class EmptyLifeCycle implements LifeCycleInterface {
+}
+export { CompositeLifeCycle, ConsoleLifeCycle, EmptyLifeCycle };

package/dist/lockfile-hasher.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Resolved dependency entry from a lockfile.
+ */
+interface ResolvedDependency {
+    /** The package name */
+    name: string;
+    /** The resolved version */
+    version: string;
+}
+/**
+ * Result of parsing a lockfile for a specific package.
+ */
+interface PackageLockfileHash {
+    /** The resolved dependencies that were included in the hash */
+    dependencies: ResolvedDependency[];
+    /** Hash of the resolved dependencies relevant to this package */
+    hash: string;
+}
+/**
+ * Extracts a package name from a node_modules path.
+ * E.g., "node_modules/@scope/name" -> "@scope/name",
+ * "node_modules/name" -> "name",
+ * "node_modules/.package-lock.json" -> undefined.
+ */
+declare const extractPackageName: (path: string) => string | undefined;
+/**
+ * Parses package-lock.json (npm v2/v3 format) to extract resolved versions.
+ * The v2/v3 format uses a flat "packages" map with paths like "node_modules/pkg-name".
+ */
+declare const parseNpmLockfile: (content: string) => Map<string, string>;
+/**
+ * Parses pnpm-lock.yaml to extract resolved versions.
+ * Uses a lightweight regex-based parser to avoid a YAML dependency.
+ */
+declare const parsePnpmLockfile: (content: string) => Map<string, string>;
+/**
+ * Parses yarn.lock to extract resolved versions.
+ * Works with both Yarn Classic (v1) and Berry (v2+) formats.
+ */
+declare const parseYarnLockfile: (content: string) => Map<string, string>;
+/**
+ * Smart lockfile hasher that only hashes the resolved versions
+ * of a package's actual dependencies, not the entire lockfile.
+ *
+ * This matches Turborepo's smart lockfile hashing behavior:
+ * changing the lockfile only busts cache for affected packages.
+ *
+ * Supports:
+ * - package-lock.json (npm v2/v3)
+ * - pnpm-lock.yaml (pnpm)
+ * - yarn.lock (Yarn Classic + Berry)
+ */
+declare class LockfileHasher {
+    #private;
+    constructor(workspaceRoot: string);
+    /**
+     * Computes a hash based only on the resolved dependency versions
+     * relevant to a specific package.
+     * @param packageJsonPath Path to the package.json (relative to workspace root)
+     * @returns Hash of the relevant lockfile entries, or undefined if no lockfile found
+     */
+    hashForPackage(packageJsonPath: string): Promise<PackageLockfileHash | undefined>;
+    /**
+     * Returns the type of lockfile detected, or undefined if none found.
+     */
+    get lockfileType(): "npm" | "pnpm" | "yarn" | undefined;
+    /**
+     * Clears the cached lockfile data.
+     */
+    clearCache(): void;
+}
+export type { PackageLockfileHash, ResolvedDependency };
+export { extractPackageName, LockfileHasher, parseNpmLockfile, parsePnpmLockfile, parseYarnLockfile };

package/dist/native-binding.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Optional native bindings for performance-critical operations.
+ *
+ * The native addon (Rust via napi-rs) provides:
+ * - Parallel file hashing using rayon + xxHash xxh3-128
+ * - Optimized task hash computation
+ * - Fast graph operations (cycle detection, topological sort)
+ *
+ * Falls back to pure TypeScript implementations when the native
+ * addon is not available (not compiled, wrong platform, etc.).
+ *
+ * Build with: pnpm build:native
+ * The napi v3 CLI outputs the .node file to the package root.
+ */
+interface NativeFileHash {
+    hash: string;
+    path: string;
+}
+interface NativeTaskHashDetails {
+    command: string;
+    implicit_deps?: string[][];
+    nodes: string[][];
+    runtime?: string[][];
+}
+interface NativeTaskGraph {
+    edges: string[][];
+    task_ids: string[];
+}
+interface NativeCycleResult {
+    cycle: string[];
+    has_cycle: boolean;
+}
+interface NativeBindings {
+    collectFiles: (directory: string) => string[];
+    computeTaskHash: (details: NativeTaskHashDetails) => string;
+    findAllCycles: (graph: NativeTaskGraph) => string[][];
+    findBackEdges: (graph: NativeTaskGraph) => string[][];
+    findCycle: (graph: NativeTaskGraph) => NativeCycleResult;
+    getDependentTasks: (graph: NativeTaskGraph, taskId: string) => string[];
+    getTransitiveDeps: (graph: NativeTaskGraph, taskId: string) => string[];
+    hashCommand: (project: string, target: string, configuration: string | undefined, overridesJson: string) => string;
+    hashEnvVar: (name: string, value: string) => string;
+    hashFile: (filePath: string) => string;
+    hashFilesBatch: (filePaths: string[], workspaceRoot: string) => NativeFileHash[];
+    hashFilesInDirectory: (directory: string, workspaceRoot: string) => NativeFileHash[];
+    hashString: (input: string) => string;
+    hashStrings: (inputs: string[]) => string;
+    topologicalSort: (graph: NativeTaskGraph) => string[];
+}
+/**
+ * Attempts to load the native addon. Returns undefined if unavailable.
+ * The result is cached after the first attempt.
+ *
+ * napi v3 outputs the .node file to the package root as
+ * `task-runner-native.<platform>.node`. The napi-generated binding.js
+ * handles platform detection automatically.
+ */
+declare const loadNativeBindings: () => NativeBindings | undefined;
+/**
+ * Returns true if the native addon is loaded and available.
+ */
+declare const isNativeAvailable: () => boolean;
+export type { NativeBindings, NativeCycleResult, NativeFileHash, NativeTaskGraph, NativeTaskHashDetails };
+export { isNativeAvailable, loadNativeBindings };