@llm4ts/flow 0.17.0 → 0.18.1

package/src/PageSpec.ts

@@ -59,6 +59,9 @@ export class PageDto extends Schema.Class<PageDto>("PageDto")({
   fields: Schema.Array(FieldMapping)
 }) {}
 
+export const ResponseShape = Schema.Literals(["single", "list"])
+export type ResponseShape = typeof ResponseShape.Type
+
 export class PageApiCall extends Schema.Class<PageApiCall>("PageApiCall")({
   /** Domain operation id, e.g. `listAccounts` — becomes the OpenAPI operationId. */
   operation: Schema.String,
@@ -70,9 +73,20 @@ export class PageApiCall extends Schema.Class<PageApiCall>("PageApiCall")({
     Schema.withConstructorDefault(Effect.succeed(emptyMappings)),
     Schema.withDecodingDefaultKey(Effect.succeed(emptyMappings))
   ),
+  /**
+   * The response's fields when it is an ad-hoc object. A response that is
+   * one of the page's DTOs names it with `responseDto` instead — the
+   * `domainName` of an entry in `dtos` — and `responseShape` says whether
+   * the endpoint returns one of them or a list; a table screen is a list.
+   */
   response: Schema.Array(FieldMapping).pipe(
     Schema.withConstructorDefault(Effect.succeed(emptyMappings)),
     Schema.withDecodingDefaultKey(Effect.succeed(emptyMappings))
+  ),
+  responseDto: Schema.optionalKey(Schema.String),
+  responseShape: ResponseShape.pipe(
+    Schema.withConstructorDefault(Effect.succeed("single" as const)),
+    Schema.withDecodingDefaultKey(Effect.succeed("single" as const))
   )
 }) {}
 
@@ -131,6 +145,20 @@ export class PageSpec extends Schema.Class<PageSpec>("PageSpec")({
   )
 }) {}
 
+/**
+ * The block's shape in one paragraph, for the finding an undecodable block
+ * raises: the analyst that wrote its own richer shape is told exactly which
+ * keys the decoder accepts instead of only where decoding stopped.
+ */
+export const pageSpecShapeHint =
+  "The block must be exactly: { page, route, title, complexity: low|medium|high, " +
+  "forms: [{ name, action, fields: [{ name, label, type, required?, validations: [{ rule, message?, enforcedAt: client|server|both }] }] }], " +
+  "dtos: [{ legacyName, domainName, fields: [{ legacyName, domainName, type }] }], " +
+  "apiCalls: [{ operation, method, path, esbService (the ESB service the legacy call goes through — omit only when there is none), request: [{ legacyName, domainName, type }], response: [{ legacyName, domainName, type }] for an ad-hoc object, or responseDto: <domainName of one of the dtos> with responseShape: single|list when the endpoint returns that DTO or a list of it (a table screen is a list) }], " +
+  "navigation: { inbound: [string], outbound: [string], steps: [string] }, sessionState: [string], openQuestions: [string] }. " +
+  "No other keys (no id, url, queryParams, esbCall, trigger, serverController); every apiCalls entry is an object with operation/method/path; " +
+  "put anything that does not fit into the prose sections or openQuestions."
+
 /** The fence info string marking a page-spec block inside spec markdown. */
 export const pageSpecFenceInfo = "json pagespec"
 
@@ -199,6 +227,9 @@ 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 dtoSchemaName = (domainName: string): string =>
+  domainName.replace(/[^A-Za-z0-9]+/g, "") || "Dto"
+
 const propertyLines = (
   fields: ReadonlyArray<FieldMapping>,
   indent: string
@@ -239,13 +270,34 @@ export const openApiFor = (spec: PageSpec): string => {
     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))) {
+    lines.push(`  ${path.startsWith("/") ? path : `/${path}`}:`)
+    // One operation per method: an OpenAPI path item cannot repeat a method,
+    // so calls that share one (a page load and its JSON refresh on the same
+    // GET) collapse into the first, which names the variants it stands for.
+    const byMethod = new Map<string, Array<PageApiCall>>()
+    for (const call of calls) {
       const method = call.method.toLowerCase()
+      byMethod.set(method, [...(byMethod.get(method) ?? []), call])
+    }
+    for (const [method, variants] of [...byMethod.entries()].sort(([a], [b]) =>
+      a.localeCompare(b)
+    )) {
+      const call = variants[0]!
       lines.push(`    ${method}:`)
       lines.push(`      operationId: ${call.operation}`)
-      if (call.esbService !== undefined) {
-        lines.push(`      description: ${yamlText(`backed by ESB service ${call.esbService}`)}`)
+      const notes = [
+        ...(call.esbService === undefined ? [] : [`backed by ESB service ${call.esbService}`]),
+        ...(variants.length > 1
+          ? [
+              `also serves: ${variants
+                .slice(1)
+                .map((variant) => variant.operation)
+                .join(", ")}`
+            ]
+          : [])
+      ]
+      if (notes.length > 0) {
+        lines.push(`      description: ${yamlText(notes.join("; "))}`)
       }
       if (call.request.length > 0 && method === "get") {
         lines.push("      parameters:")
@@ -273,15 +325,40 @@ export const openApiFor = (spec: PageSpec): string => {
       lines.push("          content:")
       lines.push("            application/json:")
       lines.push("              schema:")
-      lines.push(
-        `                $ref: "#/components/schemas/${schemaName(call.operation, "Response")}"`
-      )
+      const responseRef = `"#/components/schemas/${
+        call.responseDto === undefined
+          ? schemaName(call.operation, "Response")
+          : dtoSchemaName(call.responseDto)
+      }"`
+      if (call.responseShape === "list") {
+        lines.push("                type: array")
+        lines.push("                items:")
+        lines.push(`                  $ref: ${responseRef}`)
+      } else {
+        lines.push(`                $ref: ${responseRef}`)
+      }
     }
   }
   lines.push("components:")
   lines.push("  schemas:")
   const schemaCalls = [...spec.apiCalls].sort((a, b) => a.operation.localeCompare(b.operation))
   let wroteSchema = false
+  // Every DTO a response names becomes a component the calls reference —
+  // one schema per domain entity, shared by every endpoint returning it.
+  const referencedDtos = new Set(
+    spec.apiCalls.flatMap((call) => (call.responseDto === undefined ? [] : [call.responseDto]))
+  )
+  for (const dto of [...spec.dtos].sort((a, b) => a.domainName.localeCompare(b.domainName))) {
+    if (!referencedDtos.has(dto.domainName)) {
+      continue
+    }
+    wroteSchema = true
+    lines.push(`    ${dtoSchemaName(dto.domainName)}:`)
+    lines.push("      type: object")
+    lines.push(`      description: ${yamlText(`legacy: ${dto.legacyName}`)}`)
+    lines.push("      properties:")
+    lines.push(...propertyLines(dto.fields, "        "))
+  }
   for (const call of schemaCalls) {
     for (const [side, fields] of [
       ["Request", call.request],
@@ -290,6 +367,9 @@ export const openApiFor = (spec: PageSpec): string => {
       if (side === "Request" && (fields.length === 0 || call.method.toLowerCase() === "get")) {
         continue
       }
+      if (side === "Response" && call.responseDto !== undefined) {
+        continue
+      }
       wroteSchema = true
       lines.push(`    ${schemaName(call.operation, side)}:`)
       lines.push("      type: object")
@@ -332,7 +412,11 @@ export const renderPageSpec = (spec: PageSpec): string => {
     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}`)
+      const returns =
+        call.responseDto === undefined
+          ? ""
+          : ` → ${call.responseShape === "list" ? `list of ${call.responseDto}` : call.responseDto}`
+      lines.push(`- ${call.operation}: ${call.method} ${call.path}${esb}${returns}`)
     }
   }
   if (spec.dtos.length > 0) {

package/src/SpecChecks.ts

@@ -1,5 +1,6 @@
 import * as Effect from "effect/Effect"
 import * as Schema from "effect/Schema"
+import { pageSpecShapeHint, parsePageSpec } from "./PageSpec.ts"
 import { ReviewIssue, ReviewResult } from "./Review.ts"
 import type { WorkspaceError, WorkspaceShape } from "./Workspace.ts"
 
@@ -38,56 +39,119 @@ export const matchingFiles = (
     })
     .pipe(Effect.map((paths) => [...paths].sort()))
 
-export const coverageUnits = Effect.fn("@llm4ts/flow/SpecChecks.coverageUnits")(function* (
+/** A unit a coverage rule captured, with every file it was captured from. */
+export interface CapturedUnit {
+  readonly rule: string
+  readonly unit: string
+  readonly paths: ReadonlyArray<string>
+}
+
+/**
+ * Every unit each rule captures across the workspace, in first-seen order
+ * per rule, each with the files it was found in — the provenance a
+ * wave-scoped gate needs to tell a unit of this wave from one of another.
+ */
+export const capturedUnits = Effect.fn("@llm4ts/flow/SpecChecks.capturedUnits")(function* (
   workspace: WorkspaceShape,
   rules: ReadonlyArray<CoverageRule>
-): Effect.fn.Return<Readonly<Record<string, ReadonlyArray<string>>>, WorkspaceError> {
+): Effect.fn.Return<ReadonlyArray<CapturedUnit>, WorkspaceError> {
   const paths = yield* workspace.discover()
-  const result: Record<string, ReadonlyArray<string>> = {}
+  const result: Array<{ rule: string; unit: string; paths: Array<string> }> = []
   for (const rule of rules) {
     const filePattern = new RegExp(rule.files)
     const unitPattern = new RegExp(rule.unit)
-    const units: Array<string> = []
     for (const path of paths.filter((path) => filePattern.test(path))) {
       const contents = yield* workspace.read(path)
       for (const line of contents.split(/\r?\n/)) {
         for (const unit of capture(unitPattern, line)) {
-          if (!units.includes(unit)) {
-            units.push(unit)
+          const existing = result.find((entry) => entry.rule === rule.name && entry.unit === unit)
+          if (existing === undefined) {
+            result.push({ rule: rule.name, unit, paths: [path] })
+          } else if (!existing.paths.includes(path)) {
+            existing.paths.push(path)
           }
         }
       }
     }
-    result[rule.name] = units
   }
   return result
 })
 
+export const coverageUnits = Effect.fn("@llm4ts/flow/SpecChecks.coverageUnits")(function* (
+  workspace: WorkspaceShape,
+  rules: ReadonlyArray<CoverageRule>
+): Effect.fn.Return<Readonly<Record<string, ReadonlyArray<string>>>, WorkspaceError> {
+  const captured = yield* capturedUnits(workspace, rules)
+  const result: Record<string, ReadonlyArray<string>> = {}
+  for (const rule of rules) {
+    result[rule.name] = captured
+      .filter((entry) => entry.rule === rule.name)
+      .map((entry) => entry.unit)
+  }
+  return result
+})
+
+export interface CoverageOptions {
+  /**
+   * Restricts the gate to units captured from at least one file this
+   * predicate accepts. A wave-scoped extraction passes the wave's program
+   * files here: a unit that lives only in another wave's sources (or in an
+   * estate-wide descriptor such as web.xml) is reported in `outOfScope`
+   * rather than failing this wave's gate. Absent: every unit gates.
+   */
+  readonly inScope?: (path: string) => boolean
+}
+
+export interface CoverageReport {
+  readonly result: ReviewResult
+  /** Uncovered units the scope excluded from the gate, as `rule: unit`. */
+  readonly outOfScope: ReadonlyArray<string>
+}
+
+const uncoveredIssue = (rule: string, unit: string): ReviewIssue =>
+  ReviewIssue.make({
+    severity: "Critical",
+    title: `uncovered ${rule}: ${unit}`,
+    description:
+      `'${unit}' exists in the legacy source but does not ` + "appear in the traceability matrix."
+  })
+
+/** Coverage with the scope split: what gates, and what was left to a later wave. */
+export const coverageReport = Effect.fn("@llm4ts/flow/SpecChecks.coverageReport")(function* (
+  workspace: WorkspaceShape,
+  rules: ReadonlyArray<CoverageRule>,
+  traceability: string,
+  options: CoverageOptions = {}
+): Effect.fn.Return<CoverageReport, WorkspaceError> {
+  const captured = yield* capturedUnits(workspace, rules)
+  const issues: Array<ReviewIssue> = []
+  const outOfScope: Array<string> = []
+  for (const entry of captured) {
+    if (traceability.includes(entry.unit)) {
+      continue
+    }
+    if (options.inScope === undefined || entry.paths.some(options.inScope)) {
+      issues.push(uncoveredIssue(entry.rule, entry.unit))
+    } else {
+      outOfScope.push(`${entry.rule}: ${entry.unit}`)
+    }
+  }
+  return {
+    result: ReviewResult.make({
+      issues,
+      summary: issues.length === 0 ? "coverage complete" : `${issues.length} unit(s) uncovered`
+    }),
+    outOfScope
+  }
+})
+
 export const coverage = Effect.fn("@llm4ts/flow/SpecChecks.coverage")(function* (
   workspace: WorkspaceShape,
   rules: ReadonlyArray<CoverageRule>,
-  traceability: string
+  traceability: string,
+  options: CoverageOptions = {}
 ): Effect.fn.Return<ReviewResult, WorkspaceError> {
-  const units = yield* coverageUnits(workspace, rules)
-  const issues = rules.flatMap((rule) =>
-    (units[rule.name] ?? []).flatMap((unit) =>
-      traceability.includes(unit)
-        ? []
-        : [
-            ReviewIssue.make({
-              severity: "Critical",
-              title: `uncovered ${rule.name}: ${unit}`,
-              description:
-                `'${unit}' exists in the legacy source but does not ` +
-                "appear in the traceability matrix."
-            })
-          ]
-    )
-  )
-  return ReviewResult.make({
-    issues,
-    summary: issues.length === 0 ? "coverage complete" : `${issues.length} unit(s) uncovered`
-  })
+  return (yield* coverageReport(workspace, rules, traceability, options)).result
 })
 
 const featureIssue = (path: string, contents: string): ReviewIssue | undefined => {
@@ -147,3 +211,39 @@ export const features = Effect.fn("@llm4ts/flow/SpecChecks.features")(function*
     summary: issues.length === 0 ? "features well-formed" : `${issues.length} malformed`
   })
 })
+
+/**
+ * Deterministic schema check of the specs a pack declares `spec-schema:`
+ * for: each program's spec must embed a block the schema decodes. A failure
+ * is a per-program Critical finding (titled like a judge finding, so the
+ * extraction gate's fix turn repairs that program), never a guess in a
+ * later phase — convert-page would otherwise be the first to notice.
+ */
+export const specSchemaIssues = Effect.fn("@llm4ts/flow/SpecChecks.specSchemaIssues")(function* (
+  schema: string | undefined,
+  specs: ReadonlyArray<{ readonly name: string; readonly markdown: string | undefined }>
+): Effect.fn.Return<ReadonlyArray<ReviewIssue>, never> {
+  if (schema !== "pagespec") {
+    return []
+  }
+  const issues: Array<ReviewIssue> = []
+  for (const spec of specs) {
+    const problem =
+      spec.markdown === undefined
+        ? "spec file is missing"
+        : yield* parsePageSpec(spec.markdown).pipe(
+            Effect.map(() => undefined),
+            Effect.catch((error) => Effect.succeed(error.message))
+          )
+    if (problem !== undefined) {
+      issues.push(
+        ReviewIssue.make({
+          severity: "Critical",
+          title: `judge[${spec.name}]: invalid pagespec block`,
+          description: `${problem}. ${pageSpecShapeHint}`
+        })
+      )
+    }
+  }
+  return issues
+})