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

package/dist/types.d.ts

@@ -160,6 +160,81 @@ export interface EnvironmentInput {
 export interface ExternalDependencyInput {
     externalDependencies: string[];
 }
+/**
+ * Defines tag-based dependency rules.
+ * Each key is a tag name. The value is the list of tags that a dependency
+ * must have at least one of, when the source project has that tag.
+ *
+ * Example: `{ "frontend": ["shared", "frontend"] }` means a project tagged
+ * "frontend" can only depend on projects tagged "shared" or "frontend".
+ */
+export type TagRelationships = Record<string, string[]>;
+/**
+ * Defines project-type-based dependency rules.
+ */
+export interface TypeBoundaries {
+    /**
+     * Custom rules mapping project types to allowed dependency types.
+     * Example: `{ "application": ["library"] }` means applications can only
+     * depend on libraries.
+     */
+    allowedDependencyTypes?: Record<string, string[]>;
+    /**
+     * When true, no project may depend on an "application" type project.
+     * Applications are typically deployment targets, not libraries.
+     * @default true
+     */
+    enforceApplicationBoundary?: boolean;
+}
+/**
+ * Rules based on the dependency kind (dependencies vs devDependencies vs peerDependencies).
+ */
+export interface DependencyKindRules {
+    /**
+     * When true, a "library" project must not have workspace-internal devDependencies
+     * on other libraries that are also in its production dependencies.
+     * Prevents publishing libraries that silently rely on dev-only workspace packages.
+     * @default false
+     */
+    noDevDependencyOnProductionDep?: boolean;
+    /**
+     * When true, production `dependencies` must not point to "application" type projects.
+     * devDependencies on applications are allowed (e.g., for testing).
+     * @default false
+     */
+    noProductionDependencyOnApplication?: boolean;
+}
+/**
+ * Configuration for project constraint enforcement.
+ */
+export interface ConstraintsConfig {
+    /** Rules based on the dependency kind (static vs devDependency vs peerDependency) */
+    dependencyKindRules?: DependencyKindRules;
+    /** Tag-based dependency rules */
+    tagRelationships?: TagRelationships;
+    /** Project-type-based dependency rules */
+    typeBoundaries?: TypeBoundaries;
+}
+/**
+ * A single constraint violation detected in the project graph.
+ */
+export interface ConstraintViolation {
+    /** The project being depended on */
+    dependencyProject: string;
+    /** Human-readable description of the violation */
+    message: string;
+    /** The type of rule that was violated */
+    rule: "dependency-kind" | "tag-relationship" | "type-boundary";
+    /** The project that has the invalid dependency */
+    sourceProject: string;
+}
+/**
+ * Controls how far to traverse the dependency graph in a given direction.
+ * - "none": Don't traverse — only directly changed projects are included.
+ * - "direct": Include only immediate neighbors (one hop).
+ * - "deep": Include all transitive neighbors (full chain).
+ */
+export type AffectedScope = "deep" | "direct" | "none";
 /**
  * Workspace configuration containing all project configurations.
  */
@@ -167,6 +242,15 @@ export interface WorkspaceConfiguration {
     /** All projects in the workspace, keyed by project name */
     projects: Record<string, ProjectConfiguration>;
 }
+/**
+ * The kind of dependency relationship between projects.
+ * - "static": Production dependency (from `dependencies` in package.json)
+ * - "dynamic": Dynamically resolved dependency (e.g., lazy imports)
+ * - "implicit": Declared via `implicitDependencies` in project config
+ * - "devDependency": Development-only dependency (from `devDependencies`)
+ * - "peerDependency": Peer dependency (from `peerDependencies`)
+ */
+export type DependencyType = "devDependency" | "dynamic" | "implicit" | "peerDependency" | "static";
 /**
  * A dependency relationship in the project graph.
  */
@@ -176,7 +260,7 @@ export interface ProjectGraphDependency {
     /** The target project */
     target: string;
     /** The type of dependency */
-    type: "static" | "dynamic" | "implicit";
+    type: DependencyType;
 }
 /**
  * A node in the project graph.
@@ -370,6 +454,141 @@ export interface TaskRunnerContext {
     /** The workspace root directory */
     workspaceRoot: string;
 }
+/**
+ * Input for a concurrent command -- either a string or a config object.
+ */
+export type ConcurrentCommandInput = string | {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    name?: string;
+    stdin?: "inherit" | "null" | "pipe" | "pty";
+    /** Initial PTY dimensions (only used when stdin is "pty"). */
+    ptySize?: {
+        cols: number;
+        rows: number;
+    };
+};
+/**
+ * Configuration for a single command to run concurrently.
+ */
+export interface ConcurrentCommandConfig {
+    /** The command string to execute (passed to shell). */
+    command: string;
+    /** Working directory for the command. */
+    cwd?: string;
+    /** Additional environment variables merged with process env. */
+    env?: Record<string, string>;
+    /** Human-readable name for this command (used in prefixes/logs). */
+    name?: string;
+    /** Whether to use shell execution (default: true). */
+    shell?: boolean;
+    /**
+     * Stdin mode for the child process.
+     * - "null" (default): stdin closed, child cannot read input
+     * - "pipe": stdin is piped, can be written to programmatically
+     * - "inherit": child inherits parent's stdin (for interactive commands like vite dev)
+     * - "pty": child runs inside a pseudo-terminal (isatty() returns true, enables interactive prompts)
+     */
+    stdin?: "inherit" | "null" | "pipe" | "pty";
+    /**
+     * Initial PTY dimensions. Only used when stdin is "pty".
+     * Defaults to 80x24 if not specified.
+     */
+    ptySize?: {
+        cols: number;
+        rows: number;
+    };
+}
+/**
+ * Options controlling the concurrent runner behavior.
+ */
+export interface ConcurrentRunnerOptions {
+    /** Conditions under which to kill other processes: "success", "failure". */
+    killOthers?: ("failure" | "success")[];
+    /** Signal to send when killing processes (default: "SIGTERM"). */
+    killSignal?: string;
+    /** Milliseconds to wait after kill signal before sending SIGKILL (default: 5000). */
+    killTimeout?: number;
+    /** Maximum number of processes to run simultaneously. 0 = unlimited. */
+    maxProcesses?: number;
+    /** Callback for real-time process events. */
+    onEvent?: (event: ProcessEvent) => void;
+    /** Restart options for failed commands. */
+    restart?: {
+        /** Delay between restarts in ms. "exponential" for 2^attempt * 1000ms. */
+        delay?: number | "exponential";
+        /** Maximum restart attempts per command. 0 = no restarts. -1 = infinite. */
+        tries: number;
+    };
+    /**
+     * Custom shell path for command execution.
+     * Overrides the platform default (/bin/sh on Unix, cmd.exe on Windows).
+     * Automatically detected from npm's `script-shell` config if not set.
+     */
+    shellPath?: string;
+    /** Success condition: "first", "last", "all", or "command-&lt;name|index>". */
+    successCondition?: string;
+    /** Commands to run sequentially after all processes complete. */
+    teardown?: string[];
+    /** Working directory for teardown commands. */
+    teardownCwd?: string;
+    /** Print a timing summary table after completion. Default: false. */
+    timings?: boolean;
+}
+/**
+ * An event emitted during concurrent execution.
+ */
+export interface ProcessEvent {
+    /** Command name (for close events). */
+    commandName?: string;
+    /** Duration in milliseconds (for close events). */
+    durationMs?: number;
+    /** Exit code (for close events). */
+    exitCode?: number;
+    /** Index of the command that produced this event. */
+    index: number;
+    /** Whether the process was killed (for close events). */
+    killed?: boolean;
+    /** Kill the child process/PTY. Only present on "started" events. */
+    kill?: (signal?: string) => void;
+    /** Event type: "stdout", "stderr", "close", "error", "started". */
+    kind: "close" | "error" | "started" | "stderr" | "stdout";
+    /** Error message (for error events). */
+    message?: string;
+    /** Resize the child's PTY. Only present on "started" events with stdin "pty". */
+    resize?: (cols: number, rows: number) => void;
+    /** Text content (for stdout/stderr events). */
+    text?: string;
+    /** Write data to the child's stdin (pipe) or PTY. Only present on "started" events. */
+    write?: (data: string) => void;
+}
+/**
+ * Result of a close event for a single command.
+ */
+export interface ConcurrentCloseEvent {
+    /** The command string that was executed. */
+    command: string;
+    /** Duration in milliseconds. */
+    durationMs: number;
+    /** Exit code. -1 if killed by signal. */
+    exitCode: number;
+    /** Index of the command. */
+    index: number;
+    /** Whether the process was forcefully killed. */
+    killed: boolean;
+    /** The command name (if provided). */
+    name?: string;
+}
+/**
+ * Overall result of a concurrent run.
+ */
+export interface ConcurrentRunResult {
+    /** Close events for all commands, in completion order. */
+    closeEvents: ConcurrentCloseEvent[];
+    /** Whether the run succeeded according to the success condition. */
+    success: boolean;
+}
 /**
  * Interface for lifecycle event handlers.
  */