fix(lambda-rs-args): Optimize parsed argument lookup and positional argument assignment

[vmarcella]

Summary

Speed up lambda-rs-args parsing results and improve docs to match lambda-rs rustdoc conventions.

Related Issues

Relates to: (none)

Changes

• Build an index for ParsedArgs so has() / get_*() are O(1) by name instead of scanning.
• Track a positional cursor so positional assignment after -- is O(p) total instead of O(p^2).
• Update rustdoc for the touched APIs/helpers using # Arguments / # Returns / # Errors / # Panics sections.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• Feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation (updates to docs, specs, tutorials, or comments)
• Refactor (code change that neither fixes a bug nor adds a feature)
• Performance (change that improves performance)
• Test (adding or updating tests)
• Build/CI (changes to build process or CI configuration)

Affected Crates

• lambda-rs
• lambda-rs-platform
• lambda-rs-args
• lambda-rs-logging
• Other:

Checklist

• Code follows the repository style guidelines (cargo +nightly fmt --all)
• Code passes clippy (cargo clippy --workspace --all-targets -- -D warnings)
• Tests pass (cargo test --workspace)
• New code includes appropriate documentation
• Public API changes are documented
• Breaking changes are noted in this PR description

Testing

Commands run:

cargo test -p lambda-rs-args

Manual verification steps (if applicable):

1. N/A

Screenshots/Recordings

N/A

Platform Testing

• macOS
• Windows
• Linux

Additional Notes

[github-actions]

✅ Coverage Report

📊 View Full HTML Report (download artifact)

Overall Coverage

Metric	Value
Total Line Coverage	76.71%
Lines Covered	12528 / 16331

Changed Files in This PR

File	Coverage	Lines
crates/lambda-rs-args/src/lib.rs	75.35%	743/986

PR Files Coverage: 75.35% (743/986 lines)

---

Generated by cargo-llvm-cov · Latest main coverage

_{Last updated: 2026-03-04 19:10:14 UTC · Commit: 27511d1}

[Copilot]

Pull request overview

This PR optimizes lambda-rs-args runtime argument lookup and positional assignment performance, while updating rustdoc to follow the repository’s sectioned documentation style.

Changes:

• Build a name→index map inside ParsedArgs so has() / get_*() are O(1) instead of scanning the parsed vector.
• Track a positional cursor for assigning values after --, avoiding repeated rescans of positionals.
• Expand/standardize rustdoc for parse, compile, ParsedArgs getters, and add a targeted test for has() behavior.

---

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

[Copilot]

get_count's doc example uses "-v" as the lookup name, but has() (and the parse docs) explicitly state that aliases like -p are not resolved at lookup time and callers should use the declared/canonical name. Consider changing the example to a canonical long name (e.g. "--verbose") or clarifying that "-v" is only correct when it is the declared name rather than an alias.

Suggested change

	/// - `name`: The declared argument name (for example, `"-v"`).
	/// - `name`: The declared argument name (for example, `"--verbose"`).

[Copilot]

The parse rustdoc mentions "unknown argument ... in strict mode", but the API surface here is ignore_unknown(bool) and there is no named "strict mode" concept elsewhere in this crate. Consider rewording this bullet to explicitly reference ignore_unknown(false) (default) vs ignore_unknown(true) to avoid ambiguity.

[Copilot]

In the parse rustdoc, the last two bullets are behavior notes (alias resolution / clustered short flags), not error conditions, but they currently live under the # Errors section. Moving these into a separate section (e.g. # Notes/# Behavior) would make the docs clearer and more consistent with rustdoc section semantics.