@ryanfw/prompt-orchestration-pipeline 0.11.0 → 0.13.0

package/src/task-analysis/extractors/llm-calls.js

@@ -0,0 +1,176 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const traverse =
+  require("@babel/traverse").default ?? require("@babel/traverse");
+import * as t from "@babel/types";
+import { getStageName } from "../utils/ast.js";
+
+/**
+ * Extract LLM method calls from the AST.
+ *
+ * Matches direct calls like:
+ * - llm.deepseek.chat(...)
+ * - llm.openai.gpt5Mini(...)
+ * - llm.anthropic.sonnet45(...)
+ * - llm.gemini.flash25(...)
+ *
+ * And destructured calls like:
+ * - const { deepseek } = llm; deepseek.chat(...)
+ *
+ * @param {import("@babel/types").File} ast - The AST to analyze
+ * @returns {Array<{provider: string, method: string, stage: string}>} Array of LLM call references
+ * @throws {Error} If LLM call is found outside an exported function
+ */
+export function extractLLMCalls(ast) {
+  const calls = [];
+
+  traverse(ast, {
+    CallExpression(path) {
+      const { callee } = path.node;
+
+      // Match: llm.provider.method(...)
+      if (isDirectLLMCall(callee)) {
+        const provider = callee.object.property.name;
+        const method = callee.property.name;
+        const stage = getStageName(path);
+
+        if (!stage) {
+          throw new Error(
+            `LLM call found outside an exported function at ${path.node.loc?.start?.line}:${path.node.loc?.start?.column}`
+          );
+        }
+
+        calls.push({ provider, method, stage });
+      }
+
+      // Match: provider.method(...) where provider was destructured from llm
+      if (isDestructuredLLMCall(callee, path)) {
+        const provider = callee.object.name;
+        const method = callee.property.name;
+        const stage = getStageName(path);
+
+        if (!stage) {
+          throw new Error(
+            `LLM call found outside an exported function at ${path.node.loc?.start?.line}:${path.node.loc?.start?.column}`
+          );
+        }
+
+        calls.push({ provider, method, stage });
+      }
+    },
+  });
+
+  return calls;
+}
+
+/**
+ * Check if a callee node is a direct LLM call pattern.
+ *
+ * Matches nested member expressions: llm.provider.method
+ *
+ * @param {import("@babel/types").Node} callee - The callee node to check
+ * @returns {boolean} True if the callee is a direct LLM call pattern
+ */
+function isDirectLLMCall(callee) {
+  // Must be a member expression (e.g., llm.provider.method)
+  if (!t.isMemberExpression(callee)) {
+    return false;
+  }
+
+  // The object must also be a member expression (e.g., llm.provider)
+  if (!t.isMemberExpression(callee.object)) {
+    return false;
+  }
+
+  // The root object must be identifier "llm"
+  if (!t.isIdentifier(callee.object.object, { name: "llm" })) {
+    return false;
+  }
+
+  // The object property must be an identifier (the provider)
+  if (!t.isIdentifier(callee.object.property)) {
+    return false;
+  }
+
+  // The callee property must be an identifier (the method)
+  if (!t.isIdentifier(callee.property)) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Check if a callee node is a destructured LLM call pattern.
+ *
+ * Matches: provider.method(...) where provider was destructured from llm
+ * Uses scope analysis to verify the identifier was actually destructured from llm
+ * in the current scope, avoiding false positives from same-named identifiers in different scopes.
+ *
+ * @param {import("@babel/types").Node} callee - The callee node to check
+ * @param {import("@babel/traverse").NodePath} path - The path of the call expression
+ * @returns {boolean} True if the callee is a destructured LLM call pattern
+ */
+function isDestructuredLLMCall(callee, path) {
+  // Must be a member expression (e.g., provider.method)
+  if (!t.isMemberExpression(callee)) {
+    return false;
+  }
+
+  // The object must be an identifier (the destructured provider)
+  if (!t.isIdentifier(callee.object)) {
+    return false;
+  }
+
+  // The callee property must be an identifier (the method)
+  if (!t.isIdentifier(callee.property)) {
+    return false;
+  }
+
+  // Get the binding for this identifier in the current scope
+  const binding = path.scope.getBinding(callee.object.name);
+  if (!binding) {
+    return false;
+  }
+
+  // Check if it was destructured from llm in a variable declaration
+  if (t.isVariableDeclarator(binding.path.node)) {
+    const { id, init } = binding.path.node;
+    // Match: const { provider } = llm
+    if (t.isObjectPattern(id) && t.isIdentifier(init, { name: "llm" })) {
+      return true;
+    }
+  }
+
+  // Check if it was destructured from llm in function parameters
+  // Match: ({ llm: { provider } }) => {}
+  if (binding.kind === "param" && t.isObjectPattern(binding.path.node)) {
+    // The binding points to the entire parameter ObjectPattern
+    // Look for a property with key "llm" whose value is an ObjectPattern
+    const llmProperty = binding.path.node.properties.find(
+      (prop) =>
+        t.isObjectProperty(prop) &&
+        t.isIdentifier(prop.key, { name: "llm" }) &&
+        t.isObjectPattern(prop.value)
+    );
+
+    if (llmProperty) {
+      // Check if the provider identifier is in the nested ObjectPattern
+      // Handles both shorthand ({ llm: { provider } }) and renamed ({ llm: { provider: alias } }) patterns
+      const providerInPattern = llmProperty.value.properties.some((innerProp) =>
+        t.isObjectProperty(innerProp)
+          ? // Check key for shorthand pattern: { provider }
+            t.isIdentifier(innerProp.key, { name: callee.object.name }) ||
+            // Check value for renamed pattern: { provider: alias } where we're looking for alias
+            t.isIdentifier(innerProp.value, { name: callee.object.name })
+          : false
+      );
+
+      if (providerInPattern) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}

package/src/task-analysis/extractors/stages.js

@@ -0,0 +1,51 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const traverse =
+  require("@babel/traverse").default ?? require("@babel/traverse");
+
+/**
+ * Extract exported function stages from an AST.
+ *
+ * Visits ExportNamedDeclaration nodes and extracts stage information
+ * including name, line order, and async status.
+ *
+ * @param {import("@babel/types").File} ast - The parsed AST
+ * @returns {Array<{name: string, order: number, isAsync: boolean}>}
+ *          Array of stages sorted by order (line number)
+ */
+export function extractStages(ast) {
+  const stages = [];
+
+  traverse(ast, {
+    ExportNamedDeclaration(path) {
+      const declaration = path.node.declaration;
+
+      // Handle: export function name() {}
+      if (declaration?.type === "FunctionDeclaration") {
+        stages.push({
+          name: declaration.id.name,
+          order: path.node.loc?.start.line ?? 0,
+          isAsync: declaration.async ?? false,
+        });
+        return;
+      }
+
+      // Handle: export const name = () => {} or export const name = async () => {}
+      // or export const name = function() {}
+      if (declaration?.type === "VariableDeclaration") {
+        const declarator = declaration.declarations[0];
+        const init = declarator?.init;
+
+        if (init?.type === "ArrowFunctionExpression" || init?.type === "FunctionExpression") {
+          stages.push({
+            name: declarator.id.name,
+            order: path.node.loc?.start.line ?? 0,
+            isAsync: init.async ?? false,
+          });
+        }
+      }
+    },
+  });
+
+  return stages.sort((a, b) => a.order - b.order);
+}

package/src/task-analysis/index.js

@@ -0,0 +1,103 @@
+import { parseTaskSource } from "./parser.js";
+import { extractStages } from "./extractors/stages.js";
+import {
+  extractArtifactReads,
+  extractArtifactWrites,
+} from "./extractors/artifacts.js";
+import { extractLLMCalls } from "./extractors/llm-calls.js";
+import { writeAnalysisFile } from "./enrichers/analysis-writer.js";
+
+/**
+ * Analyze task source code and extract metadata.
+ *
+ * This is the main entry point for the task analysis library. It parses
+ * the source code and extracts:
+ * - Stages (exported functions with order and async status)
+ * - Artifacts (read/write operations with stage context)
+ * - Models (LLM provider and method calls with stage context)
+ *
+ * @param {string} code - The task source code to analyze
+ * @param {string|null} taskFilePath - Path to the task file (optional)
+ * @returns {TaskAnalysis} Complete analysis of the task
+ * @throws {Error} If parsing or extraction fails
+ *
+ * @example
+ * const code = `
+ *   export function ingestion({ io, llm, data, flags }) {
+ *     const content = io.readArtifact("input.json");
+ *     const result = llm.deepseek.chat(content);
+ *     io.writeArtifact("output.json", result);
+ *   }
+ * `;
+ * const analysis = analyzeTask(code, "/path/to/task.js");
+ * // Returns:
+ * // {
+ * //   taskFilePath: "/path/to/task.js",
+ * //   stages: [{ name: "ingestion", order: 2, isAsync: false }],
+ * //   artifacts: {
+ * //     reads: [{ fileName: "input.json", stage: "ingestion", required: true }],
+ * //     writes: [{ fileName: "output.json", stage: "ingestion" }]
+ * //   },
+ * //   models: [{ provider: "deepseek", method: "chat", stage: "ingestion" }]
+ * // }
+ */
+export { writeAnalysisFile };
+
+export function analyzeTask(code, taskFilePath = null) {
+  // Parse the source code into an AST
+  const ast = parseTaskSource(code);
+
+  // Extract all metadata from the AST
+  const stages = extractStages(ast);
+  const reads = extractArtifactReads(ast);
+  const writes = extractArtifactWrites(ast);
+  const models = extractLLMCalls(ast);
+
+  // Compose into the TaskAnalysis object
+  return {
+    taskFilePath,
+    stages,
+    artifacts: {
+      reads,
+      writes,
+    },
+    models,
+  };
+}
+
+/**
+ * @typedef {Object} TaskAnalysis
+ * @property {string|null} taskFilePath - Path to the task file
+ * @property {Array<Stage>} stages - Array of exported function stages
+ * @property {Object} artifacts - Artifact operations
+ * @property {Array<ArtifactRead>} artifacts.reads - Artifact read operations
+ * @property {Array<ArtifactWrite>} artifacts.writes - Artifact write operations
+ * @property {Array<ModelCall>} models - LLM method calls
+ */
+
+/**
+ * @typedef {Object} Stage
+ * @property {string} name - Stage function name
+ * @property {number} order - Line number for execution order
+ * @property {boolean} isAsync - Whether the stage is async
+ */
+
+/**
+ * @typedef {Object} ArtifactRead
+ * @property {string} fileName - Name of the artifact file
+ * @property {string} stage - Stage name where read occurs
+ * @property {boolean} required - Whether the read is required (not wrapped in try/catch)
+ */
+
+/**
+ * @typedef {Object} ArtifactWrite
+ * @property {string} fileName - Name of the artifact file
+ * @property {string} stage - Stage name where write occurs
+ */
+
+/**
+ * @typedef {Object} ModelCall
+ * @property {string} provider - LLM provider name (e.g., "deepseek", "openai")
+ * @property {string} method - LLM method name (e.g., "chat", "gpt5Mini")
+ * @property {string} stage - Stage name where LLM call occurs
+ */

package/src/task-analysis/parser.js

@@ -0,0 +1,28 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const parser = require("@babel/parser");
+
+/**
+ * Parse task source code into a Babel AST.
+ *
+ * @param {string} code - The source code to parse
+ * @returns {import("@babel/types").File} The parsed AST
+ * @throws {Error} If parsing fails, includes syntax error location and message
+ */
+export function parseTaskSource(code) {
+  try {
+    const ast = parser.parse(code, {
+      sourceType: "module",
+      plugins: ["jsx"],
+    });
+    return ast;
+  } catch (error) {
+    const loc = error.loc
+      ? `line ${error.loc.line}, column ${error.loc.column}`
+      : "unknown location";
+    throw new Error(
+      `Failed to parse task source code at ${loc}: ${error.message}`,
+      { cause: error }
+    );
+  }
+}

package/src/task-analysis/utils/ast.js

@@ -0,0 +1,43 @@
+/**
+ * Check if a path is inside a try/catch block.
+ *
+ * @param {import("@babel/traverse").NodePath} path - The node path to check
+ * @returns {boolean} True if inside try/catch, false otherwise
+ */
+export function isInsideTryCatch(path) {
+  return path.findParent((p) => p.isTryStatement()) !== null;
+}
+
+/**
+ * Get the stage name by finding the nearest exported function.
+ *
+ * Walks up the AST to find the parent ExportNamedDeclaration and returns
+ * the exported identifier name.
+ *
+ * @param {import("@babel/traverse").NodePath} path - The node path to start from
+ * @returns {string | null} The stage name or null if not in exported function
+ */
+export function getStageName(path) {
+  const exportPath = path.findParent((p) => p.isExportNamedDeclaration());
+
+  if (!exportPath) {
+    return null;
+  }
+
+  const declaration = exportPath.node.declaration;
+
+  // Handle: export function name() {}
+  if (declaration?.type === "FunctionDeclaration") {
+    return declaration.id?.name ?? null;
+  }
+
+  // Handle: export const name = () => {}
+  if (declaration?.type === "VariableDeclaration") {
+    const declarator = declaration.declarations[0];
+    if (declarator?.id?.type === "Identifier") {
+      return declarator.id.name;
+    }
+  }
+
+  return null;
+}

package/src/ui/client/adapters/job-adapter.js

@@ -3,6 +3,8 @@ import {
   normalizeTaskState,
   deriveJobStatusFromTasks,
 } from "../../../config/statuses.js";
+import { classifyJobForDisplay } from "../../../utils/jobs.js";
+import { decideTransition } from "../../../core/lifecycle-policy.js";
 
 /**
  * Normalize a raw task state into canonical enum.
@@ -225,6 +227,9 @@ export function adaptJobSummary(apiJob) {
     job.totalTokens = job.costsSummary.totalTokens;
   }
 
+  // Compute and attach display category for UI bucketing
+  job.displayCategory = classifyJobForDisplay(job);
+
   // Include warnings for debugging
   if (warnings.length > 0) job.__warnings = warnings;
 
@@ -284,8 +289,63 @@ export function adaptJobDetail(apiDetail) {
     detail.costs = apiDetail.costs;
   }
 
+  // Compute and attach display category for UI bucketing
+  detail.displayCategory = classifyJobForDisplay(detail);
+
   // Include warnings for debugging
   if (warnings.length > 0) detail.__warnings = warnings;
 
   return detail;
 }
+
+/**
+ * deriveAllowedActions(adaptedJob, pipelineTasks)
+ * - adaptedJob: normalized job object from adaptJobSummary/adaptJobDetail
+ * - pipelineTasks: array of task names in execution order from pipeline.json
+ * Returns { start, restart } boolean flags for UI controls.
+ */
+export function deriveAllowedActions(adaptedJob, pipelineTasks) {
+  // Check if any task is running
+  const hasRunningTask = Object.values(adaptedJob.tasks || {}).some(
+    (task) => task.state === "running"
+  );
+
+  // Default to disabled if job state is running or any task is running
+  if (adaptedJob.status === "running" || hasRunningTask) {
+    return { start: false, restart: false };
+  }
+
+  // Default to enabled for restart if not running
+  const restart = true;
+
+  // Start requires checking if ANY task can be started (not ALL tasks)
+  // Edge case: if no pipeline tasks, default to enabled
+  if (pipelineTasks.length === 0) {
+    return { start: true, restart };
+  }
+
+  const start = pipelineTasks.some((taskName) => {
+    const task = adaptedJob.tasks[taskName];
+    if (!task) return false; // Task not found, skip
+
+    const taskState = task.state || "pending";
+
+    // Check if all upstream tasks are done for dependency evaluation
+    const taskIndex = pipelineTasks.indexOf(taskName);
+    const upstreamTasks = pipelineTasks.slice(0, taskIndex);
+    const dependenciesReady = upstreamTasks.every((upstreamTaskName) => {
+      const upstreamTask = adaptedJob.tasks[upstreamTaskName];
+      return upstreamTask && upstreamTask.state === "done";
+    });
+
+    const startDecision = decideTransition({
+      op: "start",
+      taskState,
+      dependenciesReady,
+    });
+
+    return startDecision.ok;
+  });
+
+  return { start, restart };
+}