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

Relationships

#351 Surface type-extraction failures in doctor JSON output

Opened by stack72 · 5/13/2026· Shipped 5/14/2026

Problem

Post-W7 (#342), models with non-literal type fields (e.g. type: TYPE where TYPE is a const) produce stderr warnings via emitTypeExtractionFailure but don't appear in swamp doctor extensions --json output and don't flip the doctor exit code. Users have a silently-broken extension state — the model doesn't register but doctor reports "pass."

Why this exists

W7 removed registries.failures[] which previously surfaced these via the recordLoadFailures → getExtensionLoadWarnings pipeline. The new sourceDetails[] surface derives from the Extension aggregate, but type-extraction failures don't write to the aggregate — they only emit stderr warnings.

Proposed solution

Two implementation options:

  1. New RowState TypeExtractionFailed — route through the aggregate with a catalog state, migration, and aggregate transition. Most consistent with W7's single-surface design.
  2. Add warnings[] field to doctor JSON output — lighter touch, keeps type-extraction warnings as warnings (not failures) but makes them visible in JSON mode and available for exit-code derivation.

Alternatives considered

  • Accept as a known limitation — rejected because it creates a silent UX failure where users think their model is healthy.

Acceptance criteria

  • A model with const TYPE = "@foo/bar"; export const model = { type: TYPE } appears in swamp doctor extensions --json output
  • Doctor exit code reflects the presence of type-extraction failures
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 8 MOREREVIEW+ 3 MOREPR_MERGEDSHIPPED

Shipped

5/14/2026, 2:48:06 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack725/14/2026, 12:59:08 AM
Editable. Press Enter to edit.

stack72 commented 5/14/2026, 11:40:50 AM

Runtime verification — corrected framing

Triage reproduction confirms the extension works correctly at runtime despite the type-extraction warning:

  1. swamp model type search — returns @test/broken-type in results
  2. swamp model method run validate — executes successfully (status: succeeded)
  3. swamp model type describe — returns full schema with methods and arguments

What's actually happening: The static regex-based type extractor in populateCatalogFromDir can't parse non-literal type fields (type: TYPE where TYPE is a const), but the runtime bundler/importer resolves the const correctly. The extension registers, loads, and executes fine. The only gap is a cosmetic stderr warning invisible to JSON consumers.

Design implication: The original framing ('silent UX failure — the model doesn't register but doctor reports pass') overstates the impact. The model DOES register. Doctor correctly reports pass because the extension genuinely works. The proposed Option 1 (new TypeExtractionFailed RowState) would be misleading — it would mark a working extension as failed and produce false-alarm exit codes in CI.

Revised direction: Option 2 (add warnings[] field to doctor JSON output) is the appropriate surface. This treats the type-extraction gap as what it is — a diagnostic warning about a suboptimal-but-working pattern, not a failure. Exit code semantics can be gated separately (e.g., --fail-on-warnings) without conflating with failure-state mechanics.

Sign in to post a ripple.