Skip to content

Restore the man page SYNOPSIS fallback suppressed by ortho_config 0.10.0 (#959) - #1043

Merged
leynos merged 4 commits into
mainfrom
issue-959-fix-the-man-page-synopsis-showing-missing-netsuke-usage-a-0-10-0-derive-regression
Oct 31, 2026
Merged

leynos merged 4 commits into
mainfrom
issue-959-fix-the-man-page-synopsis-showing-missing-netsuke-usage-a-0-10-0-derive-regression

Conversation

@leynos

@leynos leynos commented Oct 30, 2026 •

Copy link
Copy Markdown
Owner

Summary

Restores the man page SYNOPSIS that ortho_config 0.10.0's derive change
suppressed.

ortho_config_macros 0.10.0 now defaults a derived root synopsis_id to
Some("<app>-usage"); 0.9.0 emitted None. No catalogue declares
netsuke-usage, and cargo-orthohelp prints the unresolved id, so the
published page carried:

.SH SYNOPSIS
.B netsuke
[missing: netsuke-usage]

ReleaseHelpCli::try_get_doc_metadata now clears the root synopsis_id
after replacing about_id. None selects cargo-orthohelp's
option-listing fallback, restoring the 0.9.0 rendering with no catalogue
cost, and the regenerated page contains no [missing: marker.

Upstream's cli-usage cannot be substituted: cargo-orthohelp resolves a
synopsis without ever supplying LocalizationArgs, so a parameterized key
cannot format. A curated synopsis must be a variable-free key declared in
src/localization/keys.rs and present in every catalogue.

The identifier guard now collects root and immediate-subcommand
synopsis_id values, and the metadata snapshot pins them at null, so a
future derive default cannot reintroduce the placeholder silently.

This also retracts PR #953's "Out of scope / pre-existing" classification:
git grep netsuke-usage could never find the identifier because the derive
generates it.

Closes #959.

Verification

  • Guard verified red then green: with the assignment removed it fails with
    release help should name a netsuke-declared key, got netsuke-usage; with
    it restored all 27 release_help tests pass.
  • Real cargo-orthohelp 0.10.0 run: scripts/generate-release-help.sh x86_64-unknown-linux-gnu netsuke ... produces a SYNOPSIS from the
    fallback with no [missing: marker. The USIZE/LIST/UTF8PATHBUF
    placeholders 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: all
    green.
  • coderabbit review --agent: 0 findings across the changed files.

Follow-ups

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:

  • Restore the generated man page SYNOPSIS by using the option-listing fallback instead of emitting an unresolved netsuke-usage marker.
  • Prevent future derived synopsis identifiers from silently reintroducing missing localization references.

Enhancements:

  • Expand release-help metadata validation and snapshots to cover root and subcommand synopsis identifiers.

Documentation:

  • Document the synopsis regression, its fallback-based resolution, and the remaining curated-synopsis follow-up.

Tests:

  • Add behavioral coverage for the generated SYNOPSIS fallback and unresolved-identifier control case.

leynos and others added 2 commits October 30, 2026 17:49
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>
@coderabbitai

coderabbitai Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Note

Reviews paused

It 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 reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • Resume reviews
  • Trigger review

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Team
  • Run ID: 82cce1d2-1a1b-4c6b-8af5-37adaf72972f
Commits

Reviewing files that changed from the base of the PR and between 7929a3f and 147d08a.

Files ignored due to path filters: 1
  • tests/snapshots/ortho_config_metadata_snapshot_tests__release_help_documentation_metadata_is_stable.snap is excluded by !**/*.snap
Files selected for processing: 5
  • docs/developers-guide.md
  • docs/execplans/issue-951-migrate-from-ortho-config-v0-9-0-to-v0-10-0.md
  • src/cli/release_help/metadata_tests.rs
  • src/cli/release_help/mod.rs
  • tests/ortho_config_metadata_snapshot_tests.rs
Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Summary

  • Restore the release-help synopsis fallback by clearing the root synopsis_id in ReleaseHelpCli::try_get_doc_metadata.
  • Extend the release-help identifier guard and metadata snapshot to include root and immediate-subcommand synopsis IDs.
  • Document that the ortho_config 0.10.0 migration introduced the regression and that a parameterized synopsis remains blocked on ortho-config#630.
  • Update the migration execution plan with the repair and its verification context.

This addresses issue #959. The fallback’s value placeholders remain outside this change.

Walkthrough

The root release-help metadata now clears synopsis_id, so synopsis generation uses the option-listing fallback. Identifier checks and metadata snapshots cover synopsis IDs. The developer guide and migration execution plan record the repair and its remaining limitations.

Changes

Release-help synopsis repair

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

Failed Failed checks: 2 errors · 1 warning

Check name Status Explanation Resolution
Module-Level Documentation Error 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 exp… Replace the metadata_tests.rs module 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 …
Testing (Unit And Behavioural) Error 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.rs checks identifiers and `tests/ortho_… Add a release-help behavioural test that propagates the serialised root synopsis_id into the generator fixture and asserts that the generated man page contains the fallback SYNOPSIS and no [missing: marker. Prefer an integration run wit…
User-Facing Documentation Warning The pull request changes a user-facing release artefact: ReleaseHelpCli::try_get_doc_metadata clears the root synopsis_id, which changes the published manual page from [missing: netsuke-usage] t… Update docs/users-guide.md in the command-line interface section. Document the release manual's restored option-listing SYNOPSIS and the supported top-level command shape. Keep implementation details about synopsis_id, catalogue keys, a…
Passed Passed checks: 12 passed
Check name Status Explanation
Title check Passed Accept the title. It accurately describes the SYNOPSIS fallback repair and references issue #959 as required.
Description check Passed Accept the description. It directly explains the root synopsis fix, regression guard, tests, and remaining follow-ups.
Linked Issues check Passed Linked issue #959 is 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-listin…
Out of Scope Changes check Passed All changed paths connect to #959 or 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 gu…
Docstring Coverage Passed 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. Documentat…
Testing (Overall) Passed Pass the testing check. The behavioural change at src/cli/release_help/mod.rs:37-50 is guarded by two meaningful tests. release_help_identifiers_are_netsuke_declared_not_generated now inspects roo…
Developer Documentation Passed Pass. Document the changed release-help metadata behaviour in docs/developers-guide.md:3731-3743, including the synopsis_id fallback, the cli-usage limitation, the catalogue requirement, and the…
Testing (Property / Proof) Passed 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 …
Testing (Compile-Time / Ui) Passed 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 …
Unit Architecture Passed Pass the Unit Architecture check. In src/cli/release_help/mod.rs:36-54, the change clears synopsis_id on the locally assembled DocMetadata; it does not write external state or add a side-effecti…
Domain Architecture Passed Pass. The change stays within src/cli/release_help, which is explicitly an adapter for cargo-orthohelp. It translates generated DocMetadata before the external help generator consumes it; it doe…
Observability Passed Pass the observability check. The pull request changes release-help metadata and generated man-page output only: ReleaseHelpCli::try_get_doc_metadata clears synopsis_id, and tests pin the resultin…
Full details: Linked Issues check

Explanation

Linked issue #959 is 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 #959 change 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 #959 or 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 #959 repair, the residual gaps, and the ownership correction that #959 requests. 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 #958 placeholder 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-50 is guarded by two meaningful tests. release_help_identifiers_are_netsuke_declared_not_generated now inspects root and subcommand synopsis_id values and rejects generated or unresolved identifiers (src/cli/release_help/metadata_tests.rs:317-353). The metadata snapshot records the required root synopsis_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-party cargo-orthohelp internals.

Full details: Developer Documentation

Explanation

Pass. Document the changed release-help metadata behaviour in docs/developers-guide.md:3731-3743, including the synopsis_id fallback, the cli-usage limitation, 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_id values as null (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_id values 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 as null (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 by cargo-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 clears synopsis_id on the locally assembled DocMetadata; it does not write external state or add a side-effecting dependency. The existing fallible assembly remains explicit through Result, 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 for cargo-orthohelp. It translates generated DocMetadata before 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 root synopsis_id and 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_metadata clears synopsis_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 subcommand synopsis_id values, identifier catalogue resolution, and ReleaseHelpCli metadata. The existing text does not explain the module’s full purpose, utility, or its relationship to the release-help localizer and cargo-orthohelp. The parent release_help module and the integration snapshot module have adequate documentation.

Resolution

Replace the metadata_tests.rs module 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 before cargo-orthohelp consumes 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.rs checks identifiers and tests/ortho_config_metadata_snapshot_tests.rs pins synopsis_id: null, but neither invokes cargo-orthohelp nor verifies the generated SYNOPSIS. The existing generates_manual_page_for_non_windows_target test uses a fake generator whose man-page fixture hard-codes [OPTIONS] and ignores synopsis_id, so it would pass if [missing: netsuke-usage] returned.

Resolution

Add a release-help behavioural test that propagates the serialised root synopsis_id into the generator fixture and asserts that the generated man page contains the fallback SYNOPSIS and no [missing: marker. Prefer an integration run with the supported cargo-orthohelp when the test environment provides it; otherwise make the existing script-boundary fixture inspect synopsis_id and 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_metadata clears the root synopsis_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 in docs/developers-guide.md:3731-3743, but it does not change docs/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.md in the command-line interface section. Document the release manual's restored option-listing SYNOPSIS and the supported top-level command shape. Keep implementation details about synopsis_id, catalogue keys, and LocalizationArgs in the developers' guide.

Clear the root key.
Let option listings appear.
Check each synopsis ID.
Keep the snapshot in step.
Leave the placeholders downstream.

codescene-access[bot]

This comment was marked as outdated.

@sourcery-ai

sourcery-ai Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Reviewer's Guide

The PR fixes the ortho_config 0.10.0 regression that emitted [missing: netsuke-usage] by clearing the root synopsis identifier so cargo-orthohelp uses its option-listing fallback, and adds identifier validation plus metadata snapshot coverage to prevent a future derive default from silently reintroducing the placeholder. Documentation and migration records explain the fallback, localization constraints, and remaining upstream/curated-synopsis follow-ups.

Sequence diagram for release help synopsis fallback

sequenceDiagram
    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
Loading

Flow diagram for synopsis identifier regression guard

flowchart 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"]
Loading

File-Level Changes

Change Details Files
Restore the generated man page’s SYNOPSIS fallback by explicitly removing the derived root synopsis identifier.
  • Set root synopsis_id to None after replacing about_id.
  • Document why cli-usage cannot be used and why a curated synopsis remains a follow-up.
src/cli/release_help/mod.rs
docs/developers-guide.md
docs/execplans/issue-951-migrate-from-ortho-config-v0-9-0-to-v0-10-0.md
Expand regression checks to detect generated synopsis identifiers before they can reach published documentation.
  • Validate root and immediate-subcommand synopsis_id values alongside existing help and about identifiers.
  • Snapshot root and subcommand synopsis metadata, pinning the repaired root value to null.
src/cli/release_help/metadata_tests.rs
tests/ortho_config_metadata_snapshot_tests.rs
tests/snapshots/ortho_config_metadata_snapshot_tests__release_help_documentation_metadata_is_stable.snap

Possibly linked issues


Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@leynos

leynos commented Oct 30, 2026

Copy link
Copy Markdown
Owner Author

@sourcery-ai guide

@leynos

leynos commented Oct 30, 2026

Copy link
Copy Markdown
Owner Author

@coderabbitai please assess the implementation in this PR for completeness and correctness against the original issue:

## Correction to PR #953's "Out of scope" note

PR #953 lists this under **Out of scope** as pre-existing, on this reasoning:

> `git grep netsuke-usage 88f20d588` finds nothing, so it predates this work.

**That inference is wrong, and the classification should be retracted.** The
identifier is never written to source: `ortho_config_macros` *generates* it at
derive time, so `git grep` cannot find it in either version. The migration
introduced it.

An A/B probe with byte-identical source, differing only in the
`ortho_config` dependency version, settles it:

```text
0.9.0  -> synopsis_id = None
0.10.0 -> synopsis_id = Some("probe-usage")
```

The cause is a 0.10.0 derive change. `ortho_config_macros-0.10.0`
`src/derive/generate/docs/sections.rs:61`:

```rust
pub(super) fn synopsis_id_tokens(doc: &DocStructAttrs, krate: &TokenStream) -> TokenStream {
    doc.synopsis_id.as_deref().map_or_else(
        || quote! { Some(#krate::message_id_for(command_path, "usage")) },
        |synopsis_id| { /* ... */ },
    )
}
```

0.9.0's equivalent emitted the opposite default — `option_string_tokens`
(`src/derive/generate/docs/mod.rs:124-126`) returns `quote! { None }` when the
attribute is unset.

That version difference is decisive because `cargo-orthohelp`'s
`synopsis_section` treats the two cases completely differently: `Some(text)`
prints the text, `None` *engages a fallback* that lists the visible options.
So the derive change did not merely change a marker — it suppressed the
synopsis the 0.9.0 build rendered.

## Observed defect

`man/man1/netsuke.1` from the real `cargo-orthohelp` 0.10.0:

```roff
.SH SYNOPSIS
.B netsuke
[missing: netsuke-usage]
```

`[missing: ...]` is `cargo-orthohelp`'s marker for an unresolvable
identifier, so this ships a placeholder into a published artefact.

Netsuke never sets a root `synopsis_id`. `src/cli/release_help/mod.rs:125`
sets `synopsis_id: None` in `documented_subcommand`, which covers subcommands
only; the root metadata comes from `CliConfig::get_doc_metadata()` and
inherits the derive's generated id.

## Can netsuke fix this now?

**Yes. Option A below needs no upstream feature, so this issue is not blocked.**
The two upstream gaps this defect exposes are filed separately; they constrain
Option B only, not the migration corrective. See "Blocking notice" below.

### Option A — restore the pre-migration rendering (one line)

Set the root's `synopsis_id` back to `None` in
`ReleaseHelpCli::try_get_doc_metadata`, after the `CliConfig` call:

```rust
metadata.synopsis_id = None;
```

`cargo-orthohelp` then takes its fallback branch and renders the synopsis from
the IR's own fields, exactly as the 0.9.0 build did. Zero catalogue cost. This
is the correct shape for the migration itself, whose contract is that no
observable output changes.

Caveat: the fallback reuses `value_type_placeholder`, so it will emit the
`USIZE`/`LIST`/`UTF8PATHBUF` placeholders described in the `value_name` issue
until that is fixed. That is pre-existing fallback behaviour, not new breakage.

### Option B — declare a real synopsis (the better end state)

Declare a variable-free key and point the root at it:

```rust
metadata.synopsis_id = Some(keys::CLI_SYNOPSIS.to_owned());
```

with `cli.synopsis = netsuke [OPTIONS] <COMMAND>` defined in
`src/localization/keys.rs` **and all 35 catalogues**, because
`build_l10n_audit/compare.rs` fails any declared key absent from a locale.

### Trap: do not reuse upstream's `cli-usage`

`ortho_l10n` 0.10.0 ships `cli-usage = Usage: { $binary } [OPTIONS] <COMMAND>`,
so setting `synopsis_id = "cli-usage"` looks like the obvious fix. **It does not
work.** `cargo-orthohelp` resolves a synopsis through
`resolve_optional` → `resolve_message(id)` → `localizer.lookup(id, None)`
(`src/ir.rs:191`, `348-352`, `380-382`) and **never supplies
`LocalizationArgs`** — no `$binary`, no anything. `FluentLocalizer::lookup`
therefore fails to format the pattern, reports the issue, falls through to the
next bundle, and returns `None`, which renders as `[missing: cli-usage]`. The
placeholder just changes name.

Probe evidence, against a localizer built exactly as the netsuke one is:

```text
cli-synopsis-static    lookup(None) -> Some("netsuke [OPTIONS] <COMMAND>")
cli-usage              lookup(None) -> None
netsuke-usage          lookup(None) -> None
```

A consumer key **with no variables** resolves. A key with variables cannot, for
any synopsis, at this release.

## Why no test caught it

`release_help_identifiers_are_netsuke_declared_not_generated`
(`src/cli/release_help/metadata_tests.rs:311`) is named for exactly this
guarantee, and its doc comment says "every published identifier is a key
`build_l10n_audit` can attribute to `src/localization`". Its collection list
covers `fields[].help_id`, `metadata.about_id`, and
`subcommands[].about_id` — but **not `synopsis_id`**, which `rg` confirms is
absent from that file. So the one generated identifier still published is the
one the guard does not read.

Whichever option is taken, the guard should collect `synopsis_id` too, so a
future derive default cannot reintroduce this silently.

## Suggested shape

1. Option A now, as the migration corrective, with `synopsis_id` added to the
   identifier guard.
2. Option B as a follow-up once the `value_name` issue lands, so the curated
   synopsis and the fallback both render well.

## Blocking notice: upstream dependency

Both root causes are tracked in `leynos/ortho-config` as
**[leynos/ortho-config#630](https://github.com/leynos/ortho-config/issues/630)**,
"The derive emits an unresolvable `synopsis_id`, and synopsis lookup can never
supply `LocalizationArgs`". One issue because the two defects meet on the same
code path:

- the unannounced 0.10.0 derive default that generates
  `Some("<app>-usage")`, which is the change that caused this regression; and
- the absence of any way to pass `LocalizationArgs` to a synopsis id, which is
  what makes Option B's obvious spelling (`cli-usage`) fail.

**Blocking assessment.** Neither gap blocks the migration corrective: Option A
sets the id back to `None` and uses only APIs present in 0.10.0. Option B — a
parameterised synopsis drawn from upstream's own `cli-usage` — is blocked on
[leynos/ortho-config#630](https://github.com/leynos/ortho-config/issues/630),
item 1. Until that lands, a variable-free netsuke-declared key is the only shape
that resolves.

No upstream roadmap item covers either gap. The one plausible candidate,
[§12.3, "Separate documenting a type from loading
it"](https://github.com/leynos/ortho-config/blob/v0.10.0/docs/roadmap.md#123-separate-documenting-a-type-from-loading-it)
(whose 12.3.1 proposes a standalone `OrthoConfigDocs` derive), would not change
what the current `OrthoConfig` derive emits, so it is context only, not a
tracking item.

## Related

- Raised from the "Out of scope" section of #951 / PR #953; the
  "predates this work" claim there is retracted by this issue.
- Two further man-page defects are filed separately: value placeholders render
  as `UTF8PATHBUF`/`USIZE` (#958), and `--default-targets` is advertised while
  the binary rejects it (#960).
- Upstream: [leynos/ortho-config#630](https://github.com/leynos/ortho-config/issues/630).

@coderabbitai

coderabbitai Bot commented Oct 30, 2026

Copy link
Copy Markdown
Contributor

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail
gh pr view 1043 --repo leynos/netsuke --json headRefOid,baseRefOid,files,statusCheckRollup
gh pr diff 1043 --repo leynos/netsuke
fd -H '^AGENTS\.md$' .
ast-grep outline src/cli/release_help/mod.rs --items all
ast-grep outline src/cli/release_help/metadata_tests.rs --items all

Length of output: 30324


🏁 Script executed:

#!/bin/bash
set -euo pipefail
cat AGENTS.md
sed -n '1,170p' src/cli/release_help/mod.rs
sed -n '290,365p' src/cli/release_help/metadata_tests.rs
ast-grep outline tests/ortho_config_metadata_snapshot_tests.rs --items all
sed -n '1,185p' tests/ortho_config_metadata_snapshot_tests.rs
ast-grep outline src/localization/keys.rs --items all
sed -n '1,75p' src/localization/keys.rs
fd -H '^(generate-release-help\.sh|Cargo\.toml|.*release.*\.ya?ml|netsuke\.1)$' .
rg -n -C3 'ReleaseHelpCli|ortho_config|orthohelp' Cargo.toml
sed -n '1,230p' scripts/generate-release-help.sh
rg -n -C3 'retract|pre-existing|Out of.scope|git grep netsuke-usage' docs/execplans/issue-951-migrate-from-ortho-config-v0-9-0-to-v0-10-0.md
gh run view 41094932666 --repo leynos/netsuke --log | rg -n -C2 'generate-release-help|orthohelp|missing:|SYNOPSIS' | head -110

Length of output: 95647


@leynos Accept the implementation as a correct and complete Option A fix for #959. I found no blocking implementation defect at af11dbb6ba1af331871851180e0aadbd19033360. Make one documentation clarification.

Correctness and completeness

  • Restore the fallback at the correct boundary. ReleaseHelpCli::try_get_doc_metadata clears metadata.synopsis_id immediately after replacing about_id. No later operation overwrites it. Cargo.toml selects netsuke::cli::ReleaseHelpCli as the release-help root, so the change reaches the published documentation path.
  • Close the reported guard gap. release_help_identifiers_are_netsuke_declared_not_generated now collects root and immediate-subcommand synopsis_id values. A restored netsuke-usage would fail the cli. prefix check. Collected identifiers must also resolve with lookup(identifier, None), which checks the relevant argument-free lookup contract.
  • Pin the fallback choice separately. The metadata snapshot records synopsis_id: ~ for the root and all five documented subcommands. This detects any change from None, including a resolvable identifier that the identifier guard would accept.
  • Keep the correction narrowly scoped. The PR adds no catalogue key and does not substitute the parameterized cli-usage. Leave #958’s value placeholders and #960’s flag-surface defect outside this corrective. Neither defect prevents restoration of the fallback.

Immediate-subcommand coverage is sufficient for the current adapter: documented_subcommand creates no nested subcommands. The revised test comment also correctly states that the guard is not a complete census of every IR identifier.

Documentation clarification

In docs/execplans/issue-951-migrate-from-ortho-config-v0-9-0-to-v0-10-0.md, replace the remaining statement:

Out of this migration's scope; repaired by its follow-up …

Use wording that distinguishes delivery scope from regression ownership:

Introduced by the migration; repaired in the separate #959 corrective PR.

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 boundary

The current check results show successful CI and Linux, macOS, and Windows release builds. The release log also confirms that cargo-orthohelp 0.10.0 generated a non-empty manual page.

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 [missing: marker. Successful generation alone does not establish those content properties.

Keep Option B as a follow-up. Do not block this corrective on upstream #630.

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>
codescene-access[bot]

This comment was marked as outdated.

@wafflecat-df12

Copy link
Copy Markdown
Collaborator

@coderabbitai Has the documentation clarification you requested now been
addressed in 147d08a?

Original assessment:
#1043 (comment), which
accepted the Option A implementation as correct and complete and asked for one
documentation change.

Requested change: in
docs/execplans/issue-951-migrate-from-ortho-config-v0-9-0-to-v0-10-0.md,
replace the remaining "Out of this migration's scope; repaired by its follow-up
…" wording so delivery scope is separated from regression ownership.

Repair: commit 147d08aa4. The Surprises & discoveries entry now reads
"Introduced by the migration, not pre-existing, and repaired in the separate
#959 corrective PR …", and a tenth revision note records the correction. No
other content changed.

Validation on the published tree: make check-fmt, make markdownlint,
make nixie, make lint, make doc-coverage (98.21%), make test (4804
passed), and make test-workflow-contracts (27 passed) all green. Hosted CI
for 147d08aa4 is green, including build-test, Windows, kani-smoke, the
release dry run, CodeScene (pass), and Gecko Security Review (pass).

Assessment-ID: 959-doc-clarification-147d08aa4.

Please echo the Assessment-ID and assessed head in your substantive reply, and
confirm whether the requested documentation clarification is fully addressed or
identify what remains. This is a focused follow-up to the existing assessment
conversation, not a request to start a formal PR review.

@coderabbitai

coderabbitai Bot commented Oct 31, 2026

Copy link
Copy Markdown
Contributor

Tip

For best results, initiate chat on the files or code changes.

Analysis chain

Script executed:

#!/bin/bash
set -euo pipefail
sha=147d08aa4d1e362f4a78022ce245636a5121bd42
path=docs/execplans/issue-951-migrate-from-ortho-config-v0-9-0-to-v0-10-0.md
fd -H '^AGENTS\.md$' .
if [ -f AGENTS.md ]; then cat AGENTS.md; fi
for guidance in docs/AGENTS.md docs/execplans/AGENTS.md; do
  if [ -f "$guidance" ]; then cat "$guidance"; fi
done
git show --format=fuller --stat "$sha"
git show --format= --no-ext-diff "$sha" -- "$path"
git show "$sha:$path" | nl -ba | grep -E -C 7 'Introduced by the migration|Out of this migration|[Tt]enth|Revision note|revision note|not pre-existing'
gh pr view 1043 --repo leynos/netsuke --json headRefOid

Length of output: 201003


@wafflecat-df12 Yes. Treat the requested documentation clarification as fully addressed.

  • Assessment-ID: 959-doc-clarification-147d08aa4
  • Assessed head: 147d08aa4d1e362f4a78022ce245636a5121bd42
  • Scope: Focused documentation follow-up, not a formal PR review.

I inspected docs/execplans/issue-951-migrate-from-ortho-config-v0-9-0-to-v0-10-0.md at that commit. GitHub also reports that commit as the current PR head.

At Line 478–482, the entry states that the migration introduced the regression and that the separate #959 corrective PR repaired it. This separates regression ownership from delivery scope.

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.

@leynos
leynos marked this pull request as ready for review October 31, 2026 16:54
@sourcery-ai

sourcery-ai Bot commented Oct 31, 2026

Copy link
Copy Markdown
Contributor

Sorry @leynos, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 5 days and 6 hours by commenting @sourcery-ai review. Upgrade to get a review now.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ⚠️ Failed 2026-10-31T16:54:13.297003Z
We couldn’t complete this review. Comment @codex review to try again.
147d08a Draft marked ready
🔒 Security Review ⚠️ Failed 2026-10-31T16:54:19.756170Z
We couldn’t complete this review. Comment @codex security review to try again.
147d08a Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@chatgpt-codex-connector

Copy link
Copy Markdown

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.

@coderabbitai coderabbitai Bot added the Issue A pull request originating from an issue label Oct 31, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pre-merge checks failed. Please resolve the failing checks before merging.

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>
@pandalump

Copy link
Copy Markdown
Collaborator

@coderabbitai Pre-merge reconciliation of the three failed rows reported on
147d08aa4d1e362f4a78022ce245636a5121bd42, on the repair head 2d7ccb353500faa6b868f1fd1ed9e66b85829a74.

Assessment-ID: 959-premerge-reconciliation-2d7ccb353500faa6b868f1fd1ed9e66b85829a74

  1. Module-Level Documentation — fixed. The
    src/cli/release_help/metadata_tests.rs module docstring now describes the
    complete contract: the configuration-help projection, the parser-only field
    and value-shape derivation, and the identifiers carried by the composed root
    and immediate subcommand documentation metadata.

  2. Testing (Unit And Behavioural) — fixed using the alternative your
    resolution offered: the script-boundary fixture now models synopsis_id.
    The new tests/release_help_synopsis_tests.rs serialises
    ReleaseHelpCli::get_doc_metadata() to JSON, feeds it to a fake
    cargo-orthohelp that renders [missing: <id>] for a set synopsis_id and
    the option listing for an absent one, runs the real
    scripts/generate-release-help.sh for a non-Windows target, and asserts the
    staged man/man1/netsuke.1 contains .SH SYNOPSIS, the
    -C/--directory and --config fallback selectors, and no [missing:
    marker. A second test is the harness control: injecting
    "synopsis_id": "netsuke-usage" makes the same run render
    [missing: netsuke-usage], proving the artefact assertion can fail. The
    positive test reads the metadata Netsuke actually serialises, so the
    regression cannot return without failing it.

    tests/release_help/mod.rs and tests/snapshots/release_help/ were
    deliberately left untouched; the new suite is self-contained so the
    existing fixture and its committed snapshots keep their current shape.

  3. User-Facing Documentation — no change proposed, for two reasons.

    First, the accepted implementation scope for Fix the man page SYNOPSIS showing [missing: netsuke-usage], a 0.10.0 derive regression #959 explicitly instructs that
    docs/users-guide.md is not to be updated. That instruction was part of the
    authorised repair plan, and it governs this pull request.

    Second, the guide already states the restored behaviour. It gives the
    top-level shape netsuke [OPTIONS] [COMMAND] at

    netsuke/docs/users-guide.md

    Lines 1018 to 1025 in 2d7ccb3

    ## Use the command-line interface
    The top-level command shape is:
    <!-- tested-example: guide-cli-usage -->
    ```plaintext
    netsuke [OPTIONS] [COMMAND]

    and states that "The generated help describes the complete public CLI,
    including -C/--directory, --config, and the documented command tree" at

    netsuke/docs/users-guide.md

    Lines 1134 to 1138 in 2d7ccb3

    Manual pages and PowerShell help shipped in releases are generated in `en-US`
    only. Translated copy reaches users through the running binary, which embeds
    every catalogue. The generated help describes the complete public CLI, including
    `-C/--directory`, `--config`, and the documented command tree.
    .
    The restored option-listing SYNOPSIS is exactly that listing, so the
    published page now matches the guide. The regression was undocumented
    breakage of the documented surface, not a new user-facing contract.

    If you see a specific inaccuracy in the current guide text, please name the
    sentence; otherwise please confirm the warning is resolved.

Please confirm these three dispositions on 2d7ccb353500faa6b868f1fd1ed9e66b85829a74, echo the
Assessment-ID, and flag any pre-merge row that remains unresolved. This is a
reconciliation of existing findings, not a request to start a fresh review.

@coderabbitai

coderabbitai Bot commented Oct 31, 2026

Copy link
Copy Markdown
Contributor

Tip

For best results, initiate chat on the files or code changes.

Analysis chain

Script executed:

#!/bin/bash
set -euo pipefail
git rev-parse HEAD
gh pr view 1043 --repo leynos/netsuke --json headRefOid
fd -H '^AGENTS\.md$' .
if [ -f AGENTS.md ]; then cat AGENTS.md; fi
git diff --stat 147d08aa4d1e362f4a78022ce245636a5121bd42 2d7ccb353500faa6b868f1fd1ed9e66b85829a74
ast-grep outline tests/release_help_synopsis_tests.rs --items all
ast-grep outline src/cli/release_help/metadata_tests.rs --items all
ast-grep outline scripts/generate-release-help.sh --items all
git diff 147d08aa4d1e362f4a78022ce245636a5121bd42 2d7ccb353500faa6b868f1fd1ed9e66b85829a74 -- src/cli/release_help/metadata_tests.rs

Length of output: 36168


Script executed:

#!/bin/bash
set -eu
ast-grep outline tests/release_help_synopsis_tests.rs --items all
ast-grep outline src/cli/release_help/metadata_tests.rs --items all
ast-grep outline src/cli/release_help/mod.rs --items all
ast-grep outline scripts/generate-release-help.sh --items all || true
printf '\n--- Synopsis boundary tests ---\n'
nl -ba tests/release_help_synopsis_tests.rs | sed -n '1,400p'
printf '\n--- Module documentation ---\n'
nl -ba src/cli/release_help/metadata_tests.rs | sed -n '1,40p'
printf '\n--- Root metadata assembly ---\n'
nl -ba src/cli/release_help/mod.rs | sed -n '1,85p'
printf '\n--- Existing user guide ---\n'
nl -ba docs/users-guide.md | sed -n '1010,1035p;1120,1145p'
printf '\n--- Generation boundary ---\n'
nl -ba scripts/generate-release-help.sh | sed -n '1,260p'
printf '\n--- Current check summaries (not a new run) ---\n'
gh pr view 1043 --repo leynos/netsuke --json headRefOid,statusCheckRollup --jq '{headRefOid,checks:[.statusCheckRollup[]|{name,conclusion,status}]}'

Length of output: 33097


@pandalump Accept all three source-level dispositions at the repair head. Keep test execution and merge readiness separate from this reconciliation.

  • Assessment-ID: 959-premerge-reconciliation-2d7ccb353500faa6b868f1fd1ed9e66b85829a74
  • Assessed head: 2d7ccb353500faa6b868f1fd1ed9e66b85829a74
  • Scope: Reconciliation of the three existing findings, not a fresh review.

GitHub and the inspected checkout both report the assessed head.

1. Module-Level Documentation — addressed

Accept the revised module documentation in src/cli/release_help/metadata_tests.rs, Line 1–5. It describes the configuration-help projection, parser-only fields, value-shape derivation, and identifiers in root and immediate-subcommand metadata. This addresses the original incomplete-purpose finding. No further wording is required.

2. Testing (Unit And Behavioural) — remedy implemented

Accept the script-boundary alternative offered in the original finding.

In tests/release_help_synopsis_tests.rs:

  • Line 65–72 makes the fake generator read serialized metadata and select between the missing marker and option listing.
  • Line 134–150 invokes the real release-help script for a non-Windows target.
  • Line 182–213 uses ReleaseHelpCli::get_doc_metadata() and checks the generated manual for a SYNOPSIS, both fallback selectors, and no [missing: marker.
  • Line 234–258 injects netsuke-usage and checks that the same boundary produces the missing marker.

This supplies the requested regression-sensitive fixture and negative control. It does not test the real cargo-orthohelp implementation, but the original remedy explicitly allowed this alternative.

3. User-Facing Documentation — withdraw the warning

Keep docs/users-guide.md unchanged for this repair.

The guide already documents netsuke [OPTIONS] [COMMAND] at Line 1020–1026. It also describes release-generated help and explicitly includes -C/--directory, --config, and the command tree at Line 1134–1137.

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 verification

No 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, build-test, Windows tests, release builds, and other checks were still running or queued. Wait for the required checks on this head to complete, and retain the earlier final-artefact check: confirm a populated SYNOPSIS and no [missing: marker in the real generated manual.

This reply neither changes the saved gate nor submits PR approval.

You are interacting with an AI system.

@pandalump

Copy link
Copy Markdown
Collaborator

@coderabbitai approve

Published head: 2d7ccb353500faa6b868f1fd1ed9e66b85829a74; base: 7929a3fc24759d98ed3ffe70c8abf7b66861f17d.

The latest completed review round raised no actionable comments. Its three
pre-merge rows were reconciled on the published head, and your reply accepted
all three source-level dispositions
(#1043 (comment),
Assessment-ID 959-premerge-reconciliation-2d7ccb353500faa6b868f1fd1ed9e66b85829a74):

  • Module-Level Documentation — fixed in
    src/cli/release_help/metadata_tests.rs.
  • Testing (Unit And Behavioural) — fixed by
    tests/release_help_synopsis_tests.rs, which binds the serialised metadata,
    runs the real scripts/generate-release-help.sh, and carries a negative
    control that renders [missing: netsuke-usage].
  • User-Facing Documentation — warning withdrawn: the guide already states
    the restored surface.

Pre-merge checks: your saved gate has not re-evaluated since that reply, so the
summary still shows 2 errors and 1 warning against 147d08aa4. No source-level
finding remains open; the three rows above are the complete inventory and there
are no inline review threads on the pull request.

Final-artefact check you asked us to retain, now performed on the real release
build for this head (Release Dry Run run 41230660651, both completed):

  • netsuke-linux-amd64 — man/man1/netsuke.1 has a populated .SH SYNOPSIS
    listing the full option set, including -C/--directory and --config, and
    contains zero [missing: markers.
  • netsuke-windows-amd64 — Netsuke/en-US/Netsuke-help.xml contains zero
    [missing: markers. The PowerShell about-help has no synopsis line, which is
    the pre-0.10.0 behaviour this repair restores, not a new omission: until the
    derive change, the root synopsis_id was None on both surfaces.

CI: all applicable checks on this head have completed — CI, Release Dry Run,
Netsuke Build Test, CodeScene, Gecko — with 19 passing and only the
automerge/review-provider checks skipped. No check is pending, red, cancelled,
or unknown.

Rebase/stack state: base is main at 7929a3fc24759d98ed3ffe70c8abf7b66861f17d,
the pull request is MERGEABLE/CLEAN, no prerequisite stack applies, and the
branch is up to date with its target.

Please approve if those findings are resolved. If approval remains blocked,
identify the specific unresolved finding or missing required inspection.

@coderabbitai

coderabbitai Bot commented Oct 31, 2026

Copy link
Copy Markdown
Contributor

@pandalump The three source-level findings remain reconciled on 2d7ccb353500faa6b868f1fd1ed9e66b85829a74. No additional source change is required by that assessment.

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

Changes approved. Review threads were not changed.

@leynos
leynos merged commit 2da4eb6 into main Oct 31, 2026
24 checks passed
@leynos
leynos deleted the issue-959-fix-the-man-page-synopsis-showing-missing-netsuke-usage-a-0-10-0-derive-regression branch October 31, 2026 19:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Issue A pull request originating from an issue

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fix the man page SYNOPSIS showing [missing: netsuke-usage], a 0.10.0 derive regression

3 participants