@llm4ts/runner 2.36.0 → 2.38.0

package/dist/Graph.d.ts

@@ -0,0 +1,66 @@
+import * as Effect from "effect/Effect";
+import { type FlowError } from "@llm4ts/flow/FlowError";
+import type { Pack } from "@llm4ts/flow/Pack";
+import type { PlainFileStoreShape } from "@llm4ts/flow/Persistence";
+import { type WorkspaceError, type WorkspaceShape } from "@llm4ts/flow/Workspace";
+import { type KitTierPaths } from "./Kits.ts";
+import { type PackNotFound } from "./Packs.ts";
+/**
+ * `llm4ts graph` (ADR 0030 decision 7): the code graph of a legacy estate as a
+ * CLI. `build` is the scanner pass (the LLM worklist runs in modernize-survey);
+ * every other command reads the cache through `freshGraph`, so a stale cache
+ * is rebuilt rather than refused.
+ */
+export type GraphFormat = "text" | "json" | "mermaid" | "dot";
+export type GraphCommand = {
+    readonly _tag: "build";
+    readonly repo: string;
+    readonly pack?: string;
+} | {
+    readonly _tag: "query";
+    readonly repo: string;
+    readonly pack?: string;
+    readonly text: string;
+    readonly kind?: string;
+    readonly hops: number;
+    readonly format: GraphFormat;
+    readonly all: boolean;
+    readonly force: boolean;
+} | {
+    readonly _tag: "path";
+    readonly repo: string;
+    readonly pack?: string;
+    readonly from: string;
+    readonly to: string;
+    readonly max: number;
+    readonly format: GraphFormat;
+    readonly force: boolean;
+} | {
+    readonly _tag: "closure";
+    readonly repo: string;
+    readonly pack?: string;
+    readonly program: string;
+    readonly max: number;
+    readonly format: GraphFormat;
+    readonly force: boolean;
+} | {
+    readonly _tag: "stats";
+    readonly repo: string;
+    readonly pack?: string;
+    readonly format: GraphFormat;
+} | {
+    readonly _tag: "probe";
+    readonly repo: string;
+    readonly pack?: string;
+    readonly format: GraphFormat;
+};
+export type GraphProgramError = FlowError | PackNotFound | WorkspaceError;
+export interface GraphDependencies {
+    readonly files: PlainFileStoreShape;
+    readonly workspace: (root: string) => Effect.Effect<WorkspaceShape, WorkspaceError>;
+    readonly openPack: (repo: string, pack: string | undefined) => Effect.Effect<Pack, GraphProgramError>;
+}
+export declare const makeGraphProgram: (command: GraphCommand, deps: GraphDependencies) => Effect.Effect<string, GraphProgramError, never>;
+/** Node-backed dependencies: the disk, a legacy-sized workspace, packs from the kit tiers. */
+export declare const nodeGraphDependencies: (environment: Readonly<Record<string, string | undefined>>, kits: KitTierPaths) => GraphDependencies;
+//# sourceMappingURL=Graph.d.ts.map

package/dist/Graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Graph.d.ts","sourceRoot":"","sources":["../src/Graph.ts"],"names":[],"mappings":"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"}

package/dist/Graph.js

@@ -0,0 +1,122 @@
+import { homedir } from "node:os";
+import * as Effect from "effect/Effect";
+import { FlowAborted } from "@llm4ts/flow/FlowError";
+import { freshGraph, graphCachePath } from "@llm4ts/flow/GraphCache";
+import { closureView, graphStats, neighborhood, pathBetween, probeResults, resolveNodeRef, searchNodes, viewOfPath, wholeView } from "@llm4ts/flow/GraphQuery";
+import { renderGraphDot, renderGraphMermaid, renderGraphText } from "@llm4ts/flow/GraphRender";
+import { nodeId } from "@llm4ts/flow/Survey";
+import { legacySourceWorkspaceLimits, workspaceLimitsFromEnv } from "@llm4ts/flow/Workspace";
+import { kitTierPaths } from "./Kits.js";
+import { nodePlainFileStore } from "./NodePlainFileStore.js";
+import { makeNodeWorkspace } from "./NodeWorkspace.js";
+import { openPack } from "./Packs.js";
+const render = (view, graph, format, force) => {
+    switch (format) {
+        case "json":
+            return JSON.stringify(view, undefined, 2);
+        case "mermaid":
+            return renderGraphMermaid(view, graph, { force });
+        case "dot":
+            return renderGraphDot(view, graph);
+        case "text":
+            return renderGraphText(view);
+    }
+};
+const counts = (record) => Object.entries(record)
+    .map(([key, count]) => `${key} ${count}`)
+    .join(", ");
+const requireNode = (graph, ref) => {
+    const node = resolveNodeRef(graph, ref);
+    return node === undefined
+        ? Effect.fail(FlowAborted.make({
+            message: `no node matches '${ref}' (try: llm4ts graph query "${ref}")`
+        }))
+        : Effect.succeed(nodeId(node));
+};
+export const makeGraphProgram = Effect.fn("@llm4ts/runner/Graph.make")(function* (command, deps) {
+    const pack = yield* deps.openPack(command.repo, command.pack);
+    const workspace = yield* deps.workspace(command.repo);
+    const cachePath = graphCachePath(command.repo, pack.name);
+    const { graph, reused } = yield* freshGraph(deps.files, cachePath, pack, workspace);
+    switch (command._tag) {
+        case "build": {
+            const stats = graphStats(graph);
+            return [
+                `pack ${pack.name} — graph ${reused ? "reused from" : "written to"} ${cachePath}`,
+                `nodes: ${stats.total.nodes} (${counts(stats.nodes)})`,
+                `edges: ${stats.total.edges} (${counts(stats.edges)})`,
+                `unresolved: ${stats.total.unresolved} (${counts(stats.unresolved) || "none"})`
+            ].join("\n");
+        }
+        case "stats": {
+            const stats = graphStats(graph);
+            if (command.format === "json") {
+                return JSON.stringify(stats, undefined, 2);
+            }
+            const rows = (label, record) => Object.entries(record).map(([key, count]) => `${label} ${key}\t${count}`);
+            return [
+                "kind\tcount",
+                ...rows("node", stats.nodes),
+                ...rows("edge", stats.edges),
+                ...rows("mechanism", stats.mechanism),
+                ...rows("origin", stats.origin),
+                ...rows("confidence", stats.confidence),
+                ...rows("unresolved", stats.unresolved)
+            ].join("\n");
+        }
+        case "query": {
+            const hits = searchNodes(graph, command.text, command.kind === undefined ? {} : { kind: command.kind });
+            if (hits.length === 0) {
+                return `no node matches '${command.text}'`;
+            }
+            const view = command.all
+                ? wholeView(graph)
+                : neighborhood(graph, hits.map((hit) => nodeId(hit.node)), command.hops);
+            return render(view, graph, command.format, command.force);
+        }
+        case "path": {
+            const from = yield* requireNode(graph, command.from);
+            const to = yield* requireNode(graph, command.to);
+            const found = pathBetween(graph, from, to, command.max, { projected: true });
+            const path = found.forward ?? found.backward;
+            if (path === undefined) {
+                return `no path within ${command.max} hops between ${from} and ${to} in either direction`;
+            }
+            const direction = found.forward === undefined ? `(reverse: ${to} → ${from})\n` : "";
+            return `${direction}${render(viewOfPath(graph, path), graph, command.format, command.force)}`;
+        }
+        case "closure":
+            return render(closureView(graph, command.program, command.max), graph, command.format, command.force);
+        case "probe": {
+            const results = probeResults(graph, pack.graph.probes);
+            if (command.format === "json") {
+                return JSON.stringify(results.map((result) => ({
+                    name: result.probe.name,
+                    status: result.status,
+                    ...(result.path === undefined ? {} : { hops: result.path.length })
+                })), undefined, 2);
+            }
+            return results.length === 0
+                ? `pack ${pack.name} declares no '## Probe:' section`
+                : results
+                    .map((result) => `${result.probe.name}: ${result.status}${result.path === undefined
+                    ? ""
+                    : ` via ${result.path.map((edge) => edge.kind).join(" → ")}`}`)
+                    .join("\n");
+        }
+    }
+});
+/** Node-backed dependencies: the disk, a legacy-sized workspace, packs from the kit tiers. */
+export const nodeGraphDependencies = (environment, kits) => ({
+    files: nodePlainFileStore,
+    workspace: (root) => makeNodeWorkspace(root, workspaceLimitsFromEnv(environment, legacySourceWorkspaceLimits)),
+    openPack: (repo, pack) => openPack({
+        environment: { ...environment, ...(pack === undefined ? {} : { LLM4TS_PACK: pack }) },
+        launchDir: repo,
+        flowDir: repo,
+        kits: kits.builtin === undefined
+            ? kitTierPaths({ cwd: repo, homeDir: homedir(), environment })
+            : kits
+    }).pipe(Effect.map((opened) => opened.pack))
+});
+//# sourceMappingURL=Graph.js.map

package/dist/Graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Graph.js","sourceRoot":"","sources":["../src/Graph.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/runner",
-  "version": "2.36.0",
+  "version": "2.38.0",
   "description": "Node runner, CLI, terminal, and MCP composition for llm4ts",
   "license": "MIT",
   "type": "module",
@@ -24,6 +24,7 @@
     "./ExecutorRoster": "./dist/ExecutorRoster.js",
     "./FlowArgs": "./dist/FlowArgs.js",
     "./FlowRunner": "./dist/FlowRunner.js",
+    "./Graph": "./dist/Graph.js",
     "./Kits": "./dist/Kits.js",
     "./McpStdio": "./dist/McpStdio.js",
     "./NodeGeminiAcpBridge": "./dist/NodeGeminiAcpBridge.js",
@@ -69,8 +70,8 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/core": "2.36.0",
-    "@llm4ts/flow": "2.36.0"
+    "@llm4ts/core": "2.38.0",
+    "@llm4ts/flow": "2.38.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"

package/src/Graph.ts

@@ -0,0 +1,248 @@
+import { homedir } from "node:os"
+import * as Effect from "effect/Effect"
+import { FlowAborted, type FlowError } from "@llm4ts/flow/FlowError"
+import { freshGraph, graphCachePath } from "@llm4ts/flow/GraphCache"
+import {
+  closureView,
+  graphStats,
+  neighborhood,
+  pathBetween,
+  probeResults,
+  resolveNodeRef,
+  searchNodes,
+  viewOfPath,
+  wholeView,
+  type GraphView
+} from "@llm4ts/flow/GraphQuery"
+import { renderGraphDot, renderGraphMermaid, renderGraphText } from "@llm4ts/flow/GraphRender"
+import type { Pack } from "@llm4ts/flow/Pack"
+import type { PlainFileStoreShape } from "@llm4ts/flow/Persistence"
+import { nodeId, type SurveyGraph } from "@llm4ts/flow/Survey"
+import {
+  legacySourceWorkspaceLimits,
+  workspaceLimitsFromEnv,
+  type WorkspaceError,
+  type WorkspaceShape
+} from "@llm4ts/flow/Workspace"
+import { kitTierPaths, type KitTierPaths } from "./Kits.ts"
+import { nodePlainFileStore } from "./NodePlainFileStore.ts"
+import { makeNodeWorkspace } from "./NodeWorkspace.ts"
+import { openPack, type PackNotFound } from "./Packs.ts"
+
+/**
+ * `llm4ts graph` (ADR 0030 decision 7): the code graph of a legacy estate as a
+ * CLI. `build` is the scanner pass (the LLM worklist runs in modernize-survey);
+ * every other command reads the cache through `freshGraph`, so a stale cache
+ * is rebuilt rather than refused.
+ */
+export type GraphFormat = "text" | "json" | "mermaid" | "dot"
+
+export type GraphCommand =
+  | { readonly _tag: "build"; readonly repo: string; readonly pack?: string }
+  | {
+      readonly _tag: "query"
+      readonly repo: string
+      readonly pack?: string
+      readonly text: string
+      readonly kind?: string
+      readonly hops: number
+      readonly format: GraphFormat
+      readonly all: boolean
+      readonly force: boolean
+    }
+  | {
+      readonly _tag: "path"
+      readonly repo: string
+      readonly pack?: string
+      readonly from: string
+      readonly to: string
+      readonly max: number
+      readonly format: GraphFormat
+      readonly force: boolean
+    }
+  | {
+      readonly _tag: "closure"
+      readonly repo: string
+      readonly pack?: string
+      readonly program: string
+      readonly max: number
+      readonly format: GraphFormat
+      readonly force: boolean
+    }
+  | {
+      readonly _tag: "stats"
+      readonly repo: string
+      readonly pack?: string
+      readonly format: GraphFormat
+    }
+  | {
+      readonly _tag: "probe"
+      readonly repo: string
+      readonly pack?: string
+      readonly format: GraphFormat
+    }
+
+export type GraphProgramError = FlowError | PackNotFound | WorkspaceError
+
+export interface GraphDependencies {
+  readonly files: PlainFileStoreShape
+  readonly workspace: (root: string) => Effect.Effect<WorkspaceShape, WorkspaceError>
+  readonly openPack: (
+    repo: string,
+    pack: string | undefined
+  ) => Effect.Effect<Pack, GraphProgramError>
+}
+
+const render = (
+  view: GraphView,
+  graph: SurveyGraph,
+  format: GraphFormat,
+  force: boolean
+): string => {
+  switch (format) {
+    case "json":
+      return JSON.stringify(view, undefined, 2)
+    case "mermaid":
+      return renderGraphMermaid(view, graph, { force })
+    case "dot":
+      return renderGraphDot(view, graph)
+    case "text":
+      return renderGraphText(view)
+  }
+}
+
+const counts = (record: Readonly<Record<string, number>>): string =>
+  Object.entries(record)
+    .map(([key, count]) => `${key} ${count}`)
+    .join(", ")
+
+const requireNode = (graph: SurveyGraph, ref: string): Effect.Effect<string, FlowAborted> => {
+  const node = resolveNodeRef(graph, ref)
+  return node === undefined
+    ? Effect.fail(
+        FlowAborted.make({
+          message: `no node matches '${ref}' (try: llm4ts graph query "${ref}")`
+        })
+      )
+    : Effect.succeed(nodeId(node))
+}
+
+export const makeGraphProgram = Effect.fn("@llm4ts/runner/Graph.make")(function* (
+  command: GraphCommand,
+  deps: GraphDependencies
+): Effect.fn.Return<string, GraphProgramError> {
+  const pack = yield* deps.openPack(command.repo, command.pack)
+  const workspace = yield* deps.workspace(command.repo)
+  const cachePath = graphCachePath(command.repo, pack.name)
+  const { graph, reused } = yield* freshGraph(deps.files, cachePath, pack, workspace)
+  switch (command._tag) {
+    case "build": {
+      const stats = graphStats(graph)
+      return [
+        `pack ${pack.name} — graph ${reused ? "reused from" : "written to"} ${cachePath}`,
+        `nodes: ${stats.total.nodes} (${counts(stats.nodes)})`,
+        `edges: ${stats.total.edges} (${counts(stats.edges)})`,
+        `unresolved: ${stats.total.unresolved} (${counts(stats.unresolved) || "none"})`
+      ].join("\n")
+    }
+    case "stats": {
+      const stats = graphStats(graph)
+      if (command.format === "json") {
+        return JSON.stringify(stats, undefined, 2)
+      }
+      const rows = (label: string, record: Readonly<Record<string, number>>) =>
+        Object.entries(record).map(([key, count]) => `${label} ${key}\t${count}`)
+      return [
+        "kind\tcount",
+        ...rows("node", stats.nodes),
+        ...rows("edge", stats.edges),
+        ...rows("mechanism", stats.mechanism),
+        ...rows("origin", stats.origin),
+        ...rows("confidence", stats.confidence),
+        ...rows("unresolved", stats.unresolved)
+      ].join("\n")
+    }
+    case "query": {
+      const hits = searchNodes(
+        graph,
+        command.text,
+        command.kind === undefined ? {} : { kind: command.kind }
+      )
+      if (hits.length === 0) {
+        return `no node matches '${command.text}'`
+      }
+      const view = command.all
+        ? wholeView(graph)
+        : neighborhood(
+            graph,
+            hits.map((hit) => nodeId(hit.node)),
+            command.hops
+          )
+      return render(view, graph, command.format, command.force)
+    }
+    case "path": {
+      const from = yield* requireNode(graph, command.from)
+      const to = yield* requireNode(graph, command.to)
+      const found = pathBetween(graph, from, to, command.max, { projected: true })
+      const path = found.forward ?? found.backward
+      if (path === undefined) {
+        return `no path within ${command.max} hops between ${from} and ${to} in either direction`
+      }
+      const direction = found.forward === undefined ? `(reverse: ${to} → ${from})\n` : ""
+      return `${direction}${render(viewOfPath(graph, path), graph, command.format, command.force)}`
+    }
+    case "closure":
+      return render(
+        closureView(graph, command.program, command.max),
+        graph,
+        command.format,
+        command.force
+      )
+    case "probe": {
+      const results = probeResults(graph, pack.graph.probes)
+      if (command.format === "json") {
+        return JSON.stringify(
+          results.map((result) => ({
+            name: result.probe.name,
+            status: result.status,
+            ...(result.path === undefined ? {} : { hops: result.path.length })
+          })),
+          undefined,
+          2
+        )
+      }
+      return results.length === 0
+        ? `pack ${pack.name} declares no '## Probe:' section`
+        : results
+            .map(
+              (result) =>
+                `${result.probe.name}: ${result.status}${
+                  result.path === undefined
+                    ? ""
+                    : ` via ${result.path.map((edge) => edge.kind).join(" → ")}`
+                }`
+            )
+            .join("\n")
+    }
+  }
+})
+
+/** Node-backed dependencies: the disk, a legacy-sized workspace, packs from the kit tiers. */
+export const nodeGraphDependencies = (
+  environment: Readonly<Record<string, string | undefined>>,
+  kits: KitTierPaths
+): GraphDependencies => ({
+  files: nodePlainFileStore,
+  workspace: (root) =>
+    makeNodeWorkspace(root, workspaceLimitsFromEnv(environment, legacySourceWorkspaceLimits)),
+  openPack: (repo, pack) =>
+    openPack({
+      environment: { ...environment, ...(pack === undefined ? {} : { LLM4TS_PACK: pack }) },
+      launchDir: repo,
+      flowDir: repo,
+      kits:
+        kits.builtin === undefined
+          ? kitTierPaths({ cwd: repo, homeDir: homedir(), environment })
+          : kits
+    }).pipe(Effect.map((opened) => opened.pack))
+})