Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLI
Assigneesstack72

#330 Add `swamp doctor workflows` subcommand to surface workflow YAML parse errors during preflight

Opened by bixu · 5/12/2026· Shipped 5/12/2026

Problem

The existing swamp doctor subcommands cover audit integration health (doctor audit) and extension load health (doctor extensions), but there is no preflight check for workflow YAML files in the repo. Workflows are only validated lazily — when someone runs swamp workflow get <id> or actually executes the workflow.

That gap recently bit us. While iterating on PR #237 in hivemq/hivemq-terraform-harvester, I introduced a workflow with an unquoted CEL ternary expression as a count: value. The colon-space inside the ternary made the file invalid YAML under jsr:@std/yaml, which is what swamp's workflow loader uses. But the broken file slipped through my local validation because:

  • swamp doctor extensions passes — it doesn't touch workflow YAML.
  • swamp doctor audit passes — same.
  • swamp workflow search <name> passes — it matches on the name field but doesn't parse the rest of the body, so a parse error deep in the file goes undetected.
  • The CI yamllint job also missed it (yamllint is style-focused; this case slips past its rule set).

The first time anything flagged the problem was a downstream consumer doing swamp workflow get <id>, which threw the exact jsr:@std/yaml error pointing at the right line and column. swamp had the answer the whole time — it just wasn't surfaced by the obvious "is my repo healthy" command.

Proposed Solution

Add swamp doctor workflows as a peer to doctor audit and doctor extensions. The implementation would:

  • Enumerate every workflow YAML file under the repo's workflow directory (same paths the workflow loader already knows about).
  • Parse each one through the existing workflow loader (the same code path swamp workflow get uses, so the YAML library, schema validation, and CEL-template syntax checks all stay consistent).
  • Report parse failures, schema violations, and any other load-time errors in the same human + --json formats doctor extensions uses today.
  • Exit non-zero when any workflow fails to load, so CI can gate on it.

Affected Components

  • swamp doctor command dispatcher — add the workflows subcommand alongside audit and extensions.
  • Workflow loader / validator — expose the existing parse + validate path for batch use (it likely already returns structured errors).
  • Doctor reporter — reuse the existing pass/fail rendering used by doctor extensions.

High-Level Approach

Mirror the shape of doctor extensions. That command walks the extension directory, calls the extension loader for each entry, collects pass/fail results, and renders them. doctor workflows would do the same against the workflow directory using the workflow loader. No new YAML library or new validation rules are needed — just exposing what workflow get already does, in batch.

Why It Matters

This collapses one of the most common "works on my machine" failure modes for workflow authors. A single swamp doctor invocation should be sufficient to gate a commit; today the workflow surface area is the one gap, and the error message I got from the lazy path was good (clear line + column) — so plumbing it into doctor is mostly mechanical. The cost of catching this at preflight time, especially for fleet-mutating workflows like the emergency kernel-update one I was authoring, is meaningfully lower than catching it during a run.

02Bog Flow
OPENTRIAGEDIN PROGRESSSHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 3 MOREPR_MERGEDSHIPPED

Shipped

5/12/2026, 9:41:32 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack725/12/2026, 8:32:37 PM

Sign in to post a ripple.