@llm4ts/flow 2.37.0 → 2.39.0

package/src/GraphQuery.ts

@@ -0,0 +1,315 @@
+import type { ProbeRule } from "./GraphRules.ts"
+import {
+  SurveyEdge,
+  SurveyGraph,
+  closureFor,
+  edgeConfidence,
+  edgeOrigin,
+  nodeAttrs,
+  nodeId,
+  nodeKind,
+  nodeLabel,
+  projectToFiles,
+  unitName,
+  type SurveyNode
+} from "./Survey.ts"
+
+/**
+ * Pure queries over the code graph (ADR 0030 decision 7): what the `llm4ts
+ * graph` verb renders today and a seat tool would wrap tomorrow. Nothing here
+ * reads a file or calls a model.
+ */
+export interface GraphView {
+  readonly nodes: ReadonlyArray<SurveyNode>
+  readonly edges: ReadonlyArray<SurveyEdge>
+}
+
+export interface SearchHit {
+  readonly node: SurveyNode
+  readonly score: number
+}
+
+const lower = (text: string): string => text.toLowerCase()
+
+/** Substring search over id, name, label, path and attr values; file-mates of a strong hit get a small boost. */
+export const searchNodes = (
+  graph: SurveyGraph,
+  text: string,
+  options: { readonly kind?: string; readonly limit?: number } = {}
+): ReadonlyArray<SearchHit> => {
+  const needle = lower(text.trim())
+  if (needle.length === 0) {
+    return []
+  }
+  const base = graph.nodes.map((node) => {
+    let score = 0
+    if (lower(node.name) === needle) {
+      score += 6
+    } else if (lower(node.name).includes(needle)) {
+      score += 3
+    }
+    if (lower(nodeLabel(node)).includes(needle)) {
+      score += 2
+    }
+    if (Object.values(nodeAttrs(node)).some((value) => lower(value).includes(needle))) {
+      score += 2
+    }
+    if (lower(nodeId(node)).includes(needle) || lower(node.path).includes(needle)) {
+      score += 1
+    }
+    return { node, score }
+  })
+  const strongFiles = new Set(base.filter((hit) => hit.score >= 2).map((hit) => hit.node.path))
+  return (
+    base
+      .map((hit) =>
+        hit.score === 0 && strongFiles.has(hit.node.path) ? { ...hit, score: 0.5 } : hit
+      )
+      // A co-located node (score 0.5) rides along an open search; an explicit
+      // kind asks for real matches of that kind only.
+      .filter((hit) =>
+        options.kind === undefined
+          ? hit.score > 0
+          : hit.score >= 1 && nodeKind(hit.node) === options.kind
+      )
+      .sort(
+        (left, right) =>
+          right.score - left.score || nodeId(left.node).localeCompare(nodeId(right.node))
+      )
+      .slice(0, options.limit ?? 20)
+  )
+}
+
+const viewOf = (graph: SurveyGraph, ids: ReadonlySet<string>): GraphView => ({
+  nodes: graph.nodes.filter((node) => ids.has(nodeId(node))),
+  edges: graph.edges.filter((edge) => ids.has(edge.from) && ids.has(edge.to))
+})
+
+export const neighborhood = (
+  graph: SurveyGraph,
+  ids: ReadonlyArray<string>,
+  hops: number
+): GraphView => {
+  const seen = new Set(ids)
+  let frontier: ReadonlyArray<string> = ids
+  for (let hop = 0; hop < hops && frontier.length > 0; hop += 1) {
+    const next = frontier
+      .flatMap((id) => [
+        ...graph.outgoing(id).map((edge) => edge.to),
+        ...graph.incoming(id).map((edge) => edge.from)
+      ])
+      .filter((id) => !seen.has(id))
+    next.forEach((id) => seen.add(id))
+    frontier = [...new Set(next)]
+  }
+  return viewOf(graph, seen)
+}
+
+/**
+ * Raw edges + projected file edges + file→sub-node containment: the graph
+ * probes and `--projected` paths walk, so a page reaches the servlet its form
+ * posts to and the servlet reaches the ESB call inside it.
+ */
+export const probeGraph = (graph: SurveyGraph): SurveyGraph => {
+  const projected = projectToFiles(graph)
+  const containment = graph.nodes
+    .filter((node) => nodeKind(node) !== "file")
+    .map((node) =>
+      SurveyEdge.make({
+        from: unitName(node.path),
+        to: nodeId(node),
+        kind: "contains",
+        mechanism: "contraction"
+      })
+    )
+  return SurveyGraph.make({
+    nodes: graph.nodes,
+    edges: [...graph.edges, ...projected.edges, ...containment],
+    unresolved: graph.unresolved,
+    fills: graph.fills
+  })
+}
+
+/** Bidirectional BFS over directed edges; the path as edges from `from` to `to`. */
+export const shortestPath = (
+  graph: SurveyGraph,
+  from: string,
+  to: string,
+  maxHops = 12,
+  options: { readonly projected?: boolean } = {}
+): ReadonlyArray<SurveyEdge> | undefined => {
+  const walk = options.projected === true ? probeGraph(graph) : graph
+  if (from === to) {
+    return []
+  }
+  const forward = new Map<string, SurveyEdge | undefined>([[from, undefined]])
+  const backward = new Map<string, SurveyEdge | undefined>([[to, undefined]])
+  let frontF: ReadonlyArray<string> = [from]
+  let frontB: ReadonlyArray<string> = [to]
+  const join = (meet: string): ReadonlyArray<SurveyEdge> => {
+    const head: Array<SurveyEdge> = []
+    for (let edge = forward.get(meet); edge !== undefined; edge = forward.get(edge.from)) {
+      head.unshift(edge)
+    }
+    const tail: Array<SurveyEdge> = []
+    for (let edge = backward.get(meet); edge !== undefined; edge = backward.get(edge.to)) {
+      tail.push(edge)
+    }
+    return [...head, ...tail]
+  }
+  for (let hop = 0; hop < maxHops; hop += 1) {
+    if (frontF.length === 0 && frontB.length === 0) {
+      break
+    }
+    if (frontF.length > 0 && (frontF.length <= frontB.length || frontB.length === 0)) {
+      const next: Array<string> = []
+      for (const id of frontF) {
+        for (const edge of walk.outgoing(id)) {
+          if (!forward.has(edge.to)) {
+            forward.set(edge.to, edge)
+            next.push(edge.to)
+          }
+          if (backward.has(edge.to)) {
+            return join(edge.to)
+          }
+        }
+      }
+      frontF = next
+    } else {
+      const next: Array<string> = []
+      for (const id of frontB) {
+        for (const edge of walk.incoming(id)) {
+          if (!backward.has(edge.from)) {
+            backward.set(edge.from, edge)
+            next.push(edge.from)
+          }
+          if (forward.has(edge.from)) {
+            return join(edge.from)
+          }
+        }
+      }
+      frontB = next
+    }
+  }
+  return undefined
+}
+
+export const pathBetween = (
+  graph: SurveyGraph,
+  a: string,
+  b: string,
+  maxHops = 12,
+  options: { readonly projected?: boolean } = {}
+): {
+  readonly forward?: ReadonlyArray<SurveyEdge>
+  readonly backward?: ReadonlyArray<SurveyEdge>
+} => {
+  const forward = shortestPath(graph, a, b, maxHops, options)
+  const backward = shortestPath(graph, b, a, maxHops, options)
+  return {
+    ...(forward === undefined ? {} : { forward }),
+    ...(backward === undefined ? {} : { backward })
+  }
+}
+
+export const viewOfPath = (graph: SurveyGraph, path: ReadonlyArray<SurveyEdge>): GraphView => {
+  const ids = new Set(path.flatMap((edge) => [edge.from, edge.to]))
+  return { nodes: graph.nodes.filter((node) => ids.has(nodeId(node))), edges: path }
+}
+
+/** The program and its bounded closure, on the file projection. */
+export const closureView = (graph: SurveyGraph, program: string, maxFiles: number): GraphView => {
+  const projected = projectToFiles(graph)
+  const paths = new Set(closureFor(graph, program, maxFiles))
+  const ids = new Set(
+    projected.nodes.filter((node) => node.name === program || paths.has(node.path)).map(nodeId)
+  )
+  return viewOf(projected, ids)
+}
+
+export const wholeView = (graph: SurveyGraph): GraphView => ({
+  nodes: graph.nodes,
+  edges: graph.edges
+})
+
+export interface GraphStats {
+  readonly nodes: Readonly<Record<string, number>>
+  readonly edges: Readonly<Record<string, number>>
+  readonly origin: Readonly<Record<string, number>>
+  readonly mechanism: Readonly<Record<string, number>>
+  readonly confidence: Readonly<Record<string, number>>
+  readonly unresolved: Readonly<Record<string, number>>
+  readonly total: {
+    readonly nodes: number
+    readonly edges: number
+    readonly unresolved: number
+    readonly fills: number
+  }
+}
+
+const tally = (keys: ReadonlyArray<string>): Readonly<Record<string, number>> => {
+  const counts: Record<string, number> = {}
+  for (const key of keys) {
+    counts[key] = (counts[key] ?? 0) + 1
+  }
+  return counts
+}
+
+export const graphStats = (graph: SurveyGraph): GraphStats => ({
+  nodes: tally(graph.nodes.map(nodeKind)),
+  edges: tally(graph.edges.map((edge) => edge.kind)),
+  origin: tally(graph.edges.map(edgeOrigin)),
+  mechanism: tally(graph.edges.map((edge) => edge.mechanism ?? "capture")),
+  confidence: tally(graph.edges.map(edgeConfidence)),
+  unresolved: tally(graph.unresolved.map((item) => item.reason)),
+  total: {
+    nodes: graph.nodes.length,
+    edges: graph.edges.length,
+    unresolved: graph.unresolved.length,
+    fills: graph.fills.length
+  }
+})
+
+/** An id, `<kind>:<name>` (first node of that kind with that name), or a bare file unit name. */
+export const resolveNodeRef = (graph: SurveyGraph, ref: string): SurveyNode | undefined => {
+  const exact = graph.node(ref)
+  if (exact !== undefined) {
+    return exact
+  }
+  const colon = ref.indexOf(":")
+  if (colon > 0 && !ref.includes("#")) {
+    const kind = ref.slice(0, colon)
+    const name = ref.slice(colon + 1)
+    return graph.nodes.find((node) => nodeKind(node) === kind && node.name === name)
+  }
+  return graph.nodes.find((node) => nodeKind(node) === "file" && node.name === ref)
+}
+
+export type ProbeStatus = "ok" | "broken" | "unknown-from" | "unknown-to"
+
+export interface ProbeResult {
+  readonly probe: ProbeRule
+  readonly status: ProbeStatus
+  readonly path?: ReadonlyArray<SurveyEdge>
+}
+
+/** Each probe's verdict on the union graph: connected, broken, or an endpoint nothing matches. */
+export const probeResults = (
+  graph: SurveyGraph,
+  probes: ReadonlyArray<ProbeRule>,
+  maxHops = 12
+): ReadonlyArray<ProbeResult> => {
+  const walk = probeGraph(graph)
+  return probes.map((probe) => {
+    const from = resolveNodeRef(graph, probe.from)
+    const to = resolveNodeRef(graph, probe.to)
+    if (from === undefined) {
+      return { probe, status: "unknown-from" }
+    }
+    if (to === undefined) {
+      return { probe, status: "unknown-to" }
+    }
+    const path = shortestPath(walk, nodeId(from), nodeId(to), maxHops)
+    return path === undefined ? { probe, status: "broken" } : { probe, status: "ok", path }
+  })
+}

package/src/GraphRender.ts

@@ -0,0 +1,208 @@
+import { clusterPrograms, type ConsolidateRules } from "./Domains.ts"
+import { neighborhood, type GraphView } from "./GraphQuery.ts"
+import {
+  edgeConfidence,
+  nodeId,
+  nodeKind,
+  nodeLabel,
+  projectToFiles,
+  type SurveyGraph,
+  type SurveyNode
+} from "./Survey.ts"
+
+/**
+ * Renders of a graph view (ADR 0030 decision 7): one view model, three
+ * emitters. Nodes group by file, edges carry their kind, inferred edges are
+ * dotted, unresolved nodes are red, and every node line ends with its id so a
+ * reader can paste it into `llm4ts graph path`.
+ */
+export const mermaidNodeCap = 150
+
+interface KindStyle {
+  readonly mermaid: string
+  readonly shape: string
+}
+
+/** Reserved kinds get a fixed look; any pack-defined kind falls back to `neutral`. */
+const styles: Readonly<Record<string, KindStyle>> = {
+  file: { mermaid: "fill:#eef,stroke:#446,color:#000", shape: "box" },
+  page: { mermaid: "fill:#efe,stroke:#464,color:#000", shape: "note" },
+  "ajax-call": { mermaid: "fill:#ffe,stroke:#664,color:#000", shape: "ellipse" },
+  form: { mermaid: "fill:#ffe,stroke:#664,color:#000", shape: "ellipse" },
+  "servlet-mapping": { mermaid: "fill:#fee,stroke:#644,color:#000", shape: "hexagon" },
+  "servlet-decl": { mermaid: "fill:#fee,stroke:#644,color:#000", shape: "hexagon" },
+  "esb-call": { mermaid: "fill:#fdf,stroke:#646,color:#000", shape: "component" },
+  "cobol-section": { mermaid: "fill:#eff,stroke:#466,color:#000", shape: "folder" },
+  "cobol-paragraph": { mermaid: "fill:#eff,stroke:#466,color:#000", shape: "box" }
+}
+
+const neutral: KindStyle = { mermaid: "fill:#f4f4f4,stroke:#888,color:#000", shape: "box" }
+
+const styleOf = (kind: string): KindStyle => styles[kind] ?? neutral
+
+const escapeMermaid = (text: string): string =>
+  text.replaceAll('"', "'").replaceAll("$", "＄").replaceAll("{", "(").replaceAll("}", ")")
+
+const escapeDot = (text: string): string => text.replaceAll("\\", "\\\\").replaceAll('"', '\\"')
+
+/** Mermaid class names may not contain `:` or `/`; kinds are kebab-case already. */
+const mermaidClass = (kind: string): string => kind.replace(/[^A-Za-z0-9_-]/g, "_")
+
+const unresolvedIds = (graph: SurveyGraph): ReadonlySet<string> =>
+  new Set(graph.unresolved.map((item) => item.node))
+
+const groupedByFile = (
+  view: GraphView
+): ReadonlyArray<readonly [string, ReadonlyArray<SurveyNode>]> => {
+  const groups = new Map<string, Array<SurveyNode>>()
+  for (const node of [...view.nodes].sort((a, b) => nodeId(a).localeCompare(nodeId(b)))) {
+    groups.set(node.path, [...(groups.get(node.path) ?? []), node])
+  }
+  return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))
+}
+
+export const renderGraphText = (view: GraphView): string =>
+  [
+    ...groupedByFile(view).flatMap(([path, nodes]) => [
+      path,
+      ...nodes.map((node) => `  ${nodeId(node)} [${nodeKind(node)}]`)
+    ]),
+    "",
+    ...view.edges.map(
+      (edge) =>
+        `${edge.from} -> ${edge.to} [${edge.kind}]${edgeConfidence(edge) === "inferred" ? " (inferred)" : ""}`
+    )
+  ].join("\n")
+
+export const renderGraphMermaid = (
+  view: GraphView,
+  graph: SurveyGraph,
+  options: { readonly cap?: number; readonly force?: boolean } = {}
+): string => {
+  const cap = options.cap ?? mermaidNodeCap
+  if (view.nodes.length > cap && options.force !== true) {
+    return [
+      `${view.nodes.length} nodes exceed the mermaid cap of ${cap}; pass --force to render anyway. Text view:`,
+      "",
+      renderGraphText(view)
+    ].join("\n")
+  }
+  const ids = new Map(view.nodes.map((node, index) => [nodeId(node), `n${index}`]))
+  const flagged = unresolvedIds(graph)
+  const kinds = [...new Set(view.nodes.map(nodeKind))]
+  const lines = ["flowchart LR"]
+  groupedByFile(view).forEach(([path, nodes], index) => {
+    lines.push(`  subgraph f${index}["${escapeMermaid(path)}"]`)
+    for (const node of nodes) {
+      const id = nodeId(node)
+      const cls = flagged.has(id) ? ":::unresolved" : `:::${mermaidClass(nodeKind(node))}`
+      lines.push(`    ${ids.get(id)}["${escapeMermaid(nodeLabel(node))}"]${cls} %% ${id}`)
+    }
+    lines.push("  end")
+  })
+  for (const edge of view.edges) {
+    const arrow = edgeConfidence(edge) === "inferred" ? "-.->" : "-->"
+    lines.push(`  ${ids.get(edge.from)} ${arrow}|${escapeMermaid(edge.kind)}| ${ids.get(edge.to)}`)
+  }
+  for (const kind of kinds) {
+    lines.push(`  classDef ${mermaidClass(kind)} ${styleOf(kind).mermaid};`)
+  }
+  lines.push("  classDef unresolved fill:#fdd,stroke:#c00,color:#900;")
+  return lines.join("\n")
+}
+
+export const renderGraphDot = (view: GraphView, graph: SurveyGraph): string => {
+  const ids = new Map(view.nodes.map((node, index) => [nodeId(node), `n${index}`]))
+  const flagged = unresolvedIds(graph)
+  const lines = ["digraph llm4ts {", "  rankdir=LR;", "  node [fontname=Helvetica];"]
+  groupedByFile(view).forEach(([path, nodes], index) => {
+    lines.push(`  subgraph "cluster_${index}" {`, `    label="${escapeDot(path)}";`)
+    for (const node of nodes) {
+      const id = nodeId(node)
+      const color = flagged.has(id) ? " color=red fontcolor=red" : ""
+      lines.push(
+        `    ${ids.get(id)} [label="${escapeDot(nodeLabel(node))}" shape=${styleOf(nodeKind(node)).shape} tooltip="${escapeDot(id)}"${color}];`
+      )
+    }
+    lines.push("  }")
+  })
+  for (const edge of view.edges) {
+    const style = edgeConfidence(edge) === "inferred" ? " style=dashed" : ""
+    lines.push(
+      `  ${ids.get(edge.from)} -> ${ids.get(edge.to)} [label="${escapeDot(edge.kind)}"${style}];`
+    )
+  }
+  lines.push("}")
+  return lines.join("\n")
+}
+
+/** From every projected node nothing points at, the chains it starts, depth-first, bounded. */
+export const renderEntryPaths = (
+  graph: SurveyGraph,
+  options: { readonly maxDepth?: number; readonly maxLines?: number } = {}
+): string => {
+  const maxDepth = options.maxDepth ?? 4
+  const maxLines = options.maxLines ?? 200
+  const projected = projectToFiles(graph)
+  const entries = projected.nodes.filter(
+    (node) => projected.incoming(node.name).length === 0 && projected.outgoing(node.name).length > 0
+  )
+  const lines: Array<string> = []
+  const walk = (id: string, trail: string, seen: ReadonlySet<string>, depth: number): void => {
+    if (lines.length >= maxLines) {
+      return
+    }
+    const out = projected.outgoing(id)
+    if (out.length === 0 || depth === maxDepth) {
+      lines.push(trail)
+      return
+    }
+    for (const edge of out) {
+      if (seen.has(edge.to)) {
+        lines.push(`${trail} → ${edge.to} (${edge.kind}) ↺`)
+        continue
+      }
+      walk(edge.to, `${trail} → ${edge.to} (${edge.kind})`, new Set([...seen, edge.to]), depth + 1)
+    }
+  }
+  for (const entry of entries) {
+    walk(entry.name, entry.name, new Set([entry.name]), 0)
+  }
+  return [
+    "## Entry paths",
+    "",
+    ...(lines.length === 0 ? ["(none)"] : lines.map((line) => `- ${line}`)),
+    ...(lines.length >= maxLines ? [`- … truncated at ${maxLines} lines`] : []),
+    ""
+  ].join("\n")
+}
+
+/** One mermaid block per multi-program consolidate cluster, on the file projection. */
+export const renderClusterDiagrams = (
+  graph: SurveyGraph,
+  consolidate: ConsolidateRules,
+  programs: ReadonlyArray<string>,
+  options: { readonly cap?: number } = {}
+): string => {
+  const projected = projectToFiles(graph)
+  const clusters = clusterPrograms(graph, programs, consolidate).filter(
+    (cluster) => cluster.programs.length > 1
+  )
+  if (clusters.length === 0) {
+    return "## Clusters\n\n(no multi-program cluster)\n"
+  }
+  return [
+    "## Clusters",
+    "",
+    ...clusters.flatMap((cluster, index) => [
+      `### Cluster ${index + 1}: ${[...cluster.programs].sort().join(", ")}`,
+      "",
+      "```mermaid",
+      renderGraphMermaid(neighborhood(projected, cluster.programs, 1), projected, {
+        cap: options.cap ?? mermaidNodeCap
+      }),
+      "```",
+      ""
+    ])
+  ].join("\n")
+}