feat(parse): add Parser builder for custom env var handling

[jdx]

Summary

• Adds a Parser struct that allows customizing parsing behavior
• Particularly useful for providing a custom environment variable map instead of using the process environment

This is needed for tools like mise where monorepo tasks may have env vars defined in child config files that aren't in the current process environment.

Example usage

use std::collections::HashMap;
use usage::parse::Parser;

let env: HashMap<String, String> = [("NAME".into(), "john".into())].into();
let result = Parser::new(&spec)
    .with_env(env)
    .parse(&args)?;

The existing parse() function is unchanged and continues to work as before (it now uses Parser internally with default options).

API Design

The Parser struct uses #[non_exhaustive] to allow adding new options in the future without breaking changes.

🤖 Generated with Claude Code

---

Note

Introduce Parser for customizable parsing

• Export new parse::Parser with with_env to supply a custom HashMap<String, String> for env lookups; parse() now delegates to Parser
• Refactor parse_partial into internal parse_partial_with_env and update required arg/flag validation to consider the custom env map before std::env
• Preserve existing behavior by default (process env) while enabling monorepo/task workflows needing non-process env vars
• Add tests covering custom env for required args/flags, precedence, and error cases

Public API: Parser exported via lib.rs

^{Written by Cursor Bugbot for commit 6294833. This will update automatically on new commits. Configure here.}

[Copilot]

Pull request overview

This PR introduces a Parser builder pattern to enable custom environment variable handling during command-line parsing. The primary motivation is to support tools like mise where monorepo tasks may define environment variables in child config files rather than the process environment.

Changes:

• Added a Parser struct with a builder pattern for configurable parsing options
• Modified the existing parse() function to use Parser internally while maintaining backward compatibility
• Exported the new Parser type from the library's public API

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
lib/src/parse.rs	Implements the Parser builder struct with with_env() method and refactors environment variable lookups to use either custom or process environment
lib/src/lib.rs	Exports the new Parser type alongside the existing parse function

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The get_env closure is defined inside the parse method but could be extracted as a private method on Parser. This would improve readability and make the logic easier to test independently. Consider adding a method like fn get_env_var(&self, key: &str) -> Option<String>.

[codecov]

Codecov Report

❌ Patch coverage is 42.92035% with 129 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.43%. Comparing base (6125f1f) to head (6294833).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/src/parse.rs	42.92%	66 Missing and 63 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #464      +/-   ##
==========================================
- Coverage   76.50%   71.43%   -5.08%     
==========================================
  Files          47       47              
  Lines        6253     6480     +227     
  Branches     6253     6480     +227     
==========================================
- Hits         4784     4629     -155     
- Misses       1110     1238     +128     
- Partials      359      613     +254     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cursor]

Custom env map ignored during required arg/flag validation

Medium Severity

When using Parser::with_env() with a custom environment map, required args/flags that have env vars defined will incorrectly fail validation if the env var exists in the custom map but not in the process environment. The parse_partial function validates required args/flags by checking std::env::var() directly (ignoring the custom env map), and adds MissingArg/MissingFlag errors before Parser::parse applies the custom env values. These errors then cause the parse to fail even though the env var would have been resolved correctly from the custom map.

 

[jdx]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR