Add target descriptions and netsuke help targets (#551)

[leynos]

Closes #551

Summary

Add an optional description field to manifest targets (and, by inheritance,
actions) and expose the rendered target and action catalogue through a new
netsuke help targets subcommand.

• Targets and actions accept an optional description rendered through the
  normal Jinja pipeline, including foreach expansions. A target description
  is discovery metadata; it never replaces a referenced rule description in
  Ninja progress output.
• netsuke help targets loads, expands, renders, and validates the selected
  manifest without invoking Ninja. It lists actions and targets with their
  descriptions, defaults, and the established colour, accessibility, locale,
  and JSON-output conventions.
• Parser, validation, rendering, expansion, snapshot, integration, BDD, and
  documentation coverage support the new surface across all locales.

References

• Issue: Add target descriptions and netsuke help targets #551
• Lody session: https://lody.ai/leynos/sessions/f78ccfcf-d218-4aaf-88e3-1e6390495dad

[coderabbitai]

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

Summary

• Add optional Jinja-rendered description fields to manifest targets and actions, including foreach expansions.
• Keep discovery descriptions separate from rule descriptions used in Ninja progress output.
• Add read-only netsuke help targets with deterministic text and versioned JSON catalogues.
• Support manifest selection, defaults, accessibility, colour, localisation, validation, and restricted side-effect-free rendering.
• Avoid Ninja resolution, recipe execution, and build-output creation during help queries.
• Add bounded telemetry, localized diagnostics, shell completions, manual-page and PowerShell help updates, and release staging.
• Expand parser, integration, BDD, property, contract, snapshot, and regression test coverage.
• Update user, developer, design, migration, roadmap, and ExecPlan documentation.

References

• Issue #551
• docs/execplans/issue-551-add-target-descriptions-and-netsuke-help-targets.md
• docs/netsuke-cli-design-document.md
• docs/netsuke-design.md

Walkthrough

The change adds netsuke help, including help targets. It preserves target and action descriptions through expansion. It renders localised text and versioned JSON catalogues without running Ninja. It generates and stages shell-completion sidecars.

Changes

Help catalogue and target metadata

Layer / File(s)	Summary
Manifest metadata and restricted queries src/ast/*, src/manifest/*, src/stdlib/*	Add optional target descriptions. Preserve descriptions during parsing and expansion. Restrict manifest-query helpers to read-only operations.
Catalogue execution and rendering src/runner/help*.rs, src/runner/path_helpers.rs	Load, validate, and catalogue actions and targets. Render text and versioned JSON output. Escape control characters. Record bounded telemetry.
CLI help dispatch and localisation src/cli/*, src/main.rs, src/runner/dispatch.rs, locales/*	Add help topics. Localise help text and catalogue markers. Dispatch informational help before Ninja resolution.
Validation and integration coverage tests/*, dylint.toml	Add parser, expansion, snapshot, property, BDD, integration, telemetry, smoke, and no-recipe tests.
Release output and documentation build.rs, .github/release-staging.toml, Cargo.toml, docs/*	Generate five shell-completion files. Stage completion sidecars in release archives. Document descriptions, help topics, query restrictions, JSON output, and release behaviour.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI
  participant HelpQuery
  participant Manifest
  participant Renderer
  User->>CLI: run help targets
  CLI->>HelpQuery: load selected manifest
  HelpQuery->>Manifest: parse with restricted helpers
  Manifest-->>HelpQuery: validated actions and targets
  HelpQuery->>Renderer: provide catalogue
  Renderer-->>User: write text or JSON output

Loading

Possibly related PRs

• leynos/netsuke#326 — Both changes extend localised CLI help handling and tests.
• leynos/netsuke#353 — Both changes modify StringOrList.
• leynos/netsuke#558 — Both changes update release-help generation and tooling integration.

Suggested labels: Roadmap, Issue

Suggested reviewers: codescene-access, codescene-delta-analysis

Poem

Help lists targets in clear rows,
Descriptions show what each one knows.
Ninja waits while queries run,
Five shell completions join the sun.
Locales guide the work.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error, 1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Security And Privacy	❌ Error	The new help query feeds unrestricted manifest target names into BuildGraph diagnostics; LocalizedMessage::with_arg preserves controls, so help targets can emit terminal escapes from a YAML name.	Escape terminal controls in every help-targets diagnostic and log field, or reject them before graph validation; add a regression test for a control-bearing target name with a missing rule.
Concurrency And State	⚠️ Warning	The new timeout-handling change keeps a zero-capacity receiver alive while joining; if recv_timeout expires, the contender blocks in send and join deadlocks.	Drop the receiver before joining on timeout, or use a non-blocking completion channel, then join the contender on every path.
Architectural Complexity And Maintainability	❓ Inconclusive	I need to inspect the cumulative feature diff before deciding whether its added architecture is disproportionate.	Review the new query, stdlib, release-help, and build abstractions against the feature boundary.

✅ Passed checks (17 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the target descriptions and help targets changes and includes the linked issue number (#551).
Description check	✅ Passed	The description directly explains the target descriptions, help targets command, behaviour, testing, and related documentation changes.
Linked Issues check	✅ Passed	The changes address the linked issue requirements for descriptions, rendering, validation, catalogue output, safety, options, localisation, and release documentation.
Out of Scope Changes check	✅ Passed	The changes remain within the linked issue scope, including implementation, tests, documentation, localisation, completions, and manual-page coverage.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Testing (Overall)	✅ Passed	Accept testing: parser, rendering, expansion, snapshot, BDD, and end-to-end tests assert descriptions, ordering, defaults, JSON, localisation, safety, and no recipe execution.
User-Facing Documentation	✅ Passed	Accept the check: the users' guide documents descriptions, help targets, ordering, defaults, safety, options, accessibility, localisation, JSON output, and release completions; the migration guid...
Developer Documentation	✅ Passed	The pull request documents the help-query boundary, restricted Jinja surface, telemetry, release-help tooling, completions, design decisions, roadmap completion, and a current execplan.
Module-Level Documentation	✅ Passed	Mark this check PASS: every changed Rust module begins with //!; new help, query, telemetry, test, and fixture modules document purpose and component relationships.
Testing (Unit And Behavioural)	✅ Passed	Unit tests cover parsing, rendering, expansion, errors and invariants; CLI integration tests invoke the binary for text, JSON, locale, accessibility and no-execution paths, with BDD coverage for co...
Testing (Property / Proof)	✅ Passed	The PR adds substantive proptest coverage for arbitrary foreach inputs and for catalogue ordering, name expansion, metadata, action classification, and defaults; both tests are wired into the Rust...
Testing (Compile-Time / Ui)	✅ Passed	The PR adds runtime CLI and manifest behaviour, not compile-time diagnostics; focused Insta snapshots cover text, accessible, Spanish, JSON, and CLI help, with semantic integration assertions.
Unit Architecture	✅ Passed	The query returns explicit Results, uses a restricted stdlib with impure helpers disabled, and avoids Ninja, recipes, and output creation; command presentation and telemetry remain separate.
Domain Architecture	✅ Passed	AST and IR remain free of CLI, filesystem, process, and status dependencies; the new catalogue is pure, while manifest loading and help rendering stay in adapter/runner modules.
Observability	✅ Passed	Accept: the new query has an explicit span, completion event, counter, and duration histogram; tests and docs confirm fixed low-cardinality labels with no manifest data.
Performance And Resource Use	✅ Passed	The diff uses input-sized catalogue vectors and hash-set lookups, performs one manifest read with no per-entry I/O, and keeps telemetry labels fixed and bounded.
Rust Compiler Lint Integrity	✅ Passed	The PR adds no forbidden broad allow suppression; new helpers have callers, and the only production sharing clone is Arc<str> for catalogue entries.

📋 Issue Planner

Built with CodeRabbit's Coding Plans for faster development and fewer bugs.

View plan used: #551

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-551-add-target-descriptions-and-netsuke-help-targets

---

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Reviewer's Guide

Adds an optional description field to manifest targets/actions and introduces a localized netsuke help subcommand, including help targets which renders a text/JSON catalogue of actions/targets using existing manifest loading and IR validation pipelines, with full tests and documentation updates.

Sequence diagram for netsuke help targets execution pipeline

sequenceDiagram
    actor User
    participant Cli as Cli_parser
    participant Runner as runner_dispatch
    participant Help as runner_help
    participant Manifest as load_manifest_with_stage_reporting
    participant Graph as BuildGraph
    participant Process as process

    User->>Cli: netsuke help targets
    Cli->>Runner: Commands::Help(HelpArgs { topic: Some(HelpTopic::Targets) })
    Runner->>Help: execute_help(cli, &args, context)
    Help->>Help: handle_help_targets(cli, reporter)
    Help->>Help: resolve_manifest_path(cli)
    Help->>Help: ensure_manifest_exists_or_error(cli, reporter, manifest_path)
    Help->>Help: cli.network_policy()
    Help->>Manifest: load_manifest_with_stage_reporting(manifest_path, policy, reporter)
    Manifest-->>Help: NetsukeManifest
    Help->>Graph: BuildGraph::from_manifest(&manifest)
    Graph-->>Help: validation result
    Help->>Help: build_catalogue(&manifest)
    alt cli.json == true
        Help->>Help: render_json(&entries)
    else cli.json == false
        Help->>Help: render_text(&entries, resolved_prefs(cli))
    end
    Help->>Process: write_text_stdout(rendered)
    Help->>Help: reporter.report_complete(status_key)
    Process-->>User: catalogue output

Loading

File-Level Changes

Change	Details	Files
Introduce optional discovery descriptions on targets and actions, including render/expand behaviour and AST validation.	Add description: Option<String> to Target AST with serde default and docs clarifying it is discovery metadata only. Render target descriptions through the Jinja pipeline in render_target, using target vars for interpolation. Ensure foreach/when expansion preserves or drops description consistently via new manifest expansion test cases. Add AST tests covering presence/absence of description, duplicates, and unknown fields; confirm actions remain phony when they have a description.	src/ast.rs src/manifest/render.rs src/manifest/expand_tests.rs src/manifest/expand_test_cases/description_cases.rs tests/ast_tests.rs tests/ast_tests/descriptions.rs tests/ast_tests/actions.rs
Add netsuke help subcommand with topic-based dispatch, including help targets catalogue rendering and JSON output.	Define HelpArgs and HelpTopic enums and add Commands::Help(HelpArgs) in the CLI, disabling clap’s implicit help subcommand. Implement dispatcher branch to route Commands::Help to new helper functions for root help, subcommand help, or targets catalogue. Create runner::help module that loads and validates the manifest, builds an in-memory catalogue of actions/targets/defaults, and renders either localized text sections or a versioned JSON document. Integrate output preferences (emoji/accessibility/theme) and localization keys for headings and default markers into catalogue rendering.	src/cli/help.rs src/cli/mod.rs src/cli/parser.rs src/runner/mod.rs src/runner/dispatch.rs src/runner/help.rs src/localization/keys.rs src/output_prefs.rs
Extend localization for the new help subcommand and catalogue headings across all locales and status reporting.	Add Fluent messages for cli.subcommand.help.* and cli.help.* headings/markers in all locale files. Register new localization keys for help subcommand about/long_about, catalogue headings, default marker, and status tool name. Ensure status pipeline reports help targets activity using a new STATUS_TOOL_HELP_TARGETS key. Update CLI localization helpers to understand the help subcommand and its about/long_about, while suppressing flag help for clean/help.	src/localization/keys.rs src/cli_l10n.rs locales/ar/messages.ftl locales/cs/messages.ftl locales/cy/messages.ftl locales/da/messages.ftl locales/de/messages.ftl locales/el/messages.ftl locales/en-GB/messages.ftl locales/en-US/messages.ftl locales/es-419/messages.ftl locales/es-ES/messages.ftl locales/fa/messages.ftl locales/fi/messages.ftl locales/fr/messages.ftl locales/gd/messages.ftl locales/he/messages.ftl locales/hi/messages.ftl locales/hu/messages.ftl locales/id/messages.ftl locales/it/messages.ftl locales/ja/messages.ftl locales/ko/messages.ftl locales/nb/messages.ftl locales/nl/messages.ftl locales/pl/messages.ftl locales/pt-BR/messages.ftl locales/pt-PT/messages.ftl locales/ro/messages.ftl locales/ru/messages.ftl locales/sv/messages.ftl locales/th/messages.ftl locales/tr/messages.ftl locales/uk/messages.ftl locales/vi/messages.ftl locales/zh-Hans/messages.ftl locales/zh-Hant/messages.ftl
Add tests and BDD coverage for parsing and running netsuke help/help targets, including snapshots and integration tests.	Extend CLI parsing tests to include help command, topics, and manifest/working-directory flags; add verification helpers for help topic presence/absence. Add unit snapshot tests for help targets catalogue (text, accessible, localized, JSON) using a fixed manifest fixture. Introduce integration tests for help targets running via the binary and via runner API, covering text/JSON output, -C and --file behaviour, defaults, and error handling for invalid manifests. Add BDD feature and step definitions for full-process help targets scenarios; wire new steps into the BDD module and adjust manifest-command helpers visibility. Update documentation example tests to include the new guide-help-targets example and assert catalogue output sections. Exclude new help-target-related test modules from Dylint linting in dylint.toml and register expected snapshot IDs.	tests/bdd/steps/cli_verify.rs tests/features/cli.feature tests/bdd/steps/cli.rs tests/bdd/steps/help_targets.rs tests/features/help_targets.feature tests/documentation_examples_tests.rs tests/runner_help_targets_tests.rs src/runner/help_tests.rs src/snapshots/help_targets/netsuke__runner__help__tests__accessible_catalogue.snap src/snapshots/help_targets/netsuke__runner__help__tests__json_catalogue.snap src/snapshots/help_targets/netsuke__runner__help__tests__localized_catalogue_es_es.snap src/snapshots/help_targets/netsuke__runner__help__tests__text_catalogue.snap src/snapshots/cli/netsuke__cli__parser__tests__help_en_us.snap src/snapshots/cli/netsuke__cli__parser__tests__help_es_es.snap tests/ast_tests/actions.rs tests/ast_tests/descriptions.rs tests/ast_tests.rs tests/manifest_command.rs tests/bdd/steps/manifest_command_helpers.rs tests/bdd/steps/mod.rs dylint.toml
Update user documentation and execution plan to describe target descriptions and the new help targets subcommand.	Extend users’ guide to document optional target/action description, its purpose as discovery metadata, and its non-impact on Ninja progress output. Add help [TOPIC] to the command list with explanation of help targets and cross-references to the artefact inspection section. Introduce a new worked example for help targets with a tested-example tag and describe text/JSON behaviour including result.command = help-targets. Add an execution plan document explaining constraints, design decisions, risks, and validation steps for this feature.	docs/users-guide.md docs/execplans/fef13161.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#551	Extend the manifest, AST, rendering, expansion, and parsing so that targets and actions support an optional description field that is preserved through the pipeline without affecting rule descriptions or Ninja progress output.	✅
#551	Implement a netsuke help targets subcommand (and associated help-topic handling) that loads, expands, renders, and validates the selected manifest without running Ninja, then emits a deterministic catalogue of actions and targets with descriptions, supporting text, accessible, localized, and JSON modes and honouring manifest-selection and output preferences.	✅
#551	Update documentation and CLI help to describe the new description field for targets/actions and the netsuke help targets subcommand, including localized help text and related surfaces such as shell completions/man pages/PowerShell help.	✅

Possibly linked issues

• Add target descriptions and netsuke help targets #551: The PR fully implements optional target/action descriptions plus the netsuke help targets subcommand, including rendering, JSON output, tests, and docs as specified in the issue.

---

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

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[leynos]

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph.

If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced.

src/runner/help_tests.rs

Comment on lines +105 to +114

fn json_catalogue_snapshot() -> Result<()> {
    let _lock = localizer_lock();
    let _guard = en_localizer();
    let entries = fixture_entries()?;
    let rendered = render_json(&entries)?;
    snapshot_settings("help_targets").bind(|| {
        assert_snapshot!("json_catalogue", rendered);
    });
    Ok(())
}

❌ New issue: Code Duplication
The module contains 4 functions with similar structure: accessible_catalogue_snapshot,json_catalogue_snapshot,localized_catalogue_snapshot,text_catalogue_snapshot

[leynos]

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph.

If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced.

tests/bdd/steps/cli_verify.rs

Comment on lines +55 to +66

pub(super) fn verify_help_topic(world: &TestWorld, expected: &HelpTopic) -> Result<()> {
    let command = get_command(world)?;
    let Commands::Help(args) = &command else {
        bail!("expected help command, got {command:?}");
    };
    ensure!(
        args.topic.as_ref() == Some(expected),
        "expected help topic {expected:?}, got {:?}",
        args.topic
    );
    Ok(())
}

❌ New issue: Code Duplication
The module contains 2 functions with similar structure: verify_help_has_no_topic,verify_help_topic

[leynos]

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response.

Overall Code Complexity

src/manifest/render.rs:

What lead to degradation?

This module has a mean cyclomatic complexity of 4.14 across 7 functions. The mean complexity threshold is 4

Why does this problem occur?

Overall Code Complexity is measured by the mean cyclomatic complexity across all functions in the file. The lower the number, the better.
Cyclomatic complexity is a function level metric that measures the number of logical branches (if-else, loops, etc.). Cyclomatic complexity is a rough complexity measure, but useful as a way of estimating the minimum number of unit tests you would need. As such, prefer functions with low cyclomatic complexity (2-3 branches).

How to fix it?

You address the overall cyclomatic complexity by a) modularizing the code, and b) abstract away the complexity. Let's look at some examples:
Modularizing the Code: Do an X-Ray and inspect the local hotspots. Are there any complex conditional expressions? If yes, then do a DECOMPOSE CONDITIONAL refactoring. Extract the conditional logic into a separate function and put a good name on that function. This clarifies the intent and makes the original function easier to read. Repeat until all complex conditional expressions have been simplified./

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[wafflecat-df12]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[codescene-access]

Gates Failed
Enforce advisory code health rules (1 file with Code Duplication)

Our agent can fix these. Install it.

Gates Passed
5 Quality Gates Passed

Reason for failure

Enforce advisory code health rules	Violations	Code Health Impact
runner_help_targets_tests.rs	1 advisory rule	9.39	Suppress

See analysis details in CodeScene

Active suppressions
1 suppression

Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.

[codescene-access]

No quality gates enabled for this code.