Overhaul v0.9.0 user documentation by leynos · Pull Request #422 · leynos/ortho-config

leynos · 2026-08-09T16:12:48Z

Summary

This branch replaces the v0.9.0 public documentation with a benefit-led,
low-time-to-Hello-World introduction, a task-oriented user's guide, and a
complete impact-labelled migration guide. It also makes every README and
user's-guide example executable so published guidance cannot drift from the
library's behaviour.

The implementation follows the
documentation execplan.
The final review pass also synchronizes the crate's published README, corrects
the subcommand and tracing examples, documents all load_first outcomes, and
hardens the example runner against unsafe identifiers, paths, and inherited
environment secrets.

Review walkthrough

Start with the
README
for the benefits, quick start, now-and-next summary, and routes into deeper
material. The
crate README
is kept byte-identical for crates.io.
Continue with the
user's guide
for worked CLI, TOML, environment, discovery, subcommand, diagnostics, and
generated-help flows.
Review the
migration guide
for the v0.8.0 to v0.9.0 compatibility boundaries and adoption choices.
Finish with the
example loader,
isolated workspace,
runtime contracts,
and
format and packaging contracts.

Validation

cargo test -p ortho_config --test documentation_examples_loader_tests --test documentation_examples_tests --test documentation_examples_rust_tests:
passed.
Isolated cargo check --offline of the migration guide's subcommand example:
passed.
cargo package -p ortho_config --allow-dirty --no-verify: passed; the
packaged README matches the repository README byte for byte.
make check-fmt: passed.
make lint: passed (cargo doc, Clippy, and Whitaker).
make test: passed, including documentation examples and doctests.
make markdownlint: passed, including spelling.
make nixie: passed.
mbake validate Makefile: passed.
git diff --check: passed.

An independent scrutineer reran every repository gate above and reported no
findings.

Notes

The README intentionally remains an entry point rather than a condensed copy
of the user's guide. The migration guide groups changes by upgrade impact, so
required compatibility work remains distinct from recommended and low-cost
opt-ins.

coderabbitai · 2026-08-09T16:12:58Z

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

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 85170a39-76ee-4c9a-b1d6-8d1acd686ef3

📥 Commits

Reviewing files that changed from the base of the PR and between 6d120ec and 392e377.

📒 Files selected for processing (3)

ortho_config/tests/documentation_examples/cargo_runner.rs
ortho_config/tests/documentation_examples/mod.rs
ortho_config/tests/documentation_examples_loader_tests.rs

🔗 Linked repositories identified

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

leynos/weaver (auto-detected)
leynos/netsuke (auto-detected)
leynos/rstest-bdd (auto-detected)

Summary

Replace the root and crate READMEs with concise v0.9.0 quick-start guides.
Rework the user’s guide around practical CLI tasks.
Add the v0.8.0-to-v0.9.0 migration guide.
Add the completed v0.9.0 documentation ExecPlan.
Update documentation navigation and developer guidance for executable examples.
Add strict validation for 23 README and user’s-guide examples.
Validate Markdown fences, markers, identifiers, languages, duplicates, source locations, and CRLF normalisation.
Compile and run Rust examples in isolated temporary Cargo workspaces.
Validate configuration formats, dependency aliases, console output, error handling, environment variables, and generated agent context.
Harden example execution with identifier and path validation, isolated environments, safe workspace handling, and platform-independent manifest paths.
Document all ConfigDiscovery::load_first outcomes.
Cache parsed examples once per integration-test process and return borrowed examples.
Use typed borrowed values for dependency aliases, example IDs, and run-file paths.
Keep the root and crate READMEs byte-for-byte identical.
Preserve production APIs and documented runtime behaviour.
Run linting, tests, Markdown checks, Nixie, Makefile validation, packaging, and whitespace checks.

Walkthrough

The pull request rewrites the v0.9.0 documentation and adds infrastructure to parse, compile, and run marked Rust examples. It adds contract tests for documentation synchronisation, configuration formats, command output, environment isolation, and documented workflows.

Changes

Documentation and executable examples

Layer / File(s)	Summary
Rewrite v0.9.0 user documentation `README.md`, `ortho_config/README.md`, `docs/users-guide.md`, `docs/v0-9-0-migration-guide.md`, `docs/contents.md`, `docs/developers-guide.md`, `docs/execplans/...`	The documentation covers v0.9.0 usage, migration actions, supported features, executable-example rules, repository links, and delivery details.
Parse and register documented examples `ortho_config/tests/documentation_examples/*`, `ortho_config/tests/documentation_examples_loader_tests.rs`	The loader parses marked fences, validates identifiers and languages, preserves bodies, reports source locations, and rejects malformed or duplicate examples.
Compile and run documented Rust examples `ortho_config/tests/documentation_examples/workspace.rs`, `ortho_config/tests/documentation_examples/cargo_runner.rs`, `ortho_config/tests/documentation_examples_rust_tests.rs`	The test workspace builds examples offline, sanitises environments, configures supported Windows toolchains, writes fixtures, and validates output, errors, aliases, and safe paths.
Validate documentation contracts `ortho_config/tests/documentation_examples_tests.rs`	The tests validate registered identifiers, manifests, configuration formats, agent-context data, generated command output, and documented console flows.

Sequence Diagram(s)

sequenceDiagram
  participant Documentation
  participant ExampleLoader
  participant ExampleWorkspace
  participant Cargo
  participant ExampleBinary
  Documentation->>ExampleLoader: provide marked examples
  ExampleLoader->>ExampleWorkspace: return validated examples
  ExampleWorkspace->>Cargo: build examples offline
  Cargo-->>ExampleWorkspace: return build result
  ExampleWorkspace->>ExampleBinary: run with arguments and sanitised environment
  ExampleBinary-->>ExampleWorkspace: return output

Possibly related PRs

leynos/netsuke#497 — Shares isolated child-process environment handling and explicit environment overrides.

Suggested reviewers: codescene-access

Poem

Marked fences hold their form,
Cargo runs each example warm.
Clean environments clear the way,
Contract tests guard each display.
v0.9.0 guides the day.

Important

Pre-merge checks failed

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

❌ Failed checks (1 warning, 6 inconclusive)

Check name	Status	Explanation	Resolution
Performance And Resource Use	⚠️ Warning	New test runners use Command::output() for Cargo and documented binaries without output limits or timeouts, so child output and wait time can grow unbounded (workspace.rs:100,184; cargo_runner.rs:1...	Capture stdout and stderr through fixed-size readers and enforce a bounded child timeout; apply the same limits to Cargo and MSVC discovery commands.
Testing (Overall)	❓ Inconclusive	Investigation is still in progress; no verdict has been submitted yet.	Inspect the changed test infrastructure and verify that tests fail for plausible incorrect implementations.
Developer Documentation	❓ Inconclusive	Investigation started; no verdict yet.	Await code and documentation diff evidence.
Testing (Compile-Time / Ui)	❓ Inconclusive	Investigation is still in progress; no assessment has been made.	Inspect the PR diff and test strategy before deciding whether the stated compile-time or snapshot requirements apply.
Unit Architecture	❓ Inconclusive	Investigation in progress; no verdict has been established.	Inspect the changed example-loader, workspace, and Cargo-runner boundaries and their diff before deciding.
Domain Architecture	❓ Inconclusive	Assessment pending repository diff and boundary evidence.	Inspect the pull-request diff and determine whether any changed code places domain logic in infrastructure or adapter concerns.
Architectural Complexity And Maintainability	❓ Inconclusive	Investigation started; no verdict evidence has been gathered yet.	Inspect the pull-request diff and the new documentation-test architecture before deciding.

✅ Passed checks (13 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarises the v0.9.0 documentation overhaul and no roadmap or issue reference applies.
Description check	✅ Passed	The description directly explains the documentation overhaul, executable examples, validation, and implementation details.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
User-Facing Documentation	✅ Passed	The diff adds no shipped product code; it changes guides/README and test-only infrastructure. The user’s guide covers the documented v0.9.0 features, and the migration guide signposts required comp...
Module-Level Documentation	✅ Passed	All six new documentation-example Rust modules have `//!` purpose/function comments, and both nested `tests` modules also document their role; no undocumented module was introduced.
Testing (Unit And Behavioural)	✅ Passed	Accept the testing coverage: parser tests cover malformed fences, identifiers, CRLF, caching, concurrency, and properties; behavioural tests compile and run the 23 documented examples and exercise...
Testing (Property / Proof)	✅ Passed	The pull request introduces range-based parser invariants and includes proptest coverage for malformed input, identifiers, fences, line endings, and round trips.
Observability	✅ Passed	The PR changes only documentation and test-only example infrastructure; it does not alter production operational behaviour or add an operational failure mode.
Security And Privacy	✅ Passed	Keep the change: the diff adds documentation and test-only infrastructure, uses fake test values, validates identifiers and paths, and clears child environments before applying narrow allow-lists.
Concurrency And State	✅ Passed	Pending investigation; no verdict yet.
Rust Compiler Lint Integrity	✅ Passed	The PR diff adds no dead-code or unused-import suppressions or artificial anchors; helper APIs are exercised, and the only clones are Arc::clone plus an owned cached-error conversion.

✨ 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 v0-9-0-prep

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

sourcery-ai · 2026-08-09T16:13:15Z

Reviewer's Guide

Overhauls public user documentation for OrthoConfig v0.9.0: a concise, benefit-led README and a task-oriented user’s guide backed by an executable Markdown example contract, plus a substantially expanded migration guide and supporting execplan and tests.

Flow diagram for v0.9.0 migration guide adoption steps

flowchart TD
  Start["Start: existing project on v0.8.0"] --> ReadGuide["Read v0-9-0-migration-guide.md impact table"]
  ReadGuide --> UpdateDeps["Update ortho_config and ortho_config_macros to 0.9.0"]
  UpdateDeps --> HandleDiscovery["Review ConfigDiscovery::load_first error semantics"]
  HandleDiscovery --> CheckYAML["If yaml feature enabled: test YAML 1.2 and duplicate keys"]
  CheckYAML --> OptionalImprovements["Adopt recommended improvements (MapEnv tests, discovery attribute, localization, docs IR)"]
  OptionalImprovements --> Observability["Optionally enable tracing and metrics for discovery"]
  Observability --> Validate["Run full test, lint, and documentation gates"]
  Validate --> Done["Complete migration to v0.9.0"]

File-Level Changes

Change	Details	Files
Rewrite README into a short Hello-World-focused entry point that links out to deeper docs instead of duplicating the user’s guide.	Replace long, reference-style README content with a concise overview of OrthoConfig’s benefits and a minimal layered configuration example. Update installation instructions and example code to target v0.9.0 and current dependency versions. Add curated links to the user’s guide, migration guide, Hello World example, API docs, design, changelog, roadmap, and developer guide. Remove embedded detailed migration sections now covered by the dedicated migration guide.	`README.md`
Replace the monolithic user’s guide with a task-oriented walkthrough of building layered CLIs, discovery, subcommands, errors, localization, observability, docs, and formats, using small executable examples.	Rewrite introductory material to focus on OrthoConfig as a way to build layered CLI configurations rather than an exhaustive feature catalog. Restructure content around practical tasks: install, first layered CLI, configuration files, discovery customization, hermetic tests, subcommands, error handling, localization, tracing/metrics, documentation/agent context, aliases, and YAML. Update and add code and config examples to reflect v0.9.0 APIs and conventions (e.g., discovery attribute, MapEnv, SelectedSubcommandMerge, OrthoConfigDocs, Fluent-based localization). Introduce executable example markers (tested-example IDs) for all fenced blocks that are validated by new tests.	`docs/users-guide.md`
Expand and reorganize the v0.9.0 migration guide to clearly separate required, review, recommended, and optional changes and cover all public deltas since v0.8.0.	Add a "Who should read this" section and an impact-at-a-glance matrix categorizing changes by priority (required/review/recommended/optional). Document behavioural changes such as ConfigDiscovery::load_first error semantics and YAML 1.2 parsing with duplicate-key rejection. Cover new features and patterns: dependency aliasing and re-exports, derive-driven discovery customization, subcommand documentation derives, localization helpers, environment injection, tracing and metrics, agent context, and error-contract notes. Provide concrete before/after examples and upgrade checklist, clarifying that OrthoError::MissingRequiredValues is still proposed and not part of v0.9.0.	`docs/v0-9-0-migration-guide.md`
Introduce a strict executable documentation-example contract and test harness that loads fenced examples from README and user’s guide and exercises them end-to-end.	Add a shared test module that loads Markdown files, enforces tested-example markers, parses fences, rejects malformed/unmarked/duplicate examples, and exposes a query API for tests. Add loader property tests (including proptest) and regression tests ensuring all fences are properly marked and unique. Add integration tests that parse TOML/YAML examples, verify manifest dependency versions, validate agent-context JSON against runtime defaults, and run cargo-orthohelp to generate agent-context output. Add Rust workspace helper and tests that assemble temporary Cargo projects from example code, compile binaries, and run documented commands to assert their stdout matches the documentation. Ensure environment isolation in example runs via cap-std and HOME/XDG overrides to keep tests hermetic.	`ortho_config/tests/documentation_examples_tests.rs` `ortho_config/tests/documentation_examples/mod.rs` `ortho_config/tests/documentation_examples_rust_tests.rs` `ortho_config/tests/documentation_examples/workspace.rs` `ortho_config/tests/documentation_examples_loader_tests.rs` `docs/developers-guide.md`
Record and index the documentation overhaul work via an ExecPlan and contents updates.	Add an execution plan document describing constraints, risks, decisions, and validation criteria for the v0.9.0 documentation refresh. Update the documentation contents index to link to the v0.9.0 migration guide and the new execplan. Clarify in the developers guide the ownership, scope, and reuse boundaries of the documentation example loader and workspace helper. Align internal guidance on EnvSource behaviour and home-fallback semantics with the updated user’s guide and migration doc.	`docs/execplans/prepare-v0-9-0-user-documentation.md` `docs/contents.md` `docs/developers-guide.md`

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 · 2026-08-09T16:21:29Z

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

String Heavy Function Arguments

ortho_config/tests/documentation_examples/workspace.rs:

What lead to degradation?

In this module, 46.2% of all arguments to its 7 functions are strings. The threshold for string arguments is 39.0%

Why does this problem occur?

String is a generic type that fail to capture the constraints of the domain object it represents. In this module, 46 % of all function arguments are string types.

How to fix it?

Heavy string usage indicates a missing domain language. Introduce data types that encapsulate the semantics. For example, a user_name is better represented as a constrained User type rather than a pure string, which could be anything.

sourcery-ai

Sorry @leynos, your pull request is larger than the review limit of 150000 diff characters

leynos · 2026-08-09T18:40:30Z

@coderabbitai Have the following failed checks now been resolved?

If further work is required, please provide an AI agent prompt for the remaining work to be done to address these failures.

Do not treat warnings as optional or aspirational. Where a change is out of scope for this PR, propose a GitHub issue unless one exists already. (Treat o11y, code safety, documentation and validation coverage as in scope).

❌ Failed checks (1 error, 2 warnings)

Check name	Status	Explanation	Resolution
Security And Privacy	❌ Error	The new test runner uses unvalidated Markdown IDs in filesystem and executable paths and inherits the full process environment, so PR examples can cause path traversal or expose CI secrets.	Validate IDs against a closed filename-safe grammar, reject unsafe paths, and clear child environments with an explicit allow-list of non-sensitive variables and documented overrides.
User-Facing Documentation	⚠️ Warning	The user's guide covers discovery but omits the changed `ConfigDiscovery::load_first` contract; only the migration guide documents `Ok(None)` versus `Err`.	Add a user-guide section for `ConfigDiscovery::load_first` that documents the three outcomes and shows distinct absent-file and failed-file handling.
Title check	⚠️ Warning	The title describes the documentation overhaul but omits the required roadmap item reference for this execplan implementation.	Add the applicable roadmap item reference to the title, for example: “Overhaul v0.9.0 user documentation (1.2.3.)”.

leynos · 2026-08-09T18:50:54Z

@coderabbitai Re:

Title check: not resolved.
PR #422 still has the title Overhaul v0.9.0 user documentation. Add the applicable roadmap reference, such as Overhaul v0.9.0 user documentation (1.2.3.).

No roadmap link is needed if there is no roadmap item for the PR.

wafflecat-df12 · 2026-08-09T19:03:46Z

@coderabbitai review

coderabbitai · 2026-08-09T20:27:33Z

Tip

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

@leynos Correct. Do not add a roadmap reference when this PR has no applicable roadmap item.

Withdraw the title-check finding. The prior reply assumed that roadmap item 1.2.3. applied to PR #422. That assumption was not verified.

✏️ Learnings added

Learnt from: leynos
URL: https://github.com/leynos/ortho-config/pull/422

Timestamp: 2026-08-09T20:27:31.265Z
Learning: For leynos/ortho-config pull request titles, include a roadmap item reference only when an applicable roadmap item exists. Do not require a roadmap reference for a pull request without one.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

_{You are interacting with an AI system.}

coderabbitai · 2026-08-09T20:27:35Z

✅ 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.

leynos · 2026-08-09T20:28:54Z

@coderabbitai Please investigate the cause of the following issue arising in Windows CI using codegraph exploration and research, identify a fix and provide an AI coding agent prompt for the fix:

          FAIL [   0.571s] (658/979) ortho_config::documentation_examples_rust_tests aliased_dependency_example_compiles_and_runs
    stdout ───
  
      running 1 test
      test aliased_dependency_example_compiles_and_runs ... FAILED
  
      failures:
  
      failures:
          aliased_dependency_example_compiles_and_runs
  
      test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 2 filtered out; finished in 0.41s
      
    stderr ───
      Error: documented Rust failed to compile:
      error: invalid escape sequence
      expected `b`, `f`, `n`, `r`, `t`, `u`, `U`, `\`, `"`
       --> Cargo.toml:7:56
        |
      7 | config_layer = { package = "ortho_config", path = "D:\a\ortho-config\ortho-config\ortho_config" }
        |                                                        ^
        |
  
  
      Stack backtrace:
         0: std::backtrace_rs::backtrace::win64::trace
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\std\src\..\..\backtrace\src\backtrace\win64.rs:85
         1: std::backtrace_rs::backtrace::trace_unsynchronized
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\std\src\..\..\backtrace\src\backtrace\mod.rs:66
         2: std::backtrace::Backtrace::create
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\std\src\backtrace.rs:331
         3: std::backtrace::Backtrace::capture
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\std\src\backtrace.rs:296
         4: <anyhow::Error>::msg::<alloc::string::String>
         5: <documentation_examples_rust_tests::workspace::ExampleWorkspace>::build
         6: documentation_examples_rust_tests::aliased_dependency_example_compiles_and_runs::{closure#0}
         7: documentation_examples_rust_tests::aliased_dependency_example_compiles_and_runs::{closure#0}
         8: <documentation_examples_rust_tests::aliased_dependency_example_compiles_and_runs::{closure#0} as core::ops::function::FnOnce<()>>::call_once
         9: core::ops::function::FnOnce::call_once
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\core\src\ops\function.rs:250
        10: test::__rust_begin_short_backtrace<enum2$<core::result::Result<tuple$<>,alloc::string::String> >,enum2$<core::result::Result<tuple$<>,alloc::string::String> > (*)()>
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\test\src\lib.rs:648
        11: test::run_test_in_process
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\test\src\lib.rs:671
        12: test::run_test::closure$0
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\test\src\lib.rs:592
        13: test::run_test::closure$1
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\test\src\lib.rs:622
        14: std::sys::backtrace::__rust_begin_short_backtrace<test::run_test::closure_env$1,tuple$<> >
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\std\src\sys\backtrace.rs:152
        15: core::ops::function::FnOnce::call_once<std::thread::impl$0::spawn_unchecked_::closure_env$1<test::run_test::closure_env$1,tuple$<> >,tuple$<> >
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\core\src\ops\function.rs:250
        16: alloc::boxed::impl$28::call_once
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\alloc\src\boxed.rs:1966
        17: alloc::boxed::impl$28::call_once
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\alloc\src\boxed.rs:1966
        18: std::sys::pal::windows::thread::impl$0::new::thread_start
                   at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\std\src\sys\pal\windows\thread.rs:60
        19: BaseThreadInitThunk
        20: RtlUserThreadStart
  
    Cancelling due to test failure: 3 tests still running
          SLOW [> 60.000s] (───────) cargo-orthohelp::rstest_bdd rstest_bdd::behaviour::scenarios::orthohelp_ir_feature_scenarios::orthohelp_ir_generate_per_locale_ir_json
          PASS [  71.324s] (659/979) cargo-orthohelp::rstest_bdd rstest_bdd::behaviour::scenarios::orthohelp_ir_feature_scenarios::orthohelp_ir_generate_per_locale_ir_json
          SLOW [>240.000s] (───────) ortho_config::crate_path_trybuild crate_path_alias_compiles
          PASS [ 271.035s] (660/979) ortho_config::crate_path_trybuild crate_path_alias_compiles
          SLOW [>120.000s] (───────) ortho_config::declarative_merge_trybuild declarative_merge_compiles_with_collection_strategies
          PASS [ 122.944s] (661/979) ortho_config::declarative_merge_trybuild declarative_merge_compiles_with_collection_strategies
  ────────────
       Summary [ 486.146s] 661/979 tests run: 660 passed (11 slow), 1 failed, 0 skipped
          FAIL [   0.571s] (658/979) ortho_config::documentation_examples_rust_tests aliased_dependency_example_compiles_and_runs
  warning: 318/979 tests were not run due to test failure (run with --no-fail-fast to run all tests, or run with --max-fail)
  error: test run failed

buzzybee-df12 · 2026-08-11T21:48:53Z

@coderabbitai review

coderabbitai · 2026-08-11T21:49:02Z

✅ 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.

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ortho_config/tests/documentation_examples/cargo_runner.rs`:
- Around line 81-86: In the conditional Windows MSVC x86_64 branch of the cargo
environment preparation function, replace the explicit return in the block with
prepare_msvc_environment(state_directory) as the block’s tail expression,
preserving the non-Windows default path.

In `@ortho_config/tests/documentation_examples/mod.rs`:
- Around line 46-47: Preserve the exact source line endings when constructing
`DocumentedExample::body`; avoid using `contents.lines()` and unconditional LF
joins that strip CRLF terminators. Update the related extraction paths at the
indicated locations to retain original terminators, or explicitly normalize to
LF and add a CRLF regression test documenting that behavior.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d3151a38-f5e7-4c1d-bbfb-96e79904d562

📥 Commits

Reviewing files that changed from the base of the PR and between 09e1424 and 6d120ec.

📒 Files selected for processing (9)

docs/developers-guide.md
docs/execplans/prepare-v0-9-0-user-documentation.md
docs/users-guide.md
ortho_config/tests/documentation_examples/cargo_runner.rs
ortho_config/tests/documentation_examples/mod.rs
ortho_config/tests/documentation_examples/workspace.rs
ortho_config/tests/documentation_examples_loader_tests.rs
ortho_config/tests/documentation_examples_rust_tests.rs
ortho_config/tests/documentation_examples_tests.rs

🔗 Linked repositories identified

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

leynos/weaver (auto-detected)
leynos/netsuke (auto-detected)
leynos/rstest-bdd (auto-detected)

Use a tail expression for Windows MSVC Cargo environment preparation and make the loader's canonical LF body representation explicit with CRLF regression coverage.

buzzybee-df12 · 2026-08-12T01:40:11Z

@coderabbitai review

coderabbitai · 2026-08-12T01:40:17Z

✅ 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.

Capture Cargo, host-tool, and documented-binary output through fixed-size buffers and terminate children that exceed the shared test deadline. Cover output truncation and timeout handling so documentation checks cannot consume unbounded memory or wait indefinitely.

leynos · 2026-08-12T02:53:03Z

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

ortho_config/tests/documentation_examples/process_runner.rs

Comment on file

//! Bounded subprocess execution for executable documentation tests.

❌ New issue: String Heavy Function Arguments
In this module, 42.1% of all arguments to its 9 functions are strings. The threshold for string arguments is 39.0%

leynos · 2026-08-12T02:53:36Z

@coderabbitai Have the following failed checks now been resolved?

If further work is required, please provide an AI agent prompt for the remaining work to be done to address these failures.

Do not treat warnings as optional or aspirational. Where a change is out of scope for this PR, propose a GitHub issue unless one exists already. (Treat o11y, code safety, documentation and validation coverage as in scope).

❌ Failed checks (1 warning, 6 inconclusive)

Check name	Status	Explanation	Resolution
Performance And Resource Use	⚠️ Warning	New test runners use Command::output() for Cargo and documented binaries without output limits or timeouts, so child output and wait time can grow unbounded (workspace.rs:100,184; cargo_runner.rs:1...	Capture stdout and stderr through fixed-size readers and enforce a bounded child timeout; apply the same limits to Cargo and MSVC discovery commands.

Distinguish operation descriptions from raw command arguments and model the closed stdout and stderr set explicitly in documentation test runners. Preserve existing diagnostic text and keep Rust test-harness selectors as plain strings.

codescene-access

No quality gates enabled for this code.