Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | 2x | // SPDX-FileCopyrightText: 2024-2026 Hack23 AB
// SPDX-License-Identifier: Apache-2.0
/**
* @module Workflows/Types
* @description Shared type definitions for the agentic workflow bounded contexts.
* These types define the contracts between pipeline stages (A → B → C → D → E)
* and the data shapes flowing through the workflow system.
*/
// ─── Data Mode ───────────────────────────────────────────────────────────────
/**
* Declares the level of data availability during a run.
* When EP/IMF/WB data sources are partially unavailable, the manifest records
* a degraded mode so downstream validators can adjust thresholds proportionally.
*/
export type DataMode = 'full' | 'title-only' | 'degraded-imf' | 'degraded-voting' | 'minimal';
/**
* Reduction factors applied to line-floor thresholds per data mode.
* Structural checks (mermaid, WEP, Admiralty, SATs) are never reduced.
*/
export const DATA_MODE_REDUCTION: Readonly<Record<DataMode, number>> = {
full: 1.0,
'title-only': 0.75,
'degraded-imf': 0.85,
'degraded-voting': 0.85,
minimal: 0.65,
};
// ─── Stage Gate Results ──────────────────────────────────────────────────────
/**
* Stage C gate verdict emitted to the `STAGE_C_GATE:` stdout line.
* Downstream tooling parses only `GREEN` (proceed to Stage D) and `RED` (block).
*/
export type StageCVerdict = 'GREEN' | 'RED';
/**
* Full manifest `gateResult` union, as stored in `manifest.history[].gateResult`
* and read back by `src/utils/file-utils.ts#readLatestGateResult`.
*
* **Note:** `RED` is intentionally excluded — Stage C failures are never persisted
* to the manifest history; they are emitted only via the `STAGE_C_GATE:` stdout line
* and surfaced via {@link StageCVerdict}. The manifest records the resolved outcome
* after the gate: GREEN, warnings, analysis-only mode, or still-pending.
*
* - `GREEN` — Stage C passed; article generation proceeds.
* - `GREEN_WITH_WARNINGS` — Stage C passed with non-blocking warnings.
* - `ANALYSIS_ONLY` — Analysis written but article generation skipped.
* - `PENDING` — Default/sentinel before Stage C completes.
*/
export type GateVerdict = 'GREEN' | 'GREEN_WITH_WARNINGS' | 'ANALYSIS_ONLY' | 'PENDING';
/**
* Structured result emitted by the Stage C completeness validator.
* Corresponds to the `STAGE_C_GATE:` output line parsed by downstream tooling.
* The `verdict` field here is narrowed to `StageCVerdict` (GREEN | RED only).
*/
export interface StageGateResult {
/** The final verdict: GREEN (pass) or RED (fail). */
readonly verdict: StageCVerdict;
/** The article type slug resolved from the manifest. */
readonly articleType: string;
/** Total number of mandatory artifacts validated. */
readonly artifactCount: number;
/** Total line count across all validated artifacts (GREEN only). */
readonly totalLines?: number;
/** Count of missing artifacts (RED only). */
readonly missingCount?: number;
/** Count of artifacts below line-floor thresholds (RED only). */
readonly shortCount?: number;
/** Count of artifacts with placeholder markers (RED only). */
readonly placeholderCount?: number;
}
// ─── Validation Issue Severity ───────────────────────────────────────────────
/** Severity level for validation issues detected during Stage C. */
export type IssueSeverity = 'error' | 'warning';
/**
* A single validation issue found in an artifact during Stage C analysis.
*/
export interface ValidationIssue {
/** The artifact-relative path where the issue was found. */
readonly artifactPath: string;
/** Human-readable issue description (e.g. 'mermaid:missing', 'short:42<80'). */
readonly code: string;
/** Whether this issue blocks the gate (error) or is advisory (warning). */
readonly severity: IssueSeverity;
}
// ─── Artifact Validation Result ──────────────────────────────────────────────
/**
* Per-artifact validation result from the completeness gate.
*/
export interface ArtifactValidationResult {
/** Artifact path relative to the run directory. */
readonly relativePath: string;
/** Line count of the artifact file. */
readonly lines: number;
/** Blocking issues that cause a RED gate. */
readonly issues: readonly string[];
/** Non-blocking warnings (advisory only unless --strict). */
readonly warnings: readonly string[];
}
// ─── Pipeline Stage ──────────────────────────────────────────────────────────
/**
* Pipeline stages in the agentic workflow execution model.
* Each unified news-*.md workflow runs stages A → E in sequence.
*/
export type PipelineStage =
| 'A' // Data Collection
| 'B' // Analysis Protocol (2-pass)
| 'C' // Completeness Gate
| 'D' // Article Generation (2-pass)
| 'E'; // PR & Safe Outputs
/**
* Stage metadata recorded in manifest.history[] entries.
* Field names align with {@link AnalysisManifestHistoryEntry} in
* `src/utils/file-utils.ts` — uses `finishedAt` (not `completedAt`) and
* the full {@link GateVerdict} union (not just GREEN | RED).
*/
export interface StageHistoryEntry {
/** Which pipeline stage this entry describes. */
readonly stage: PipelineStage;
/** ISO 8601 timestamp when the stage started. */
readonly startedAt: string;
/** ISO 8601 timestamp when the stage finished (absent if in-progress). */
readonly finishedAt?: string;
/** Stage C gate result (only present for stage C). Full union per manifest spec. */
readonly gateResult?: GateVerdict;
/** Summary text for audit logging. */
readonly summary?: string;
/** Files written during this stage. */
readonly filesWritten?: readonly string[];
}
|