Repository navigation
Conversation
ortho_config 0.10.0's derive now defaults the root `synopsis_id` to a generated `<app>-usage` identifier. No catalogue declares `netsuke-usage`, so cargo-orthohelp printed `[missing: netsuke-usage]` into the generated man page instead of the option-listing fallback that the 0.9.0 derive selected via `None`. Clear the root `synopsis_id` in ReleaseHelpCli::try_get_doc_metadata, immediately after replacing `about_id`. The comment records why upstream's `cli-usage` key cannot be substituted: cargo-orthohelp never supplies LocalizationArgs, so a parameterized synopsis cannot format. Extend the identifier guard to collect root and immediate-subcommand `synopsis_id` values, and project the field into the metadata snapshot so both stay pinned at `null`. The guard was verified red (it fails with `got netsuke-usage`) before the fix was restored; all 27 release-help tests pass with it in place. Co-Authored-By: Claude Code <noreply@anthropic.com>
Update the ortho_config 0.9.0 -> 0.10.0 ExecPlan with the Option A repair: clearing the root synopsis_id restores the 0.9.0 option-listing fallback. Record the regenerated cargo-orthohelp 0.10.0 SYNOPSIS evidence (no `[missing:` marker, #958 placeholders retained), the guard and snapshot coverage, and the retraction of the PR #953 "pre-existing" classification. Option B stays a follow-up after #958, and a parameterized synopsis stays blocked on leynos/ortho-config#630. Document the root synopsis convention and the LocalizationArgs limitation in the developers' guide. Co-Authored-By: Claude Code <noreply@anthropic.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review.
|
| Layer / File(s) | Summary |
|---|---|
Root synopsis fallback and coverage src/cli/release_help/mod.rs, src/cli/release_help/metadata_tests.rs, tests/ortho_config_metadata_snapshot_tests.rs |
try_get_doc_metadata clears the root synopsis_id. Identifier checks now include root and immediate-subcommand synopsis IDs. Metadata snapshots include top-level and subcommand synopsis IDs. |
Repair record docs/developers-guide.md, docs/execplans/issue-951-migrate-from-ortho-config-v0-9-0-to-v0-10-0.md |
The documentation records the fallback repair, its verification, and remaining limitations, including the parameterised synopsis dependency on upstream issue #630. |
Possibly related PRs
- leynos/netsuke#953: Records the OrthoConfig 0.10.0 migration associated with the generated root synopsis identifier fixed here.
Suggested labels: Issue
Suggested reviewers: codescene-access
Change: Bug fix · Severity of issue fixed: Medium
Merge Risk: 
Low · previous review 147d0
-
Man-page output is repaired, but PowerShell users lose the root command synopsis. The change is otherwise mergeable with bounded follow-up.
Caution
Pre-merge checks failed
Please resolve all errors before merging. Addressing warnings is optional.
- Ignore

Passed checks: 12 passed
-
Full details: Linked Issues check
-
Explanation
Linked issue
#959is the only active direct target. Its coding requirements are met by the reviewable changes.[
#959] Objective 1: clear the root synopsis_id so cargo-orthohelp uses its option-listing fallback. Implemented in src/cli/release_help/mod.rs (+15 lines). The assignment sets synopsis_id to None after the about_id replacement in ReleaseHelpCli::try_get_doc_metadata. This matches Option A in the issue. The fallback selection follows the issue's analysis of cargo-orthohelp's synopsis_section. The author reports a real cargo-orthohelp 0.10.0 run with no [missing: marker. This assessment did not independently verify that generated output.[
#959] Objective 2: extend the identifier guard to synopsis_id. Implemented in src/cli/release_help/metadata_tests.rs (+16/-12). The guard now collects root and immediate-subcommand synopsis_id values. It applies the existing generated-shape, cli. prefix, and catalogue-resolution checks to them. The author reports the guard fails when the assignment is removed.[
#959] Objective 3: pin synopsis identifiers in the metadata snapshot so a future derive default fails the test. The test source in tests/ortho_config_metadata_snapshot_tests.rs (+4) adds the values. The snapshot file tests/snapshots/ortho_config_metadata_snapshot_tests__release_help_documentation_metadata_is_stable.snap is in ignored_files, so its contents were not inspected. The issue does not state the snapshot pin as a separate requirement, so this does not change the verdict.[
#959] Correction of the PR#953'Out of scope' classification. The developers' guide and the migration execution plan now state that the migration introduced the regression and that the separate#959change repairs it. This is documentation, and it is included.Not required by
#959: Option B (curated cli.synopsis key in all catalogues), the value placeholders in#958, the flag-surface issue#960, and upstream ortho-config#630. The PR correctly leaves these as follow-ups.
Full details: Out of Scope Changes check
-
Explanation
All changed paths connect to
#959or its documented correction.- src/cli/release_help/mod.rs: the root synopsis_id clearing. This is the core repair.
- src/cli/release_help/metadata_tests.rs: the guard extension to synopsis_id. This is the regression guard requested by
#959. - tests/ortho_config_metadata_snapshot_tests.rs: adds synopsis_id values to the metadata snapshot. This supports the guard.
- tests/snapshots/...release_help_documentation_metadata_is_stable.snap: excluded by ignored_files. Its contents were not inspected. It is the expected output of the snapshot test above.
- docs/developers-guide.md (+17/-2): documents the repair, why cli-usage is unsuitable, and the guard coverage. This supports the change.
- docs/execplans/issue-951-migrate-from-ortho-config-v0-9-0-to-v0-10-0.md (+95/-26): records the
#959repair, the residual gaps, and the ownership correction that#959requests. The text on same-tree man-page comparison supports the verification account.
No catalogue, localization key, or unrelated source change appears in the summary. The PR does not add Option B. It does not change the
#958placeholder behaviour. No unrelated change was found.
Full details: Docstring Coverage
-
Explanation
Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 2 functions across 3 files. (2 skipped: 2 unsupported.)
Full details: Testing (Overall)
-
Explanation
Pass the testing check. The behavioural change at
src/cli/release_help/mod.rs:37-50is guarded by two meaningful tests.release_help_identifiers_are_netsuke_declared_not_generatednow inspects root and subcommandsynopsis_idvalues and rejects generated or unresolved identifiers (src/cli/release_help/metadata_tests.rs:317-353). The metadata snapshot records the required rootsynopsis_id: ~and subcommand values (tests/snapshots/ortho_config_metadata_snapshot_tests__release_help_documentation_metadata_is_stable.snap:12,237-251). Removing the assignment would produce the generated root identifier and fail these assertions. The tests verify Netsuke's metadata contract; they do not rely on a test of third-partycargo-orthohelpinternals.
Full details: Developer Documentation
-
Explanation
Pass. Document the changed release-help metadata behaviour in
docs/developers-guide.md:3731-3743, including thesynopsis_idfallback, thecli-usagelimitation, the catalogue requirement, and the regression guards. Update the existing COMPLETE execplan with the repair, verification evidence, residual follow-ups, and revision history. Keep the existing architecture boundary unchanged. No new execplan, roadmap completion, or translated developer-guide variant requires further documentation.
Full details: Testing (Property / Proof)
-
Explanation
Keep the existing unit and snapshot tests. The introduced invariant applies to a fixed release-help metadata shape: one root and five immediate subcommands. The identifier test iterates the collected identifiers, and the snapshot records root and subcommand
synopsis_idvalues asnull(src/cli/release_help/metadata_tests.rs:299-355;tests/snapshots/ortho_config_metadata_snapshot_tests__release_help_documentation_metadata_is_stable.snap). The change introduces no broad input range, state space, ordering space, transition, or proof assumption that needs a property test or exhaustive proof.
Full details: Testing (Compile-Time / Ui)
-
Explanation
Pass the testing check. The change is runtime metadata composition, not a compile-time diagnostic or macro implementation, so a trybuild test is not required. The focused identifier test now includes root and immediate-subcommand
synopsis_idvalues and fails on generated or unresolved keys (src/cli/release_help/metadata_tests.rs:299-355). The stable YAML snapshot records the root and subcommand synopsis values asnull(tests/ortho_config_metadata_snapshot_tests.rs:22-148; snapshot lines 12 and 267-279). This is a meaningful, stable expectation for the structured IR consumed bycargo-orthohelp, with no floating values or secrets.
Full details: Unit Architecture
-
Explanation
Pass the Unit Architecture check. In
src/cli/release_help/mod.rs:36-54, the change clearssynopsis_idon the locally assembledDocMetadata; it does not write external state or add a side-effecting dependency. The existing fallible assembly remains explicit throughResult, and the existing boundary handles the error. The metadata and snapshot changes only read and record returned values (src/cli/release_help/metadata_tests.rs:318-355,tests/ortho_config_metadata_snapshot_tests.rs:75-148). No command, query, dependency, or responsibility boundary becomes less visible.
Full details: Domain Architecture
-
Explanation
Pass. The change stays within
src/cli/release_help, which is explicitly an adapter forcargo-orthohelp. It translates generatedDocMetadatabefore the external help generator consumes it; it does not add transport, storage, filesystem, or vendor concerns to domain logic. The only behaviour change clears the rootsynopsis_idand preserves the existing metadata composition. The remaining changes update adapter-focused tests, snapshots, and documentation.
Full details: Observability
-
Explanation
Pass the observability check. The pull request changes release-help metadata and generated man-page output only:
ReleaseHelpCli::try_get_doc_metadataclearssynopsis_id, and tests pin the resulting metadata. This is build-time documentation behaviour, not a production operation, process boundary, throughput path, or runtime failure mode. No logging, metrics, tracing, or alert is required by this check.
-
Full details: Module-Level Documentation
-
Explanation
Update the module-level documentation for
src/cli/release_help/metadata_tests.rs. The module still says only “Unit tests for parser-only release-help metadata composition” at line 1, but this PR expands it to test root and subcommandsynopsis_idvalues, identifier catalogue resolution, andReleaseHelpClimetadata. The existing text does not explain the module’s full purpose, utility, or its relationship to the release-help localizer andcargo-orthohelp. The parentrelease_helpmodule and the integration snapshot module have adequate documentation.Resolution
Replace the
metadata_tests.rsmodule docstring with a concise description of the complete release-help metadata contract. State that the tests validate configuration and parser metadata, root and subcommand documentation identifiers, and resolution through Netsuke’s Fluent catalogues beforecargo-orthohelpconsumes the metadata.
Full details: Testing (Unit And Behavioural)
-
Explanation
The PR adds metadata unit and snapshot coverage, but it does not add a behavioural test for the changed man-page boundary.
src/cli/release_help/metadata_tests.rschecks identifiers andtests/ortho_config_metadata_snapshot_tests.rspinssynopsis_id: null, but neither invokescargo-orthohelpnor verifies the generated SYNOPSIS. The existinggenerates_manual_page_for_non_windows_targettest uses a fake generator whose man-page fixture hard-codes[OPTIONS]and ignoressynopsis_id, so it would pass if[missing: netsuke-usage]returned.Resolution
Add a release-help behavioural test that propagates the serialised root
synopsis_idinto the generator fixture and asserts that the generated man page contains the fallback SYNOPSIS and no[missing:marker. Prefer an integration run with the supportedcargo-orthohelpwhen the test environment provides it; otherwise make the existing script-boundary fixture inspectsynopsis_idand emit the unresolved marker for non-null IDs so the test fails if the regression returns. Keep the metadata snapshot and identifier guard as invariant coverage.
Full details: User-Facing Documentation
-
Explanation
The pull request changes a user-facing release artefact:
ReleaseHelpCli::try_get_doc_metadataclears the rootsynopsis_id, which changes the published manual page from[missing: netsuke-usage]to the option-listing synopsis (src/cli/release_help/mod.rs:31-49). The pull request documents the implementation indocs/developers-guide.md:3731-3743, but it does not changedocs/users-guide.md. The user's guide only gives the general CLI shape and option list (docs/users-guide.md:1018-1073) and does not clearly document the restored release-manual synopsis behaviour.Resolution
Update
docs/users-guide.mdin the command-line interface section. Document the release manual's restored option-listing SYNOPSIS and the supported top-level command shape. Keep implementation details aboutsynopsis_id, catalogue keys, andLocalizationArgsin the developers' guide.
Clear the root key.
Let option listings appear.
Check each synopsis ID.
Keep the snapshot in step.
Leave the placeholders downstream.
Reviewer's GuideThe PR fixes the ortho_config 0.10.0 regression that emitted Sequence diagram for release help synopsis fallbacksequenceDiagram
participant ReleaseHelpCli
participant CliConfig
participant CargoOrthohelp
participant ManPage
ReleaseHelpCli->>CliConfig: get_doc_metadata()
CliConfig-->>ReleaseHelpCli: DocMetadata with derived synopsis_id
ReleaseHelpCli->>ReleaseHelpCli: try_get_doc_metadata()
ReleaseHelpCli->>CargoOrthohelp: synopsis_id = None
CargoOrthohelp->>CargoOrthohelp: render option-listing fallback
CargoOrthohelp-->>ManPage: SYNOPSIS without missing marker
Flow diagram for synopsis identifier regression guardflowchart LR
Metadata["Release-help metadata"] --> Collect["Collect root and immediate-subcommand synopsis_id"]
Collect --> Validate["Validate identifiers against Netsuke catalogues"]
Validate --> Snapshot["Pin synopsis_id in metadata snapshot"]
Snapshot --> Detect["Detect a future derived identifier such as netsuke-usage"]
File-Level Changes
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
@sourcery-ai guide |
|
@coderabbitai please assess the implementation in this PR for completeness and correctness against the original issue: |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain
Correctness and completeness
Immediate-subcommand coverage is sufficient for the current adapter: Documentation clarificationIn
Use wording that distinguishes delivery scope from regression ownership:
The plan already retracts the false “pre-existing” classification. Remove this remaining ambiguity to match the original issue’s requested correction. Treat this as a documentation issue, not a runtime blocker. Verification boundaryThe current check results show successful CI and Linux, macOS, and Windows release builds. The release log also confirms that I did not execute repository code or independently inspect the generated manual-page contents. The recorded red/green guard test and marker-free SYNOPSIS remain author-supplied evidence. For final artefact verification, inspect the dry-run manual page and confirm both a populated SYNOPSIS and no Keep Option B as a follow-up. Do not block this corrective on upstream You are interacting with an AI system. |
Rewrite the remaining "Out of this migration's scope" sentence in the Surprises and discoveries entry. The migration delivered the [missing: netsuke-usage] SYNOPSIS regression, while the repair belongs to the separate #959 corrective PR. Stating both facts removes the last trace of the retracted pre-existing classification. Record the correction as the tenth revision. Co-Authored-By: Claude Code <noreply@anthropic.com>
|
@coderabbitai Has the documentation clarification you requested now been Original assessment: Requested change: in Repair: commit Validation on the published tree: Assessment-ID: 959-doc-clarification-147d08aa4. Please echo the Assessment-ID and assessed head in your substantive reply, and |
|
Tip For best results, initiate chat on the files or code changes. Analysis chain
I inspected At Line 478–482, the entry states that the migration introduced the regression and that the separate At Line 1617–1622, the tenth revision note records the clarification and explains why the previous wording was ambiguous. No further change is required for this documentation request. The earlier Option A correctness assessment remains unchanged. This focused check does not independently verify the reported test results, CI results, or generated manual-page contents. You are interacting with an AI system. |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
The account paying for this security review has reached its Codex usage limits. The payer can check the Codex usage dashboard. For personal accounts, using credits requires enabling “Use credits for security reviews” in Code review settings. If you do not manage the paying account, contact this repository's admins. |
Drive the release-help generation script with a fake cargo-orthohelp that models the generator's synopsis resolution: a set root synopsis_id renders `[missing: <id>]`, while an absent one renders the option listing. The positive case serialises the metadata Netsuke actually emits, so restoring the derived `netsuke-usage` identifier of #959 fails on the generated page and not only in the metadata unit tests. A second case injects the identifier to prove the artefact assertion can fail. Refresh the metadata_tests module docstring to describe the complete release-help metadata contract, and add the new integration test crate to the Whitaker ambient-filesystem exemption list alongside the other script-level test crates. Co-Authored-By: Claude Code <noreply@anthropic.com>
|
@coderabbitai Pre-merge reconciliation of the three failed rows reported on Assessment-ID: 959-premerge-reconciliation-2d7ccb353500faa6b868f1fd1ed9e66b85829a74
Please confirm these three dispositions on |
|
Tip For best results, initiate chat on the files or code changes. Analysis chain
GitHub and the inspected checkout both report the assessed head. 1. Module-Level Documentation — addressedAccept the revised module documentation in 2. Testing (Unit And Behavioural) — remedy implementedAccept the script-boundary alternative offered in the original finding. In
This supplies the requested regression-sensitive fixture and negative control. It does not test the real 3. User-Facing Documentation — withdraw the warningKeep The guide already documents The repair restores documented behaviour. It does not introduce a new user-facing contract. I found no specific inaccuracy in those passages that requires this PR to change them. The earlier warning imposed an unnecessary documentation requirement. Remaining verificationNo source-level finding remains unresolved among these three rows. Do not treat this reply as a refreshed pre-merge gate result. I did not execute repository tests or inspect a real generated release manual. At inspection time, This reply neither changes the saved gate nor submits PR approval. You are interacting with an AI system. |
|
@coderabbitai approve Published head: The latest completed review round raised no actionable comments. Its three
Pre-merge checks: your saved gate has not re-evaluated since that reply, so the Final-artefact check you asked us to retain, now performed on the real release
CI: all applicable checks on this head have completed — CI, Release Dry Run, Rebase/stack state: base is Please approve if those findings are resolved. If approval remains blocked, |
|
@pandalump The three source-level findings remain reconciled on Your reported CI and final-artefact checks address the remaining verification requests. I have not independently verified those results in this reply. Use the approval workflow to check current permissions and review readiness. The workflow will report whether approval succeeds or identify the remaining blocker. Action performed
|
Summary
Restores the man page SYNOPSIS that
ortho_config0.10.0's derive changesuppressed.
ortho_config_macros0.10.0 now defaults a derived rootsynopsis_idtoSome("<app>-usage"); 0.9.0 emittedNone. No catalogue declaresnetsuke-usage, andcargo-orthohelpprints the unresolved id, so thepublished page carried:
ReleaseHelpCli::try_get_doc_metadatanow clears the rootsynopsis_idafter replacing
about_id.Noneselectscargo-orthohelp'soption-listing fallback, restoring the 0.9.0 rendering with no catalogue
cost, and the regenerated page contains no
[missing:marker.Upstream's
cli-usagecannot be substituted:cargo-orthohelpresolves asynopsis without ever supplying
LocalizationArgs, so a parameterized keycannot format. A curated synopsis must be a variable-free key declared in
src/localization/keys.rsand present in every catalogue.The identifier guard now collects root and immediate-subcommand
synopsis_idvalues, and the metadata snapshot pins them atnull, so afuture derive default cannot reintroduce the placeholder silently.
This also retracts PR #953's "Out of scope / pre-existing" classification:
git grep netsuke-usagecould never find the identifier because the derivegenerates it.
Closes #959.
Verification
release help should name a netsuke-declared key, got netsuke-usage; withit restored all 27
release_helptests pass.cargo-orthohelp0.10.0 run:scripts/generate-release-help.sh x86_64-unknown-linux-gnu netsuke ...produces a SYNOPSIS from thefallback with no
[missing:marker. TheUSIZE/LIST/UTF8PATHBUFplaceholders from Declare cli value_name so generated help stops showing UTF8PATHBUF and USIZE placeholders #958 remain, as expected of the fallback.
make check-fmt,make markdownlint,make nixie,make lint,make doc-coverage,make test,make test-workflow-contracts: allgreen.
coderabbit review --agent: 0 findings across the changed files.Follow-ups
cli.synopsiskey in all 35catalogues) remains a follow-up after Declare cli value_name so generated help stops showing UTF8PATHBUF and USIZE placeholders #958.
leynos/ortho-config#630.
References
🤖 Generated with Claude Code
Summary by Sourcery
Restore the release-help man page's option-listing SYNOPSIS and strengthen metadata safeguards against unresolved derived identifiers.
Bug Fixes:
netsuke-usagemarker.Enhancements:
Documentation:
Tests: