Add agent-context output to cargo-orthohelp (6.2.1)#342
Merged
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (5)
👮 Files not reviewed due to content moderation or server errors (5)
SummaryThis pull request implements roadmap item 6.2.1 by adding a new Key ChangesCore Implementation:
Design Decisions:
Testing Coverage:
Observability & Safety:
Documentation UpdatesRelated design documents were updated to reflect the new capability:
Review OutcomesThe extensive iterative review addressed:
ValidationPassing: WalkthroughImplement --format agent-context end-to-end: add optional command summaries to the schema, implement an IR→AgentContext transformer producing deterministic flattened command paths and inputs, wire CLI and EN‑US localiser gating, atomically write pretty JSON to /agent-context.json with concurrency safety, and validate via unit, proptest, golden and BDD tests plus documentation. ChangesAgent-context generation feature
Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 20✅ Passed checks (20 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Contributor
Reviewer's GuideExecPlan-only PR that adds a detailed execution plan document for roadmap item 6.2.1, specifying how a new Sequence diagram for cargo-orthohelp --format agent-context executionsequenceDiagram
actor User
participant CLI as cargo_orthohelp::cli
participant Main as main::run
participant Bridge as bridge::load_or_build_ir
participant Xform as agent_context::bridge_ir_to_agent_context
participant Output as output::write_agent_context
User->>CLI: parse --format agent-context
CLI->>Main: OutputFormat::AgentContext
Main->>Bridge: load_or_build_ir()
Bridge-->>Main: DocMetadata
Main->>Xform: bridge_ir_to_agent_context(DocMetadata, package, localizer)
Xform-->>Main: AgentContext
Main->>Output: write_agent_context(out_dir, AgentContext)
Output-->>User: agent-context.json path
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b02c0c17e0
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Owner
|
@coderabbitai pause |
Contributor
✅ Action performedReviews paused. |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Owner
|
@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. cargo-orthohelp/tests/rstest_bdd/behaviour/steps_agent_context.rs Comment on file //! Agent-context JSON step definitions for `cargo-orthohelp` behavioural tests.
❌ New issue: String Heavy Function Arguments |
This comment was marked as resolved.
This comment was marked as resolved.
lodyai
Bot
force-pushed
the
6-2-1-cargo-orthohelp-agent-context-format
branch
from
25baf04 to
5e67bc9
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Owner
|
@coderabbitai resume |
Contributor
✅ Action performedReviews resumed. |
Add the execution plan for roadmap item 6.2.1, "Add `--format agent-context` to `cargo-orthohelp`". The plan covers the bridge-IR-to- agent-context transform, the new CLI variant, the single-file emitter at `<out_dir>/agent-context.json`, and the documentation updates. The plan incorporates the Logisphere community-of-experts review: - Scope the schema change to a single additive `summary: Option<String>` field on `AgentCommand`. Do not introduce an `AgentInput.kind` field; detect positional inputs from existing `CliMetadata` data instead. - Exclude `agent-context` from `--format all` until later items lock the schema version and populate the semantic fields that currently default to `unknown`. - Sort commands by path and inputs by name inside the transform so the golden snapshot stays stable without redactions. - Narrow `proptest` coverage to a single uniqueness invariant on command paths. - Document explicitly that `interaction_mode`, `mutation_effect`, and `policy.agent_native` are placeholders pending later roadmap items. Plan status: DRAFT. Implementation is gated on maintainer approval.
Add the optional `AgentCommand.summary` field to the reusable agent-context schema and cover its omission, preservation, and legacy defaulting behaviour. Record the cargo-orthohelp transform expectation for concise en-US summaries and update the active ExecPlan with Milestone 1 validation evidence.
Add `agent-context` to the supported `--format` values and cover the parser surface with a positive test, preserved invalid-value coverage, and the existing property strategy. Update the active ExecPlan with Milestone 2 validation and CodeRabbit review evidence.
Add the bridge from documentation metadata into the compact `AgentContext` schema, including deterministic command and input ordering. Wire `--format agent-context` through the CLI runner and output writer so it writes `agent-context.json` without requiring localized IR generation. Record the Milestone 3 validation, CodeRabbit review findings, rate-limit retries, and final clean review in the execplan.
Add focused unit coverage for command flattening, summaries, canonical verbs, visible CLI inputs, positional inputs, and summary omission cases. Add a proptest invariant that generated metadata trees produce unique command paths without relying on rejection filtering. Record the Milestone 4 gates, CodeRabbit finding, rate-limit retries, and clean follow-up review in the execplan.
Add an rstest-bdd scenario that exercises cargo-orthohelp with `--format agent-context` against the fixture and verifies the generated `agent-context.json` shape. Add a focused golden snapshot test for the fixture output so the exact agent-context JSON remains stable across future transformer changes. Record the Milestone 5 gate results, CodeRabbit follow-up, and snapshot test layout decision in the execplan.
Update the user and developer guides for the implemented `cargo orthohelp --format agent-context` flow, including the generated `agent-context.json` path, non-localized summary rule, and positional input convention. Refresh the cargo-orthohelp and agent-native design notes so compact agent-context output is no longer described as missing, while still leaving JSON status, policy reporting, and agent-native linting as future work. Record the Milestone 6 validation and clean CodeRabbit review in the execplan.
Mark roadmap item 6.2.1 and its sub-items complete now that `cargo-orthohelp --format agent-context` is implemented, documented, and covered by behavioural and golden tests. Close the execplan with final outcomes, full gate results, and the clean CodeRabbit review.
Update the completed execplan constraint so it matches the implemented adapter boundary: an en-US Localizer may be passed only for the short command summary used by agent command selection. Keep the non-localized agent-context rule intact for Fluent identifiers, long help, and any other locale-specific behaviour.
Remove an extra blank line introduced while resolving the rebase so the Markdown gate remains clean after replaying the branch on main.
Replace stringly JSON field identifiers in the agent-context BDD assertion helpers with a local `JsonField` enum. Keep assertion values and step text unchanged while reducing the helper argument string ratio that CodeScene reports.
lodyai
Bot
force-pushed
the
6-2-1-cargo-orthohelp-agent-context-format
branch
from
f8a0722 to
cd55ba5
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Owner
|
@coderabbitai resume |
Contributor
✅ Action performedReviews resumed. |
Tighten `temp_file_open_fails_when_file_already_exists` to assert the returned `OrthohelpError::Io` wraps a `std::io::Error` whose kind is `ErrorKind::AlreadyExists`, matching its sibling `temp_file_collision_fails_hard`. The previous `result.is_err()` check would have passed on an unrelated failure (a `NotFound` or permission error), so it did not actually prove the `create_new(true)` collision path.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@cargo-orthohelp/src/output.rs`:
- Around line 328-331: The test currently only checks that
open_agent_context_temp_file(...) returns Err but doesn't verify the error kind;
update the assertion in this test to mirror temp_file_collision_fails_hard by
checking that the returned io::Error kind is io::ErrorKind::AlreadyExists (e.g.,
unwrap the Err and assert the error.kind() == io::ErrorKind::AlreadyExists or
use matches!) so permission or other I/O errors won't be treated as a passing
collision case; reference open_agent_context_temp_file and the test name
temp_file_collision_fails_hard when locating the failing assertion to change.
🪄 Autofix (Beta)
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: 28d7e0ac-619a-476b-adab-5fe7bfaa5b4e
📒 Files selected for processing (1)
cargo-orthohelp/src/output.rs
Owner
|
@coderabbitai review |
Contributor
✅ Action performedReview finished.
|
Owner
|
@coderabbitai review |
Contributor
✅ Action performedReview finished.
|
Contributor
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
echo "=== cargo-orthohelp/src/output.rs ==="
cat cargo-orthohelp/src/output.rs
echo ""
echo "=== Key markers ==="
rg -n "create_new|create(true)|truncate|debug!|tracing::|collision|temp_file_open_fails|AlreadyExists|ambient_authority" cargo-orthohelp/src/output.rsLength of output: 13858
Note: Line 37 ( |
Owner
|
@coderabbitai resume |
Contributor
✅ Action performedReviews resumed. |
Document `agent-context` in the cargo-orthohelp README, add debug traces for skipped generation and package-aware writer diagnostics, and record the temp counter invariants that keep concurrent manifest writes collision-resistant.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
cargo-orthohelp/README.md (1)
19-25: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick winVary sentence structure to improve readability.
Four consecutive sentences begin with "It," reducing flow. Rework the numbered list to vary structure whilst preserving clarity.
♻️ Proposed rewrite
## How it works -1. It discovers your package and root config type from Cargo metadata or CLI - flags. -2. It builds a tiny bridge binary that calls - `OrthoConfigDocs::get_doc_metadata()`. -3. It resolves Fluent message IDs for each requested locale. -4. It emits localized IR JSON, roff man pages, PowerShell external help, - compact agent-context JSON, or all formats. +1. Discovers your package and root config type from Cargo metadata or CLI + flags. +2. Builds a tiny bridge binary that calls + `OrthoConfigDocs::get_doc_metadata()`. +3. Resolves Fluent message IDs for each requested locale. +4. Emits localised IR JSON, roff man pages, PowerShell external help, + compact agent-context JSON, or all formats.Triage:
[type:docstyle]🤖 Prompt for 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. In `@cargo-orthohelp/README.md` around lines 19 - 25, Rewrite the four-item numbered list so each line varies its sentence structure while keeping the same meaning: e.g., start items with verbs or descriptive phrases instead of repeating "It" — reference the existing concepts like discovering package/root config via Cargo metadata or CLI flags, building a tiny bridge binary that calls OrthoConfigDocs::get_doc_metadata(), resolving Fluent message IDs for each requested locale, and emitting localized IR JSON, roff man pages, PowerShell external help, compact agent-context JSON, or all formats; keep the numbered sequence and concise wording but vary the openings (e.g., "Discovers...", "Builds...", "Resolves...", "Emits..." or use gerunds/clauses) to improve flow and readability.cargo-orthohelp/src/main.rs (1)
88-90:⚠️ Potential issue | 🟠 Major | ⚡ Quick winGate locale resolution behind the human-output formats.
Line 90 still resolves locales before the format gate, so any locale parsing or
selection failure aborts--format agent-contexteven though that artefact is
explicitly non-localized. Movelocale::resolve_locales(...)behind the
Ir | Man | Pspath, or resolve it insidelocalize_docs_if_requested.Patch
- let locales = locale::resolve_locales(&args, &selection)?; - let out_dir = resolve_out_dir(args.out_dir.clone(), &selection); @@ let should_generate_ir = matches!(args.format, OutputFormat::Ir | OutputFormat::All); let should_generate_man = matches!(args.format, OutputFormat::Man | OutputFormat::All); let should_generate_ps = matches!(args.format, OutputFormat::Ps | OutputFormat::All); + let should_generate_localized_docs = + should_generate_ir || should_generate_man || should_generate_ps; + let locales = if should_generate_localized_docs { + locale::resolve_locales(&args, &selection)? + } else { + Vec::new() + }; generate_agent_context_if_requested(&args, &selection, &doc_metadata, &out_dir)?; let localized_docs = localize_docs_if_requested( - should_generate_ir || should_generate_man || should_generate_ps, + should_generate_localized_docs, &selection, &doc_metadata, &locales, )?;Based on learnings: "The agent-context output must ... be non-localized" and
the PR objective to gate localisation on requested formats.🤖 Prompt for 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. In `@cargo-orthohelp/src/main.rs` around lines 88 - 90, Move locale resolution out from the top-level flow so locale::resolve_locales(&args, &selection) is only called when we will actually generate localized artifacts: compute should_generate_ir/man/ps using matches!(args.format, OutputFormat::Ir | OutputFormat::All) etc., combine into should_generate_localized_docs = should_generate_ir || should_generate_man || should_generate_ps, then call locale::resolve_locales(...) only if should_generate_localized_docs (otherwise use an empty Vec); update the call to localize_docs_if_requested to take should_generate_localized_docs (instead of recomputing the expression) and leave generate_agent_context_if_requested(...) before any locale work so agent-context remains non-localized — adjust variables around metadata::load_metadata(), metadata::select_package(), resolve_out_dir(), doc_metadata, and localize_docs_if_requested accordingly.Source: Learnings
🤖 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 `@cargo-orthohelp/README.md`:
- Around line 32-33: Reword the README line that lists "PowerShell help (`ps`),
compact agent-context JSON (`agent-context`), or all formats (`all`)" to make
explicit that `--format all` does NOT include `agent-context`; update the
phrasing to something like "PowerShell help (`ps`), compact agent-context JSON
(`agent-context`), or all output formats (`all`) — note: `--format all`
currently excludes `agent-context` until schema versioning is locked" so readers
know `agent-context` is intentionally excluded from `--format all`.
---
Outside diff comments:
In `@cargo-orthohelp/README.md`:
- Around line 19-25: Rewrite the four-item numbered list so each line varies its
sentence structure while keeping the same meaning: e.g., start items with verbs
or descriptive phrases instead of repeating "It" — reference the existing
concepts like discovering package/root config via Cargo metadata or CLI flags,
building a tiny bridge binary that calls OrthoConfigDocs::get_doc_metadata(),
resolving Fluent message IDs for each requested locale, and emitting localized
IR JSON, roff man pages, PowerShell external help, compact agent-context JSON,
or all formats; keep the numbered sequence and concise wording but vary the
openings (e.g., "Discovers...", "Builds...", "Resolves...", "Emits..." or use
gerunds/clauses) to improve flow and readability.
In `@cargo-orthohelp/src/main.rs`:
- Around line 88-90: Move locale resolution out from the top-level flow so
locale::resolve_locales(&args, &selection) is only called when we will actually
generate localized artifacts: compute should_generate_ir/man/ps using
matches!(args.format, OutputFormat::Ir | OutputFormat::All) etc., combine into
should_generate_localized_docs = should_generate_ir || should_generate_man ||
should_generate_ps, then call locale::resolve_locales(...) only if
should_generate_localized_docs (otherwise use an empty Vec); update the call to
localize_docs_if_requested to take should_generate_localized_docs (instead of
recomputing the expression) and leave generate_agent_context_if_requested(...)
before any locale work so agent-context remains non-localized — adjust variables
around metadata::load_metadata(), metadata::select_package(), resolve_out_dir(),
doc_metadata, and localize_docs_if_requested accordingly.
🪄 Autofix (Beta)
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: 6fa68212-1663-4caa-8646-7f4dcfc1bd96
📒 Files selected for processing (3)
cargo-orthohelp/README.mdcargo-orthohelp/src/main.rscargo-orthohelp/src/output.rs
Document that `--format all` excludes `agent-context` while the schema is still being locked. Defer locale resolution until a localized output format is actually requested so agent-context-only generation remains non-localized.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Owner
|
@coderabbitai resume |
Contributor
✅ Action performedReviews resumed. |
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
Add the 6.2.1 public API signatures to the developer guide so the stable agent-context surface is discoverable from the documentation. Add a trybuild compile-fail test that records the compiler enforcement path for ignored `#[must_use]` return values.
Contributor
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
echo "=== docs/developers-guide.md (agent-context section) ==="
grep -n "bridge_ir_to_agent_context\|write_agent_context\|OutputFormat::AgentContext\|Public API\|### Public API" docs/developers-guide.md | head -40
echo ""
echo "=== docs/developers-guide.md lines around agent-context section ==="
grep -n "agent.context\|Generating agent" docs/developers-guide.md | head -20
echo ""
echo "=== cargo-orthohelp/Cargo.toml dev-dependencies ==="
grep -n "trybuild" cargo-orthohelp/Cargo.toml || echo "trybuild absent"
echo ""
echo "=== trybuild tests ==="
fd -e rs . cargo-orthohelp/tests/ 2>/dev/null | sort | head -30
echo ""
echo "=== cargo-orthohelp/tests/compile_time.rs ==="
cat cargo-orthohelp/tests/compile_time.rs 2>/dev/null || echo "FILE NOT FOUND"
echo ""
echo "=== cargo-orthohelp/tests/ui/ ==="
ls cargo-orthohelp/tests/ui/ 2>/dev/null || echo "DIR NOT FOUND"
echo ""
echo "=== PR description ==="
gh pr view 342 --json title,body --jq '.body' | head -40Length of output: 6035
No further work is required on this PR. |
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This pull request delivers the full implementation of roadmap item 6.2.1: "Add
--format agent-contexttocargo-orthohelp".The branch contains the execution plan, production code, tests, and documentation updates.
The implementation extends
cargo-orthohelpwith a new--format agent-contextoutput that emits a compact, machine-oriented JSON manifest of the CLI command tree for LLM agents. The bridge IR, existing--format ir|man|ps|alloutputs, and theOrthoConfigDocsderive contract remain unchanged.Roadmap task: 6.2.1
What ships
ortho_config::agent_context::AgentCommandgainssummary: Option<String>(additive, serde-safe).cargo_orthohelp::agent_context::bridge_ir_to_agent_context(meta: &DocMetadata, package: &str, localizer: Option<&dyn Localizer>) -> AgentContextcargo_orthohelp::output::write_agent_context(out_dir: &Utf8Path, payload: &AgentContext) -> Result<Utf8PathBuf, OrthohelpError>— atomic write via PID+counter temp file and rename.OutputFormat::AgentContextvariant;--format agent-contextaccepted by clap.Key design decisions
CliMetadata; noAgentInput.kindextension.--format allremainsir + man + ps;agent-contextexcluded until 6.2.2 locks the schema version.<out_dir>/agent-context.json; no per-locale layout.interaction_mode,mutation_effect,policy.agent_nativeleft at schema defaults for v1.create_new(true)+AtomicU64counter enforces collision hard-failure and concurrent-write safety.sync_parent_dirstub carries#[expect(clippy::unnecessary_wraps)]to preserve signature parity.Validation
make lint && cargo test --workspaceReferences