orchestrator-workflow 0.35.0 → 0.37.0

package/dist/review-report.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Structural schema for the reviewer output contract (the final ```yaml
+ * block in `assets/agents/reviewer.md`, mirrored byte-for-byte in
+ * `assets/skill/references/contracts.md`). This module is the single
+ * hand-maintained copy of that shape in code; `test/docs-consistency.test.ts`
+ * parses the contract block itself and asserts it matches the constants
+ * below exactly, so a contract edit without a matching edit here fails the
+ * suite instead of drifting silently.
+ *
+ * This validator checks structure only. It never judges semantic adequacy,
+ * never waives a finding, and its passing is never orchestrator acceptance.
+ */
+/** Top-level field names, in the contract's own order. */
+export declare const TOP_LEVEL_FIELDS: readonly ["status", "role", "task_id", "summary", "findings", "acceptance_recommendation", "missing_tests", "residual_risks", "reproduction", "method_applied", "withdrawn"];
+/** Field names of one `findings[]` entry, in the contract's own order. */
+export declare const FINDING_FIELDS: readonly ["severity", "category", "description", "suggested_fix", "recurrence", "introduced_by_delta"];
+/** Field names of the `reproduction` object, in the contract's own order. */
+export declare const REPRODUCTION_FIELDS: readonly ["method", "sample_size", "result", "matches_implementer_claim"];
+/** Field names of one `withdrawn[]` entry, in the contract's own order. */
+export declare const WITHDRAWN_FIELDS: readonly ["description", "reason"];
+/**
+ * Enum spellings keyed by their bare field name. Every enum-bearing field
+ * in the contract has a name unique across the whole block, so a flat map
+ * (rather than one keyed by full path) is enough and matches how the
+ * contract text itself reads (`key: a | b | c`).
+ */
+export declare const ENUM_VALUES: Readonly<Record<string, readonly string[]>>;
+export interface Diagnostic {
+    /** Dotted/bracketed location of the offending field, e.g. `findings[0].severity`. */
+    path: string;
+    /** What the schema requires at that path. */
+    expected: string;
+    /** What was actually found (or "missing"). */
+    got: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    diagnostics: Diagnostic[];
+    /** Non-fatal observations, e.g. prose found after the fenced block. */
+    warnings: string[];
+}
+/**
+ * This validator reports structural validity only. It does not judge
+ * semantic adequacy, cannot waive findings, and passing it does not
+ * constitute orchestrator acceptance.
+ */
+export declare const STRUCTURAL_ONLY_NOTE = "Structural check only: this does not judge semantic adequacy, cannot waive findings, and does not constitute orchestrator acceptance.";
+/** Every field name any of the four contract constants declares. */
+export type SchemaFieldName = (typeof TOP_LEVEL_FIELDS)[number] | (typeof FINDING_FIELDS)[number] | (typeof REPRODUCTION_FIELDS)[number] | (typeof WITHDRAWN_FIELDS)[number];
+/**
+ * The structural kind of one contract field: which input classes its
+ * checker accepts and which it rejects. Declared once, next to the
+ * dispatch tables above, and read by both this module (for the `expected`
+ * text a diagnostic carries) and `test/review-report.test.ts`'s case
+ * generator, which derives its whole case list from these kinds rather
+ * than from a hand-enumerated list of checks.
+ *
+ * - `enum`: present, a string, and one of `ENUM_VALUES[field]`.
+ * - `string`: present and a string; the empty string is accepted.
+ * - `non-empty-string`: present, a string, and not blank.
+ * - `scalar`: present and either a string or a number.
+ * - `array`: present and an array; an empty array is accepted, and every
+ *   element must be a string (each non-string element is its own
+ *   diagnostic at `<field>[<index>]`; see {@link checkArrayField}).
+ * - `mapping-list`: `array`, and every element a mapping.
+ * - `mapping`: present and a mapping.
+ *
+ * A new kind is declared here, in {@link KIND_EXPECTED}, and in the
+ * generator's own `Record<FieldKind, ...>` value tables; each of those is
+ * keyed by this type, so a kind with no expectation text or no input
+ * classes is a compile error rather than an untested kind.
+ */
+export type FieldKind = "enum" | "string" | "non-empty-string" | "scalar" | "array" | "mapping-list" | "mapping";
+/**
+ * The declared kind of every field of every contract constant, keyed by
+ * bare field name the way {@link ENUM_VALUES} is: a name is unique across
+ * the whole contract block except for `description`, which `findings[]`
+ * and `withdrawn[]` share with the same kind. The `satisfies
+ * Record<SchemaFieldName, FieldKind>` clause means a name added to any of
+ * the four constants without a kind here is a TypeScript compile error,
+ * the same way it is already an error to add one without a checker in the
+ * dispatch tables above. Were a future contract to reuse one name at two
+ * levels with two different kinds, this flat map could hold only one of
+ * them: the generator asserts each field's real diagnostics against its
+ * declared kind, so that shows up as a failing generated case rather than
+ * as an unchecked field.
+ */
+export declare const FIELD_KINDS: {
+    status: "enum";
+    role: "enum";
+    task_id: "non-empty-string";
+    summary: "array";
+    findings: "mapping-list";
+    acceptance_recommendation: "enum";
+    missing_tests: "array";
+    residual_risks: "array";
+    reproduction: "mapping";
+    method_applied: "enum";
+    withdrawn: "mapping-list";
+    severity: "enum";
+    category: "enum";
+    description: "string";
+    suggested_fix: "string";
+    recurrence: "enum";
+    introduced_by_delta: "enum";
+    method: "scalar";
+    sample_size: "scalar";
+    result: "scalar";
+    matches_implementer_claim: "enum";
+    reason: "string";
+};
+/**
+ * The `expected` text this validator's diagnostics about `field` carry.
+ * The checkers above hold that text literally, at their own push sites;
+ * this is the schema's declaration of the same text, which the generated
+ * test cases assert the checkers actually produce, so a checker whose
+ * behaviour stops matching its declared kind fails a case instead of
+ * drifting quietly.
+ */
+export declare function expectedTextFor(field: SchemaFieldName): string;
+/** The `expected` text a diagnostic about one element of a `mapping-list` carries. */
+export declare const MAPPING_LIST_ELEMENT_EXPECTED: string;
+/** The `expected` text a diagnostic about one non-string element of a plain `array`-kind field (`summary`, `missing_tests`, `residual_risks`) carries. */
+export declare const ARRAY_ELEMENT_EXPECTED: string;
+interface ExtractedYaml {
+    yamlText: string;
+    warnings: string[];
+}
+/**
+ * A reviewer return is commonly wrapped in a single fenced code block.
+ * Strips one leading/trailing fence when present, whatever language tag
+ * it carries (```yaml, ```yml, a bare ``` , or any other tag -- a
+ * language-less fence previously fell through to the "literal YAML"
+ * branch below and produced a confusing YAML parse error instead of a
+ * clean structural diagnostic; fix-round, review finding L2); anything
+ * unfenced is treated as literal YAML. The fence is located anywhere in
+ * the input, not only at its very start: a return prefixed with prose
+ * ("Here is my report:\n```yaml ...") previously fell through to the
+ * "literal YAML" branch, since the fence pattern was anchored to the
+ * start of the string, and produced a raw parse error instead of a
+ * structural diagnostic (fix-round, review finding L1). Prose found
+ * before the opening fence or after the closing fence is tolerated, but
+ * each is named as its own warning rather than silently dropped.
+ *
+ * The opening fence's whole backtick run is captured, and the closing
+ * fence must be a run at least as long, starting at column 0, with
+ * nothing but whitespace after it (CommonMark's own rule): the pattern
+ * backreferences the captured run and anchors it with `^` under the `m`
+ * flag. So a triple-backtick sequence inside a value (a reviewer quoting
+ * a fenced snippet in a `description` block scalar, which YAML
+ * necessarily indents) can no longer close the block early and hand the
+ * parser a truncated document, which surfaced as diagnostics about
+ * fields the return actually carried (fix-round, review finding L3);
+ * and a return a reviewer wrapped in four backticks precisely because
+ * it contains a fence of its own is closed by its own four-backtick run
+ * rather than by that inner one. Matching a fixed three backticks
+ * instead of the run left a longer opener's remaining backticks in the
+ * info string, which read as the tag `` `yaml `` and matched no
+ * yaml/yml fence at all. The OPENING fence keeps its own position
+ * discipline unchanged: it is located anywhere in the input rather than
+ * anchored to a line start.
+ *
+ * Lookarounds on both sides of the run keep it whole, so the opening
+ * run is never re-entered at a shorter length. Without them, an input
+ * whose long backtick run has no valid closer is retried at every
+ * shorter run length from every offset inside the run, each retry
+ * rescanning the lazy body: work quadratic in the run's length, which a
+ * single pasted return of a few hundred backticks already turns into
+ * seconds (CHANGELOG [Unreleased] names the measurement). Keeping the
+ * run whole also makes the "closing run at least as long as the opening
+ * one" rule above literal: an opener longer than any closing run in the
+ * input is no fence at all, where splitting the run instead matched it
+ * and pushed the leftover backticks into the info string. One cost
+ * stays: every backtick run is still tried as an opener candidate, and a
+ * candidate with no qualifying closer scans to the end of the input, so
+ * an input of many runs with no valid closer costs work quadratic in the
+ * number of runs (well under a second at several thousand runs; a
+ * well-formed return is unaffected). Anchoring the opener to a line
+ * start would remove it, at the price of the position-free opener the
+ * paragraph above keeps.
+ *
+ * When the input carries more than one fenced block (a reviewer pasting
+ * a worked example ahead of the real return, say), the FIRST fence whose
+ * info string's first whitespace-delimited word is `yaml` or `yml`
+ * (case-insensitive) is preferred over every earlier fence, tagged or
+ * not; only when none of the fences carries that word does today's
+ * original first-fence behaviour apply. The whole info string is
+ * captured, not only a leading run of letters, so a tag followed by
+ * attributes (` ```yaml title=x `) is still recognised as `yaml` --
+ * previously the capture stopped at the first non-letter and required a
+ * newline right after it, so an attribute-bearing info string matched no
+ * fence at all, tagged or not; this also widens the untagged first-fence
+ * fallback, so an attribute-bearing fence with no yaml/yml word is at
+ * least recognised as a fence. This preference rule is not free of
+ * surprises of its own: a reviewer whose own return is left unfenced and
+ * who then quotes a ```yaml example afterward has that later example
+ * validated instead of their real return, which the emitted warning
+ * names. Preferring a later, differently-positioned fence over
+ * `fences[0]` is itself named as a warning, distinct from the existing
+ * before/after prose warnings; the before-warning is suppressed when the
+ * text preceding the chosen fence consists only of the skipped fence(s)
+ * and whitespace, since calling a legitimate (if unpreferred) fenced
+ * block "prose" alongside the skip warning that already names it is
+ * redundant; real prose ahead of a skipped fence still warns as before.
+ */
+export declare function extractYamlSource(raw: string): ExtractedYaml;
+/**
+ * Validates a reviewer return against the reviewer output contract's
+ * structure. Reports structural validity ONLY: it never judges semantic
+ * adequacy, never waives a finding, and passing it is never orchestrator
+ * acceptance.
+ */
+export declare function validateReviewReport(raw: string): ValidationResult;
+export {};