Module output_envelope 

Typed envelope structs for the JSON output contract. Live here rather than in fallow-types because the body fields reach into fallow-core and into this crate’s own health_types. Typed envelope structs for the JSON output contract.

Each top-level fallow command (check, dupes, health, audit, explain, coverage setup, plus the bare combined invocation and the CodeClimate / review-envelope side outputs) emits a distinct envelope shape. This module is the schema-side source of truth for those shapes: every type carries Serialize plus a cfg-gated JsonSchema derive so the committed docs/output-schema.json can be regenerated from Rust.

Living in fallow-cli rather than fallow-types because the body fields pull in DuplicationReport (from fallow-core) and HealthReport (from this crate), neither of which is reachable from the lower-level types crate. The shared utility shapes (SchemaVersion, Meta, BaselineDeltas, …) still live in fallow_types::envelope because they depend only on serde primitives.

Runtime construction of these envelopes happens in crates/cli/src/report/json.rs; the JSON layer builds an envelope struct and converts it to a serde_json::Value via serde_json::to_value. The only remaining work on the Value tree is path relativisation (strip_root_prefix) and the cross-result-type suppress-line action harmonizer (harmonize_multi_kind_suppress_line_actions); both span envelope boundaries that typed wrappers do not.

Runtime emit for the CodeClimate, review-envelope, and coverage-setup shapes now flows through the typed structs in this module: crates/cli/src/report/codeclimate.rs constructs CodeClimateIssue directly via cc_issue, crates/cli/src/report/ci/review.rs::render_review_envelope constructs ReviewEnvelopeOutput, and crates/cli/src/coverage/mod.rs::build_setup_envelope constructs CoverageSetupOutput. The wire serde_json::Value is the serde_json::to_value(&envelope) of those typed structs, so adding a field to one of those structs automatically flows to the wire. The AuditOutput and ListBoundariesOutput families remain schema-source-of-truth only (their wire is still hand-built via serde_json::json!); the drift gate keeps them honest.

Structs

AuditOutput

Envelope emitted by fallow audit --format json. Combines dead code, complexity, and duplication scoped to changed files with a verdict (pass / warn / fail), a per-category summary, optional new-vs-inherited attribution, and full sub-results.

BoundariesListLogicalGroup

A pre-expansion autoDiscover logical group surfaced for observability (issue #373). Captured during expand_auto_discover so consumers can see the user-authored parent name and grouping intent after expansion would otherwise flatten it out of BoundariesListing::zones.

BoundariesListRule

A boundary import rule, expanded to operate on concrete child zone names after autoDiscover flattening. The user’s pre-expansion rule (keyed on the logical parent name, if any) is preserved on the corresponding BoundariesListLogicalGroup::authored_rule.

BoundariesListZone

A boundary zone after preset and autoDiscover expansion. Each entry classifies files into a single zone via glob patterns.

BoundariesListing

boundaries block carried by ListBoundariesOutput.

CheckGroupedEntry

Single resolver bucket inside CheckGroupedOutput. Carries the group’s identifier, optional section owners, and a per-group flattened AnalysisResults.

CheckGroupedOutput

Envelope emitted by fallow dead-code --group-by ... --format json.

CheckOutput

Envelope emitted by fallow dead-code --format json (plus the check block inside the combined and audit envelopes).

CodeClimateIssue

Single CodeClimate-compatible issue inside CodeClimateOutput.

CodeClimateLines

lines.begin for CodeClimateLocation.

CodeClimateLocation

Location block inside CodeClimateIssue::location.

CodeClimateOutput

Envelope emitted by fallow --format codeclimate and fallow --format gitlab-codequality. GitLab Code Quality consumes the same shape. The wire form is a bare JSON array, not an object.

CombinedOutput

Envelope emitted by bare fallow --format json (the combined invocation). Wraps the per-analysis sub-results inside a single envelope with the standard schema_version / version / elapsed_ms header.

CoverageAnalyzeOutput

Envelope emitted by fallow coverage analyze --format json.

CoverageSetupFileToEdit

Single file to edit inside CoverageSetupMember::files_to_edit or CoverageSetupOutput::files_to_edit.

CoverageSetupMember

Per-workspace setup recipe inside CoverageSetupOutput::members.

CoverageSetupOutput

Envelope emitted by fallow coverage setup --json. Deterministic agent-readable runtime coverage setup instructions. In workspaces, members carries one entry per detected runtime package; runtime_targets is the union of all member targets.

CoverageSetupSnippet

Single code snippet inside CoverageSetupMember::snippets or CoverageSetupOutput::snippets.

DupesOutput

Envelope emitted by fallow dupes --format json (plus the dupes block inside the combined and audit envelopes).

ExplainOutput

Envelope emitted by fallow explain <issue-type> --format json.

GitHubReviewComment

GitHub pull-request review comment.

GitLabReviewComment

GitLab merge-request discussion comment.

GitLabReviewPosition

position block inside GitLabReviewComment. Mirrors the GitLab merge-request discussion-position API.

HealthOutput

Envelope emitted by fallow health --format json (plus the health block inside the combined and audit envelopes).

ListBoundariesOutput

Envelope emitted by fallow list --boundaries --format json. Surfaces the architecture boundary zones, rules, and (issue #373) the user’s pre-expansion autoDiscover logical groups so consumers can render grouping intent that expand_auto_discover would otherwise flatten out of zones[].

ReviewEnvelopeMeta

meta block inside ReviewEnvelopeOutput.

ReviewEnvelopeOutput

Envelope emitted by fallow --format review-github / review-gitlab. Consumed by action/scripts/review.sh and ci/scripts/review.sh to post inline PR / MR review comments.

ReviewEnvelopeSummary

Summary block on ReviewEnvelopeOutput. Always present on v2 emit; serde(default) keeps schemars from marking it required so a future Deserialize derivation against v1 historical input synthesizes an empty value rather than erroring.

ReviewReconcileOutput

Envelope emitted by fallow ci reconcile-review --format json. Used by CI integrations to drive comment carry-over and stale-comment cleanup across PR / MR revisions.

Enums

AuditCommand

Singleton command discriminator for AuditOutput.

CodeClimateIssueKind

Discriminator value for CodeClimateIssue::kind.

CodeClimateSeverity

CodeClimate severity scale.

CoverageAnalyzeSchemaVersion

Singleton schema-version discriminator for CoverageAnalyzeOutput. Independent from the global SchemaVersion because the runtime coverage envelope versions independently from the rest of the JSON contract.

CoverageSetupFramework

Framework label inside coverage setup output.

CoverageSetupPackageManager

Package manager label inside coverage setup output.

CoverageSetupRuntimeTarget

Runtime target inside coverage setup output.

CoverageSetupSchemaVersion

Singleton schema-version discriminator for CoverageSetupOutput.

FallowOutput

Typed root of every fallow --format json envelope shape that serializes as a JSON object. The schema derived from this enum drives the document-root oneOf in docs/output-schema.json, replacing the previously hand-maintained block.

GitHubReviewSide

Singleton side discriminator for GitHubReviewComment::side.

GitLabReviewPositionType

Singleton position-type discriminator for GitLabReviewPosition.

GroupByMode

Resolver mode label for grouped envelopes (dead-code, dupes, health).

ReviewCheckConclusion

meta.check_conclusion for the GitHub review envelope. Maps to the GitHub Checks API conclusion field.

ReviewComment

Per-line review comment. Schema is an anyOf between GitHub and GitLab shapes; at runtime every entry in a single envelope comes from the same provider because the envelope is built from one provider’s branch in crates/cli/src/report/ci/review.rs::render_review_envelope.

ReviewEnvelopeEvent

Singleton GitHub review-event marker.

ReviewEnvelopeSchema

Schema-version discriminator for the review envelope.

ReviewProvider

Review-envelope provider tag.

ReviewReconcileSchema

Schema-version discriminator for the review reconcile envelope.

Constants

MARKER_REGEX_FLAGS_V2

Canonical v2 marker-regex flags. Paired with MARKER_REGEX_V2.

MARKER_REGEX_V2

Canonical v2 marker-regex literal. Mirrored by MARKER_PREFIX_V2 on the render side; if you change one, change the other and refresh both snapshots. NO (?m) baked into the pattern; consumers pass MARKER_REGEX_FLAGS_V2 as the second arg to their regex engine so the ^ / $ anchors match at line boundaries inside a multi-line comment body. Pairing pattern + flags lets the wire stay compatible with both Rust’s regex crate (via RegexBuilder::multi_line(true)) and JavaScript RegExp (new RegExp(pat, "m")).

Functions

default_marker_regex

Default for ReviewEnvelopeOutput::marker_regex. The canonical regex is stable across the v2 schema. Consumers that hardcode this string instead of reading the field stay correct until a v3 bump.

default_marker_regex_flags

Default for ReviewEnvelopeOutput::marker_regex_flags. Always "m" today; emitted as a sibling field rather than baked into the regex because JavaScript RegExp rejects the standalone (?m) inline flag group with SyntaxError: Invalid regular expression ... Invalid group.

is_false

Helper for skip_serializing_if = "is_false" on truncated fields above. Serde calls skip_serializing_if with &T, so the reference signature is dictated by the trait and cannot be changed to pass-by-value. Uses #[allow] rather than #[expect] per .claude/rules/code-quality.md: trivially_copy_pass_by_ref is a pedantic lint that fires inconsistently across build configurations (lib vs bin), which would trigger unfulfilled_lint_expectations under #[expect].