@cargo-ai/cli 1.0.55 → 1.0.57

package/build/commands/orchestration/nodeDiagram.js

@@ -13,24 +13,117 @@
 //   * `childrenUuids` order carries the routing semantics (index 0 of a
 //     `branch` is the matched path), so edge labels are table-driven rather
 //     than inferred from node names.
-const ROUTING_ACTIONS = [
+/** Actions that route rather than do work. Shared, so adding one to the
+ * platform does not have to be mirrored in each renderer. */
+export const ROUTING_ACTIONS = new Set([
     "branch",
     "filter",
     "switch",
     "split",
     "balance",
     "humanReview",
-];
+]);
 const CODE_ACTIONS = ["python", "script"];
 // ---------------------------------------------------------------------------
+// Graph basics, shared by every renderer
+// ---------------------------------------------------------------------------
+export function isStart(node) {
+    if (node === undefined)
+        return false;
+    return node.kind === "native" && node.actionSlug === "start";
+}
+export function isEnd(node) {
+    if (node === undefined)
+        return false;
+    return node.kind === "native" && node.actionSlug === "end";
+}
+export function indexByUuid(nodes) {
+    const byUuid = new Map();
+    for (const node of nodes) {
+        if (typeof node.uuid === "string")
+            byUuid.set(node.uuid, node);
+    }
+    return byUuid;
+}
+/** Where the graph begins — the `start` node, or the first node if it has none. */
+export function findStart(nodes) {
+    const start = nodes.find(isStart);
+    return start === undefined ? nodes[0] : start;
+}
+/**
+ * Whether a user-supplied `--paid` / `--highlight` token names this node.
+ * Slugs repeat within a release, so a slug token marks every node carrying it;
+ * pass a uuid to mark exactly one.
+ */
+export function matchesNode(node, needles) {
+    const slug = node.slug === null ? undefined : node.slug;
+    return needles.some((needle) => needle === node.uuid || needle === slug);
+}
+/**
+ * A node's outgoing edges, in `childrenUuids` order, labelled by what the
+ * routing node means. Shared because this encodes routing *semantics* — index
+ * order, and the rule that a fallback pointing at the node's own next step is
+ * the same arrow rather than a second one. Two copies would let the two formats
+ * draw different graphs from one release.
+ */
+/**
+ * A fallback pointing at the node's own next step: a failure here does not stop
+ * the run. It is not a second arrow — it is the same one — so it shows as a mark
+ * on the step rather than an edge. Silently dropping it makes a step that
+ * survives a provider outage look like one that dies on it, which is the exact
+ * misread this command exists to prevent.
+ */
+export function continuesOnFailure(node) {
+    const fallback = node.fallbackChildUuid;
+    if (typeof fallback !== "string")
+        return false;
+    return childrenOf(node).includes(fallback);
+}
+/** A node's child slots, in order, including the empty ones. */
+function childrenOf(node) {
+    const children = node.childrenUuids;
+    return children === null || children === undefined ? [] : children;
+}
+export function outgoingEdges(node, byUuid) {
+    const children = childrenOf(node);
+    const labels = edgeLabels(node, children.length);
+    const edges = [];
+    children.forEach((child, index) => {
+        if (typeof child === "string" && byUuid.has(child)) {
+            edges.push({ to: child, label: labels[index] });
+        }
+    });
+    const fallback = node.fallbackChildUuid;
+    if (typeof fallback === "string" &&
+        byUuid.has(fallback) &&
+        !children.includes(fallback)) {
+        edges.push({ to: fallback, label: "on failure", dashed: true });
+    }
+    return edges;
+}
+/** Structural problems worth saying out loud rather than drawing over. */
+export function graphWarnings(nodes, byUuid, reached) {
+    const warnings = [];
+    const name = (node) => node.slug === null || node.slug === undefined ? node.uuid : node.slug;
+    const orphans = nodes.filter((node) => typeof node.uuid === "string" && !reached.has(node.uuid));
+    if (orphans.length > 0) {
+        warnings.push(`unreachable from start: ${orphans.map(name).join(", ")} — these nodes never run`);
+    }
+    const dangling = nodes.filter((node) => childrenOf(node).some((child) => child === null || byUuid.has(child) === false));
+    if (dangling.length > 0) {
+        warnings.push(`dangling childrenUuids (null or unknown) on: ${dangling.map(name).join(", ")} — the graph stops there`);
+    }
+    return warnings;
+}
+// ---------------------------------------------------------------------------
 // Shapes and labels
 // ---------------------------------------------------------------------------
 function shapeFor(node) {
     const action = node.actionSlug ?? "";
     if (node.kind === "native") {
-        if (action === "start" || action === "end")
+        if (isStart(node) || isEnd(node))
             return ["([", "])"];
-        if (ROUTING_ACTIONS.includes(action))
+        if (ROUTING_ACTIONS.has(action))
             return ["{", "}"];
         if (CODE_ACTIONS.includes(action))
             return ["[/", "/]"];
@@ -146,7 +239,7 @@ export function labelFor(node) {
  * is the matched path, index 1 the unmatched one. Getting this backwards
  * inverts the diagram's meaning, so it is table-driven, never inferred.
  */
-function edgeLabels(node, count) {
+export function edgeLabels(node, count) {
     const action = node.kind === "native" ? (node.actionSlug ?? "") : "";
     if (action === "branch")
         return ["yes", "no"];
@@ -179,9 +272,6 @@ function edgeLabels(node, count) {
 // ---------------------------------------------------------------------------
 // Rendering
 // ---------------------------------------------------------------------------
-function matches(node, needles) {
-    return needles.some((needle) => needle === node.uuid || needle === (node.slug ?? undefined));
-}
 function subNodes(node) {
     const nested = node.config?.["_nodes"];
     return Array.isArray(nested) && nested.length > 0
@@ -192,11 +282,7 @@ function renderNodes(nodes, context) {
     const warnings = [];
     const highlighted = [];
     const direction = context.direction;
-    const byUuid = new Map();
-    for (const node of nodes) {
-        if (typeof node.uuid === "string")
-            byUuid.set(node.uuid, node);
-    }
+    const byUuid = indexByUuid(nodes);
     // Ids come from a breadth-first walk from `start`, so the diagram reads in
     // execution order and is stable across runs. Slugs are never used as ids:
     // they repeat within a single release.
@@ -204,7 +290,7 @@ function renderNodes(nodes, context) {
     const ids = new Map();
     const seen = new Set();
     const queue = [];
-    const start = nodes.find((node) => node.kind === "native" && node.actionSlug === "start") ?? nodes[0];
+    const start = findStart(nodes);
     if (start !== undefined)
         queue.push(start.uuid);
     while (queue.length > 0) {
@@ -236,28 +322,29 @@ function renderNodes(nodes, context) {
     if (orphans.length > 0) {
         warnings.push(`unreachable from start: ${orphans.map((node) => node.slug ?? node.uuid).join(", ")} — these nodes never run`);
     }
+    // Edges come from the shared walk, so both formats encode routing the same
+    // way — index order, and the rule that a fallback pointing at a node's own
+    // next step is a ↷ mark rather than a second arrow. Only the id mapping is
+    // Mermaid's own.
     const edges = [];
     const dangling = new Set();
     for (const { id, node } of order) {
-        const children = node.childrenUuids ?? [];
-        const labels = edgeLabels(node, children.length);
-        children.forEach((child, index) => {
-            const target = child !== null && child !== undefined ? ids.get(child) : undefined;
-            if (target === undefined) {
-                dangling.add(node.slug ?? id);
-                return;
-            }
-            edges.push({ from: id, to: target, label: labels[index] });
-        });
-        // A fallback pointing at the node's own next step means "a failure here
-        // does not stop the run" — the same arrow, not a second one. Drawing it
-        // twice clutters the graph, so it becomes a ↷ marker on the label instead.
-        const fallbackUuid = node.fallbackChildUuid;
-        if (fallbackUuid !== null && fallbackUuid !== undefined) {
-            const target = ids.get(fallbackUuid);
-            if (target !== undefined && !children.includes(fallbackUuid)) {
-                edges.push({ from: id, to: target, label: "on failure", dashed: true });
-            }
+        for (const edge of outgoingEdges(node, byUuid)) {
+            const target = ids.get(edge.to);
+            if (target === undefined)
+                continue;
+            edges.push({
+                from: id,
+                to: target,
+                label: edge.label,
+                dashed: edge.dashed,
+            });
+        }
+        // `outgoingEdges` drops unusable slots by design; the diagram still has to
+        // report them, and it reports the node rather than the slot.
+        const hasUnusableSlot = childrenOf(node).some((child) => child === null || byUuid.has(child) === false);
+        if (hasUnusableSlot) {
+            dangling.add(node.slug === null || node.slug === undefined ? id : node.slug);
         }
     }
     if (dangling.size > 0) {
@@ -266,14 +353,10 @@ function renderNodes(nodes, context) {
     const lines = [];
     for (const { id, node } of order) {
         const [open, close] = shapeFor(node);
-        const paid = matches(node, context.paid) ? "💳 " : "";
-        if (matches(node, context.highlight))
+        const paid = matchesNode(node, context.paid) ? "💳 " : "";
+        if (matchesNode(node, context.highlight))
             highlighted.push(id);
-        const children = node.childrenUuids ?? [];
-        const continuesOnFailure = node.fallbackChildUuid !== null &&
-            node.fallbackChildUuid !== undefined &&
-            children.includes(node.fallbackChildUuid);
-        lines.push(`    ${id}${open}"${paid}${labelFor(node)}${continuesOnFailure ? " ↷" : ""}"${close}`);
+        lines.push(`    ${id}${open}"${paid}${labelFor(node)}${continuesOnFailure(node) ? " ↷" : ""}"${close}`);
         // A group's steps are drawn inside a sub-graph, under an id namespace of
         // their own — `--paid` and `--highlight` apply just as they do out here,
         // since a billing step buried in a loop is exactly the one worth seeing.

package/build/commands/orchestration/nodeDiagramAscii.d.ts

@@ -0,0 +1,32 @@
+import { displayWidth } from "./asciiBlocks.js";
+import { type DiagramNode } from "./nodeDiagram.js";
+/**
+ * Display names from the integration catalog. A graph stores wire slugs
+ * (`apolloio`, `enrichPerson`); the reader knows the product by its name.
+ * Optional throughout, so a graph diagrammed offline still renders.
+ */
+export type NameBook = {
+    /** integration slug → product name, e.g. `apolloio` → `Apollo.io`. */
+    integrations?: Record<string, string>;
+    /** integration slug → action slug → action name. */
+    actions?: Record<string, Record<string, string>>;
+    /** native action slug → action name, e.g. `script` → `JavaScript`. */
+    native?: Record<string, string>;
+};
+export type AsciiOptions = {
+    title?: string;
+    /** Catalog names, so steps read as products rather than as slugs. */
+    names?: NameBook;
+    /** Node slugs or uuids that bill credits — marked with 💳. */
+    paid?: string[];
+    /** Node slugs or uuids to mark, e.g. the failing node in a trace. */
+    highlight?: string[];
+};
+export { displayWidth };
+export type AsciiResult = {
+    diagram: string;
+    format: "ascii";
+    warnings: string[];
+};
+export declare function renderNodeAscii(nodes: DiagramNode[], options?: AsciiOptions): AsciiResult;
+//# sourceMappingURL=nodeDiagramAscii.d.ts.map

package/build/commands/orchestration/nodeDiagramAscii.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeDiagramAscii.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/nodeDiagramAscii.ts"],"names":[],"mappings":"AA4BA,OAAO,EAEL,YAAY,EAWb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAEL,KAAK,WAAW,EAQjB,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAkkBF,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAAE,EACpB,OAAO,GAAE,YAAiB,GACzB,WAAW,CAiDb"}