@llm4ts/flow 2.17.0 → 2.18.0

package/src/EpicBrief.ts

@@ -473,6 +473,24 @@ export const BriefProblem = Schema.Union([
     scenario: Schema.String,
     disposition: Schema.String
   }),
+  Schema.Struct({
+    kind: Schema.Literal("AlreadyOwned"),
+    program: Schema.String,
+    scenario: Schema.String,
+    /** The approved epic that already has the scenario in scope. */
+    epic: Schema.String
+  }),
+  Schema.Struct({
+    kind: Schema.Literal("ContradictsBrief"),
+    program: Schema.String,
+    scenario: Schema.String,
+    /** The approved epic that decided otherwise. */
+    epic: Schema.String,
+    /** This brief's disposition, in words. */
+    here: Schema.String,
+    /** The other epic's disposition, in words. */
+    disposition: Schema.String
+  }),
   Schema.Struct({
     kind: Schema.Literal("ApprovedWithOpenPoints"),
     numbers: Schema.Array(Schema.Int)
@@ -498,11 +516,77 @@ export const renderBriefProblem = (problem: BriefProblem): string => {
       return `${problem.program}${cite}${problem.scenario} has no disposition: put it in scope, or drop, mark provided or defer it`
     case "RefineConflict":
       return `${problem.program}${cite}${problem.scenario} is in scope, but modernize-refine marked it ${problem.disposition}; answer \`keep: <why>\` to keep it in scope, or move it out`
+    case "AlreadyOwned":
+      return `${problem.program}${cite}${problem.scenario} is in scope here and in epic ${problem.epic}; answer \`keep: <why>\` to share it, or move it out`
+    case "ContradictsBrief":
+      return `${problem.program}${cite}${problem.scenario} is ${problem.here} here, but epic ${problem.epic} has it ${problem.disposition}; answer \`keep: <why>\` to keep this brief's decision, or follow the other`
     case "ApprovedWithOpenPoints":
       return `the brief is approved with unanswered open points: ${problem.numbers.join(", ")}`
   }
 }
 
+/** How a brief disposes of a scenario. */
+export type BriefDisposition = "in-scope" | "dropped" | "provided" | "deferred"
+
+export const dispositionWords: Readonly<Record<BriefDisposition, string>> = {
+  "in-scope": "in scope",
+  dropped: "dropped",
+  provided: "provided",
+  deferred: "deferred"
+}
+
+/** What an approved brief of another epic decided about a scenario (the coverage ledger). */
+export interface InheritedDecision {
+  readonly program: string
+  readonly scenario: string
+  readonly epic: string
+  readonly disposition: BriefDisposition
+  readonly note: string
+  /** The epics this decision was kept against on purpose (`keep: <why>` in that brief). */
+  readonly keptAgainst?: ReadonlyArray<string>
+}
+
+/**
+ * The one rule for two briefs on one scenario, read from the side of the
+ * brief that has `here`. A deferred scenario is free on either side; two
+ * briefs that agree are fine; both in scope is ownership shared or disputed;
+ * anything else is a contradiction. The ledger and the per-brief check both
+ * use it, so they cannot disagree about what a conflict is.
+ */
+export const crossProblem = (
+  program: string,
+  scenario: string,
+  here: BriefDisposition,
+  other: { readonly epic: string; readonly disposition: BriefDisposition }
+): BriefProblem | undefined => {
+  if (here === "deferred" || other.disposition === "deferred") return undefined
+  if (here === other.disposition) {
+    return here === "in-scope"
+      ? { kind: "AlreadyOwned", program, scenario, epic: other.epic }
+      : undefined
+  }
+  return {
+    kind: "ContradictsBrief",
+    program,
+    scenario,
+    epic: other.epic,
+    here: dispositionWords[here],
+    disposition: dispositionWords[other.disposition]
+  }
+}
+
+/**
+ * Whether the brief overrides a check on purpose: the check's own `[check]`
+ * question, answered `keep: <why>`. Any other answer, or an answer to
+ * another question, overrides nothing.
+ */
+export const hasOverride = (brief: EpicBrief, problem: BriefProblem): boolean =>
+  brief.openPoints.some(
+    (point) =>
+      point.question === `${checkMark} ${renderBriefProblem(problem)}` &&
+      (point.answer ?? "").trim().toLowerCase().startsWith("keep")
+  )
+
 /** The pointers of the provided entries: what the caller verifies before checking. */
 export const providedPointers = (brief: EpicBrief): ReadonlyArray<string> => [
   ...new Set(brief.provided.map((entry) => entry.note).filter((note) => note.length > 0))
@@ -515,6 +599,14 @@ export interface BriefCheckInputs {
   readonly pack: PackIndex
   /** The provided pointers that were found in the target (or its pack). */
   readonly pointers: ReadonlySet<string>
+  /**
+   * What approved briefs of other epics decided (the coverage ledger). Their
+   * decisions are inherited: they count towards completeness, and deciding
+   * otherwise here is a problem. Absent: the brief is checked on its own.
+   */
+  readonly others?: ReadonlyArray<InheritedDecision>
+  /** This brief's epic, as the other briefs name it. Default: the brief's own id. */
+  readonly epicId?: string
 }
 
 /** Every problem of a brief against the pack, all at once; empty means acceptable. */
@@ -593,6 +685,11 @@ export const checkEpicBrief = (
       problems.push({ kind: "DuplicateDisposition", program, scenario, lists: where })
     }
   }
+  const inherited = new Map<string, Array<InheritedDecision>>()
+  for (const decision of inputs.others ?? []) {
+    const key = slot(decision.program, decision.scenario)
+    inherited.set(key, [...(inherited.get(key) ?? []), decision])
+  }
   // Complete means every program the brief touches: the ones it lists as
   // considered, and any it cites or disposes of without listing.
   const touched = [
@@ -610,20 +707,13 @@ export const checkEpicBrief = (
       continue
     }
     for (const scenario of known.scenarios) {
-      if (!lists.has(slot(known.name, scenario))) {
+      if (!lists.has(slot(known.name, scenario)) && !inherited.has(slot(known.name, scenario))) {
         problems.push({ kind: "Unaccounted", program: known.name, scenario })
       }
     }
   }
 
   // A scenario refine took out of the pack's scope can come back only on purpose.
-  // The override is explicit: the check's own question, answered `keep: <why>`.
-  const justified = (conflict: BriefProblem): boolean =>
-    brief.openPoints.some(
-      (point) =>
-        point.question === `${checkMark} ${renderBriefProblem(conflict)}` &&
-        (point.answer ?? "").trim().toLowerCase().startsWith("keep")
-    )
   for (const item of brief.scope) {
     for (const citation of item.citations) {
       const refined = inputs.pack.refine.find(
@@ -639,11 +729,35 @@ export const checkEpicBrief = (
           scenario: citation.scenario,
           disposition: refined.disposition
         }
-        if (!justified(conflict)) problems.push(conflict)
+        if (!hasOverride(brief, conflict)) problems.push(conflict)
       }
     }
   }
 
+  // Approved briefs of other epics stand; `crossProblem` says when two briefs
+  // clash. A clash one side kept on purpose is settled: shared ownership when
+  // either keeps it, a contradiction when exactly one does.
+  const self = inputs.epicId ?? brief.epicId
+  const byWords = new Map<string, BriefDisposition>([
+    ["in scope", "in-scope"],
+    ["dropped", "dropped"],
+    ["provided", "provided"],
+    ["deferred", "deferred"]
+  ])
+  for (const [key, where] of lists) {
+    const [program = "", scenario = ""] = key.split("\u0000")
+    const here = byWords.get(where[0] ?? "")
+    if (here === undefined) continue
+    for (const other of inherited.get(key) ?? []) {
+      const problem = crossProblem(program, scenario, here, other)
+      if (problem === undefined) continue
+      const theyKept = (other.keptAgainst ?? []).includes(self)
+      const iKept = hasOverride(brief, problem)
+      const settled = problem.kind === "AlreadyOwned" ? theyKept || iKept : theyKept !== iKept
+      if (!settled) problems.push(problem)
+    }
+  }
+
   const pending = unanswered(brief)
   if (brief.status === "approved" && pending.length > 0) {
     problems.push({ kind: "ApprovedWithOpenPoints", numbers: pending.map((point) => point.number) })