@procedures/dag 0.2.3 → 0.4.0

package/dist/register.js

@@ -0,0 +1,10 @@
+/**
+ * Importing this file registers the procedures of @procedures/dag in the global registry:
+ * `import "@procedures/dag/register"`. The package root and the `./module` entry register nothing
+ * (ARCHITECTURE-PROPOSALS-2026-10, P9). `dag.traverse` calls `lib.scan`: also import
+ * `@procedures/lib/register`.
+ */
+import { registerDagProcedures } from "./module.js";
+export * from "./module.js";
+registerDagProcedures();
+//# sourceMappingURL=register.js.map

package/dist/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,cAAc,aAAa,CAAC;AAE5B,qBAAqB,EAAE,CAAC"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/dag",
-  "version": "0.2.3",
-  "description": "Dependency graph algorithms for TypeScript: build a DAG, detect cycles, compute topological levels and traverse in parallel with a concurrency limit.",
+  "version": "0.4.0",
+  "description": "Dependency graph algorithms for TypeScript: build a DAG, detect cycles, compute topological levels and traverse in parallel with a concurrency limit. The procedure dag.traverse visits workspace packages in dependency order.",
   "keywords": [
     "dag",
     "graph",
@@ -30,6 +30,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js"
     }
   },
   "files": [
@@ -40,7 +48,9 @@
     "!src/**/__tests__",
     "CHANGELOG.md"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/register.js"
+  ],
   "engines": {
     "node": ">=22"
   },
@@ -54,6 +64,13 @@
     "@mark1russell7/cue": "^1.0.0",
     "vitest": "^5.0.3"
   },
+  "dependencies": {
+    "@procedures/client": "0.4.0",
+    "zod": "^4.6.5"
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
   "scripts": {
     "build": "tsc -b",
     "typecheck": "tsc --noEmit",

package/src/index.ts

@@ -62,3 +62,18 @@ export {
   createNode,
   buildNodeMap,
 } from "./dag/index.js";
+
+// The procedure dag.traverse. The root registers nothing: import "@procedures/dag/register", or
+// give the module to createRegistry() with the module of @procedures/lib.
+export * from "./module.js";
+export {
+  DagTraverseInputSchema,
+  DagTraverseOutputSchema,
+  type DagTraverseInput,
+  type DagTraverseOutput,
+  type TraverseNodeResult,
+  type ScannedPackage,
+  type ScanOutput,
+  type PackageNode,
+} from "./procedures/types.js";
+export { dagTraverse, packageNodes, callsGit, keyedLock, repositoryRoot } from "./procedures/traverse.js";

package/src/module.ts

@@ -0,0 +1,76 @@
+/**
+ * Module (no side effects): the procedures of this package as data, for `createRegistry()`.
+ *
+ * The package has one procedure, `dag.traverse`. It came from `@procedures/lib`, and its name
+ * stays the same. The graph algorithms of the package root do not need this module.
+ */
+
+import {
+  createProcedure,
+  zodAdapter,
+  RUNS_REFS_TAG,
+  defineModule,
+  PROCEDURE_REGISTRY,
+  registerModules,
+  type ProcedureContext,
+  type ProcedureModule,
+  type ProcedureRegistry,
+} from "@procedures/client";
+import { dagTraverse } from "./procedures/traverse.js";
+import {
+  DagTraverseInputSchema,
+  DagTraverseOutputSchema,
+  type DagTraverseInput,
+  type DagTraverseOutput,
+} from "./procedures/types.js";
+
+// =============================================================================
+// dag.* Procedures
+// =============================================================================
+
+const dagTraverseProcedure = createProcedure()
+  .path(["dag", "traverse"])
+  .input(zodAdapter<DagTraverseInput>(DagTraverseInputSchema))
+  .output(zodAdapter<DagTraverseOutput>(DagTraverseOutputSchema))
+  .meta({
+    description: "Traverse ecosystem packages in dependency order, executing visit procedure for each",
+    // It runs the procedure refs of its input: a server with an expose rule limits what they call
+    tags: [RUNS_REFS_TAG],
+    // It gets the packages from lib.scan (@procedures/lib). This package cannot import that one,
+    // because @procedures/lib depends on this package.
+    calls: ["lib.scan"],
+    // Its own effect is the scan of the workspace. The admission examines each visit call.
+    effects: { reads: ["fs"], writes: [] },
+    args: [],
+    shorts: { root: "r", concurrency: "j", continueOnError: "c", dryRun: "d" },
+    output: "streaming",
+  })
+  .handler(async (input: DagTraverseInput, ctx: ProcedureContext): Promise<DagTraverseOutput> => {
+    return dagTraverse(input, ctx);
+  })
+  .build();
+
+// =============================================================================
+// Registration
+// =============================================================================
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ *
+ * `dag.traverse` uses `lib.scan`. This module cannot list the module of `@procedures/lib` as a
+ * dependency, because that package depends on this one. A host registers both modules
+ * (`bundle-dev`, `bundle-mcp` and `mark` do).
+ */
+export const dagModule: ProcedureModule = defineModule("@procedures/dag", [dagTraverseProcedure]);
+
+export default dagModule;
+
+/**
+ * This function registers the procedures of @procedures/dag in a registry. The default is the
+ * global registry. Importing this file registers nothing: the `./register` entry starts this
+ * function (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+export function registerDagProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [dagModule]);
+}

package/src/procedures/traverse.ts

@@ -0,0 +1,308 @@
+/**
+ * dag.traverse procedure
+ *
+ * General-purpose DAG traversal that executes a visit procedure
+ * for each node in dependency order.
+ *
+ * This enables declarative composition of traversals:
+ * ```typescript
+ * // Execute git add on all packages (using $when: "$parent")
+ * await client.exec({
+ *   $proc: ["dag", "traverse"],
+ *   input: {
+ *     visit: {
+ *       $proc: ["git", "add"],
+ *       input: { all: true },
+ *       $when: "$parent"  // Defer to dag.traverse
+ *     }
+ *   }
+ * });
+ *
+ * // Simple form with just procedure path
+ * await client.exec({
+ *   $proc: ["dag", "traverse"],
+ *   input: {
+ *     visit: ["git", "add"]
+ *   }
+ * });
+ * ```
+ *
+ * The `$when` field controls when nested $proc refs are executed:
+ * - "$immediate" (default): Execute during hydration
+ * - "$parent": Defer to parent procedure (dag.traverse executes per-node)
+ * - "$never": Never auto-execute, pass as pure data
+ *
+ * The procedure gets the packages of the workspace from `lib.scan` of `@procedures/lib`, through
+ * `ctx.client`. It does not import that package, because `@procedures/lib` depends on this one.
+ * Thus a registry with `dag.traverse` also needs the module of `@procedures/lib`.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { ProcedureContext, ProcedurePath } from "@procedures/client";
+import { isAnyProcedureRef, hydrateInput, scopeOf } from "@procedures/client";
+import type {
+  DagTraverseInput,
+  DagTraverseOutput,
+  PackageNode,
+  ScanOutput,
+  TraverseNodeResult,
+} from "./types.js";
+import {
+  buildLeveledDAG,
+  executeDAG,
+  createProcessor,
+  filterDAGFromRoot,
+} from "../dag/index.js";
+
+/**
+ * This function gives the nodes of the packages of a `lib.scan` output. A dependency on a
+ * package that the scan did not find is not an edge.
+ */
+export function packageNodes(packages: ScanOutput["packages"]): Map<string, PackageNode> {
+  const nodes = new Map<string, PackageNode>();
+  for (const [name, info] of Object.entries(packages)) {
+    nodes.set(name, {
+      id: name,
+      name,
+      repoPath: info.repoPath,
+      dependencies: info.mark1russell7Deps.filter((dep) => packages[dep] !== undefined),
+    });
+  }
+  return nodes;
+}
+
+/** The folder of the git repository that holds `path` (it has `.git`), or `path` itself. */
+export function repositoryRoot(path: string): string {
+  let current = resolve(path);
+  for (;;) {
+    if (existsSync(join(current, ".git"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return resolve(path);
+    current = parent;
+  }
+}
+
+/** True when the value names a `git` procedure: a path, or a `$proc` ref at any depth. */
+export function callsGit(value: unknown): boolean {
+  if (Array.isArray(value)) {
+    if (value[0] === "git" && value.every((part) => typeof part === "string")) return true;
+    return value.some(callsGit);
+  }
+  if (typeof value === "object" && value !== null) {
+    return Object.values(value).some(callsGit);
+  }
+  return false;
+}
+
+/**
+ * Run the tasks of one key one at a time, in the order of the calls. Tasks of other keys run
+ * in parallel.
+ */
+export function keyedLock(): <T>(key: string, task: () => Promise<T>) => Promise<T> {
+  const tails = new Map<string, Promise<void>>();
+  return async <T>(key: string, task: () => Promise<T>): Promise<T> => {
+    const previous = tails.get(key) ?? Promise.resolve();
+    let release!: () => void;
+    const done = new Promise<void>((resolveDone) => {
+      release = resolveDone;
+    });
+    const tail = previous.then(() => done);
+    tails.set(key, tail);
+    await previous;
+    try {
+      return await task();
+    } finally {
+      release();
+      if (tails.get(key) === tail) tails.delete(key);
+    }
+  };
+}
+
+/**
+ * Execute a DAG traversal with a custom visit procedure
+ *
+ * The visits of nodes in one git repository run one at a time when the visit calls git (or
+ * with `serialize: "repository"`). All the packages of a workspace share one repository, and
+ * concurrent `git add` calls failed on `index.lock` (deep dive DATA-17).
+ */
+export async function dagTraverse(
+  input: DagTraverseInput,
+  ctx: ProcedureContext
+): Promise<DagTraverseOutput> {
+  const startTime = Date.now();
+  const results: TraverseNodeResult[] = [];
+
+  // Scan for all packages (lib.scan of @procedures/lib)
+  const scanResult = await ctx.client.call<{ rootPath?: string }, ScanOutput>(
+    ["lib", "scan"],
+    input.rootPath !== undefined ? { rootPath: input.rootPath } : {}
+  );
+  let allNodes = packageNodes(scanResult.packages);
+
+  // Filter to specific packages if requested
+  if (input.filter && input.filter.length > 0) {
+    const filtered = new Map<string, PackageNode>();
+    for (const name of input.filter) {
+      const node = allNodes.get(name);
+      if (node) {
+        filtered.set(name, node);
+      }
+    }
+    allNodes = filtered;
+  }
+
+  // Filter to root and its dependencies if requested
+  if (input.root) {
+    const rootNode = allNodes.get(input.root);
+    if (!rootNode) {
+      return {
+        success: false,
+        results: [],
+        totalDuration: Date.now() - startTime,
+        visited: 0,
+        failed: 0,
+      };
+    }
+    allNodes = filterDAGFromRoot(allNodes, input.root);
+  }
+
+  // Build DAG for dependency-ordered execution
+  const dag = buildLeveledDAG(allNodes);
+
+  // Determine how to execute the visit procedure
+  // visit can be:
+  // - Array: procedure path like ["git", "add"]
+  // - $proc ref: { $proc: [...], input: {...}, $when: "$parent" }
+  const visitIsRef = isAnyProcedureRef(input.visit);
+  let visitPath: ProcedurePath;
+  let baseInput: unknown = {};
+
+  if (Array.isArray(input.visit)) {
+    visitPath = input.visit;
+  } else if (visitIsRef && typeof input.visit === "object" && "$proc" in input.visit) {
+    visitPath = input.visit.$proc;
+    baseInput = input.visit.input ?? {};
+  } else {
+    throw new Error("visit must be a procedure path or $proc reference with $when");
+  }
+
+  const serialize = input.serialize ?? "auto";
+  const oneAtATime = serialize === "repository" || (serialize === "auto" && callsGit(input.visit));
+  const lock = keyedLock();
+
+  // Create processor that executes visit procedure per node
+  const processor = createProcessor(async (node: PackageNode) => {
+    if (oneAtATime) {
+      await lock(repositoryRoot(node.repoPath), () => visit(node));
+    } else {
+      await visit(node);
+    }
+  });
+
+  async function visit(node: PackageNode): Promise<void> {
+    if (input.dryRun) {
+      results.push({
+        name: node.name,
+        path: node.repoPath,
+        success: true,
+        duration: 0,
+        output: { dryRun: true, wouldExecute: visitPath },
+      });
+      return;
+    }
+
+    const nodeStartTime = Date.now();
+
+    try {
+      // Merge base input with node context
+      const visitInput = {
+        ...(typeof baseInput === "object" ? baseInput : {}),
+        cwd: node.repoPath,
+        node: {
+          name: node.name,
+          path: node.repoPath,
+          dependencies: node.dependencies,
+        },
+      };
+
+      // Create executor for hydration that injects cwd into every call
+      const executor = async <TIn, TOut>(path: ProcedurePath, inp: TIn): Promise<TOut> => {
+        // Inject cwd into the input so nested procedures run in correct directory
+        const inputWithCwd = typeof inp === "object" && inp !== null
+          ? { ...inp, cwd: node.repoPath }
+          : inp;
+        return ctx.client.call(path, inputWithCwd) as Promise<TOut>;
+      };
+
+      // Hydrate the input (execute any nested procedure refs like chain steps)
+      // Push "dag.traverse" onto context stack so refs with $when: "dag.traverse" execute
+      const hydratedInput = await hydrateInput(visitInput, executor, {
+        contextStack: ["dag.traverse"],
+        onRef: ctx.onRef,
+        // The names of the chain around this procedure: a `$ref` in the visit can read them
+        scope: scopeOf(input),
+      });
+
+      // Execute visit procedure with hydrated input
+      const output = await ctx.client.call(visitPath, hydratedInput);
+
+      results.push({
+        name: node.name,
+        path: node.repoPath,
+        success: true,
+        duration: Date.now() - nodeStartTime,
+        output,
+      });
+    } catch (error) {
+      const result: TraverseNodeResult = {
+        name: node.name,
+        path: node.repoPath,
+        success: false,
+        duration: Date.now() - nodeStartTime,
+        error: error instanceof Error ? error.message : String(error),
+      };
+      results.push(result);
+      throw error; // Re-throw for DAG executor to handle
+    }
+  }
+
+  // Execute DAG traversal
+  const dagResult = await executeDAG(dag, processor, {
+    concurrency: input.concurrency ?? 4,
+    failFast: !input.continueOnError,
+  });
+
+  // If dry run, we already populated results in the processor
+  if (!input.dryRun) {
+    // Ensure all nodes have results (some may have been skipped due to errors)
+    for (const [name, nodeResult] of dagResult.results) {
+      const existing = results.find((r) => r.name === name);
+      // No test reaches this branch: each visit adds its result before it ends or throws, and
+      // executeDAG gives no result for a node of a level that it skipped. The branch came with
+      // the procedure from client-lib (2026-10). It stays until a decision about it.
+      /* v8 ignore if -- @preserve */
+      if (!existing) {
+        const node = allNodes.get(name);
+        const result: TraverseNodeResult = {
+          name,
+          path: node?.repoPath ?? "unknown",
+          success: nodeResult.success,
+          duration: nodeResult.duration,
+        };
+        if (nodeResult.error?.message) {
+          result.error = nodeResult.error.message;
+        }
+        results.push(result);
+      }
+    }
+  }
+
+  return {
+    success: dagResult.success,
+    results,
+    totalDuration: Date.now() - startTime,
+    visited: results.filter((r) => r.success).length,
+    failed: results.filter((r) => !r.success).length,
+  };
+}

package/src/procedures/types.ts

@@ -0,0 +1,133 @@
+/**
+ * The types and schemas of the `dag.traverse` procedure.
+ *
+ * The procedure came from `@procedures/lib` (roadmap, items for a decision). Its name stays
+ * `dag.traverse`.
+ */
+
+import { z } from "zod";
+import type { DAGNode } from "../types.js";
+
+/**
+ * Schema for $proc references with $when control.
+ */
+const ProcRefSchema: z.ZodObject<{
+  $proc: z.ZodArray<z.ZodString>;
+  input: z.ZodOptional<z.ZodUnknown>;
+  $when: z.ZodOptional<z.ZodString>;
+  $name: z.ZodOptional<z.ZodString>;
+}> = z.object({
+  $proc: z.array(z.string()),
+  input: z.unknown().optional(),
+  $when: z.string().optional(),
+  $name: z.string().optional(),
+});
+
+export const DagTraverseInputSchema: z.ZodObject<{
+  visit: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, typeof ProcRefSchema]>;
+  filter: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  root: z.ZodOptional<z.ZodString>;
+  rootPath: z.ZodOptional<z.ZodString>;
+  concurrency: z.ZodDefault<z.ZodNumber>;
+  serialize: z.ZodDefault<z.ZodEnum<{ auto: "auto"; repository: "repository"; none: "none" }>>;
+  continueOnError: z.ZodDefault<z.ZodBoolean>;
+  dryRun: z.ZodDefault<z.ZodBoolean>;
+}> = z.object({
+  /**
+   * The procedure to start for each node.
+   * - A list: a procedure path, for example ["git", "add"]
+   * - A `$proc` ref with `$when: "$never"` or `"$parent"`: deferred. The traversal starts it for each node.
+   *
+   * Example:
+   * ```json
+   * { "$proc": ["git", "add"], "input": { "all": true }, "$when": "$parent" }
+   * ```
+   */
+  visit: z.union([
+    z.array(z.string()),
+    ProcRefSchema,
+  ]).describe("Procedure to execute for each node. - Array: procedure path, e.g., [\"git\", \"add\"] - $proc with $when: \"$never\" or \"$parent\": deferred, executed per-node Example: ```json { \"$proc\": [\"git\", \"add\"], \"input\": { \"all\": true }, \"$when\": \"$parent\" } ```"),
+  /** Filter to specific package names */
+  filter: z.array(z.string()).optional().describe("Filter to specific package names"),
+  /** Start from specific root package */
+  root: z.string().optional().describe("Start from specific root package"),
+  /** The workspace root that `lib.scan` reads (default: the pnpm workspace that contains client-lib) */
+  rootPath: z.string().optional().describe("Workspace root (defaults to the pnpm workspace that contains client-lib)"),
+  /** Max parallel operations (default: 4) */
+  concurrency: z.number().default(4).describe("Max parallel operations (default: 4)"),
+  /**
+   * When the visits of nodes in one git repository start one at a time (default: "auto").
+   * - "auto": when the visit uses a `git` procedure (git locks the index of the repository)
+   * - "repository": always
+   * - "none": not at any time
+   */
+  serialize: z.enum(["auto", "repository", "none"]).default("auto").describe("When the visits of nodes in one git repository run one at a time (default: \"auto\"). - \"auto\": when the visit calls a `git` procedure (git locks the index of the repository) - \"repository\": always - \"none\": never"),
+  /** Continue on error (default: false) */
+  continueOnError: z.boolean().default(false).describe("Continue on error (default: false)"),
+  /** Give the plan only, and start no visit (default: false) */
+  dryRun: z.boolean().default(false).describe("Preview without executing (default: false)"),
+});
+
+export type DagTraverseInput = z.infer<typeof DagTraverseInputSchema>;
+
+export interface TraverseNodeResult {
+  name: string;
+  path: string;
+  success: boolean;
+  duration: number;
+  error?: string | undefined;
+  output?: unknown | undefined;
+}
+
+export interface DagTraverseOutput {
+  success: boolean;
+  results: TraverseNodeResult[];
+  totalDuration: number;
+  visited: number;
+  failed: number;
+}
+
+export const DagTraverseOutputSchema: z.ZodType<DagTraverseOutput> = z.looseObject({
+  success: z.boolean().describe("True when every visit succeeded"),
+  results: z
+    .array(
+      z.looseObject({
+        name: z.string().describe("The package name of the node"),
+        path: z.string().describe("The folder of the node"),
+        success: z.boolean().describe("True when the visit succeeded"),
+        duration: z.number().describe("The time of the visit, in milliseconds"),
+        error: z.string().optional().describe("The error of a failed visit"),
+        output: z.unknown().optional().describe("The result of the visit"),
+      })
+    )
+    .describe("The result of each visited node"),
+  totalDuration: z.number().describe("The time of the traversal, in milliseconds"),
+  visited: z.number().describe("The number of visited nodes"),
+  failed: z.number().describe("The number of failed visits"),
+});
+
+/**
+ * A package of the output of `lib.scan`: the fields that `dag.traverse` reads. The type is local,
+ * because `@procedures/lib` depends on this package, and this package must not depend on it.
+ */
+export interface ScannedPackage {
+  /** The package name */
+  name: string;
+  /** The folder of the package */
+  repoPath: string;
+  /** The ecosystem packages that the package depends on */
+  mark1russell7Deps: string[];
+}
+
+/** The output of `lib.scan`: the fields that `dag.traverse` reads. */
+export interface ScanOutput {
+  packages: Record<string, ScannedPackage>;
+}
+
+/** A node of the traversal: a workspace package. `id` is the package name. */
+export interface PackageNode extends DAGNode {
+  /** The package name. It is the same as `id`. */
+  name: string;
+  /** The folder of the package */
+  repoPath: string;
+}

package/src/register.ts

@@ -0,0 +1,12 @@
+/**
+ * Importing this file registers the procedures of @procedures/dag in the global registry:
+ * `import "@procedures/dag/register"`. The package root and the `./module` entry register nothing
+ * (ARCHITECTURE-PROPOSALS-2026-10, P9). `dag.traverse` calls `lib.scan`: also import
+ * `@procedures/lib/register`.
+ */
+
+import { registerDagProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerDagProcedures();