@llm4ts/flow 0.13.5 → 0.14.0

package/src/PageSpec.ts

@@ -0,0 +1,354 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { PlanParseError } from "./FlowError.ts"
+
+// The Page Spec is the per-page contract of the J2EE→SPA conversion scenario
+// (ADR 0012): extraction embeds it in the spec markdown as a ```json pagespec
+// fenced block, conversion decodes it here and derives the anti-corruption
+// contract from its API section. It rides inside the existing extract
+// artifacts rather than adding a fifth artifact stream, so modernize-extract
+// stays untouched and the judge sees spec and page-spec as one document.
+
+export const PageSpecVersion = 1
+
+export const ValidationSite = Schema.Literals(["client", "server", "both"])
+export type ValidationSite = typeof ValidationSite.Type
+
+const emptyStrings: ReadonlyArray<string> = Object.freeze([])
+
+export class PageValidation extends Schema.Class<PageValidation>("PageValidation")({
+  rule: Schema.String,
+  message: Schema.optionalKey(Schema.String),
+  enforcedAt: ValidationSite
+}) {}
+
+const emptyValidations: ReadonlyArray<PageValidation> = Object.freeze([])
+
+export class PageFormField extends Schema.Class<PageFormField>("PageFormField")({
+  name: Schema.String,
+  label: Schema.String,
+  type: Schema.String,
+  required: Schema.Boolean.pipe(
+    Schema.withConstructorDefault(Effect.succeed(false)),
+    Schema.withDecodingDefaultKey(Effect.succeed(false))
+  ),
+  validations: Schema.Array(PageValidation).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyValidations)),
+    Schema.withDecodingDefaultKey(Effect.succeed(emptyValidations))
+  )
+}) {}
+
+export class PageForm extends Schema.Class<PageForm>("PageForm")({
+  name: Schema.String,
+  action: Schema.String,
+  fields: Schema.Array(PageFormField)
+}) {}
+
+/** One legacy field renamed into domain language — the anti-corruption table. */
+export class FieldMapping extends Schema.Class<FieldMapping>("FieldMapping")({
+  legacyName: Schema.String,
+  domainName: Schema.String,
+  type: Schema.String
+}) {}
+
+const emptyMappings: ReadonlyArray<FieldMapping> = Object.freeze([])
+
+export class PageDto extends Schema.Class<PageDto>("PageDto")({
+  legacyName: Schema.String,
+  domainName: Schema.String,
+  fields: Schema.Array(FieldMapping)
+}) {}
+
+export class PageApiCall extends Schema.Class<PageApiCall>("PageApiCall")({
+  /** Domain operation id, e.g. `listAccounts` — becomes the OpenAPI operationId. */
+  operation: Schema.String,
+  method: Schema.String,
+  path: Schema.String,
+  /** The ESB service behind the legacy endpoint, when known. */
+  esbService: Schema.optionalKey(Schema.String),
+  request: Schema.Array(FieldMapping).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyMappings)),
+    Schema.withDecodingDefaultKey(Effect.succeed(emptyMappings))
+  ),
+  response: Schema.Array(FieldMapping).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyMappings)),
+    Schema.withDecodingDefaultKey(Effect.succeed(emptyMappings))
+  )
+}) {}
+
+export class PageNavigation extends Schema.Class<PageNavigation>("PageNavigation")({
+  inbound: Schema.Array(Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyStrings)),
+    Schema.withDecodingDefaultKey(Effect.succeed(emptyStrings))
+  ),
+  outbound: Schema.Array(Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyStrings)),
+    Schema.withDecodingDefaultKey(Effect.succeed(emptyStrings))
+  ),
+  /** Multi-step flows: the page names in order, when this page is one step. */
+  steps: Schema.Array(Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyStrings)),
+    Schema.withDecodingDefaultKey(Effect.succeed(emptyStrings))
+  )
+}) {}
+
+export const PageComplexity = Schema.Literals(["low", "medium", "high"])
+export type PageComplexity = typeof PageComplexity.Type
+
+const emptyForms: ReadonlyArray<PageForm> = Object.freeze([])
+const emptyDtos: ReadonlyArray<PageDto> = Object.freeze([])
+const emptyCalls: ReadonlyArray<PageApiCall> = Object.freeze([])
+
+export class PageSpec extends Schema.Class<PageSpec>("PageSpec")({
+  /** The program name keying every artifact — matches `specs/<page>.md`. */
+  page: Schema.String,
+  route: Schema.String,
+  title: Schema.String,
+  complexity: PageComplexity,
+  forms: Schema.Array(PageForm).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyForms)),
+    Schema.withDecodingDefaultKey(Effect.succeed(emptyForms))
+  ),
+  dtos: Schema.Array(PageDto).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyDtos)),
+    Schema.withDecodingDefaultKey(Effect.succeed(emptyDtos))
+  ),
+  apiCalls: Schema.Array(PageApiCall).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyCalls)),
+    Schema.withDecodingDefaultKey(Effect.succeed(emptyCalls))
+  ),
+  navigation: PageNavigation.pipe(
+    Schema.withConstructorDefault(Effect.sync(() => PageNavigation.make({}))),
+    Schema.withDecodingDefaultKey(Effect.sync(() => PageNavigation.make({})))
+  ),
+  sessionState: Schema.Array(Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyStrings)),
+    Schema.withDecodingDefaultKey(Effect.succeed(emptyStrings))
+  ),
+  openQuestions: Schema.Array(Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyStrings)),
+    Schema.withDecodingDefaultKey(Effect.succeed(emptyStrings))
+  )
+}) {}
+
+/** The fence info string marking a page-spec block inside spec markdown. */
+export const pageSpecFenceInfo = "json pagespec"
+
+const fencePattern = /```json[ \t]+pagespec[ \t]*\r?\n([\s\S]*?)\r?\n[ \t]*```/
+
+/** The raw JSON of the first ```json pagespec fenced block, if any. */
+export const pageSpecBlock = (markdown: string): string | undefined =>
+  fencePattern.exec(markdown)?.[1]
+
+/**
+ * Decodes the page spec embedded in a spec markdown document. A missing block
+ * and a malformed one are both `PlanParseError`s — the extraction gate treats
+ * either as an incomplete extraction, never as "no spec needed".
+ */
+export const parsePageSpec = Effect.fn("@llm4ts/flow/PageSpec.parse")(function* (
+  markdown: string
+): Effect.fn.Return<PageSpec, PlanParseError> {
+  const block = pageSpecBlock(markdown)
+  if (block === undefined) {
+    return yield* PlanParseError.make({
+      message: "no ```json pagespec fenced block in the spec markdown"
+    })
+  }
+  return yield* Schema.decodeUnknownEffect(Schema.fromJsonString(PageSpec))(block).pipe(
+    Effect.mapError((error) =>
+      PlanParseError.make({
+        message: `invalid page spec block: ${String(error)}`
+      })
+    )
+  )
+})
+
+/** Renders a spec as a ```json pagespec fenced block — the inverse of `parsePageSpec`. */
+export const renderPageSpecBlock = Effect.fn("@llm4ts/flow/PageSpec.renderBlock")(function* (
+  spec: PageSpec
+): Effect.fn.Return<string, PlanParseError> {
+  const encoded = yield* Schema.encodeEffect(PageSpec)(spec).pipe(
+    Effect.mapError((error) =>
+      PlanParseError.make({
+        message: `failed to encode page spec: ${String(error)}`
+      })
+    )
+  )
+  return `\`\`\`${pageSpecFenceInfo}\n${JSON.stringify(encoded, undefined, 2)}\n\`\`\``
+})
+
+const openApiType = (type: string): { readonly type: string; readonly format?: string } => {
+  const lowered = type.toLowerCase()
+  if (/int|number|decimal|amount|count/.test(lowered)) {
+    return { type: "number" }
+  }
+  if (/bool/.test(lowered)) {
+    return { type: "boolean" }
+  }
+  if (/datetime|timestamp/.test(lowered)) {
+    return { type: "string", format: "date-time" }
+  }
+  if (/date/.test(lowered)) {
+    return { type: "string", format: "date" }
+  }
+  return { type: "string" }
+}
+
+const yamlText = (value: string): string => JSON.stringify(value)
+
+const schemaName = (operation: string, side: "Request" | "Response"): string =>
+  `${operation.charAt(0).toUpperCase()}${operation.slice(1)}${side}`
+
+const propertyLines = (
+  fields: ReadonlyArray<FieldMapping>,
+  indent: string
+): ReadonlyArray<string> =>
+  fields.flatMap((field) => {
+    const mapped = openApiType(field.type)
+    return [
+      `${indent}${field.domainName}:`,
+      `${indent}  type: ${mapped.type}`,
+      ...(mapped.format === undefined ? [] : [`${indent}  format: ${mapped.format}`]),
+      `${indent}  description: ${yamlText(`legacy: ${field.legacyName}`)}`
+    ]
+  })
+
+/**
+ * Deterministic OpenAPI 3.0 fragment for the page's API calls, in DOMAIN
+ * names — the anti-corruption contract the port, the mock adapter, and a
+ * future B4F implement. Emitted by code, not by a model: the contract must
+ * be a projection of the reviewed page spec, never an invention.
+ */
+export const openApiFor = (spec: PageSpec): string => {
+  const byPath = new Map<string, Array<PageApiCall>>()
+  for (const call of spec.apiCalls) {
+    const bucket = byPath.get(call.path) ?? []
+    bucket.push(call)
+    byPath.set(call.path, bucket)
+  }
+  const paths = [...byPath.entries()].sort(([left], [right]) => left.localeCompare(right))
+  const lines: Array<string> = [
+    "openapi: 3.0.3",
+    "info:",
+    `  title: ${yamlText(`${spec.title} service contract`)}`,
+    `  description: ${yamlText(`Anti-corruption contract for page ${spec.page} (${spec.route})`)}`,
+    "  version: 0.1.0",
+    "paths:"
+  ]
+  if (paths.length === 0) {
+    lines[lines.length - 1] = "paths: {}"
+  }
+  for (const [path, calls] of paths) {
+    lines.push(`  ${path}:`)
+    for (const call of [...calls].sort((a, b) => a.method.localeCompare(b.method))) {
+      const method = call.method.toLowerCase()
+      lines.push(`    ${method}:`)
+      lines.push(`      operationId: ${call.operation}`)
+      if (call.esbService !== undefined) {
+        lines.push(`      description: ${yamlText(`backed by ESB service ${call.esbService}`)}`)
+      }
+      if (call.request.length > 0 && method === "get") {
+        lines.push("      parameters:")
+        for (const field of call.request) {
+          const mapped = openApiType(field.type)
+          lines.push(`        - name: ${field.domainName}`)
+          lines.push("          in: query")
+          lines.push("          schema:")
+          lines.push(`            type: ${mapped.type}`)
+        }
+      }
+      if (call.request.length > 0 && method !== "get") {
+        lines.push("      requestBody:")
+        lines.push("        required: true")
+        lines.push("        content:")
+        lines.push("          application/json:")
+        lines.push("            schema:")
+        lines.push(
+          `              $ref: "#/components/schemas/${schemaName(call.operation, "Request")}"`
+        )
+      }
+      lines.push("      responses:")
+      lines.push('        "200":')
+      lines.push(`          description: ${yamlText(`${call.operation} result`)}`)
+      lines.push("          content:")
+      lines.push("            application/json:")
+      lines.push("              schema:")
+      lines.push(
+        `                $ref: "#/components/schemas/${schemaName(call.operation, "Response")}"`
+      )
+    }
+  }
+  lines.push("components:")
+  lines.push("  schemas:")
+  const schemaCalls = [...spec.apiCalls].sort((a, b) => a.operation.localeCompare(b.operation))
+  let wroteSchema = false
+  for (const call of schemaCalls) {
+    for (const [side, fields] of [
+      ["Request", call.request],
+      ["Response", call.response]
+    ] as const) {
+      if (side === "Request" && (fields.length === 0 || call.method.toLowerCase() === "get")) {
+        continue
+      }
+      wroteSchema = true
+      lines.push(`    ${schemaName(call.operation, side)}:`)
+      lines.push("      type: object")
+      if (fields.length === 0) {
+        lines.push("      properties: {}")
+      } else {
+        lines.push("      properties:")
+        lines.push(...propertyLines(fields, "        "))
+      }
+    }
+  }
+  if (!wroteSchema) {
+    lines[lines.length - 1] = "  schemas: {}"
+  }
+  return lines.join("\n") + "\n"
+}
+
+/** Human-readable summary — the review surface next to the JSON contract. */
+export const renderPageSpec = (spec: PageSpec): string => {
+  const lines: Array<string> = [
+    `# Page: ${spec.page}`,
+    "",
+    `- Route: ${spec.route}`,
+    `- Title: ${spec.title}`,
+    `- Complexity: ${spec.complexity}`
+  ]
+  for (const form of spec.forms) {
+    lines.push("", `## Form: ${form.name} → ${form.action}`)
+    for (const field of form.fields) {
+      const rules = field.validations
+        .map((validation) => `${validation.rule} (${validation.enforcedAt})`)
+        .join(", ")
+      lines.push(
+        `- ${field.name} (${field.type})${field.required ? " required" : ""}` +
+          (rules.length === 0 ? "" : ` — ${rules}`)
+      )
+    }
+  }
+  if (spec.apiCalls.length > 0) {
+    lines.push("", "## API calls")
+    for (const call of spec.apiCalls) {
+      const esb = call.esbService === undefined ? "" : ` — ESB ${call.esbService}`
+      lines.push(`- ${call.operation}: ${call.method} ${call.path}${esb}`)
+    }
+  }
+  if (spec.dtos.length > 0) {
+    lines.push("", "## Anti-corruption renames")
+    for (const dto of spec.dtos) {
+      lines.push(`- ${dto.legacyName} → ${dto.domainName}`)
+      for (const field of dto.fields) {
+        lines.push(`  - ${field.legacyName} → ${field.domainName} (${field.type})`)
+      }
+    }
+  }
+  if (spec.sessionState.length > 0) {
+    lines.push("", "## Session state", ...spec.sessionState.map((item) => `- ${item}`))
+  }
+  if (spec.openQuestions.length > 0) {
+    lines.push("", "## Open questions", ...spec.openQuestions.map((item) => `- ${item}`))
+  }
+  return lines.join("\n") + "\n"
+}

package/src/SpecChecks.ts

@@ -21,16 +21,22 @@ const capture = (regex: RegExp, text: string): ReadonlyArray<string> => {
   return values
 }
 
+/**
+ * Repo-relative paths matching `regex` and not matching `exclude`, sorted.
+ * The regex is applied INSIDE discovery so the workspace's result cap counts
+ * candidate units, not every file that shares the tree with them.
+ */
 export const matchingFiles = (
   workspace: WorkspaceShape,
-  regex: string
+  regex: string,
+  exclude?: string
 ): Effect.Effect<ReadonlyArray<string>, WorkspaceError> =>
-  workspace.discover().pipe(
-    Effect.map((paths) => {
-      const expression = new RegExp(regex)
-      return paths.filter((path) => expression.test(path)).sort()
+  workspace
+    .discover("**/*", {
+      matching: new RegExp(regex),
+      ...(exclude === undefined ? {} : { excluding: new RegExp(exclude) })
     })
-  )
+    .pipe(Effect.map((paths) => [...paths].sort()))
 
 export const coverageUnits = Effect.fn("@llm4ts/flow/SpecChecks.coverageUnits")(function* (
   workspace: WorkspaceShape,

package/src/Survey.ts

@@ -66,25 +66,59 @@ export const closureFor = (
   return walk([program], new Set([program]), [])
 }
 
-const unitName = (path: string): string => {
+/**
+ * A source file's unit name: its basename without the extension. The graph
+ * keys nodes by it, and `resolveUnit` folds edge targets onto it.
+ */
+export const unitName = (path: string): string => {
   const base = path.split("/").at(-1) ?? path
   const dot = base.lastIndexOf(".")
   return dot < 0 ? base : base.slice(0, dot)
 }
 
+/**
+ * The unit a captured reference points at. COBOL rules capture the bare unit
+ * name (`CALL 'FEECALC'`), but web estates reference units by PATH —
+ * `<jsp:include page="header.jsp">`, `page="/WEB-INF/fragments/footer.jsp"`
+ * — so a raw capture would never equal a node name, every fragment would show
+ * zero incoming edges, and the inventory would flag the most-included files
+ * in the estate as retire candidates. Unknown references stay as captured:
+ * an edge to a unit the estate does not contain is itself a finding.
+ */
+export const resolveUnit = (reference: string, known: ReadonlySet<string>): string => {
+  if (known.has(reference)) {
+    return reference
+  }
+  const folded = unitName(reference)
+  return known.has(folded) ? folded : reference
+}
+
 const matches = (regex: string, contents: string): ReadonlyArray<string> => {
   const expression = new RegExp(regex, "g")
   return [...contents.matchAll(expression)].map((match) => match[1] ?? match[0])
 }
 
+export interface SurveyGraphOptions {
+  /** Regex over repo-relative paths to leave out even when `sources` matches. */
+  readonly exclude?: string
+}
+
 export const surveyGraph = Effect.fn("@llm4ts/flow/Survey.graph")(function* (
   workspace: WorkspaceShape,
   sources: string,
   units: ReadonlyArray<CoverageRule>,
-  edgeRules: ReadonlyArray<CoverageRule>
+  edgeRules: ReadonlyArray<CoverageRule>,
+  options: SurveyGraphOptions = {}
 ): Effect.fn.Return<SurveyGraph, WorkspaceError> {
-  const sourcePattern = new RegExp(sources)
-  const paths = (yield* workspace.discover()).filter((path) => sourcePattern.test(path)).sort()
+  // The source regex narrows discovery itself, so the workspace's result cap
+  // counts candidate units rather than every jar, image, and generated file
+  // sharing the tree with them.
+  const paths = [
+    ...(yield* workspace.discover("**/*", {
+      matching: new RegExp(sources),
+      ...(options.exclude === undefined ? {} : { excluding: new RegExp(options.exclude) })
+    }))
+  ].sort()
   const nodes: Array<SurveyNode> = []
   const contents = new Map<string, string>()
   for (const path of paths) {
@@ -101,6 +135,7 @@ export const surveyGraph = Effect.fn("@llm4ts/flow/Survey.graph")(function* (
       })
     )
   }
+  const known = new Set(nodes.map((node) => node.name))
   const edges: Array<SurveyEdge> = []
   for (const rule of edgeRules) {
     const filePattern = new RegExp(rule.files)
@@ -108,7 +143,7 @@ export const surveyGraph = Effect.fn("@llm4ts/flow/Survey.graph")(function* (
       for (const target of new Set(matches(rule.unit, contents.get(path) ?? ""))) {
         const edge = SurveyEdge.make({
           from: unitName(path),
-          to: target,
+          to: resolveUnit(target, known),
           kind: rule.name
         })
         if (
@@ -179,3 +214,100 @@ export const renderSurveyInventory = (graph: SurveyGraph): string => {
     ""
   ].join("\n")
 }
+
+/** The `graph.json` artifact: the graph as it is read back by later phases. */
+export const renderSurveyGraphJson = (graph: SurveyGraph): string =>
+  JSON.stringify(graph, undefined, 2)
+
+/**
+ * What a pack contributes to the survey's two reasoning prompts. The frame
+ * around it — the JSON contracts, the evidence rule, the wave discipline — is
+ * stack-neutral and lives here; everything that names a technology comes
+ * from the pack: the edge rules its graph was built from, and the optional
+ * `prompts/survey-refine.md` / `prompts/survey-triage.md` sidecars describing
+ * where THAT stack hides the links regexes miss and how to weigh its units.
+ */
+export interface SurveyPromptContext {
+  /** The pack's `## Survey:` edge rules — the graph's provenance, by name. */
+  readonly rules: ReadonlyArray<CoverageRule>
+  /** The pack's stack-specific guidance, or undefined for the neutral default. */
+  readonly guidance: string | undefined
+}
+
+const ruleNames = (context: SurveyPromptContext): string =>
+  context.rules.length === 0 ? "none" : context.rules.map((rule) => rule.name).join(", ")
+
+const defaultRefineGuidance = [
+  "Regexes miss links the source establishes indirectly: invocations whose target is held",
+  "in a variable or configuration entry, wiring declared in descriptors instead of code,",
+  "fragments pulled in by inclusion or templating, and units only a build or scheduler",
+  "step names."
+].join("\n")
+
+const defaultTriageGuidance = [
+  "Weigh each unit by what depends on it and what it depends on: shared units many others",
+  "reference are migrated early or wrapped; units nothing references are retire candidates",
+  "unless an entry point outside the graph (scheduler, external caller, deployment",
+  "descriptor) reaches them."
+].join("\n")
+
+export const surveyRefinePrompt = (graph: SurveyGraph, context: SurveyPromptContext): string =>
+  [
+    "You are refining the dependency graph of a legacy estate. The graph below was built",
+    "deterministically — one node per source file (named by its file name without the",
+    `extension), one edge per regex match of the pack's survey rules (${ruleNames(context)}).`,
+    context.guidance ?? defaultRefineGuidance,
+    'You have read-only access to the estate — read the sources (each node\'s "path" names its',
+    "file) and find the dependency edges the regexes missed. Prioritise the suspicious shapes:",
+    "units with fewer outgoing edges than the source suggests, units nothing references, units",
+    "with degree 0.",
+    "",
+    "Produce:",
+    '- "edges": ONLY links the graph does not already have, and ONLY between the units listed',
+    '  below (use the exact unit names). Each edge: "from" (the referencing unit), "to" (the',
+    '  referenced unit), "kind" (how the link is made — a short kebab-case label), and',
+    '  "evidence" (file, line, and the statement that establishes the link — no evidence, no',
+    "  edge). References to external systems, platform services, or third-party libraries are",
+    '  NOT edges; put them in "notes".',
+    '- "notes": references you could not resolve to a unit — indirect targets whose value you',
+    "  could not trace, external systems. Empty if none.",
+    "",
+    `Units: ${graph.nodes
+      .map((node) => node.name)
+      .sort()
+      .join(", ")}`,
+    "",
+    "Graph (JSON):",
+    renderSurveyGraphJson(graph)
+  ].join("\n")
+
+export const surveyTriagePrompt = (
+  graph: SurveyGraph,
+  inventory: string,
+  context: SurveyPromptContext
+): string =>
+  [
+    "You are triaging a legacy estate for modernization. Below are its inventory and",
+    `dependency graph (regex-derived from the source by the pack's survey rules — ${ruleNames(context)} —`,
+    "plus `llm-…` edges the graph-refine step grounded in the source with evidence — trust them).",
+    context.guidance ?? defaultTriageGuidance,
+    "",
+    "Produce:",
+    '- "triage": for EVERY unit in the inventory, a disposition:',
+    '  - "rewrite": actively used business logic or user-facing behaviour to modernize;',
+    '  - "retire": unreferenced/dead — candidate for decommissioning, with the evidence;',
+    '  - "wrap": keep on the legacy platform and front with an API (shared units other',
+    "    estates still call, or units out of this modernization's scope).",
+    "  Rationale in one sentence, grounded in the graph (degrees, callers, size).",
+    '- "waves": dependency-coherent migration slices for the REWRITE units: a wave\'s units',
+    "  should depend only on already-migrated or same-wave units where possible; leaves and",
+    "  low-fan-in units first; name each wave (wave-1, wave-2, …) and give the ordering rationale.",
+    '- "notes": anything the graph could not resolve — indirect references, cycles worth a',
+    "  human look. Empty if none.",
+    "",
+    "Inventory:",
+    inventory,
+    "",
+    "Graph (JSON):",
+    renderSurveyGraphJson(graph)
+  ].join("\n")