@llm4ts/flow 2.36.0 → 2.38.0

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")
+}

package/src/GraphRules.ts

@@ -0,0 +1,293 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { PlanParseError } from "./FlowError.ts"
+import { fingerprintOf } from "./ReviewCache.ts"
+import type { CoverageRule } from "./SpecChecks.ts"
+import type { JoinMatch } from "./Survey.ts"
+
+/**
+ * The pack's graph vocabulary (ADR 0030). A `## Node:` rule names a sub-file
+ * node kind, an `## Edge:` rule a captured link, a `## Join:` rule a link by
+ * attribute equality across files, a `## Probe:` a flow that must be
+ * connected end to end. `## Survey:` rules are folded in as file-to-file
+ * Edge rules so a pre-0030 pack produces the same graph.
+ */
+export class NodeRule extends Schema.Class<NodeRule>("NodeRule")({
+  kind: Schema.String,
+  files: Schema.String,
+  pattern: Schema.String,
+  descriptor: Schema.Boolean,
+  anchor: Schema.optionalKey(Schema.String),
+  /** `attr → named group` copies beyond the default "every group but name". */
+  attrs: Schema.Record(Schema.String, Schema.String)
+}) {}
+
+export class EdgeRule extends Schema.Class<EdgeRule>("EdgeRule")({
+  kind: Schema.String,
+  files: Schema.String,
+  pattern: Schema.String,
+  fromKind: Schema.String,
+  toKind: Schema.String,
+  /** A folded `## Survey:` rule: the target is the first positional group (or the whole match), as before ADR 0030. */
+  positional: Schema.optionalKey(Schema.Boolean)
+}) {}
+
+export const JoinMatchMode = Schema.Literals(["exact", "url"])
+export type JoinMatchMode = typeof JoinMatchMode.Type
+export const JoinScope = Schema.Literals(["estate", "app", "file"])
+export type JoinScope = typeof JoinScope.Type
+
+export class JoinRule extends Schema.Class<JoinRule>("JoinRule")({
+  kind: Schema.String,
+  fromKind: Schema.String,
+  fromAttr: Schema.String,
+  toKind: Schema.String,
+  toAttr: Schema.String,
+  match: JoinMatchMode,
+  scope: JoinScope
+}) {}
+
+export class ProbeRule extends Schema.Class<ProbeRule>("ProbeRule")({
+  name: Schema.String,
+  from: Schema.String,
+  to: Schema.String
+}) {}
+
+export interface GraphRules {
+  readonly nodes: ReadonlyArray<NodeRule>
+  readonly edges: ReadonlyArray<EdgeRule>
+  readonly joins: ReadonlyArray<JoinRule>
+  readonly probes: ReadonlyArray<ProbeRule>
+  readonly worklistMax: number
+  readonly batchSize: number
+}
+
+export const emptyGraphRules: GraphRules = {
+  nodes: [],
+  edges: [],
+  joins: [],
+  probes: [],
+  worklistMax: 200,
+  batchSize: 20
+}
+
+/**
+ * `## Survey:` is an Edge rule between files whose first positional capture
+ * (or the whole match) is the target. The pattern is kept verbatim: rewriting
+ * its first `(` would break `(?:…)`, lookbehinds and escaped parens.
+ */
+export const edgeRuleOfSurvey = (rule: CoverageRule): EdgeRule =>
+  EdgeRule.make({
+    kind: rule.name,
+    files: rule.files,
+    pattern: rule.unit,
+    fromKind: "file",
+    toKind: "file",
+    positional: true
+  })
+
+const fail = (message: string): Effect.Effect<never, PlanParseError> =>
+  Effect.fail(PlanParseError.make({ message }))
+
+const isValidRegExp = (source: string): boolean => {
+  try {
+    new RegExp(source, "gm")
+    return true
+  } catch {
+    return false
+  }
+}
+
+const fieldsOf = (lines: ReadonlyArray<string>): Readonly<Record<string, string>> =>
+  Object.fromEntries(
+    lines.flatMap((line) => {
+      const trimmed = line.replace(/^- /, "")
+      const index = trimmed.indexOf(":")
+      return index < 0 ? [] : [[trimmed.slice(0, index).trim(), trimmed.slice(index + 1).trim()]]
+    })
+  )
+
+const yes = (value: string | undefined): boolean =>
+  value !== undefined && ["yes", "true", "on"].includes(value.trim().toLowerCase())
+
+const attrCopies = (value: string | undefined): Readonly<Record<string, string>> =>
+  Object.fromEntries(
+    (value ?? "")
+      .split(",")
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0)
+      .flatMap((item) => {
+        const [attr, group] = item.split("=").map((part) => part.trim())
+        return attr !== undefined && group !== undefined && attr.length > 0 && group.length > 0
+          ? [[attr, group]]
+          : []
+      })
+  )
+
+const kindAndAttr = (value: string | undefined): readonly [string, string] | undefined => {
+  const dot = (value ?? "").indexOf(".")
+  if (value === undefined || dot <= 0 || dot === value.length - 1) {
+    return undefined
+  }
+  return [value.slice(0, dot).trim(), value.slice(dot + 1).trim()]
+}
+
+export const parseGraphRules = (
+  sections: ReadonlyArray<string>,
+  survey: ReadonlyArray<CoverageRule>
+): Effect.Effect<GraphRules, PlanParseError> =>
+  Effect.gen(function* () {
+    const nodes: Array<NodeRule> = []
+    const edges: Array<EdgeRule> = survey.map(edgeRuleOfSurvey)
+    const joins: Array<JoinRule> = []
+    const probes: Array<ProbeRule> = []
+    let worklistMax = emptyGraphRules.worklistMax
+    let batchSize = emptyGraphRules.batchSize
+    for (const section of sections) {
+      const lines = section.split(/\r?\n/)
+      const heading = lines[0]?.trim() ?? ""
+      const fields = fieldsOf(lines.slice(1))
+      if (heading.startsWith("## Node: ")) {
+        const kind = heading.slice("## Node: ".length).trim()
+        if (fields.files === undefined || fields.pattern === undefined) {
+          return yield* fail(`'${heading}' needs 'files:' and 'pattern:'`)
+        }
+        if (!isValidRegExp(fields.pattern)) {
+          return yield* fail(`'${heading}' pattern is not a valid regex: ${fields.pattern}`)
+        }
+        if (!fields.pattern.includes("(?<name>")) {
+          return yield* fail(`'${heading}' pattern needs a (?<name>…) group`)
+        }
+        nodes.push(
+          NodeRule.make({
+            kind,
+            files: fields.files,
+            pattern: fields.pattern,
+            descriptor: yes(fields.descriptor),
+            ...(fields.anchor === undefined ? {} : { anchor: fields.anchor }),
+            attrs: attrCopies(fields.attrs)
+          })
+        )
+      } else if (heading.startsWith("## Edge: ")) {
+        const kind = heading.slice("## Edge: ".length).trim()
+        if (fields.files === undefined || fields.pattern === undefined) {
+          return yield* fail(`'${heading}' needs 'files:' and 'pattern:'`)
+        }
+        if (!isValidRegExp(fields.pattern)) {
+          return yield* fail(`'${heading}' pattern is not a valid regex: ${fields.pattern}`)
+        }
+        if (!fields.pattern.includes("(?<to>")) {
+          return yield* fail(`'${heading}' pattern needs a (?<to>…) group`)
+        }
+        edges.push(
+          EdgeRule.make({
+            kind,
+            files: fields.files,
+            pattern: fields.pattern,
+            fromKind: fields.from ?? "file",
+            toKind: fields.to ?? "file"
+          })
+        )
+      } else if (heading.startsWith("## Join: ")) {
+        const kind = heading.slice("## Join: ".length).trim()
+        const from = kindAndAttr(fields.from)
+        const to = kindAndAttr(fields.to)
+        if (from === undefined || to === undefined) {
+          return yield* fail(`'${heading}' needs 'from: <kind>.<attr>' and 'to: <kind>.<attr>'`)
+        }
+        const match: JoinMatchMode = fields.match === "url" ? "url" : "exact"
+        const scope: JoinScope =
+          fields.scope === "file" || fields.scope === "app" || fields.scope === "estate"
+            ? fields.scope
+            : match === "url"
+              ? "app"
+              : "estate"
+        joins.push(
+          JoinRule.make({
+            kind,
+            fromKind: from[0],
+            fromAttr: from[1],
+            toKind: to[0],
+            toAttr: to[1],
+            match,
+            scope
+          })
+        )
+      } else if (heading.startsWith("## Probe: ")) {
+        const name = heading.slice("## Probe: ".length).trim()
+        if (fields.from === undefined || fields.to === undefined) {
+          return yield* fail(`'${heading}' needs 'from:' and 'to:'`)
+        }
+        probes.push(ProbeRule.make({ name, from: fields.from, to: fields.to }))
+      } else if (heading === "## Graph") {
+        const max = Number.parseInt(fields["worklist-max"] ?? "", 10)
+        const batch = Number.parseInt(fields["batch-size"] ?? "", 10)
+        worklistMax = Number.isInteger(max) && max > 0 ? max : worklistMax
+        batchSize = Number.isInteger(batch) && batch > 0 ? batch : batchSize
+      }
+    }
+    const nodeKinds = new Set(["file", ...nodes.map((rule) => rule.kind)])
+    for (const rule of edges) {
+      for (const kind of [rule.fromKind, rule.toKind]) {
+        if (!nodeKinds.has(kind)) {
+          return yield* fail(
+            `'## Edge: ${rule.kind}' names node kind '${kind}' no '## Node:' declares`
+          )
+        }
+      }
+    }
+    for (const rule of joins) {
+      for (const kind of [rule.fromKind, rule.toKind]) {
+        if (!nodeKinds.has(kind)) {
+          return yield* fail(
+            `'## Join: ${rule.kind}' names node kind '${kind}' no '## Node:' declares`
+          )
+        }
+      }
+    }
+    return { nodes, edges, joins, probes, worklistMax, batchSize }
+  })
+
+/** Every edge kind the rules can produce: captured kinds plus join kinds. */
+export const edgeKindsOf = (rules: GraphRules): ReadonlySet<string> =>
+  new Set([...rules.edges.map((rule) => rule.kind), ...rules.joins.map((rule) => rule.kind)])
+
+/** Changes when any rule that shapes the graph changes; probes and budgets do not. */
+export const graphRulesHash = (rules: GraphRules): string =>
+  fingerprintOf([JSON.stringify({ n: rules.nodes, e: rules.edges, j: rules.joins })])
+
+/** `${ctx}/a/b?x=1` → `/a/b`; `salva.do` → `/salva.do`; scheme, host and fragment dropped. */
+export const normalizeUrl = (raw: string): string => {
+  let url = raw.trim()
+  url = url.replace(/^(\$\{[^}]*\}|<%=[^%]*%>)/, "")
+  url = url.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, "")
+  url = url.replace(/[?#].*$/, "")
+  if (!url.startsWith("/")) {
+    url = `/${url}`
+  }
+  if (url.length > 1 && url.endsWith("/")) {
+    url = url.slice(0, -1)
+  }
+  return url
+}
+
+/**
+ * Servlet-spec matching of a normalised request against a `url-pattern`:
+ * exact, then a `/*` prefix, then a `*.ext` extension. The extension case
+ * reads the raw pattern, since normalising `*.do` would prefix a slash.
+ */
+export const matchUrl = (request: string, pattern: string): JoinMatch | undefined => {
+  const trimmed = pattern.trim()
+  if (trimmed.startsWith("*.")) {
+    return request.endsWith(trimmed.slice(1)) ? "extension" : undefined
+  }
+  const target = normalizeUrl(trimmed)
+  if (request === target) {
+    return "exact"
+  }
+  if (target.endsWith("/*")) {
+    const prefix = target.slice(0, -2)
+    return request === prefix || request.startsWith(`${prefix}/`) ? "prefix" : undefined
+  }
+  return undefined
+}