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

package/binding.js

@@ -1,204 +0,0 @@
-/* eslint-disable */
-/* auto-generated binding loader for @visulima/task-runner native addon */
-
-const { existsSync, readFileSync } = require("node:fs");
-const { join } = require("node:path");
-
-const { platform, arch } = process;
-
-let nativeBinding = null;
-let localFileExisted = false;
-let loadError = null;
-
-function isMusl() {
-    // For Node 12+, check report.header for musl
-    if (
-        typeof process.report !== "undefined" &&
-        typeof process.report.getReport === "function"
-    ) {
-        const { glibcVersionRuntime } = process.report.getReport().header;
-        if (glibcVersionRuntime) {
-            return false;
-        }
-        return true;
-    }
-
-    try {
-        const lddOutput = readFileSync("/usr/bin/ldd", "utf8");
-        return lddOutput.includes("musl");
-    } catch {
-        try {
-            return readFileSync("/proc/self/map_files/../maps", "utf8").includes(
-                "musl"
-            );
-        } catch {
-            return false;
-        }
-    }
-}
-
-switch (platform) {
-    case "darwin":
-        switch (arch) {
-            case "x64":
-                localFileExisted = existsSync(
-                    join(__dirname, "task-runner-native.darwin-x64.node")
-                );
-                try {
-                    if (localFileExisted) {
-                        nativeBinding = require("./task-runner-native.darwin-x64.node");
-                    } else {
-                        nativeBinding = require("@visulima/task-runner-binding-darwin-x64");
-                    }
-                } catch (e) {
-                    loadError = e;
-                }
-                break;
-            case "arm64":
-                localFileExisted = existsSync(
-                    join(__dirname, "task-runner-native.darwin-arm64.node")
-                );
-                try {
-                    if (localFileExisted) {
-                        nativeBinding = require("./task-runner-native.darwin-arm64.node");
-                    } else {
-                        nativeBinding = require("@visulima/task-runner-binding-darwin-arm64");
-                    }
-                } catch (e) {
-                    loadError = e;
-                }
-                break;
-            default:
-                throw new Error(`Unsupported architecture on macOS: ${arch}`);
-        }
-        break;
-    case "linux":
-        switch (arch) {
-            case "x64":
-                if (isMusl()) {
-                    localFileExisted = existsSync(
-                        join(
-                            __dirname,
-                            "task-runner-native.linux-x64-musl.node"
-                        )
-                    );
-                    try {
-                        if (localFileExisted) {
-                            nativeBinding = require("./task-runner-native.linux-x64-musl.node");
-                        } else {
-                            nativeBinding = require("@visulima/task-runner-binding-linux-x64-musl");
-                        }
-                    } catch (e) {
-                        loadError = e;
-                    }
-                } else {
-                    localFileExisted = existsSync(
-                        join(
-                            __dirname,
-                            "task-runner-native.linux-x64-gnu.node"
-                        )
-                    );
-                    try {
-                        if (localFileExisted) {
-                            nativeBinding = require("./task-runner-native.linux-x64-gnu.node");
-                        } else {
-                            nativeBinding = require("@visulima/task-runner-binding-linux-x64-gnu");
-                        }
-                    } catch (e) {
-                        loadError = e;
-                    }
-                }
-                break;
-            case "arm64":
-                if (isMusl()) {
-                    localFileExisted = existsSync(
-                        join(
-                            __dirname,
-                            "task-runner-native.linux-arm64-musl.node"
-                        )
-                    );
-                    try {
-                        if (localFileExisted) {
-                            nativeBinding = require("./task-runner-native.linux-arm64-musl.node");
-                        } else {
-                            nativeBinding = require("@visulima/task-runner-binding-linux-arm64-musl");
-                        }
-                    } catch (e) {
-                        loadError = e;
-                    }
-                } else {
-                    localFileExisted = existsSync(
-                        join(
-                            __dirname,
-                            "task-runner-native.linux-arm64-gnu.node"
-                        )
-                    );
-                    try {
-                        if (localFileExisted) {
-                            nativeBinding = require("./task-runner-native.linux-arm64-gnu.node");
-                        } else {
-                            nativeBinding = require("@visulima/task-runner-binding-linux-arm64-gnu");
-                        }
-                    } catch (e) {
-                        loadError = e;
-                    }
-                }
-                break;
-            default:
-                throw new Error(`Unsupported architecture on Linux: ${arch}`);
-        }
-        break;
-    case "win32":
-        switch (arch) {
-            case "x64":
-                localFileExisted = existsSync(
-                    join(
-                        __dirname,
-                        "task-runner-native.win32-x64-msvc.node"
-                    )
-                );
-                try {
-                    if (localFileExisted) {
-                        nativeBinding = require("./task-runner-native.win32-x64-msvc.node");
-                    } else {
-                        nativeBinding = require("@visulima/task-runner-binding-win32-x64-msvc");
-                    }
-                } catch (e) {
-                    loadError = e;
-                }
-                break;
-            case "arm64":
-                localFileExisted = existsSync(
-                    join(
-                        __dirname,
-                        "task-runner-native.win32-arm64-msvc.node"
-                    )
-                );
-                try {
-                    if (localFileExisted) {
-                        nativeBinding = require("./task-runner-native.win32-arm64-msvc.node");
-                    } else {
-                        nativeBinding = require("@visulima/task-runner-binding-win32-arm64-msvc");
-                    }
-                } catch (e) {
-                    loadError = e;
-                }
-                break;
-            default:
-                throw new Error(`Unsupported architecture on Windows: ${arch}`);
-        }
-        break;
-    default:
-        throw new Error(
-            `Unsupported OS: ${platform}, architecture: ${arch}`
-        );
-}
-
-if (!nativeBinding) {
-    if (loadError) {
-        throw loadError;
-    }
-    throw new Error("Failed to load native binding");
-}
-
-module.exports = nativeBinding;

package/dist/affected.d.ts

@@ -1,48 +0,0 @@
-import type { ProjectConfiguration, ProjectGraph } from "./types.d.ts";
-/**
- * Options for determining affected projects.
- */
-interface AffectedOptions {
-    /** The base ref to compare against (default: "main") */
-    base?: string;
-    /** The head ref to compare (default: "HEAD") */
-    head?: string;
-    /** Project graph for dependency resolution */
-    projectGraph: ProjectGraph;
-    /** All project configurations keyed by name */
-    projects: Record<string, ProjectConfiguration>;
-    /** The workspace root directory */
-    workspaceRoot: string;
-}
-/**
- * Result of affected detection.
- */
-interface AffectedResult {
-    /** Projects affected by changes (including transitive dependents) */
-    affectedProjects: string[];
-    /** Files that changed between base and head */
-    changedFiles: string[];
-    /** Projects that were directly changed */
-    changedProjects: string[];
-}
-/**
- * Gets the list of files changed between two git refs.
- * Uses execFile with argument arrays to prevent command injection.
- */
-declare const getChangedFiles: (workspaceRoot: string, base: string, head: string) => Promise<string[]>;
-/**
- * Determines which projects are affected by changes between two git refs.
- *
- * Uses `git diff` to find changed files, maps them to projects based on
- * project roots, then walks the project dependency graph to find all
- * transitively affected projects.
- *
- * This is the same strategy used by `nx affected` and `turbo run --filter=[base...]`.
- */
-declare const getAffectedProjects: (options: AffectedOptions) => Promise<AffectedResult>;
-/**
- * Filters tasks to only include those that are affected by changes.
- */
-declare const filterAffectedTasks: (taskIds: string[], affectedProjects: Set<string>) => string[];
-export type { AffectedOptions, AffectedResult };
-export { filterAffectedTasks, getAffectedProjects, getChangedFiles };

package/dist/cache.d.ts

@@ -1,103 +0,0 @@
-import type { TaskFingerprint } from "./fingerprint.d.ts";
-/**
- * Represents a cached task result.
- */
-interface CachedResult {
-    /** The exit code of the original task execution */
-    code: number;
-    /** The auto-fingerprint data, if auto-fingerprinting was used */
-    fingerprint?: TaskFingerprint;
-    /** The hash that was used as the cache key */
-    hash: string;
-    /** The terminal output of the original task execution */
-    terminalOutput: string;
-}
-/**
- * Options for creating a Cache instance.
- */
-interface CacheOptions {
-    /** The cache directory (defaults to `{workspaceRoot}/.task-runner-cache`) */
-    cacheDirectory?: string;
-    /** Maximum age of cache entries in milliseconds (default: 7 days) */
-    maxCacheAge?: number;
-    /** Maximum cache size (e.g., "500MB", "1GB") */
-    maxCacheSize?: string;
-    /** The workspace root directory */
-    workspaceRoot: string;
-}
-/**
- * Parses a human-readable cache size string into bytes.
- * Delegates to @visulima/humanizer's parseBytes with base-2 (1024) multipliers.
- */
-declare const parseCacheSize: (sizeString: string) => number;
-/**
- * Formats a byte count into a human-readable string.
- * Delegates to @visulima/humanizer's formatBytes with base-2 (1024) multipliers.
- */
-declare const formatCacheSize: (bytes: number) => string;
-/**
- * Local file-based cache for task results.
- *
- * Cache structure:
- * ```
- * .task-runner-cache/
- *   <hash>/
- *     outputs/          (Archived build outputs)
- *     code              (Exit code)
- *     terminalOutput    (Captured terminal output)
- *     fingerprint.json  (Auto-fingerprint data, optional)
- *     .commit           (Marker indicating complete cache entry)
- *   .task-index.json    (Task ID -> hash mapping for auto-fingerprint)
- * ```
- *
- * Atomicity: Cache entries are written to a temporary directory first,
- * then renamed into place. The `.commit` marker ensures readers only
- * see complete entries.
- */
-declare class Cache {
-    #private;
-    constructor(options: CacheOptions);
-    /**
-     * Gets the cache directory path.
-     */
-    get cacheDirectory(): string;
-    /**
-     * Retrieves a cached result for the given task hash.
-     * Returns undefined if no valid cache entry exists.
-     */
-    get(hash: string): Promise<CachedResult | undefined>;
-    /**
-     * Stores a task result in the cache.
-     *
-     * Uses atomic write: builds the entry in a temporary directory,
-     * then renames into place to avoid partial reads by concurrent processes.
-     */
-    put(hash: string, terminalOutput: string, outputs: string[], code: number, fingerprint?: TaskFingerprint): Promise<void>;
-    /**
-     * Restores cached outputs to their original locations.
-     */
-    restoreOutputs(hash: string, outputs: string[]): Promise<boolean>;
-    /**
-     * Retrieves the most recent cached result for a task by its ID.
-     * Used in auto-fingerprint mode where the hash is derived from
-     * tracked file accesses rather than computed upfront.
-     */
-    getByTaskId(taskId: string): Promise<CachedResult | undefined>;
-    /**
-     * Stores the mapping from task ID to cache hash.
-     * Uses a write queue to serialize concurrent writes and prevent lost updates.
-     * Each write is atomic (temp file + rename).
-     */
-    setTaskIndex(taskId: string, hash: string): Promise<void>;
-    /**
-     * Removes old cache entries that exceed the maximum age,
-     * and enforces the maximum cache size by evicting oldest entries.
-     */
-    removeOldEntries(): Promise<void>;
-    /**
-     * Clears the entire cache.
-     */
-    clear(): Promise<void>;
-}
-export type { CachedResult, CacheOptions };
-export { Cache, formatCacheSize, parseCacheSize };

package/dist/default-task-runner.d.ts

@@ -1,44 +0,0 @@
-import type { Task, TaskResults, TaskRunnerContext, TaskRunnerOptions } from "./types.d.ts";
-/**
- * The default task runner implementation.
- *
- * Runs tasks with caching, scheduling, and lifecycle support.
- * Supports two caching modes:
- *
- * 1. **Nx-style** (default): Explicit input declarations with upfront hash computation.
- * 2. **Auto-fingerprint** (Vite Task-style): Set `autoFingerprint: true` to automatically
- * track file accesses and use them for cache invalidation.
- * @example
- * ```ts
- * import { defaultTaskRunner } from "@visulima/task-runner";
- *
- * // Nx-style (explicit inputs)
- * const results = await defaultTaskRunner(tasks, options, context);
- *
- * // Vite Task-style (auto-fingerprinting)
- * const results = await defaultTaskRunner(tasks, {
- *     ...options,
- *     autoFingerprint: true,
- *     fingerprintEnvPatterns: ["VITE_*", "NODE_ENV"],
- *     cacheDiagnostics: true,
- * }, context);
- *
- * // With remote cache
- * const results = await defaultTaskRunner(tasks, {
- *     ...options,
- *     remoteCache: {
- *         url: "https://cache.example.com",
- *         token: process.env.CACHE_TOKEN,
- *         teamId: "my-team",
- *     },
- * }, context);
- *
- * // Dry-run (inspect hashes without executing)
- * const results = await defaultTaskRunner(tasks, {
- *     ...options,
- *     dryRun: true,
- * }, context);
- * ```
- */
-declare const defaultTaskRunner: (_tasks: Task[], options: TaskRunnerOptions, context: TaskRunnerContext) => Promise<TaskResults>;
-export { defaultTaskRunner };

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

@@ -1,53 +0,0 @@
-/**
- * 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

@@ -1,45 +0,0 @@
-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

@@ -1,35 +0,0 @@
-/**
- * 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

@@ -1,74 +0,0 @@
-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

@@ -1,58 +0,0 @@
-/**
- * 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 };