@llm4ts/flow 2.16.0 → 2.18.0

package/dist/EpicBrief.d.ts

@@ -0,0 +1,239 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { JsonSchema } from "@llm4ts/core/Models";
+import { OpenPoint } from "./Decisions.ts";
+import { EpicBriefInvalid } from "./FlowError.ts";
+/**
+ * The epic brief: what `epic-design` writes and `epic-stories` plans from.
+ * The file is the state. It says what an epic delivers and, for every
+ * scenario of every legacy program it considered, whether that behaviour is
+ * carried over, dropped, already provided by the target, or deferred, each
+ * with its evidence in the extract pack (`PROGRAM › scenario title`). A human
+ * edits it, answers its open points, writes feedback, and approves it by
+ * setting `Status: approved`.
+ */
+export declare const BriefStatus: Schema.Literals<readonly ["draft", "approved"]>;
+export type BriefStatus = typeof BriefStatus.Type;
+declare const Citation_base: Schema.Class<Citation, Schema.Struct<{
+    readonly program: Schema.String;
+    readonly scenario: Schema.String;
+}>, {}>;
+/** Legacy evidence: a scenario of a program, both named exactly as in the pack. */
+export declare class Citation extends Citation_base {
+}
+declare const ScopeItem_base: Schema.Class<ScopeItem, Schema.Struct<{
+    readonly title: Schema.String;
+    readonly citations: Schema.$Array<typeof Citation>;
+    /** Why an item with no citation exists: behaviour with no legacy counterpart. */
+    readonly newBehaviour: Schema.optionalKey<Schema.String>;
+}>, {}>;
+export declare class ScopeItem extends ScopeItem_base {
+}
+declare const Disposed_base: Schema.Class<Disposed, Schema.Struct<{
+    readonly program: Schema.String;
+    readonly scenario: Schema.String;
+    readonly note: Schema.String;
+}>, {}>;
+/** A scenario not carried over; `note` is the reason (dropped), the pointer (provided) or the note (deferred). */
+export declare class Disposed extends Disposed_base {
+}
+declare const ConsideredProgram_base: Schema.Class<ConsideredProgram, Schema.Struct<{
+    readonly name: Schema.String;
+    readonly reason: Schema.String;
+}>, {}>;
+export declare class ConsideredProgram extends ConsideredProgram_base {
+}
+declare const EpicBrief_base: Schema.Class<EpicBrief, Schema.Struct<{
+    readonly epicId: Schema.String;
+    readonly status: Schema.Literals<readonly ["draft", "approved"]>;
+    /** The epic as the user asked for it; becomes the story plan's `epic`. */
+    readonly request: Schema.String;
+    readonly legacy: Schema.String;
+    readonly goal: Schema.String;
+    readonly programs: Schema.$Array<typeof ConsideredProgram>;
+    readonly scope: Schema.$Array<typeof ScopeItem>;
+    readonly dropped: Schema.$Array<typeof Disposed>;
+    readonly provided: Schema.$Array<typeof Disposed>;
+    readonly deferred: Schema.$Array<typeof Disposed>;
+    readonly constraints: Schema.String;
+    readonly openPoints: Schema.$Array<typeof OpenPoint>;
+    readonly feedback: Schema.String;
+}>, {}>;
+export declare class EpicBrief extends EpicBrief_base {
+}
+/** Open points with no answer, or an empty one. */
+export declare const unanswered: (brief: EpicBrief) => ReadonlyArray<OpenPoint>;
+export declare const renderEpicBrief: (brief: EpicBrief) => string;
+export declare const parseEpicBrief: (markdown: string, path?: string | undefined) => Effect.Effect<EpicBrief, EpicBriefInvalid, never>;
+/**
+ * The brief as the file can hold it. A model's proposal may carry a newline
+ * in a title, a `## ` line in the goal, an unclosed fence; written as they
+ * are, those would parse back as something else on the next run. Fields that
+ * live on one line are folded onto one, prose is made safe for the section
+ * grammar, and nothing else changes.
+ */
+export declare const normalizeBrief: (brief: EpicBrief) => EpicBrief;
+export interface PackProgram {
+    readonly name: string;
+    /** The first paragraph of the program's spec. */
+    readonly summary: string;
+    readonly scenarios: ReadonlyArray<string>;
+}
+/** A disposition `modernize-refine` recorded in the legacy pack's decisions.md. */
+export interface RefineDisposition {
+    readonly program: string;
+    /** Absent: the disposition covers every scenario of the program. */
+    readonly scenario?: string;
+    readonly disposition: "drop" | "provided" | "defer" | "wrap";
+}
+/** What the checks need from the extract pack, built by the flow from its files. */
+export interface PackIndex {
+    readonly programs: ReadonlyArray<PackProgram>;
+    readonly refine: ReadonlyArray<RefineDisposition>;
+}
+export declare const BriefProblem: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"UnknownProgram">;
+    readonly program: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"UnknownScenario">;
+    readonly program: Schema.String;
+    readonly scenario: Schema.String;
+    readonly closest: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"MissingPointer">;
+    readonly program: Schema.String;
+    readonly scenario: Schema.String;
+    readonly pointer: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"MissingReason">;
+    readonly where: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"DuplicateDisposition">;
+    readonly program: Schema.String;
+    readonly scenario: Schema.String;
+    readonly lists: Schema.$Array<Schema.String>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"Unaccounted">;
+    readonly program: Schema.String;
+    readonly scenario: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"RefineConflict">;
+    readonly program: Schema.String;
+    readonly scenario: Schema.String;
+    readonly disposition: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"AlreadyOwned">;
+    readonly program: Schema.String;
+    readonly scenario: Schema.String;
+    /** The approved epic that already has the scenario in scope. */
+    readonly epic: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"ContradictsBrief">;
+    readonly program: Schema.String;
+    readonly scenario: Schema.String;
+    /** The approved epic that decided otherwise. */
+    readonly epic: Schema.String;
+    /** This brief's disposition, in words. */
+    readonly here: Schema.String;
+    /** The other epic's disposition, in words. */
+    readonly disposition: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"ApprovedWithOpenPoints">;
+    readonly numbers: Schema.$Array<Schema.Int>;
+}>]>;
+export type BriefProblem = typeof BriefProblem.Type;
+export declare const renderBriefProblem: (problem: BriefProblem) => string;
+/** How a brief disposes of a scenario. */
+export type BriefDisposition = "in-scope" | "dropped" | "provided" | "deferred";
+export declare const dispositionWords: Readonly<Record<BriefDisposition, string>>;
+/** 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 declare const crossProblem: (program: string, scenario: string, here: BriefDisposition, other: {
+    readonly epic: string;
+    readonly disposition: BriefDisposition;
+}) => BriefProblem | undefined;
+/**
+ * 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 declare const hasOverride: (brief: EpicBrief, problem: BriefProblem) => boolean;
+/** The pointers of the provided entries: what the caller verifies before checking. */
+export declare const providedPointers: (brief: EpicBrief) => ReadonlyArray<string>;
+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. */
+export declare const checkEpicBrief: (brief: EpicBrief, inputs: BriefCheckInputs) => ReadonlyArray<BriefProblem>;
+declare const ProgramSelection_base: Schema.Class<ProgramSelection, Schema.Struct<{
+    readonly programs: Schema.$Array<typeof ConsideredProgram>;
+}>, {}>;
+/** The programs of the pack a request touches; the model's first typed reply. */
+export declare class ProgramSelection extends ProgramSelection_base {
+}
+declare const EpicBriefProposal_base: Schema.Class<EpicBriefProposal, Schema.Struct<{
+    readonly goal: Schema.String;
+    readonly scope: Schema.$Array<typeof ScopeItem>;
+    readonly dropped: Schema.$Array<typeof Disposed>;
+    readonly provided: Schema.$Array<typeof Disposed>;
+    readonly deferred: Schema.$Array<typeof Disposed>;
+    readonly constraints: Schema.String;
+    /** Questions only a human can answer. */
+    readonly openPoints: Schema.$Array<Schema.String>;
+}>, {}>;
+/** The model's typed proposal for a brief; checked before anything is written. */
+export declare class EpicBriefProposal extends EpicBriefProposal_base {
+}
+export declare const programSelectionJsonSchema: JsonSchema;
+export declare const epicBriefProposalJsonSchema: JsonSchema;
+export interface AssembleOptions {
+    readonly epicId: string;
+    readonly request: string;
+    readonly legacy: string;
+    readonly programs: ReadonlyArray<ConsideredProgram>;
+    readonly proposal: EpicBriefProposal;
+    /** The brief this one revises: its unanswered points the proposal did not restate are kept. */
+    readonly previous?: EpicBrief;
+    /** Problems the fix round could not clear: raised as `[check]` open points. */
+    readonly problems?: ReadonlyArray<BriefProblem>;
+}
+export declare const checkMark = "[check]";
+/**
+ * The next draft: never approved, feedback consumed, open points renumbered.
+ * Answered points are folded in by the revision and go, except answered
+ * `[check]` points: those are the human overriding a check (a scenario
+ * refine dropped, kept on purpose) and stay as the record of it.
+ */
+export declare const assembleBrief: (options: AssembleOptions) => EpicBrief;
+export type LoopAction = "propose" | "revise" | "halt" | "await-approval" | "validate";
+/** What one run does, decided from the file alone. */
+export declare const loopAction: (brief: EpicBrief | undefined) => LoopAction;
+/** What a revision changed, in lines a person reads; empty when nothing did. */
+export declare const diffBriefs: (previous: EpicBrief | undefined, next: EpicBrief) => ReadonlyArray<string>;
+export {};
+//# sourceMappingURL=EpicBrief.d.ts.map

package/dist/EpicBrief.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EpicBrief.d.ts","sourceRoot":"","sources":["../src/EpicBrief.ts"],"names":[],"mappings":"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"}