docs(variant): build-system emitter walkthrough + exit-code contract#198
Merged
docs(variant): build-system emitter walkthrough + exit-code contract#198
Conversation
…+ doc clarifications Three followups from the v0.4.3 sexpr audit: 1. `(> (count <scope>) N)` now lowers to a new `CountCompare` expr variant that evaluates the count against the store once and compares to an integer threshold. Previously the audit documented `(count ...)` as "meant for numeric comparisons" but no lowering existed — you could only use it as a standalone predicate (equivalent to `(exists <scope> true)`). Now every comparison operator (>, <, >=, <=, =, !=) accepts a `(count ...)` LHS with an integer RHS. 2. `(matches <field> "<regex>")` validates the regex at lower time instead of silently returning false at runtime on malformed patterns. Closes the "mysterious empty result" footgun the audit flagged — users typing `(matches id "[")` used to see nothing match and spend time debugging; now they get a parse error with the compiler's message. Non-literal patterns (rare; from field interpolation) still use the runtime-lenient path. 3. docs/getting-started.md gains dedicated sections for count comparisons and regex validation, plus a note that dotted accessors like `links.satisfies.target` are not supported — use the purpose-built `linked-by` / `linked-from` / `linked-to` / `links-count` predicates. Closes the doc drift where the filter language's scope was implicit. Regression tests: - count_compare_gt_threshold — basic shape lowers - count_compare_requires_integer_rhs — string on the right errors - count_compare_all_six_operators_lower — all six comparison ops - matches_rejects_invalid_regex_at_lower_time — unclosed brackets produce parse error - matches_accepts_valid_regex — good patterns still work Updated sexpr_fuzz.rs expr_to_sexpr pretty-printer to handle the new Expr::CountCompare variant (fuzz roundtrip stays equivalent). Updated sexpr_predicate_matrix.rs test that pinned the old lenient regex behavior to the new strict behavior. Implements: REQ-004 Refs: DD-058 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
New subcommands on the variant-scoped CLI surface (REQ-046):
rivet variant features --format {json,env,cargo,cmake,cpp-header,bazel,make}
rivet variant value FEATURE (exit 0/1/2 = on/off/unknown)
rivet variant attr FEATURE KEY
Feature attributes are declared on the feature-model YAML under each
feature as a typed key/value map, round-tripped through solve(), and
emitted in the requested format with long namespaced identifiers
(RIVET_FEATURE_*, RIVET_ATTR_*). Every format is loud on constraint
violations — a failing solve exits non-zero with the violation list,
never a partial emission.
Non-scalar attribute values (lists/maps) only serialise through the
JSON formatter; the build-system formatters return Error::Schema rather
than invent a silent flattening convention.
Coverage:
- 11 unit tests in rivet_core::variant_emit::tests (per-format rendering)
- 11 integration tests in rivet-cli/tests/variant_emit.rs (CLI end-to-end,
exit-code contract, loud-on-failure path)
Implements: REQ-046
Refs: DD-050
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds to docs/getting-started.md: - Feature attributes section (typed key/value metadata on each feature) - Build-system emitters table covering all 7 --format values - Worked example per format (Rust/cargo, CMake, C/C++, Bazel, Make, sh, JSON) - value/attr single-feature queries with exit-code contract (0/1/2) Trace: skip
📐 Rivet artifact deltaNo artifact changes in this PR. Code-only changes (renderer, CLI wiring, tests) don't touch the artifact graph. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
⚠️ Performance Alert ⚠️
Possible performance regression was detected for benchmark 'Rivet Criterion Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.
| Benchmark suite | Current: 104f6ca | Previous: 324936a | Ratio |
|---|---|---|---|
link_graph_build/10000 |
30140976 ns/iter (± 4615596) |
24734884 ns/iter (± 1878257) |
1.22 |
This comment was automatically generated by workflow using github-action-benchmark.
avrabe
added a commit
that referenced
this pull request
Apr 23, 2026
* feat(variant): rivet variant explain for debugging solve outcomes Answers "why did my variant pick/skip feature X?" — a dev/debug UX gap called out in the v0.4.3 scope. Two modes: # Full audit: every effective feature + origin, unselected features, # and the constraint list rivet variant explain --model fm.yaml --variant prod.yaml # Single-feature focus: origin, attribute values, and every # constraint that mentions the feature rivet variant explain --model fm.yaml --variant prod.yaml asil-c Each effective feature carries an origin: - `selected` — user listed it under `selects:` - `mandatory` — parent group is mandatory, or is the root - `implied by <X>` — a constraint forced it in once <X> was selected - `allowed` — present but not proven mandatory `--format json` emits a structured audit for scripts (dashboard uses the same shape for the variant sidebar). Coverage: - explain_single_feature_shows_origin_and_attrs (text mode) - explain_single_feature_json_mode - explain_full_variant_audit_lists_origins_and_unselected Docs: new "Debugging" subsection in docs/getting-started.md under the variant management chapter, with an origin table. Implements: REQ-046 Refs: DD-050 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(variant): enrich eu-adas-c example + per-format smoke on realistic model Adds realistic `attributes:` to examples/variant/feature-model.yaml for every market (eu/us/cn with compliance+locale) and every ASIL level (asil-numeric + required analysis techniques). These match the worked examples in docs/getting-started.md so users can run the snippets against the shipped fixture and see the same output. New integration test `every_format_renders_realistic_example` exercises all 7 --format values against the enriched example and asserts each output contains the variant name and the asil-c marker (in whatever casing the format uses). Catches regressions that pass on toy models but break on constraint-driven inclusion, multi-attr features, or non-trivial tree depth. Implements: REQ-046 Refs: DD-050 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(release): v0.4.3 Workspace version bump 0.4.2 → 0.4.3, CHANGELOG entry covering the v0.4.3 changes that have already landed on main: - rivet variant features/value/attr for 7 build systems (#197) - docs: variant emitter walkthrough + exit-code contract (#198) - rivet variant explain for debugging solve outcomes (#199) - test: enrich eu-adas-c example + per-format smoke (#199) - sexpr count-compare + matches parse-time regex (#196) - SCRC Phase 1 clippy restriction lint escalation (#195) - Rivet Delta SVG render for email/mobile (#193) - stamp --missing-provenance filter + warn-skip (#192) v043-artifacts.yaml gains five new entries matching the implementations: - DD-061 build-system emitters are namespaced and loud-on-failure - FEAT-130 rivet variant features/value/attr - FEAT-131 rivet variant explain - DD-062 matches regex + count-compare validated at lower time - FEAT-132 count-compare lowering + matches parse-time regex - FEAT-133 Rivet Delta SVG render for email/mobile - FEAT-134 rivet stamp filter + warn-skip All 41 test binaries green. rivet validate: only pre-existing SPAR aadl-component schema errors remain (unrelated to this release). Implements: REQ-046 Refs: REQ-004, REQ-010, DD-050, DD-058 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
rivet variant features / value / attr).--formatvalues with intended consumer and sample output.value/attrexit-code contract (0/1/2) with a shell-conditional example.Test plan
rivet docs checkpasses (0 violations)Trace: skip
🤖 Generated with Claude Code