feat(spec): parse usage comments from strings

[jdx]

Summary

• add Spec::parse_script_str for parsing embedded USAGE comments from an in-memory script
• preserve file-backed parsing diagnostics and filename inference
• correct the documented supported USAGE comment markers
• add coverage for parsing a complete script string

This gives embedders a direct Rust API without requiring a temporary file or deserializing Spec.

Closes #781.

Validation

• cargo test -p usage-lib --all-features
• cargo clippy -p usage-lib --all-features -- -D warnings

---

Note

Low Risk
Additive public API and clearer errors in spec parsing only; no auth, I/O, or runtime behavior changes beyond new entry points.

Overview
Adds Spec::parse_script_str so embedders can turn a script body into a Spec without writing a temp file or hand-parsing KDL. File-based parse_script now shares parse_script_with_path with the string API; only the file path still drives default bin/name inference.

String parsing uses an empty source path, so relative include paths fail with "relative includes require a source file" instead of a parent-directory error. Docs now describe the real markers (#USAGE, //USAGE, ::USAGE, and [USAGE] variants) rather than # USAGE:.

Tests cover a full embedded script and the relative-include rejection.

^{Reviewed by Cursor Bugbot for commit 4cc4e74. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features

  • Added support for extracting usage specifications from #USAGE, //USAGE, ::USAGE, and [USAGE] markers.
  • Added a public API for parsing embedded usage specifications directly from strings.
  • String-based parsing now supports absolute includes without requiring filename-based defaults.

• Bug Fixes

  • Improved script parsing consistency across supported usage-marker formats.
  • Added validation to reject unsupported relative includes when parsing strings.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Script usage parsing

Layer / File(s)	Summary
Usage marker extraction and parser delegation lib/src/spec/mod.rs	Documentation lists #USAGE, //USAGE, ::USAGE, and [USAGE] markers. parse_script delegates parsing to a shared path-aware helper.
String parsing API and validation lib/src/spec/mod.rs	Spec::parse_script_str parses usage specifications from strings without filename-derived defaults. Relative includes return a source-path error. Tests cover parsed values and this error.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ScriptString
  participant parse_script_str
  participant SharedParser
  participant Spec
  ScriptString->>parse_script_str: raw script input
  parse_script_str->>SharedParser: extract usage markers
  SharedParser->>Spec: parse usage specification
  Spec-->>parse_script_str: Spec or UsageErr

Loading

Poem

I’m a rabbit with scripts in my nest,
#USAGE markers now parse at their best.
From strings they emerge,
With flags in a surge,
And clean Spec results pass every test.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR adds the requested public API for parsing USAGE comments from in-memory script strings [#781].
Out of Scope Changes check	✅ Passed	The marker fixes, include validation, diagnostics, filename behavior, and tests directly support string-based script parsing.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding string-based parsing for usage comments.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▂▂▁▂▇▇▇█▇▇	110,500,751 → 110,483,839	-0.02%	10.47 → 10.75ms	+2.71%
startup	▁▃█▄▄▅▃██▃	1,197,833 → 1,195,781	-0.17%	0.92 → 0.98ms	+6.11%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

_{4cc4e7421706 vs 37e8bd3608a5 · measured on the runner, not pushed to the history.}

[greptile-apps]

Greptile Summary

Adds an in-memory script parsing API while preserving file-backed parsing behavior and diagnostics.

• Introduces Spec::parse_script_str and a shared parsing helper.
• Rejects relative includes when no source path is available while retaining absolute includes.
• Corrects documentation for supported USAGE markers and adds regression coverage.

Confidence Score: 5/5

The PR appears safe to merge.

The previously reported relative-include issue is fixed, and no blocking failure remains.

Important Files Changed

Filename	Overview
lib/src/spec/mod.rs	Adds string-backed script parsing and correctly closes the previously reported ambient-working-directory include behavior by rejecting relative includes without a source path.

_{Reviews (2): Last reviewed commit: "fix(spec): reject relative string includ..." | Re-trigger Greptile}

[coderabbitai]

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 `@lib/src/spec/mod.rs`:
- Around line 129-144: Fix parse_script_str and parse_script_with_path so
relative include directives resolve from the intended base path rather than the
repository root. Prefer extending the string-spec API to accept an explicit base
path and pass it into ParsingContext; otherwise keep parse_script_str pathless
and explicitly reject or document relative includes for it, while preserving
path-based resolution in parse_script_with_path.

🪄 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: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: f5430be9-5f91-4dda-948d-32147454ef5e

📥 Commits

Reviewing files that changed from the base of the PR and between f3f9761 and f47fe0d.

📒 Files selected for processing (1)

• lib/src/spec/mod.rs