@auto-engineer/job-graph-processor 1.12.1

package/src/apply-policy.specs.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import { applyPolicy } from './apply-policy';
+import { evolve, initialState } from './evolve';
+
+describe('applyPolicy', () => {
+  it('returns empty array before graph submission', () => {
+    const events = applyPolicy(initialState(), 'a');
+
+    expect(events).toEqual([]);
+  });
+
+  it('halt policy skips all pending jobs when a job fails', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+          { id: 'c', dependsOn: ['a'], target: 'lint', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+    state = evolve(state, { type: 'JobFailed', data: { jobId: 'a', error: 'build error' } });
+
+    const events = applyPolicy(state, 'a');
+
+    expect(events).toEqual([
+      { type: 'JobSkipped', data: { jobId: 'b', reason: 'halt policy' } },
+      { type: 'JobSkipped', data: { jobId: 'c', reason: 'halt policy' } },
+    ]);
+  });
+
+  it('skip-dependents policy skips only transitive dependents of failed job', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+          { id: 'c', dependsOn: [], target: 'lint', payload: {} },
+        ],
+        failurePolicy: 'skip-dependents',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+    state = evolve(state, { type: 'JobFailed', data: { jobId: 'a', error: 'build error' } });
+
+    const events = applyPolicy(state, 'a');
+
+    expect(events).toEqual([{ type: 'JobSkipped', data: { jobId: 'b', reason: 'dependency failed' } }]);
+  });
+
+  it('continue policy returns no skip events', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'continue',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+    state = evolve(state, { type: 'JobFailed', data: { jobId: 'a', error: 'build error' } });
+
+    const events = applyPolicy(state, 'a');
+
+    expect(events).toEqual([]);
+  });
+});

package/src/apply-policy.ts

@@ -0,0 +1,27 @@
+import type { GraphState, JobGraphEvent } from './evolve';
+import { getTransitiveDependents } from './evolve';
+
+export function applyPolicy(state: GraphState, failedJobId: string): JobGraphEvent[] {
+  if (state.status !== 'processing') return [];
+
+  switch (state.failurePolicy) {
+    case 'continue':
+      return [];
+    case 'skip-dependents':
+      return getTransitiveDependents(state, failedJobId).map(
+        (id): JobGraphEvent => ({
+          type: 'JobSkipped',
+          data: { jobId: id, reason: 'dependency failed' },
+        }),
+      );
+    case 'halt': {
+      const events: JobGraphEvent[] = [];
+      for (const [id, job] of state.jobs) {
+        if (job.status === 'pending') {
+          events.push({ type: 'JobSkipped', data: { jobId: id, reason: 'halt policy' } });
+        }
+      }
+      return events;
+    }
+  }
+}

package/src/commands/process-job-graph.specs.ts

@@ -0,0 +1,93 @@
+import { createMessageBus } from '@auto-engineer/message-bus';
+import { describe, expect, it } from 'vitest';
+import { commandHandler } from './process-job-graph';
+
+describe('ProcessJobGraph command handler', () => {
+  it('returns graph.dispatching with dispatched jobs when given valid graph and messageBus', async () => {
+    const messageBus = createMessageBus();
+
+    const result = await commandHandler.handle(
+      {
+        type: 'ProcessJobGraph',
+        data: {
+          graphId: 'g1',
+          jobs: [
+            { id: 'a', dependsOn: [], target: 'build', payload: { src: './app' } },
+            { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+          ],
+          failurePolicy: 'halt',
+        },
+      },
+      { messageBus },
+    );
+
+    expect(result).toEqual({
+      type: 'graph.dispatching',
+      data: {
+        graphId: 'g1',
+        dispatchedJobs: [{ jobId: 'a', target: 'build', payload: { src: './app' }, correlationId: 'graph:g1:a' }],
+      },
+    });
+  });
+
+  it('returns graph.failed when messageBus is not available in context', async () => {
+    const result = await commandHandler.handle({
+      type: 'ProcessJobGraph',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: {} }],
+        failurePolicy: 'halt',
+      },
+    });
+
+    expect(result).toEqual({
+      type: 'graph.failed',
+      data: { graphId: 'g1', reason: 'messageBus not available in context' },
+    });
+  });
+
+  it('dispatches target commands via ctx.sendCommand when provided', async () => {
+    const messageBus = createMessageBus();
+    const dispatched: Array<{ type: string; data: unknown; correlationId: string }> = [];
+    const sendCommand = async (type: string, data: unknown, correlationId?: string) => {
+      dispatched.push({ type, data, correlationId: correlationId! });
+    };
+
+    await commandHandler.handle(
+      {
+        type: 'ProcessJobGraph',
+        data: {
+          graphId: 'g1',
+          jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: { src: './app' } }],
+          failurePolicy: 'halt',
+        },
+      },
+      { messageBus, sendCommand },
+    );
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(dispatched).toEqual([{ type: 'build', data: { src: './app' }, correlationId: 'graph:g1:a' }]);
+  });
+
+  it('returns graph.failed for invalid graph', async () => {
+    const messageBus = createMessageBus();
+
+    const result = await commandHandler.handle(
+      {
+        type: 'ProcessJobGraph',
+        data: {
+          graphId: 'g1',
+          jobs: [],
+          failurePolicy: 'halt',
+        },
+      },
+      { messageBus },
+    );
+
+    expect(result).toEqual({
+      type: 'graph.failed',
+      data: { graphId: 'g1', reason: 'Graph must contain at least one job' },
+    });
+  });
+});

package/src/commands/process-job-graph.ts

@@ -0,0 +1,80 @@
+import type { Command, Event, MessageBus } from '@auto-engineer/message-bus';
+import type { FailurePolicy } from '../evolve';
+import type { DispatchFn } from '../graph-processor';
+import { createGraphProcessor, type ProcessGraphCommand } from '../graph-processor';
+import type { Job } from '../graph-validator';
+
+interface ContextWithMessageBus {
+  messageBus: MessageBus;
+  sendCommand?: (type: string, data: unknown, correlationId?: string) => Promise<void>;
+}
+
+function isContextWithMessageBus(context: unknown): context is ContextWithMessageBus {
+  return (
+    context !== null &&
+    context !== undefined &&
+    typeof context === 'object' &&
+    'messageBus' in context &&
+    context.messageBus !== null &&
+    context.messageBus !== undefined &&
+    typeof context.messageBus === 'object'
+  );
+}
+
+function buildDispatch(context: ContextWithMessageBus): DispatchFn | undefined {
+  if (typeof context.sendCommand !== 'function') return undefined;
+  const ctxSendCommand = context.sendCommand;
+  return (cmd) => ctxSendCommand(cmd.type, cmd.data, cmd.correlationId);
+}
+
+function toProcessGraphCommand(command: Command): ProcessGraphCommand {
+  const data = command.data as { graphId: string; jobs: Job[]; failurePolicy: FailurePolicy };
+  return { type: command.type, data };
+}
+
+export const commandHandler = {
+  name: 'ProcessJobGraph',
+  displayName: 'Process Job Graph',
+  alias: 'process:job-graph',
+  description: 'Process a directed acyclic graph of jobs with dependency tracking and failure policies',
+  category: 'orchestration',
+  icon: 'git-branch',
+  fields: {
+    graphId: {
+      description: 'Unique identifier for the graph',
+      required: true,
+    },
+    jobs: {
+      description: 'Array of jobs with dependencies',
+      required: true,
+    },
+    failurePolicy: {
+      description: 'Policy for handling job failures: halt, skip-dependents, or continue',
+      required: true,
+    },
+  },
+  examples: [
+    '$ auto process:job-graph --graphId=g1 --jobs=\'[{"id":"a","dependsOn":[],"target":"build","payload":{}}]\' --failurePolicy=halt',
+  ],
+  events: [
+    { name: 'graph.dispatching', displayName: 'Graph Dispatching' },
+    { name: 'graph.failed', displayName: 'Graph Failed' },
+    { name: 'graph.completed', displayName: 'Graph Completed' },
+  ],
+  handle: async (command: Command, context?: unknown): Promise<Event | Event[]> => {
+    const { graphId } = command.data;
+
+    if (!isContextWithMessageBus(context)) {
+      return {
+        type: 'graph.failed',
+        data: { graphId, reason: 'messageBus not available in context' },
+      };
+    }
+
+    const dispatch = buildDispatch(context);
+    const processor = createGraphProcessor(context.messageBus, dispatch ? { dispatch } : undefined);
+    return processor.submit(toProcessGraphCommand(command));
+  },
+};
+
+export default commandHandler;

package/src/evolve.specs.ts

@@ -0,0 +1,235 @@
+import { describe, expect, it } from 'vitest';
+import { evolve, getReadyJobs, getTransitiveDependents, initialState, isGraphComplete } from './evolve';
+
+describe('evolve', () => {
+  it('ignores job events before graph submission', () => {
+    const state = evolve(initialState(), { type: 'JobSucceeded', data: { jobId: 'a' } });
+
+    expect(getReadyJobs(state)).toEqual([]);
+    expect(isGraphComplete(state)).toBe(false);
+  });
+
+  it('ignores job events for unknown job IDs', () => {
+    const state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: {} }],
+        failurePolicy: 'halt',
+      },
+    });
+    const after = evolve(state, { type: 'JobSucceeded', data: { jobId: 'unknown' } });
+
+    expect(getReadyJobs(after)).toEqual(['a']);
+  });
+});
+
+describe('getReadyJobs', () => {
+  it('returns empty array before graph submission', () => {
+    expect(getReadyJobs(initialState())).toEqual([]);
+  });
+
+  it('returns root jobs after graph submission', () => {
+    const state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+
+    expect(getReadyJobs(state)).toEqual(['a']);
+  });
+
+  it('unlocks dependent jobs after dependency succeeds', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+    state = evolve(state, { type: 'JobSucceeded', data: { jobId: 'a' } });
+
+    expect(getReadyJobs(state)).toEqual(['b']);
+  });
+
+  it('unlocks dependents of failed job under continue policy', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'continue',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+    state = evolve(state, { type: 'JobFailed', data: { jobId: 'a', error: 'build error' } });
+
+    expect(getReadyJobs(state)).toEqual(['b']);
+  });
+
+  it('does not unlock dependents of dispatched job under continue policy', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'continue',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+
+    expect(getReadyJobs(state)).toEqual([]);
+  });
+});
+
+describe('getTransitiveDependents', () => {
+  it('returns empty array before graph submission', () => {
+    expect(getTransitiveDependents(initialState(), 'a')).toEqual([]);
+  });
+
+  it('returns direct and transitive dependents of a job', () => {
+    const state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+          { id: 'c', dependsOn: ['b'], target: 'deploy', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+
+    expect(getTransitiveDependents(state, 'a').sort()).toEqual(['b', 'c']);
+  });
+});
+
+describe('isGraphComplete', () => {
+  it('returns false before graph submission', () => {
+    expect(isGraphComplete(initialState())).toBe(false);
+  });
+
+  it('returns false when some jobs are still pending', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+    state = evolve(state, { type: 'JobSucceeded', data: { jobId: 'a' } });
+
+    expect(isGraphComplete(state)).toBe(false);
+  });
+
+  it('returns true when a job has been skipped', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: {} }],
+        failurePolicy: 'halt',
+      },
+    });
+    state = evolve(state, { type: 'JobSkipped', data: { jobId: 'a', reason: 'dependency failed' } });
+
+    expect(isGraphComplete(state)).toBe(true);
+  });
+
+  it('returns true when a job has timed out', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: {} }],
+        failurePolicy: 'halt',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+    state = evolve(state, { type: 'JobTimedOut', data: { jobId: 'a', timeoutMs: 5000 } });
+
+    expect(isGraphComplete(state)).toBe(true);
+  });
+
+  it('returns true when a job has failed', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: {} }],
+        failurePolicy: 'halt',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+    state = evolve(state, { type: 'JobFailed', data: { jobId: 'a', error: 'build error' } });
+
+    expect(isGraphComplete(state)).toBe(true);
+  });
+
+  it('returns true when all jobs have succeeded', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+    state = evolve(state, { type: 'JobSucceeded', data: { jobId: 'a' } });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'b', target: 'test', correlationId: 'graph:g1:b' },
+    });
+    state = evolve(state, { type: 'JobSucceeded', data: { jobId: 'b' } });
+
+    expect(isGraphComplete(state)).toBe(true);
+  });
+});

package/src/evolve.ts

@@ -0,0 +1,121 @@
+import type { Job } from './graph-validator';
+
+export type JobStatus = 'pending' | 'dispatched' | 'succeeded' | 'failed' | 'skipped' | 'timed-out';
+export type FailurePolicy = 'halt' | 'skip-dependents' | 'continue';
+
+interface JobState {
+  jobId: string;
+  status: JobStatus;
+  dependsOn: readonly string[];
+}
+
+type GraphSubmitted = {
+  type: 'GraphSubmitted';
+  data: { graphId: string; jobs: readonly Job[]; failurePolicy: FailurePolicy };
+};
+
+type JobDispatched = {
+  type: 'JobDispatched';
+  data: { jobId: string; target: string; correlationId: string };
+};
+type JobSucceeded = { type: 'JobSucceeded'; data: { jobId: string; result?: unknown } };
+type JobFailed = { type: 'JobFailed'; data: { jobId: string; error: string } };
+type JobSkipped = { type: 'JobSkipped'; data: { jobId: string; reason: string } };
+type JobTimedOut = { type: 'JobTimedOut'; data: { jobId: string; timeoutMs: number } };
+
+export type JobGraphEvent = GraphSubmitted | JobDispatched | JobSucceeded | JobFailed | JobSkipped | JobTimedOut;
+
+type PendingGraphState = { status: 'pending' };
+type ProcessingGraphState = {
+  status: 'processing';
+  graphId: string;
+  failurePolicy: FailurePolicy;
+  jobs: Map<string, JobState>;
+};
+
+export type GraphState = PendingGraphState | ProcessingGraphState;
+
+export function initialState(): GraphState {
+  return { status: 'pending' };
+}
+
+export function evolve(state: GraphState, event: JobGraphEvent): GraphState {
+  switch (event.type) {
+    case 'GraphSubmitted':
+      return {
+        status: 'processing',
+        graphId: event.data.graphId,
+        failurePolicy: event.data.failurePolicy,
+        jobs: new Map(
+          event.data.jobs.map((job): [string, JobState] => [
+            job.id,
+            { jobId: job.id, status: 'pending', dependsOn: job.dependsOn },
+          ]),
+        ),
+      };
+    case 'JobDispatched':
+      return updateJobStatus(state, event.data.jobId, 'dispatched');
+    case 'JobSucceeded':
+      return updateJobStatus(state, event.data.jobId, 'succeeded');
+    case 'JobFailed':
+      return updateJobStatus(state, event.data.jobId, 'failed');
+    case 'JobSkipped':
+      return updateJobStatus(state, event.data.jobId, 'skipped');
+    case 'JobTimedOut':
+      return updateJobStatus(state, event.data.jobId, 'timed-out');
+  }
+}
+
+function updateJobStatus(state: GraphState, jobId: string, status: JobStatus): GraphState {
+  if (state.status !== 'processing') return state;
+  const jobs = new Map(state.jobs);
+  const existing = jobs.get(jobId);
+  if (existing === undefined) return state;
+  jobs.set(jobId, { ...existing, status });
+  return { ...state, jobs };
+}
+
+const TERMINAL_STATUSES: ReadonlySet<JobStatus> = new Set(['succeeded', 'failed', 'skipped', 'timed-out']);
+
+export function isGraphComplete(state: GraphState): boolean {
+  if (state.status !== 'processing') return false;
+  for (const job of state.jobs.values()) {
+    if (!TERMINAL_STATUSES.has(job.status)) return false;
+  }
+  return true;
+}
+
+export function getTransitiveDependents(state: GraphState, jobId: string): string[] {
+  if (state.status !== 'processing') return [];
+  const dependents: Set<string> = new Set();
+  const queue = [jobId];
+  while (queue.length > 0) {
+    const current = queue.pop()!;
+    for (const [id, job] of state.jobs) {
+      if (!dependents.has(id) && job.dependsOn.includes(current)) {
+        dependents.add(id);
+        queue.push(id);
+      }
+    }
+  }
+  return [...dependents];
+}
+
+export function getReadyJobs(state: GraphState): string[] {
+  if (state.status !== 'processing') return [];
+  const ready: string[] = [];
+  for (const [id, job] of state.jobs) {
+    if (job.status !== 'pending') continue;
+    const allDepsResolved = job.dependsOn.every((dep) => {
+      const depJob = state.jobs.get(dep);
+      return (
+        depJob !== undefined &&
+        (depJob.status === 'succeeded' || (state.failurePolicy === 'continue' && TERMINAL_STATUSES.has(depJob.status)))
+      );
+    });
+    if (allDepsResolved) {
+      ready.push(id);
+    }
+  }
+  return ready;
+}