@auto-engineer/job-graph-processor 1.12.1

package/src/graph-processor.specs.ts

@@ -0,0 +1,331 @@
+import { createMessageBus } from '@auto-engineer/message-bus';
+import { describe, expect, it } from 'vitest';
+import { createGraphProcessor } from './graph-processor';
+
+describe('createGraphProcessor', () => {
+  it('rejects duplicate graph submissions', () => {
+    const bus = createMessageBus();
+    const processor = createGraphProcessor(bus);
+    const command = {
+      type: 'ProcessGraph' as const,
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [] as string[], target: 'build', payload: {} }],
+        failurePolicy: 'halt' as const,
+      },
+    };
+
+    processor.submit(command);
+    const second = processor.submit(command);
+
+    expect(second).toEqual({
+      type: 'graph.failed',
+      data: { graphId: 'g1', reason: 'Graph g1 already submitted' },
+    });
+  });
+
+  it('rejects invalid graph', () => {
+    const bus = createMessageBus();
+    const processor = createGraphProcessor(bus);
+
+    const result = processor.submit({
+      type: 'ProcessGraph',
+      data: { graphId: 'g1', jobs: [], failurePolicy: 'halt' },
+    });
+
+    expect(result).toEqual({
+      type: 'graph.failed',
+      data: { graphId: 'g1', reason: 'Graph must contain at least one job' },
+    });
+  });
+
+  it('dispatches ready jobs and returns dispatching event', () => {
+    const bus = createMessageBus();
+    const processor = createGraphProcessor(bus);
+
+    const result = processor.submit({
+      type: 'ProcessGraph',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: { src: './app' } },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+
+    expect(result).toEqual({
+      type: 'graph.dispatching',
+      data: {
+        graphId: 'g1',
+        dispatchedJobs: [{ jobId: 'a', target: 'build', payload: { src: './app' }, correlationId: 'graph:g1:a' }],
+      },
+    });
+  });
+
+  it('processes correlated events and emits graph.completed', async () => {
+    const bus = createMessageBus();
+    const processor = createGraphProcessor(bus);
+    const completed: Array<{ type: string; data: Record<string, unknown> }> = [];
+    bus.subscribeToEvent('graph.completed', {
+      name: 'completionTracker',
+      handle: (event) => {
+        completed.push(event);
+      },
+    });
+
+    processor.submit({
+      type: 'ProcessGraph',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: {} }],
+        failurePolicy: 'halt',
+      },
+    });
+
+    await bus.publishEvent({
+      type: 'BuildCompleted',
+      data: { output: 'ok' },
+      correlationId: 'graph:g1:a',
+    });
+
+    expect(completed).toEqual([{ type: 'graph.completed', data: { graphId: 'g1' } }]);
+  });
+
+  it('dispatches dependent jobs when deps complete via correlation', async () => {
+    const bus = createMessageBus();
+    const processor = createGraphProcessor(bus);
+    const completed: Array<{ type: string; data: Record<string, unknown> }> = [];
+    bus.subscribeToEvent('graph.completed', {
+      name: 'completionTracker',
+      handle: (event) => {
+        completed.push(event);
+      },
+    });
+
+    processor.submit({
+      type: 'ProcessGraph',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+
+    await bus.publishEvent({
+      type: 'BuildCompleted',
+      data: {},
+      correlationId: 'graph:g1:a',
+    });
+
+    await bus.publishEvent({
+      type: 'TestPassed',
+      data: {},
+      correlationId: 'graph:g1:b',
+    });
+
+    expect(completed).toEqual([{ type: 'graph.completed', data: { graphId: 'g1' } }]);
+  });
+
+  it('ignores correlated events after graph completes', async () => {
+    const bus = createMessageBus();
+    const processor = createGraphProcessor(bus);
+    const completed: Array<{ type: string; data: Record<string, unknown> }> = [];
+    bus.subscribeToEvent('graph.completed', {
+      name: 'completionTracker',
+      handle: (event) => {
+        completed.push(event);
+      },
+    });
+
+    processor.submit({
+      type: 'ProcessGraph',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: {} }],
+        failurePolicy: 'halt',
+      },
+    });
+
+    await bus.publishEvent({
+      type: 'BuildCompleted',
+      data: {},
+      correlationId: 'graph:g1:a',
+    });
+
+    await bus.publishEvent({
+      type: 'LateEvent',
+      data: {},
+      correlationId: 'graph:g1:a',
+    });
+
+    expect(completed).toEqual([{ type: 'graph.completed', data: { graphId: 'g1' } }]);
+  });
+
+  it('ignores events with unrecognized correlationId format', async () => {
+    const bus = createMessageBus();
+    const processor = createGraphProcessor(bus);
+    const completed: Array<{ type: string; data: Record<string, unknown> }> = [];
+    bus.subscribeToEvent('graph.completed', {
+      name: 'completionTracker',
+      handle: (event) => {
+        completed.push(event);
+      },
+    });
+
+    processor.submit({
+      type: 'ProcessGraph',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: {} }],
+        failurePolicy: 'halt',
+      },
+    });
+
+    await bus.publishEvent({
+      type: 'WeirdEvent',
+      data: {},
+      correlationId: 'graph:g1:',
+    });
+
+    expect(completed).toEqual([]);
+  });
+
+  it('sends target commands for initial ready jobs', async () => {
+    const bus = createMessageBus();
+    const processor = createGraphProcessor(bus);
+    const received: Array<{ type: string; data: unknown; correlationId?: string }> = [];
+    bus.registerCommandHandler({
+      name: 'build',
+      handle: async (command) => {
+        received.push({ type: command.type, data: command.data, correlationId: command.correlationId });
+        return { type: 'BuildCompleted', data: {} };
+      },
+    });
+
+    processor.submit({
+      type: 'ProcessGraph',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: { src: './app' } }],
+        failurePolicy: 'halt',
+      },
+    });
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(received).toEqual([{ type: 'build', data: { src: './app' }, correlationId: 'graph:g1:a' }]);
+  });
+
+  it('sends target commands for newly ready dependent jobs', async () => {
+    const bus = createMessageBus();
+    const processor = createGraphProcessor(bus);
+    const received: Array<{ type: string; data: unknown; correlationId?: string }> = [];
+    bus.registerCommandHandler({
+      name: 'build',
+      handle: async (command) => {
+        received.push({ type: command.type, data: command.data, correlationId: command.correlationId });
+        return { type: 'BuildCompleted', data: {} };
+      },
+    });
+    bus.registerCommandHandler({
+      name: 'test',
+      handle: async (command) => {
+        received.push({ type: command.type, data: command.data, correlationId: command.correlationId });
+        return { type: 'TestPassed', data: {} };
+      },
+    });
+
+    processor.submit({
+      type: 'ProcessGraph',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: { src: './app' } },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: { suite: 'unit' } },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(received).toEqual([
+      { type: 'build', data: { src: './app' }, correlationId: 'graph:g1:a' },
+      { type: 'test', data: { suite: 'unit' }, correlationId: 'graph:g1:b' },
+    ]);
+  });
+
+  it('uses dispatch callback instead of messageBus.sendCommand when provided', async () => {
+    const bus = createMessageBus();
+    const dispatched: Array<{ type: string; data: unknown; correlationId: string }> = [];
+    const dispatch = async (command: { type: string; data: unknown; correlationId: string }) => {
+      dispatched.push(command);
+    };
+    const processor = createGraphProcessor(bus, { dispatch });
+
+    processor.submit({
+      type: 'ProcessGraph',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: { src: './app' } }],
+        failurePolicy: 'halt',
+      },
+    });
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(dispatched).toEqual([{ type: 'build', data: { src: './app' }, correlationId: 'graph:g1:a' }]);
+  });
+
+  it('rejects command with missing jobs', () => {
+    const bus = createMessageBus();
+    const processor = createGraphProcessor(bus);
+
+    const result = processor.submit({
+      type: 'ProcessGraph',
+      data: { graphId: 'g1', failurePolicy: 'halt' } as any,
+    });
+
+    expect(result).toEqual({
+      type: 'graph.failed',
+      data: { graphId: 'g1', reason: 'jobs is required and must be an array' },
+    });
+  });
+
+  it('applies halt policy when job fails via correlation', async () => {
+    const bus = createMessageBus();
+    const processor = createGraphProcessor(bus);
+    const completed: Array<{ type: string; data: Record<string, unknown> }> = [];
+    bus.subscribeToEvent('graph.completed', {
+      name: 'completionTracker',
+      handle: (event) => {
+        completed.push(event);
+      },
+    });
+
+    processor.submit({
+      type: 'ProcessGraph',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+
+    await bus.publishEvent({
+      type: 'BuildFailed',
+      data: { error: 'compile error' },
+      correlationId: 'graph:g1:a',
+    });
+
+    expect(completed).toEqual([{ type: 'graph.completed', data: { graphId: 'g1' } }]);
+  });
+});

package/src/graph-processor.ts

@@ -0,0 +1,121 @@
+import type { Event, MessageBus } from '@auto-engineer/message-bus';
+import { applyPolicy } from './apply-policy';
+import type { FailurePolicy, GraphState } from './evolve';
+import { evolve, getReadyJobs, initialState, isGraphComplete } from './evolve';
+import type { Job } from './graph-validator';
+import { validateGraph } from './graph-validator';
+import { classifyJobEvent } from './handle-job-event';
+
+export interface ProcessGraphCommand {
+  type: string;
+  data: {
+    graphId: string;
+    jobs: readonly Job[];
+    failurePolicy: FailurePolicy;
+  };
+}
+
+interface DispatchedJob {
+  jobId: string;
+  target: string;
+  payload: unknown;
+  correlationId: string;
+}
+
+export type DispatchFn = (command: { type: string; data: unknown; correlationId: string }) => Promise<void>;
+
+export function createGraphProcessor(messageBus: MessageBus, options?: { dispatch?: DispatchFn }) {
+  const dispatch: DispatchFn =
+    options?.dispatch ??
+    ((cmd) =>
+      messageBus.sendCommand({
+        type: cmd.type,
+        data: cmd.data as Record<string, unknown>,
+        correlationId: cmd.correlationId,
+      }));
+  const graphs = new Map<string, { state: GraphState; jobById: Record<string, Job> }>();
+
+  function submit(command: ProcessGraphCommand): Event {
+    const { graphId, jobs, failurePolicy } = command.data;
+
+    if (graphs.has(graphId)) {
+      return { type: 'graph.failed', data: { graphId, reason: `Graph ${graphId} already submitted` } };
+    }
+
+    if (!Array.isArray(jobs)) {
+      return { type: 'graph.failed', data: { graphId, reason: 'jobs is required and must be an array' } };
+    }
+
+    const validation = validateGraph(jobs);
+    if (!validation.valid) {
+      return { type: 'graph.failed', data: { graphId, reason: validation.error } };
+    }
+
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: { graphId, jobs, failurePolicy },
+    });
+
+    const ready = getReadyJobs(state);
+    const jobById: Record<string, Job> = {};
+    for (const job of jobs) {
+      jobById[job.id] = job;
+    }
+
+    const dispatched: DispatchedJob[] = ready.map((jobId) => {
+      const correlationId = `graph:${graphId}:${jobId}`;
+      state = evolve(state, {
+        type: 'JobDispatched',
+        data: { jobId, target: jobById[jobId].target, correlationId },
+      });
+      return { jobId, target: jobById[jobId].target, payload: jobById[jobId].payload, correlationId };
+    });
+
+    graphs.set(graphId, { state, jobById });
+
+    messageBus.onCorrelationPrefix(`graph:${graphId}:`, (event) => {
+      onJobEvent(graphId, event);
+    });
+
+    for (const d of dispatched) {
+      dispatch({ type: d.target, data: d.payload, correlationId: d.correlationId }).catch(() => {});
+    }
+
+    return { type: 'graph.dispatching', data: { graphId, dispatchedJobs: dispatched } };
+  }
+
+  function onJobEvent(graphId: string, event: Event): void {
+    const entry = graphs.get(graphId);
+    if (entry === undefined) return;
+
+    const classified = classifyJobEvent(event);
+    if (classified === null) return;
+    let state = evolve(entry.state, classified);
+
+    if (classified.type === 'JobFailed') {
+      const policyEvents = applyPolicy(state, classified.data.jobId);
+      for (const pe of policyEvents) {
+        state = evolve(state, pe);
+      }
+    }
+
+    for (const jobId of getReadyJobs(state)) {
+      const correlationId = `graph:${graphId}:${jobId}`;
+      const { target, payload } = entry.jobById[jobId];
+      state = evolve(state, {
+        type: 'JobDispatched',
+        data: { jobId, target, correlationId },
+      });
+      dispatch({ type: target, data: payload, correlationId }).catch(() => {});
+    }
+
+    graphs.set(graphId, { ...entry, state });
+
+    if (isGraphComplete(state)) {
+      graphs.delete(graphId);
+      messageBus.publishEvent({ type: 'graph.completed', data: { graphId } });
+    }
+  }
+
+  return { submit };
+}

package/src/graph-validator.specs.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import type { Job } from './graph-validator';
+import { validateGraph } from './graph-validator';
+
+describe('validateGraph', () => {
+  it('returns valid for a correct graph with no dependencies', () => {
+    const jobs: Job[] = [
+      { id: 'a', dependsOn: [], target: 'build', payload: {} },
+      { id: 'b', dependsOn: [], target: 'test', payload: {} },
+    ];
+
+    expect(validateGraph(jobs)).toEqual({ valid: true });
+  });
+
+  it('returns valid for a correct graph with dependencies', () => {
+    const jobs: Job[] = [
+      { id: 'a', dependsOn: [], target: 'build', payload: {} },
+      { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+    ];
+
+    expect(validateGraph(jobs)).toEqual({ valid: true });
+  });
+
+  it('returns error for duplicate job IDs', () => {
+    const jobs: Job[] = [
+      { id: 'a', dependsOn: [], target: 'build', payload: {} },
+      { id: 'a', dependsOn: [], target: 'test', payload: {} },
+    ];
+
+    expect(validateGraph(jobs)).toEqual({
+      valid: false,
+      error: "Duplicate job ID: 'a'",
+    });
+  });
+
+  it('returns error for missing dependency', () => {
+    const jobs: Job[] = [{ id: 'a', dependsOn: ['missing'], target: 'build', payload: {} }];
+
+    expect(validateGraph(jobs)).toEqual({
+      valid: false,
+      error: "Job 'a' depends on unknown job 'missing'",
+    });
+  });
+
+  it('returns error for self-reference', () => {
+    const jobs: Job[] = [{ id: 'a', dependsOn: ['a'], target: 'build', payload: {} }];
+
+    expect(validateGraph(jobs)).toEqual({
+      valid: false,
+      error: "Job 'a' depends on itself",
+    });
+  });
+
+  it('returns error for cycle', () => {
+    const jobs: Job[] = [
+      { id: 'a', dependsOn: ['b'], target: 'build', payload: {} },
+      { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+    ];
+
+    expect(validateGraph(jobs)).toEqual({
+      valid: false,
+      error: "Cycle detected involving job 'a'",
+    });
+  });
+
+  it('returns error for transitive cycle', () => {
+    const jobs: Job[] = [
+      { id: 'a', dependsOn: ['c'], target: 'build', payload: {} },
+      { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+      { id: 'c', dependsOn: ['b'], target: 'lint', payload: {} },
+    ];
+
+    expect(validateGraph(jobs)).toEqual({
+      valid: false,
+      error: "Cycle detected involving job 'a'",
+    });
+  });
+
+  it('returns error for empty target', () => {
+    const jobs: Job[] = [{ id: 'a', dependsOn: [], target: '', payload: {} }];
+
+    expect(validateGraph(jobs)).toEqual({
+      valid: false,
+      error: "Job 'a' has empty target",
+    });
+  });
+
+  it('returns valid for diamond dependency graph', () => {
+    const jobs: Job[] = [
+      { id: 'a', dependsOn: [], target: 'build', payload: {} },
+      { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+      { id: 'c', dependsOn: ['a'], target: 'lint', payload: {} },
+      { id: 'd', dependsOn: ['b', 'c'], target: 'deploy', payload: {} },
+    ];
+
+    expect(validateGraph(jobs)).toEqual({ valid: true });
+  });
+
+  it('returns error for empty jobs array', () => {
+    expect(validateGraph([])).toEqual({
+      valid: false,
+      error: 'Graph must contain at least one job',
+    });
+  });
+});

package/src/graph-validator.ts

@@ -0,0 +1,94 @@
+export interface Job {
+  id: string;
+  dependsOn: readonly string[];
+  target: string;
+  payload: unknown;
+  timeoutMs?: number;
+  retries?: number;
+  backoffMs?: number;
+  maxBackoffMs?: number;
+}
+
+type ValidationResult = { valid: true } | { valid: false; error: string };
+
+export function validateGraph(jobs: readonly Job[]): ValidationResult {
+  if (jobs.length === 0) {
+    return { valid: false, error: 'Graph must contain at least one job' };
+  }
+
+  const ids = new Set<string>();
+  for (const job of jobs) {
+    if (ids.has(job.id)) {
+      return { valid: false, error: `Duplicate job ID: '${job.id}'` };
+    }
+    ids.add(job.id);
+  }
+
+  for (const job of jobs) {
+    if (job.target === '') {
+      return { valid: false, error: `Job '${job.id}' has empty target` };
+    }
+
+    for (const dep of job.dependsOn) {
+      if (dep === job.id) {
+        return { valid: false, error: `Job '${job.id}' depends on itself` };
+      }
+      if (!ids.has(dep)) {
+        return { valid: false, error: `Job '${job.id}' depends on unknown job '${dep}'` };
+      }
+    }
+  }
+
+  const cycleError = detectCycles(jobs);
+  if (cycleError !== null) {
+    return { valid: false, error: cycleError };
+  }
+
+  return { valid: true };
+}
+
+function detectCycles(jobs: readonly Job[]): string | null {
+  const adjacency: Record<string, readonly string[]> = {};
+  for (const job of jobs) {
+    adjacency[job.id] = job.dependsOn;
+  }
+
+  const visited = new Set<string>();
+  const inStack = new Set<string>();
+
+  for (const job of jobs) {
+    if (!visited.has(job.id)) {
+      const cycleNode = dfs(job.id, adjacency, visited, inStack);
+      if (cycleNode !== null) {
+        return `Cycle detected involving job '${cycleNode}'`;
+      }
+    }
+  }
+
+  return null;
+}
+
+function dfs(
+  nodeId: string,
+  adjacency: Record<string, readonly string[]>,
+  visited: Set<string>,
+  inStack: Set<string>,
+): string | null {
+  visited.add(nodeId);
+  inStack.add(nodeId);
+
+  for (const dep of adjacency[nodeId]) {
+    if (inStack.has(dep)) {
+      return dep;
+    }
+    if (!visited.has(dep)) {
+      const result = dfs(dep, adjacency, visited, inStack);
+      if (result !== null) {
+        return result;
+      }
+    }
+  }
+
+  inStack.delete(nodeId);
+  return null;
+}