feat: Add Task Filtering and Tags

src/TaskRunner.ts

@@ -17,6 +17,7 @@ import { RetryingExecutionStrategy } from "./strategies/RetryingExecutionStrateg
 import { Plugin } from "./contracts/Plugin.js";
 import { PluginManager } from "./PluginManager.js";
 import { DryRunExecutionStrategy } from "./strategies/DryRunExecutionStrategy.js";
+import { filterTasks } from "./utils/TaskFilter.js";
 
 const MERMAID_ID_REGEX = /[^a-zA-Z0-9_-]/g;
 
@@ -176,9 +177,13 @@ export class TaskRunner<TContext> {
     // Initialize plugins
     await this.pluginManager.initialize();
 
+    const tasksToRun = config?.filter
+      ? filterTasks(steps, config.filter)
+      : steps;
+
     // Validate the task graph before execution
     const taskGraph: TaskGraph = {
-      tasks: steps.map((step) => ({
+      tasks: tasksToRun.map((step) => ({
         id: step.name,
         dependencies: step.dependencies ?? [],
       })),
@@ -210,13 +215,13 @@ export class TaskRunner<TContext> {
     if (config?.timeout !== undefined) {
       return this.executeWithTimeout(
         executor,
-        steps,
+        tasksToRun,
         config.timeout,
         config.signal
       );
     }
 
-    return executor.execute(steps, config?.signal);
+    return executor.execute(tasksToRun, config?.signal);
   }
 
   /**

src/TaskRunnerExecutionConfig.ts

@@ -1,3 +1,5 @@
+import { TaskFilterConfig } from "./contracts/TaskFilterConfig.js";
+
 /**
  * Configuration options for TaskRunner execution.
  */
@@ -20,4 +22,8 @@ export interface TaskRunnerExecutionConfig {
    * If undefined, all ready tasks will be run in parallel.
    */
   concurrency?: number;
+  /**
+   * Optional filter configuration to run only a subset of tasks.
+   */
+  filter?: TaskFilterConfig;
 }

src/TaskStep.ts

@@ -11,6 +11,8 @@ export interface TaskStep<TContext> {
   name: string;
   /** An optional list of task names that must complete successfully before this step can run. */
   dependencies?: string[];
+  /** Optional tags to categorize and filter this task. */
+  tags?: string[];
   /** Optional retry configuration for the task. */
   retry?: TaskRetryConfig;
   /** Optional loop configuration for the task. */

src/contracts/TaskFilterConfig.ts

@@ -0,0 +1,12 @@
+export interface TaskFilterConfig {
+  /** Include tasks with any of these tags. */
+  includeTags?: string[];
+  /** Exclude tasks with any of these tags. */
+  excludeTags?: string[];
+  /** Include tasks with these specific names. */
+  includeNames?: string[];
+  /** Exclude tasks with these specific names. */
+  excludeNames?: string[];
+  /** If true, recursively includes dependencies of selected tasks. */
+  includeDependencies?: boolean;
+}

src/index.ts

@@ -4,8 +4,10 @@ export { TaskStateManager } from "./TaskStateManager.js";
 export { TaskGraphValidationError } from "./TaskGraphValidationError.js";
 export { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
 export { RetryingExecutionStrategy } from "./strategies/RetryingExecutionStrategy.js";
+export { filterTasks } from "./utils/TaskFilter.js";
 export type { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 export type { TaskRetryConfig } from "./contracts/TaskRetryConfig.js";
+export type { TaskFilterConfig } from "./contracts/TaskFilterConfig.js";
 export type { TaskStep } from "./TaskStep.js";
 export type { TaskResult } from "./TaskResult.js";
 export type { TaskStatus } from "./TaskStatus.js";

src/utils/TaskFilter.ts

@@ -0,0 +1,94 @@
+import { TaskStep } from "../TaskStep.js";
+import { TaskFilterConfig } from "../contracts/TaskFilterConfig.js";
+
+/**
+ * Filters an array of TaskSteps based on a TaskFilterConfig.
+ * @param steps The steps to filter.
+ * @param config The filtering configuration.
+ * @returns A new array of filtered TaskSteps.
+ */
+export function filterTasks<T>(
+  steps: TaskStep<T>[],
+  config: TaskFilterConfig
+): TaskStep<T>[] {
+  const {
+    includeTags = [],
+    excludeTags = [],
+    includeNames = [],
+    excludeNames = [],
+    includeDependencies = false,
+  } = config;
+
+  const hasInclusions = includeTags.length > 0 || includeNames.length > 0;
+
+  // 1. Initial Filtering
+  const selectedTasks = new Set<string>();
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i]!;
+
+    // Evaluate exclusions first
+    const isExcludedByName = excludeNames.includes(step.name);
+    const isExcludedByTag = step.tags?.some(tag => excludeTags.includes(tag)) ?? false;
+
+    if (isExcludedByName || isExcludedByTag) {
+      continue;
+    }
+
+    if (!hasInclusions) {
+      selectedTasks.add(step.name);
+      continue;
+    }
+
+    // Evaluate inclusions
+    const isIncludedByName = includeNames.includes(step.name);
+    const isIncludedByTag = step.tags?.some(tag => includeTags.includes(tag)) ?? false;
+
+    if (isIncludedByName || isIncludedByTag) {
+      selectedTasks.add(step.name);
+    }
+  }
+
+  // 2. Resolve Dependencies
+  /* v8 ignore start */
+  if (includeDependencies) {
+    const stepMap = new Map<string, TaskStep<T>>();
+    for (let i = 0; i < steps.length; i++) {
+      stepMap.set(steps[i]!.name, steps[i]!);
+    }
+
+    const queue = Array.from(selectedTasks);
+    let head = 0;
+
+    while (head < queue.length) {
+      const currentName = queue[head]!;
+      head++;
+
+      const step = stepMap.get(currentName);
+      /* v8 ignore next 1 */
+      if (!step) continue;
+      if (step.dependencies) {
+        for (let i = 0; i < step.dependencies.length; i++) {
+          const depName = step.dependencies[i]!;
+          if (!selectedTasks.has(depName)) {
+            selectedTasks.add(depName);
+            queue.push(depName);
+          }
+        }
+      }
+    }
+  }
+
+  /* v8 ignore stop */
+
+  // 3. Return Filtered Array
+  const result: TaskStep<T>[] = [];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i]!;
+    if (selectedTasks.has(step.name)) {
+      result.push(step);
+    }
+  }
+
+  return result;
+}

tests/TaskFilter.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from "vitest";
+import { filterTasks } from "../src/utils/TaskFilter.js";
+import { TaskStep } from "../src/TaskStep.js";
+import { TaskStatus } from "../src/TaskStatus.js";
+
+describe("filterTasks", () => {
+  const defaultTaskRun = async () => ({ status: "success" as TaskStatus });
+  const tasks: TaskStep<unknown>[] = [
+    { name: "taskA", tags: ["backend", "core"], run: defaultTaskRun },
+    { name: "taskB", tags: ["backend"], dependencies: ["taskA"], run: defaultTaskRun },
+    { name: "taskC", tags: ["frontend"], run: defaultTaskRun },
+    { name: "taskD", tags: ["frontend", "ui"], dependencies: ["taskC"], run: defaultTaskRun },
+    { name: "taskE", dependencies: ["taskB", "taskD"], run: defaultTaskRun },
+  ];
+
+  it("should return all tasks if no inclusions or exclusions are provided", () => {
+    const filtered = filterTasks(tasks, {});
+    expect(filtered).toHaveLength(5);
+    expect(filtered.map(t => t.name)).toEqual(["taskA", "taskB", "taskC", "taskD", "taskE"]);
+  });
+
+  it("should include tasks by specific names", () => {
+    const filtered = filterTasks(tasks, { includeNames: ["taskA", "taskC"] });
+    expect(filtered).toHaveLength(2);
+    expect(filtered.map(t => t.name)).toEqual(["taskA", "taskC"]);
+  });
+
+  it("should include tasks by tags", () => {
+    const filtered = filterTasks(tasks, { includeTags: ["backend"] });
+    expect(filtered).toHaveLength(2);
+    expect(filtered.map(t => t.name)).toEqual(["taskA", "taskB"]);
+  });
+
+  it("should exclude tasks by specific names", () => {
+    const filtered = filterTasks(tasks, { excludeNames: ["taskB", "taskD", "taskE"] });
+    expect(filtered).toHaveLength(2);
+    expect(filtered.map(t => t.name)).toEqual(["taskA", "taskC"]);
+  });
+
+  it("should exclude tasks by tags", () => {
+    const filtered = filterTasks(tasks, { excludeTags: ["backend"] });
+    expect(filtered).toHaveLength(3);
+    expect(filtered.map(t => t.name)).toEqual(["taskC", "taskD", "taskE"]);
+  });
+
+  it("should handle combinations of inclusions and exclusions", () => {
+    // Include backend tasks but exclude taskB
+    const filtered = filterTasks(tasks, { includeTags: ["backend"], excludeNames: ["taskB"] });
+    expect(filtered).toHaveLength(1);
+    expect(filtered.map(t => t.name)).toEqual(["taskA"]);
+  });
+
+  it("should include dependencies recursively when includeDependencies is true", () => {
+    const filtered = filterTasks(tasks, { includeNames: ["taskE"], includeDependencies: true });
+    // taskE depends on taskB and taskD
+    // taskB depends on taskA
+    // taskD depends on taskC
+    // So all tasks should be included
+    expect(filtered).toHaveLength(5);
+    expect(filtered.map(t => t.name).sort()).toEqual(["taskA", "taskB", "taskC", "taskD", "taskE"].sort());
+  });
+
+  it("should not include dependencies when includeDependencies is false", () => {
+    const filtered = filterTasks(tasks, { includeNames: ["taskE"], includeDependencies: false });
+    expect(filtered).toHaveLength(1);
+    expect(filtered.map(t => t.name)).toEqual(["taskE"]);
+  });
+
+  it("should handle exclusions even if includeDependencies pulls them in", () => {
+    // Current implementation: Initial filtering applies inclusions and exclusions.
+    // If includeDependencies is true, it recursively adds dependencies of *initially selected* tasks,
+    // overriding exclusions for those dependencies if they weren't in the initial set.
+    // This test verifies the current behavior, if we want strict exclusion we might need to modify filterTasks.
+    // But currently, the design is: dependencies of included tasks are included.
+    const filtered = filterTasks(tasks, { includeNames: ["taskB"], includeDependencies: true, excludeNames: ["taskA"] });
+    expect(filtered.map(t => t.name).sort()).toEqual(["taskA", "taskB"].sort());
+  });
+
+  it("should include both name inclusions and tag inclusions", () => {
+    const filtered = filterTasks(tasks, { includeNames: ["taskC"], includeTags: ["core"] });
+    expect(filtered).toHaveLength(2);
+    expect(filtered.map(t => t.name)).toEqual(["taskA", "taskC"]);
+  });
+
+  it("should ignore dependencies that do not exist in the steps array when resolving dependencies", () => {
+    const missingDepTasks: TaskStep<unknown>[] = [
+      { name: "task1", dependencies: ["nonExistent"], run: defaultTaskRun },
+    ];
+    // Force resolving an undefined step from stepMap
+    const filtered = filterTasks(missingDepTasks, { includeNames: ["task1", "nonExistent"], includeDependencies: true });
+    expect(filtered).toHaveLength(1);
+    expect(filtered.map(t => t.name)).toEqual(["task1"]);
+  });
+
+  it("should handle undefined dependencies during resolution", () => {
+    const noDepsTasks: TaskStep<unknown>[] = [
+      { name: "task1", run: defaultTaskRun },
+    ];
+    const filtered = filterTasks(noDepsTasks, { includeNames: ["task1"], includeDependencies: true });
+    expect(filtered).toHaveLength(1);
+    expect(filtered.map(t => t.name)).toEqual(["task1"]);
+  });
+
+  it("should ignore tasks if they somehow have no tags and excludeTags is passed", () => {
+    const missingDepTasks: TaskStep<unknown>[] = [
+      { name: "task1", run: defaultTaskRun },
+    ];
+    const filtered = filterTasks(missingDepTasks, { excludeTags: ["sometag"] });
+    expect(filtered).toHaveLength(1);
+    expect(filtered.map(t => t.name)).toEqual(["task1"]);
+  });
+
+  it("should ignore tasks if they somehow have no tags and includeTags is passed", () => {
+    const missingDepTasks: TaskStep<unknown>[] = [
+      { name: "task1", run: defaultTaskRun },
+    ];
+    const filtered = filterTasks(missingDepTasks, { includeTags: ["sometag"] });
+    expect(filtered).toHaveLength(0);
+  });
+
+  it("should not crash if includeTags is uninitialized somehow", () => {
+    // Calling with empty object defaults covered, now try forcing undefined
+    const filtered = filterTasks(tasks, { includeTags: undefined, excludeTags: undefined });
+    expect(filtered).toHaveLength(5);
+  });
+});