@llm4ts/flow 2.1.0 → 2.2.0

package/src/Pack.ts

@@ -1,6 +1,7 @@
 import * as Effect from "effect/Effect"
 import * as Schema from "effect/Schema"
 import { Dimension } from "@llm4ts/core/eval/Eval"
+import type { ConsolidateRules } from "./Domains.ts"
 import { PlanParseError } from "./FlowError.ts"
 import { parseReviewer, type Reviewer } from "./Reviewer.ts"
 import { CoverageRule } from "./SpecChecks.ts"
@@ -41,12 +42,25 @@ export interface Pack {
   // paths), `<NAME>` substituted with the program name. The seam that makes
   // per-program judging possible.
   readonly programFiles: string | undefined
+  /**
+   * Regex template locating a DOMAIN FEATURE's target files (ADR 0012
+   * addendum): `<NAME>` is the feature id, `<PAGES>` an alternation of its
+   * page names. A feature's scope is this template plus every page's own
+   * `program-files` scope.
+   */
+  readonly featureFiles: string | undefined
   /**
    * The schema every program spec must embed, validated deterministically
    * by the extraction gate: `pagespec` (a ```json pagespec block decodable
    * as `PageSpec`) is the only one today; absent means prose-only specs.
    */
   readonly specSchema: string | undefined
+  /**
+   * The `## Consolidate` section (ADR 0015): which survey edge kinds put two
+   * units in one domain feature (`cluster:`) and which only attach a shared
+   * fragment as context (`context:`). Absent: every program is its own feature.
+   */
+  readonly consolidate: ConsolidateRules | undefined
   readonly dir: string
   readonly gate: (name: string) => ReadonlyArray<string> | undefined
   readonly prompt: (name: string) => string | undefined
@@ -54,6 +68,8 @@ export interface Pack {
   // template with `<NAME>` substituted, or a case-insensitive "path contains
   // the program name" fallback.
   readonly filesFor: (program: string) => RegExp
+  /** The regex for a feature's files: its template (when set) or any of its pages' scopes. */
+  readonly filesForFeature: (feature: string, pages: ReadonlyArray<string>) => RegExp
 }
 
 interface ParsedManifest {
@@ -152,6 +168,12 @@ const dimensions = (body: string | undefined): ReadonlyArray<Dimension> =>
       : [Dimension.make({ name, rubric, maxScore })]
   })
 
+const commaList = (value: string | undefined): ReadonlyArray<string> =>
+  (value ?? "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0)
+
 const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
 
 const isValidRegExp = (source: string): boolean => {
@@ -219,12 +241,48 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
       message: `pack manifest 'programFiles:' is not a valid regex template: ${programFiles}`
     })
   }
+  const featureFiles = fields["feature-files"]
+  if (
+    featureFiles !== undefined &&
+    !isValidRegExp(featureFiles.replaceAll("<NAME>", "PROBE").replaceAll("<PAGES>", "PROBE"))
+  ) {
+    return yield* PlanParseError.make({
+      message: `pack manifest 'feature-files:' is not a valid regex template: ${featureFiles}`
+    })
+  }
   const specSchema = fields["spec-schema"]
   if (specSchema !== undefined && specSchema !== "pagespec") {
     return yield* PlanParseError.make({
       message: `pack manifest 'spec-schema:' must be 'pagespec' when set, got: ${specSchema}`
     })
   }
+  const consolidateValues = namedItems(section(manifest.sections, "Consolidate"))
+  const consolidate: ConsolidateRules | undefined =
+    section(manifest.sections, "Consolidate") === undefined
+      ? undefined
+      : {
+          cluster: commaList(consolidateValues.cluster),
+          context: commaList(consolidateValues.context)
+        }
+  if (consolidate !== undefined) {
+    const surveyNames = new Set(rules(manifest.sections, "## Survey: ").map((rule) => rule.name))
+    const unknown = [...consolidate.cluster, ...consolidate.context].filter(
+      (kind) => !surveyNames.has(kind) && !kind.startsWith("llm-") && !kind.endsWith("*")
+    )
+    if (unknown.length > 0) {
+      return yield* PlanParseError.make({
+        message:
+          `pack manifest '## Consolidate' names edge kinds no '## Survey:' rule produces: ${unknown.join(", ")} ` +
+          `(known: ${[...surveyNames].join(", ") || "none"}; 'llm-*' matches refined edges)`
+      })
+    }
+    const both = consolidate.cluster.filter((kind) => consolidate.context.includes(kind))
+    if (both.length > 0) {
+      return yield* PlanParseError.make({
+        message: `pack manifest '## Consolidate' lists ${both.join(", ")} as both cluster and context`
+      })
+    }
+  }
   const exclude = fields.exclude
   if (exclude !== undefined && !isValidRegExp(exclude)) {
     return yield* PlanParseError.make({
@@ -258,7 +316,9 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
     lenses,
     lessons: lessons === undefined || lessons.length === 0 ? undefined : lessons,
     programFiles,
+    featureFiles,
     specSchema,
+    consolidate,
     dir: directory,
     gate: (name) => gates[name],
     prompt: (name) => prompts[name],
@@ -267,7 +327,25 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
     filesFor: (program) =>
       programFiles === undefined
         ? new RegExp(escapeRegExp(program), "i")
-        : new RegExp(`^(?:${programFiles.replaceAll("<NAME>", program)})$`)
+        : new RegExp(`^(?:${programFiles.replaceAll("<NAME>", program)})$`),
+    filesForFeature: (feature, pages) => {
+      const pageScopes =
+        programFiles === undefined
+          ? pages.map((page) => escapeRegExp(page))
+          : pages.map((page) => programFiles.replaceAll("<NAME>", page))
+      const own =
+        featureFiles === undefined
+          ? []
+          : [
+              featureFiles
+                .replaceAll("<NAME>", feature)
+                .replaceAll("<PAGES>", pages.map(escapeRegExp).join("|") || "PROBE")
+            ]
+      const alternatives = [...own, ...pageScopes]
+      return programFiles === undefined && featureFiles === undefined
+        ? new RegExp(alternatives.join("|"), "i")
+        : new RegExp(`^(?:${alternatives.join("|")})$`)
+    }
   }
   return pack
 })

package/src/PageSpec.ts

@@ -1,6 +1,8 @@
 import * as Effect from "effect/Effect"
 import * as Schema from "effect/Schema"
-import { PlanParseError } from "./FlowError.ts"
+import { ContractConflict, PlanParseError } from "./FlowError.ts"
+
+export { ContractConflict } 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
@@ -251,9 +253,20 @@ const propertyLines = (
  * 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 => {
+interface ContractInfo {
+  readonly title: string
+  readonly description: string
+}
+
+/** The YAML writer shared by the per-page and the per-feature contracts. */
+const renderOpenApi = (
+  info: ContractInfo,
+  apiCalls: ReadonlyArray<PageApiCall>,
+  dtos: ReadonlyArray<PageDto>,
+  origins?: ReadonlyMap<string, ReadonlyArray<string>>
+): string => {
   const byPath = new Map<string, Array<PageApiCall>>()
-  for (const call of spec.apiCalls) {
+  for (const call of apiCalls) {
     const bucket = byPath.get(call.path) ?? []
     bucket.push(call)
     byPath.set(call.path, bucket)
@@ -262,8 +275,8 @@ export const openApiFor = (spec: PageSpec): string => {
   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})`)}`,
+    `  title: ${yamlText(info.title)}`,
+    `  description: ${yamlText(info.description)}`,
     "  version: 0.1.0",
     "paths:"
   ]
@@ -286,8 +299,12 @@ export const openApiFor = (spec: PageSpec): string => {
       const call = variants[0]!
       lines.push(`    ${method}:`)
       lines.push(`      operationId: ${call.operation}`)
+      const origin = origins?.get(`${call.method.toUpperCase()} ${call.path}`)
       const notes = [
         ...(call.esbService === undefined ? [] : [`backed by ESB service ${call.esbService}`]),
+        ...(origin === undefined
+          ? []
+          : [`declared by page${origin.length > 1 ? "s" : ""} ${origin.join(", ")}`]),
         ...(variants.length > 1
           ? [
               `also serves: ${variants
@@ -342,14 +359,14 @@ export const openApiFor = (spec: PageSpec): string => {
   }
   lines.push("components:")
   lines.push("  schemas:")
-  const schemaCalls = [...spec.apiCalls].sort((a, b) => a.operation.localeCompare(b.operation))
+  const schemaCalls = [...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]))
+    apiCalls.flatMap((call) => (call.responseDto === undefined ? [] : [call.responseDto]))
   )
-  for (const dto of [...spec.dtos].sort((a, b) => a.domainName.localeCompare(b.domainName))) {
+  for (const dto of [...dtos].sort((a, b) => a.domainName.localeCompare(b.domainName))) {
     if (!referencedDtos.has(dto.domainName)) {
       continue
     }
@@ -388,6 +405,113 @@ export const openApiFor = (spec: PageSpec): string => {
   return lines.join("\n") + "\n"
 }
 
+export const openApiFor = (spec: PageSpec): string =>
+  renderOpenApi(
+    {
+      title: `${spec.title} service contract`,
+      description: `Anti-corruption contract for page ${spec.page} (${spec.route})`
+    },
+    spec.apiCalls,
+    spec.dtos
+  )
+
+const sameFields = (
+  left: ReadonlyArray<FieldMapping>,
+  right: ReadonlyArray<FieldMapping>
+): boolean =>
+  left.length === right.length &&
+  left.every(
+    (field, index) =>
+      field.legacyName === right[index]?.legacyName &&
+      field.domainName === right[index]?.domainName &&
+      field.type === right[index]?.type
+  )
+
+const sameCall = (left: PageApiCall, right: PageApiCall): boolean =>
+  left.operation === right.operation &&
+  left.responseDto === right.responseDto &&
+  left.responseShape === right.responseShape &&
+  sameFields(left.request, right.request) &&
+  sameFields(left.response, right.response)
+
+export interface FeatureContract {
+  readonly yaml: string
+  /** `<method> <path>` of every operation and the pages that declare it. */
+  readonly operations: ReadonlyArray<{
+    readonly key: string
+    readonly pages: ReadonlyArray<string>
+  }>
+}
+
+/**
+ * ONE contract for a domain feature (ADR 0012 addendum): the union of its
+ * pages' API sections by method + path, DTOs by domain name. Two pages that
+ * declare the same method + path (or the same operation name) with different
+ * shapes, or the same DTO with different fields, are a `ContractConflict`
+ * listing every disagreement — never a silent merge. The page each
+ * operation came from is recorded in its description.
+ */
+export const openApiForFeature = (
+  feature: { readonly id: string; readonly name: string },
+  specs: ReadonlyArray<PageSpec>
+): Effect.Effect<FeatureContract, ContractConflict> => {
+  const conflicts: Array<string> = []
+  const calls = new Map<string, { call: PageApiCall; pages: Array<string> }>()
+  const byOperation = new Map<string, string>()
+  for (const spec of specs) {
+    for (const call of spec.apiCalls) {
+      const key = `${call.method.toUpperCase()} ${call.path}`
+      const existing = calls.get(key)
+      if (existing === undefined) {
+        const owner = byOperation.get(call.operation)
+        if (owner !== undefined && owner !== key) {
+          conflicts.push(
+            `operation '${call.operation}' is declared on ${owner} and on ${key} (${spec.page})`
+          )
+          continue
+        }
+        byOperation.set(call.operation, key)
+        calls.set(key, { call, pages: [spec.page] })
+      } else if (sameCall(existing.call, call)) {
+        existing.pages.push(spec.page)
+      } else {
+        conflicts.push(
+          `${key} differs between ${existing.pages.join(", ")} (${existing.call.operation}) and ${spec.page} (${call.operation})`
+        )
+      }
+    }
+  }
+  const dtos = new Map<string, { dto: PageDto; page: string }>()
+  for (const spec of specs) {
+    for (const dto of spec.dtos) {
+      const existing = dtos.get(dto.domainName)
+      if (existing === undefined) {
+        dtos.set(dto.domainName, { dto, page: spec.page })
+      } else if (!sameFields(existing.dto.fields, dto.fields)) {
+        conflicts.push(
+          `DTO '${dto.domainName}' has different fields in ${existing.page} and ${spec.page}`
+        )
+      }
+    }
+  }
+  if (conflicts.length > 0) {
+    return Effect.fail(ContractConflict.make({ feature: feature.id, conflicts }))
+  }
+  const operations = [...calls.entries()].map(([key, { pages }]) => ({ key, pages }))
+  const yaml = renderOpenApi(
+    {
+      title: `${feature.name} service contract`,
+      description:
+        `Anti-corruption contract for domain feature ${feature.id} — pages ` +
+        specs.map((spec) => spec.page).join(", ")
+    },
+    [...calls.values()].map(({ call }) => call),
+    [...dtos.values()].map(({ dto }) => dto),
+    new Map(operations.map(({ key, pages }) => [key, pages]))
+  )
+  return Effect.succeed({ yaml, operations })
+}
+
 /** Human-readable summary — the review surface next to the JSON contract. */
 export const renderPageSpec = (spec: PageSpec): string => {
   const lines: Array<string> = [

package/src/SpecChecks.ts

@@ -100,12 +100,20 @@ export interface CoverageOptions {
    * rather than failing this wave's gate. Absent: every unit gates.
    */
   readonly inScope?: (path: string) => boolean
+  /**
+   * Units a decisions overlay waives (ADR 0015): the legacy has them, a
+   * human decided not to carry them, so they never gate and are reported
+   * as waived rather than uncovered.
+   */
+  readonly waived?: ReadonlySet<string>
 }
 
 export interface CoverageReport {
   readonly result: ReviewResult
   /** Uncovered units the scope excluded from the gate, as `rule: unit`. */
   readonly outOfScope: ReadonlyArray<string>
+  /** Uncovered units a decision waived, as `rule: unit`. */
+  readonly waived: ReadonlyArray<string>
 }
 
 const uncoveredIssue = (rule: string, unit: string): ReviewIssue =>
@@ -126,10 +134,15 @@ export const coverageReport = Effect.fn("@llm4ts/flow/SpecChecks.coverageReport"
   const captured = yield* capturedUnits(workspace, rules)
   const issues: Array<ReviewIssue> = []
   const outOfScope: Array<string> = []
+  const waived: Array<string> = []
   for (const entry of captured) {
     if (traceability.includes(entry.unit)) {
       continue
     }
+    if (options.waived?.has(entry.unit) === true) {
+      waived.push(`${entry.rule}: ${entry.unit}`)
+      continue
+    }
     if (options.inScope === undefined || entry.paths.some(options.inScope)) {
       issues.push(uncoveredIssue(entry.rule, entry.unit))
     } else {
@@ -141,7 +154,8 @@ export const coverageReport = Effect.fn("@llm4ts/flow/SpecChecks.coverageReport"
       issues,
       summary: issues.length === 0 ? "coverage complete" : `${issues.length} unit(s) uncovered`
     }),
-    outOfScope
+    outOfScope,
+    waived
   }
 })