♻️ Migrate operational review documents from Show to built-in <If> - #406
Conversation
The review library shipped its own `Show.md` conditional before the engine had one. `<If>` is now a native structural directive, so the seven operational documents that still invoked `Show` duplicated engine behavior and let the review system drift from the documented language. Rename the thirteen conditional blocks in place — `when` becomes `condition`, bodies and whitespace are unchanged — and delete `.reviews/components/Show.md`. None of the conditions had a fallback and every one already evaluates to a boolean, so no `<Else>` branch is introduced and issue #258's possible truthiness change stays independent. Deleting the component and scanning for its tag proves retirement but not behavior, so the review-infrastructure suite now executes the real sources of all seven documents with no `If.md` or `Show.md` in the stub filesystem: the structural name has to win before filesystem component resolution. Compact outputs and every suppressed case are asserted by exact trimmed equality, which locks the summary, table, and section whitespace the tags surround. `ExtraneousCodePolicy.md` carries the provider contract — a counting `Sample` records zero calls below the review threshold and exactly one above it, so the empty case is non-execution rather than a probe that never wired up.
PR #406: ♻️ Migrate operational review documents from Show to built-in11 files, +339 / -64 Scope🟡 403 lines changed. PRs under 400 receive more thorough review. Structural✅ No structural bloat detected. Slop✅ Slop indicators look low. Static Analysis✅ Oxlint found no issues. CorrectnessNo extraneous code patterns detected. |
Integration evidencePR review workflow (required evidence). Run Two of its sections are direct end-to-end proof of the migration:
So the same document supplies both directions of the migrated condition in CI — Local review ( CI: all checks pass — |
Closes #219.
Why
The review library shipped its own
Show.mdconditional before the engine hadone.
<If>is now a native structural directive, so the seven operationalreview documents that still invoked
Showduplicated engine behavior and letthe review system drift from the language its own specification documents.
The release-order blocker recorded in the original issue is gone:
.github/workflows/review.ymlprepares and builds the checked-out revision andruns
./dist/xmd, so no release or workflow change is involved.What changes
Before:
After:
Thirteen blocks across seven documents, renamed in place. Bodies, indentation,
line wrapping and surrounding blank lines are unchanged, and
.reviews/components/Show.mdis deleted.Finding.mdkeeps its publicwhenprop; only its internal element becomes
<If condition={props.when}>.Every migrated condition already evaluates to a boolean and none passed
Show's optionalfallback, so no<Else>branch is introduced and #258'spossible truthiness change stays independent of this PR.
How it works
<If>is native, so it is handled by expansion and never resolved fromcomponentDirs. That is the property the new tests exercise directly: they runthe real operational sources with no
If.mdorShow.mdanywhere in the stubfilesystem.
Review guide
Start with:
scripts/tests/review-infrastructure.test.tsThen review:
.reviews/documents — a pure tag/prop rename.retires the Show component from the review library— the static guard.packages/core/tests/unused-in-diff.test.ts— fixture removal plus an exactoutput assertion.
specs/code-review-agent-spec.md§5.10.Look carefully at: the exact trimmed-equality assertions. They intentionally
lock the blank lines the migrated tags surround, including the five blank lines
OxlintSummary's two suppressed blocks leave behind.What must stay true
Showis gone from the review library — enforced by deletion and checked byretires the Show component from the review library, which walks.reviews/**/*.mdfor an opening or closingShowelement, rejects aShow.mdpath, and scans the focused test and the code-review spec. The guardasserts the walk found
Finding.mdfirst, so it cannot pass vacuously.every operational test, none of which supplies an
IforShowcomponent.skips the ExtraneousCodePolicy sample below the review threshold.packages/core/tests/expression-props.test.tsusesShowas an arbitrary component name and is deliberately untouched.How to verify it
retires the Show component from the review libraryfails if any.reviews/document, the focused test, or the spec still carries
Show.renders Finding's selected icon and message and suppresses its false caseproves exact branch output (
🔴 Broken contract.) and an exactly empty falsecase; it fails on a whitespace change inside the migrated block.
renders OxlintSummary's clean section and its unavailable warningandrenders RepoCleanupPolicy's clean section without running either branchprove the clean-section and warning paths byte-exactly.
suppresses ReleaseSpecWarning for ordinary files and warns on release changesproves both directions of its release-config condition.expands UnusedInDiff and CommentReview to nothing without an If componentproves
CommentReview's typed data component executes (it fetches the PR'scomments) while both captures and both trailing branches stay empty.
skips the ExtraneousCodePolicy sample below the review thresholdinstalls acounting
Sampleprovider: 20 changes make zero calls and render the cleansection, 21 changes make exactly one call and surface the provider result. The
selected control is what keeps the zero-call case from being vacuous.
renders the disclosure with symbol, location, count and reasoninunused-in-diff.test.tsis now exact trimmed equality over the wholedisclosure, so summary/table whitespace is locked.
Each new regression was mutation-checked: reverting
Finding.mdto<Show>(with
Show.mdrestored), reverting the spec example, widening theExtraneousCodePolicythreshold to>= 20, paddingFinding's rendered line,and removing a blank line in
UnusedInDiff's table each fail the intended testand nothing else.
Scope
Included
Show.md.Intentionally unchanged
<If>implementation, syntax, validation, and truthiness semantics (Coerce the <If> condition with JS truthiness #258).specs/executable-mdx-spec.md, which already specifies native<If>/<Else>,filesystem precedence, and selected-branch non-execution.
.github/workflows/review.ymland every other workflow.packages/core/tests/expression-props.test.ts, whereShowis an arbitrarycomponent-resolution fixture rather than a review-library claim.
UnusedInDiff's selected-disclosure and suppression coverage stays in its ownsuite, because it crosses eval,
<Each>, and filesystem fixture boundaries;the infrastructure matrix only uses its empty case.
Generated or mechanical changes
.reviews/documents contain no intended behavior change. The onlycosmetic consequence is in
OxlintSummary.md, whose wrapped condition keepsits authored continuation indentation and therefore no longer aligns under the
longer
condition={prefix.Verification
All required local checks are green on
db78a89:verify:cleanand the full per-runtime suites were not run: this change touchesno dependency state, build purity, test discovery, shared setup, or runtime
adapter. CI owns the exhaustive corpus.
Risks and limitations
deno task review:localrequires a reachable Ollama at
localhost:11434servingqwen3:30b-a3bplusGITHUB_TOKEN; neither is available in thisenvironment. This PR's own
reviewworkflow builds the checked-out source andruns
./dist/xmd, so its marked review comment is the end-to-end evidence andis a merge blocker if it fails, errors, or posts nothing substantive.
Scope confirmation