feat(xtask): add docs-sync and examples smoke#290
Conversation
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (3)
WalkthroughThis pull request introduces a documentation synchronization system for automated README maintenance. It adds a structured metadata file containing workspace crates, adapter information, examples, and feature matrices, along with a new xtask module that parses this metadata and regenerates README sections delimited by HTML comments. Two CLI subcommands manage and validate the documentation generation process. Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant CLI as xtask CLI
participant DocSync as docs_sync Module
participant MetaFile as workspace-docs.json
participant README as README.md
User->>CLI: docs-sync --check
CLI->>DocSync: docs_sync_cmd(check=true)
DocSync->>MetaFile: Load and parse metadata
MetaFile-->>DocSync: Structured data (crates, examples, matrices)
DocSync->>DocSync: Render markdown tables from metadata
DocSync->>README: Locate sync markers
README-->>DocSync: Marker positions
DocSync->>DocSync: Compare current vs. generated content
alt Content matches
DocSync-->>CLI: ✓ Check passed
else Content differs
DocSync-->>CLI: ✗ Check failed (dry-run in check mode)
end
CLI-->>User: Exit status
sequenceDiagram
actor User
participant CLI as xtask CLI
participant ExampleSmoke as examples_smoke_cmd
participant DocSync as docs_sync Module
participant CargoBuild as cargo check/run
participant Examples as example .rs files
User->>CLI: examples-smoke --run
CLI->>ExampleSmoke: examples_smoke_cmd(run=true)
ExampleSmoke->>DocSync: docs_sync_cmd(check=true)
DocSync->>DocSync: Validate README consistency
ExampleSmoke->>Examples: List example files in crates/uselesskey/examples
Examples-->>ExampleSmoke: File list
ExampleSmoke->>ExampleSmoke: Cross-check against metadata entries
alt Mismatches found
ExampleSmoke-->>CLI: ✗ Validation failed
else All match
ExampleSmoke->>CargoBuild: cargo check (each example)
CargoBuild-->>ExampleSmoke: ✓ Check results
alt run=true and run_smoke=true
ExampleSmoke->>CargoBuild: cargo run (each enabled example)
CargoBuild-->>ExampleSmoke: Execution results
end
ExampleSmoke-->>CLI: ✓ Smoke tests passed
end
CLI-->>User: Exit status
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/metadata/workspace-docs.json`:
- Around line 299-305: The "extra_features" field currently contains the literal
"-" which is rendered as code-formatted `-` instead of the empty-state glyph;
change the value of the extra_features property for the "uselesskey-ring"
adapter from "-" to an empty string "" so xtask/src/docs_sync.rs (which maps
empty extra_features to the normal glyph) will render the correct empty-state;
update the JSON entry where "adapter": "uselesskey-ring" and "extra_features"
appear accordingly.
In `@xtask/src/docs_sync.rs`:
- Around line 144-152: The Markdown fences need blank lines around them; in the
loop over metadata.dependency_snippets replace the two-step write
(writeln!(output, " ```toml\n{}", indent_lines(...)) and the subsequent
output.push_str(" ```\n\n")) with a single writeln! that writes the opening
fence, the indented snippet, and the closing fence with trailing blank line (use
the format string " ```toml\n{}\n ```\n" and pass indent_lines(&item.snippet,
" ")), and remove the separate output.push_str call so each list item gets
blank lines before and after its fenced snippet.
- Around line 287-329: In validate_examples_match_workspace, add validation over
metadata.runnable_examples to 1) detect duplicate paths (use a HashSet/BTreeSet
to track normalized entry.path and push an error if an entry.path is already
seen) and 2) verify each entry.name equals the file stem of entry.path (use
Path::new(&entry.path).file_stem().and_then(|s| s.to_str()) and push an error on
mismatch); include these errors in the same errors Vec and bail with them like
the existing filesystem/metadata drift messages so duplicates or mismatched
names are rejected before compile_example runs.
- Around line 266-274: The function compile_example uses cargo check which
doesn't perform codegen/linking; change the cargo invocation in compile_example
to use "build" instead of "check" (i.e., call cargo build --example <name> with
the same flags such as -p, --no-default-features and optional --features when
example.feature_set is non-empty) so examples are fully compiled and linked;
keep the existing crate::run(...) and with_context(...) error handling
unchanged.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 5c87ca94-9bb2-4a74-98c9-2b698fcd9de5
📒 Files selected for processing (4)
README.mddocs/metadata/workspace-docs.jsonxtask/src/docs_sync.rsxtask/src/main.rs
| for item in &metadata.dependency_snippets { | ||
| writeln!(output, "- **{}**", item.name).expect("write to string"); | ||
| writeln!( | ||
| output, | ||
| " ```toml\n{}", | ||
| indent_lines(&item.snippet, " ") | ||
| ) | ||
| .expect("write to string"); | ||
| output.push_str(" ```\n\n"); |
There was a problem hiding this comment.
Generate blank lines around the fenced snippets.
These blocks currently regenerate README.md with MD031 warnings because the fence starts immediately after the list item text.
🔧 Proposed fix
for item in &metadata.dependency_snippets {
- writeln!(output, "- **{}**", item.name).expect("write to string");
+ writeln!(output, "- **{}**\n", item.name).expect("write to string");
writeln!(
output,
- " ```toml\n{}",
+ " ```toml\n{}\n ```\n",
indent_lines(&item.snippet, " ")
)
.expect("write to string");
- output.push_str(" ```\n\n");
}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@xtask/src/docs_sync.rs` around lines 144 - 152, The Markdown fences need
blank lines around them; in the loop over metadata.dependency_snippets replace
the two-step write (writeln!(output, " ```toml\n{}", indent_lines(...)) and the
subsequent output.push_str(" ```\n\n")) with a single writeln! that writes the
opening fence, the indented snippet, and the closing fence with trailing blank
line (use the format string " ```toml\n{}\n ```\n" and pass
indent_lines(&item.snippet, " ")), and remove the separate output.push_str call
so each list item gets blank lines before and after its fenced snippet.
Summary
xtask docs-syncto generate README tables fromdocs/metadata/workspace-docs.json.xtask examples-smoketo validate example metadata, compile every runnable example, and optionally run curated smoke examples.docs/metadata/workspace-docs.json.xtaskcommand dispatch.Validation
cargo xtask docs-sync --checkcargo xtask examples-smokecargo xtask examples-smoke --runScope guardrail
Only
docs/metadata/*,xtask/src/main.rs, andxtask/src/docs_sync.rsare changed.