@inflexa-ai/harness 0.17.0 → 0.19.0

package/dist/report-model/block-walk.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The one walk over a block tree.
+ *
+ * A block kind decides where a reference sits, which prose carries a free numeral, and whether the block
+ * holds children. Three consumers need that same knowledge: the mechanical validator, the draft finish,
+ * and the draft operations. A switch for each consumer is a switch that a ninth block kind can miss in
+ * silence, because each arm returns and none of them fails to build. Thus the walk lives here one time.
+ *
+ * The walk reads a finished `Block` tree and a relaxed `DraftBlock` tree alike. The two differ only in the
+ * section rules, and the section arm reads the children of either one.
+ *
+ * The walk resolves nothing and it opens no file. It reports what the tree holds, and a caller decides
+ * which part it needs.
+ */
+import type { Block } from "../contracts/report-blocks.js";
+import type { Reference } from "../contracts/report-reference.js";
+import type { DraftBlock } from "./draft.js";
+/** A block of a finished report, or a block of a draft. The atoms are the same shape in both. */
+export type AnyBlock = Block | DraftBlock;
+/**
+ * One reference that the walk met, tied to the block that carries it.
+ *
+ * `encodingColumns` is present for a `chart` only. A chart names its axes as free strings, thus the names
+ * must be matched against the table that the binding resolves to. Nothing else can catch a chart that
+ * plots a column which does not exist. The match needs the resolved rows, thus only a value-tier consumer
+ * reads this field.
+ */
+export interface CollectedReference {
+    blockId: string;
+    reference: Reference;
+    encodingColumns?: string[];
+}
+/** An advisory warning about the content of one block. A warning never makes a report invalid. */
+export interface ReportWarning {
+    blockId: string;
+    kind: "free-numeral";
+    detail: string;
+}
+/** What one walk over a block tree found. */
+export interface BlockWalk {
+    /** Each reference, in document order, tied to the block that carries it. */
+    references: CollectedReference[];
+    /** Each id that more than one block holds, named one time, in sorted order. */
+    repeatedIds: string[];
+    /** Each free numeral that prose carries. */
+    warnings: ReportWarning[];
+}
+/** Warn for each free-standing numeral that the prose of one block carries. */
+export declare function numeralWarnings(blockId: string, prose: string): ReportWarning[];
+/**
+ * Walk a block tree, and report each reference, each repeated id, and each free numeral.
+ *
+ * An id is what makes a block addressable, thus an amend by id is well defined only while each id belongs
+ * to one block. The walk is pre-order, thus the references follow the document order.
+ */
+export declare function walkBlocks(blocks: readonly AnyBlock[]): BlockWalk;

package/dist/report-model/block-walk.js

@@ -0,0 +1,89 @@
+/**
+ * The one walk over a block tree.
+ *
+ * A block kind decides where a reference sits, which prose carries a free numeral, and whether the block
+ * holds children. Three consumers need that same knowledge: the mechanical validator, the draft finish,
+ * and the draft operations. A switch for each consumer is a switch that a ninth block kind can miss in
+ * silence, because each arm returns and none of them fails to build. Thus the walk lives here one time.
+ *
+ * The walk reads a finished `Block` tree and a relaxed `DraftBlock` tree alike. The two differ only in the
+ * section rules, and the section arm reads the children of either one.
+ *
+ * The walk resolves nothing and it opens no file. It reports what the tree holds, and a caller decides
+ * which part it needs.
+ */
+/**
+ * A free-standing token that looks like a number, with an optional decimal part and an optional percent
+ * sign.
+ *
+ * The left boundary keeps the digits of a name out of the warnings. The domain prose is dense with a
+ * symbol such as `TP53`, `CD8`, or `IL6`, and without the boundary each one warns for its digits and
+ * buries the real free figures.
+ *
+ * The check is advisory only. A natural-language numeral is brittle to police, because a numeral in prose
+ * can be a real free-standing figure or a harmless part of a name. Thus a hit warns, and it never fails
+ * the report.
+ */
+const NUMERAL_PATTERN = /(?<![A-Za-z0-9])-?\d+(?:\.\d+)?%?/g;
+/** Warn for each free-standing numeral that the prose of one block carries. */
+export function numeralWarnings(blockId, prose) {
+    const warnings = [];
+    for (const match of prose.matchAll(NUMERAL_PATTERN)) {
+        warnings.push({ blockId, kind: "free-numeral", detail: match[0] });
+    }
+    return warnings;
+}
+/**
+ * Walk a block tree, and report each reference, each repeated id, and each free numeral.
+ *
+ * An id is what makes a block addressable, thus an amend by id is well defined only while each id belongs
+ * to one block. The walk is pre-order, thus the references follow the document order.
+ */
+export function walkBlocks(blocks) {
+    const references = [];
+    const warnings = [];
+    const seenIds = new Set();
+    const repeated = new Set();
+    const visit = (block) => {
+        if (seenIds.has(block.id)) {
+            repeated.add(block.id);
+        }
+        else {
+            seenIds.add(block.id);
+        }
+        switch (block.kind) {
+            case "section":
+                for (const child of block.blocks) {
+                    visit(child);
+                }
+                return;
+            case "text":
+                warnings.push(...numeralWarnings(block.id, block.content.prose));
+                return;
+            case "claim":
+                warnings.push(...numeralWarnings(block.id, block.content.prose));
+                for (const binding of block.bindings) {
+                    references.push({ blockId: block.id, reference: binding });
+                }
+                return;
+            case "metric":
+                references.push({ blockId: block.id, reference: block.value });
+                return;
+            case "chart": {
+                const encoding = block.encoding;
+                const encodingColumns = [encoding.x, encoding.y, encoding.group, encoding.value].filter((column) => column !== undefined);
+                references.push({ blockId: block.id, reference: block.binding, encodingColumns });
+                return;
+            }
+            case "table":
+            case "figure":
+            case "citation":
+                references.push({ blockId: block.id, reference: block.binding });
+                return;
+        }
+    };
+    for (const block of blocks) {
+        visit(block);
+    }
+    return { references, repeatedIds: [...repeated].sort(), warnings };
+}

package/dist/report-model/draft-finish.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The finish of a draft.
+ *
+ * An edit refuses what is wrong. The finish refuses what is missing. Thus the finish gates the whole
+ * draft one time: the full document schema, the unique ids, and the structural tier over every reference.
+ *
+ * The finish opens no file, and it reads the snapshot alone. Thus it runs the structural tier only, and
+ * the value tier stays in the gate of the report pipeline. The chart encoding-column match needs the rows
+ * behind a binding, thus it stays with the value tier.
+ *
+ * The free-numeral scan needs no file, thus the finish runs it and reports each hit as a warning. A
+ * warning never makes a draft invalid, and it rides beside the outcome in either case. Without the
+ * channel a caller could not read the one signal that catches a figure typed into prose with no metric
+ * block behind it.
+ *
+ * The result is plain data. A gap is an expected outcome, not an error, thus the finish never throws. On
+ * a pass the finish gives the valid document, and it does not change the draft.
+ */
+import { type ReportDocument } from "../contracts/report-blocks.js";
+import type { UnresolvedReference } from "../contracts/report-reference.js";
+import { type ReportWarning } from "./block-walk.js";
+import type { DraftDocument } from "./draft.js";
+import type { ReportSnapshot } from "./reference-resolver.js";
+/** A schema conformance gap, reduced to a path and a message. */
+export interface SchemaGap {
+    kind: "schema";
+    path: string;
+    message: string;
+}
+/** A duplicate id gap. More than one block holds the id. */
+export interface DuplicateIdGap {
+    kind: "duplicate-id";
+    id: string;
+}
+/** An unresolved reference gap. It ties the block that carries the reference to the reason it did not resolve. */
+export interface UnresolvedReferenceGap {
+    kind: "unresolved-reference";
+    blockId: string;
+    failure: UnresolvedReference;
+}
+/** One completeness gap of a draft. The kind set is closed. */
+export type FinishGap = SchemaGap | DuplicateIdGap | UnresolvedReferenceGap;
+/**
+ * The finish result. On a pass it gives the valid document. On a fail it gives each gap. The warnings
+ * ride along in either case, because a warning is advisory and it never decides the outcome.
+ */
+export type FinishResult = {
+    valid: true;
+    document: ReportDocument;
+    warnings: ReportWarning[];
+} | {
+    valid: false;
+    gaps: FinishGap[];
+    warnings: ReportWarning[];
+};
+/**
+ * Finish a draft. The finish validates the schema, the unique ids, and the structural resolution of each
+ * reference, and it reports each gap as data. It warns about each free numeral in prose.
+ */
+export declare function finishDraft(draft: DraftDocument, snapshot: ReportSnapshot): FinishResult;

package/dist/report-model/draft-finish.js

@@ -0,0 +1,56 @@
+/**
+ * The finish of a draft.
+ *
+ * An edit refuses what is wrong. The finish refuses what is missing. Thus the finish gates the whole
+ * draft one time: the full document schema, the unique ids, and the structural tier over every reference.
+ *
+ * The finish opens no file, and it reads the snapshot alone. Thus it runs the structural tier only, and
+ * the value tier stays in the gate of the report pipeline. The chart encoding-column match needs the rows
+ * behind a binding, thus it stays with the value tier.
+ *
+ * The free-numeral scan needs no file, thus the finish runs it and reports each hit as a warning. A
+ * warning never makes a draft invalid, and it rides beside the outcome in either case. Without the
+ * channel a caller could not read the one signal that catches a figure typed into prose with no metric
+ * block behind it.
+ *
+ * The result is plain data. A gap is an expected outcome, not an error, thus the finish never throws. On
+ * a pass the finish gives the valid document, and it does not change the draft.
+ */
+import { ReportDocumentSchema } from "../contracts/report-blocks.js";
+import { walkBlocks } from "./block-walk.js";
+import { validateReferenceStructure } from "./structural-validation.js";
+/**
+ * Finish a draft. The finish validates the schema, the unique ids, and the structural resolution of each
+ * reference, and it reports each gap as data. It warns about each free numeral in prose.
+ */
+export function finishDraft(draft, snapshot) {
+    const gaps = [];
+    const parsed = ReportDocumentSchema.safeParse(draft);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            gaps.push({
+                kind: "schema",
+                path: issue.path.map((segment) => String(segment)).join("."),
+                message: issue.message,
+            });
+        }
+    }
+    // The walk reads the draft tree, not the parse result. The draft is already typed, thus the walk stays
+    // well-defined even when the schema parse fails, and a caller still gets the id and reference gaps.
+    const { references, repeatedIds, warnings } = walkBlocks(draft.sections);
+    for (const id of repeatedIds) {
+        gaps.push({ kind: "duplicate-id", id });
+    }
+    for (const entry of references) {
+        const result = validateReferenceStructure(entry.reference, snapshot);
+        if (result.isErr()) {
+            gaps.push({ kind: "unresolved-reference", blockId: entry.blockId, failure: result.error });
+        }
+    }
+    // A schema failure always pushes a gap. Thus an empty gap list means the parse passed. The
+    // `parsed.success` test also narrows the type for the document return.
+    if (!parsed.success || gaps.length > 0) {
+        return { valid: false, gaps, warnings };
+    }
+    return { valid: true, document: parsed.data, warnings };
+}

package/dist/report-model/draft-operations.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The pure operations that compose a draft report document.
+ *
+ * An operation takes the draft, an operation value, and the pinned snapshot. It gives a new draft, or a
+ * typed refusal in the error channel. It mutates nothing. Thus a refused operation leaves the input draft
+ * as it was.
+ *
+ * An operation validates the delta only. It parses the new payload with the draft grammar. It scans the
+ * ids that the payload brings, and it resolves each new reference against the snapshot with the
+ * structural tier. The completeness rules gate one time, at the finish.
+ *
+ * The candidate shares each untouched branch with the input draft. An operation rebuilds only the path to
+ * the edit. Thus the input stays intact, and the memory cost stays small.
+ *
+ * A destination names an anchor, not an index. An index breaks when the tree changes under the agent, and
+ * an anchor id stays stable.
+ */
+import { type Result } from "neverthrow";
+import type { UnresolvedReference } from "../contracts/report-reference.js";
+import { type DraftBlock, type DraftDocument, type DraftSectionBlock } from "./draft.js";
+import type { ReportSnapshot } from "./reference-resolver.js";
+/**
+ * The closed set of refusal reasons. Each operation gives a subset of these.
+ *
+ * `unknown-target` means that no block holds an id that the operation named. `conflicting-destination`
+ * means that the destination named two places at one time. The two are separate because the repair
+ * differs: the first sends the agent to the outline for a correct id, and the second tells it to drop one
+ * of the fields it gave.
+ */
+export type DraftRefusalReason = "malformed-block" | "duplicate-id" | "unknown-target" | "conflicting-destination" | "unresolved-reference" | "cycle" | "atom-at-root" | "not-a-section" | "payload-kind-mismatch";
+/**
+ * A typed refusal. It carries the reason and a prose detail. The `unresolved-reference` reason also
+ * carries each reference that the snapshot does not resolve.
+ */
+export type DraftRefusal = {
+    reason: Exclude<DraftRefusalReason, "unresolved-reference">;
+    detail: string;
+} | {
+    reason: "unresolved-reference";
+    detail: string;
+    unresolved: UnresolvedReference[];
+};
+/** The place inside a parent. The default place is `end`. An anchor names a sibling id. */
+export type DraftPlace = "start" | "end" | {
+    before: string;
+} | {
+    after: string;
+};
+/** The destination of an add or a move. `parentId` names a section, or the root when it is absent. */
+export interface DraftDestination {
+    parentId?: string;
+    place?: DraftPlace;
+}
+/** The add operation value. The payload can be an atom, or a section that carries children. */
+export interface AddOperation {
+    block: unknown;
+    destination?: DraftDestination;
+}
+/**
+ * The change operation value. A `title` retitles a section target. A `block` replaces an atom target.
+ * The operation stamps the target id on the block, thus an id mismatch is unrepresentable.
+ */
+export type ChangeOperation = {
+    targetId: string;
+} & ({
+    title: string;
+} | {
+    block: unknown;
+});
+/** The remove operation value. It names one block by its id. */
+export interface RemoveOperation {
+    targetId: string;
+}
+/** The move operation value. It names one block, and a destination with the shape of the add destination. */
+export interface MoveOperation {
+    targetId: string;
+    destination?: DraftDestination;
+}
+/**
+ * Set the title of the document.
+ *
+ * A title carries no id and no reference, thus it needs none of the shared checks and it cannot refuse.
+ * The document schema requires a non-empty title, and the finish reports an empty one as a gap.
+ */
+export declare function setTitle(draft: DraftDocument, title: string): DraftDocument;
+/**
+ * Add a block at a destination.
+ *
+ * The root admits a section only, thus an atom at the root refuses. The validation covers the payload and
+ * each of its descendants.
+ */
+export declare function addBlock(draft: DraftDocument, operation: AddOperation, snapshot: ReportSnapshot): Result<DraftDocument, DraftRefusal>;
+/**
+ * Change one block by its id.
+ *
+ * A section target takes a title, and its children stay as they are. An atom target takes a full block,
+ * and a kind change is permitted. A payload that does not match the target kind refuses.
+ */
+export declare function changeBlock(draft: DraftDocument, operation: ChangeOperation, snapshot: ReportSnapshot): Result<DraftDocument, DraftRefusal>;
+/**
+ * Remove one block by its id.
+ *
+ * A removed section takes its whole subtree. A removed id is free for a later add.
+ */
+export declare function removeBlock(draft: DraftDocument, operation: RemoveOperation, snapshot: ReportSnapshot): Result<DraftDocument, DraftRefusal>;
+/**
+ * Move one block to a destination.
+ *
+ * The moved block keeps its subtree. A section must not move into its own subtree, thus a move into the
+ * subtree refuses with a cycle. A move with the moved block as its own anchor refuses.
+ */
+export declare function moveBlock(draft: DraftDocument, operation: MoveOperation, snapshot: ReportSnapshot): Result<DraftDocument, DraftRefusal>;
+/** One block, the path of child indices from the root to the block, and the section that holds it. */
+export interface Located {
+    block: DraftBlock;
+    path: number[];
+    /** The section that holds the block, or `undefined` when the block sits at the root. */
+    parent?: DraftSectionBlock;
+}
+/**
+ * Find a block by its id, with the path from the root. The search visits each block one time.
+ *
+ * The read surface needs the same search, thus this is the one find-by-id in the draft model.
+ */
+export declare function locate(document: DraftDocument, id: string): Located | undefined;