feat(rules): support <var:name> in command position and per-value type

[fohte]

Why

• Command-position matching cannot mix literal and path-normalized values for the same tool invoked in multiple ways (runok, cargo run --, ./target/debug/runok)
  • Multi-word alternation ("cargo run --"|runok) handles literal alternatives but cannot apply path normalization to specific values (target/debug/runok vs ./target/debug/runok)

What

• <var:name> can now be used in the command position (first token) of a pattern
  • Multi-word values ("cargo run --") consume multiple leading tokens from the input command

definitions:
  vars:
    runok:
      values:
        - runok
        - 'cargo run --'
        - type: path
          value: target/debug/runok
rules:
  - allow: '<var:runok> check'
# Matches: runok check, cargo run -- check, ./target/debug/runok check

• definitions.vars values accept per-value type via { type, value } object form
  • Plain strings inherit the definition-level type; the object form overrides it per value

definitions:
  vars:
    runok:
      values:
        - runok                        # literal (default)
        - 'cargo run --'               # literal
        - type: path                   # per-value type override
          value: target/debug/runok

---

[codecov]

Codecov Report

❌ Patch coverage is 96.42857% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.80%. Comparing base (71b768e) to head (fdd8a29).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
src/config/model.rs	92.72%	4 Missing ⚠️
src/rules/pattern_matcher/token_matching.rs	97.53%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #208      +/-   ##
==========================================
+ Coverage   89.70%   89.80%   +0.09%     
==========================================
  Files          50       50              
  Lines       10186    10325     +139     
==========================================
+ Hits         9137     9272     +135     
- Misses       1049     1053       +4     

Flag	Coverage Δ
Linux	89.70% <96.42%> (+0.10%)	⬆️
macOS	90.97% <96.42%> (+0.08%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the flexibility and power of command matching by introducing the ability to use variable references in the command position and allowing fine-grained control over variable value types. These changes address limitations in handling commands that can be invoked through various aliases or paths, providing a more robust and adaptable configuration system.

Highlights

• Command Position Variable References: The <var:name> placeholder can now be used in the command position (the first token) of a pattern, allowing for more flexible matching of commands invoked in multiple ways.
• Per-Value Type Overrides: Variable definitions in definitions.vars now support per-value type specification using an object form { type, value }, enabling individual values to override the definition-level type.
• Multi-Word Variable Values: Multi-word values defined within a <var:name> reference (e.g., "cargo run --") will now correctly consume multiple leading tokens from the input command when matched.

Changelog

• docs/src/content/docs/configuration/schema.md
  • Updated documentation for variable definitions, including per-value types and an example.
  • Added a runok example to the variable definitions schema.
• docs/src/content/docs/pattern-syntax/overview.md
  • Updated the description for the <var:name> placeholder in the overview table to reflect command position support.
• docs/src/content/docs/pattern-syntax/placeholders.md
  • Expanded documentation for variable references, detailing per-value type overrides and usage in command position.
  • Added examples for using <var:name> in command position.
• schema/runok.schema.json
  • Modified the JSON schema to allow variable values to be either strings or objects with explicit type and value fields.
  • Introduced a new $defs/VarValue schema definition.
• src/config/model.rs
  • Introduced a new VarValue enum to represent variable values with optional type overrides.
  • Updated VarDefinition to use Vec<VarValue> for its values.
  • Implemented JsonSchema and Deserialize traits for VarValue.
  • Adjusted validation logic to use the VarValue structure.
• src/rules/pattern_matcher/mod.rs
  • Adjusted the pattern matching logic in prepare_wildcard_iteration to correctly handle <var:name> placeholders when they appear in the command position, including multi-word values.
  • Modified matches_with_captures to capture command-position variable reference values.
• src/rules/pattern_matcher/token_matching.rs
  • Implemented new functions match_value_with_type and match_var_ref_multi to support type-aware matching for variable values and to handle multi-word variable values in command position.
  • Updated match_var_ref to use effective_type from VarValue.
• src/rules/pattern_parser.rs
  • Extended the CommandPattern enum to include VarRef for variable references in the command position.
  • Updated the parser to recognize <var:name> in command position and reject <path:name> in command position.
  • Added tests for parsing <var:name> in command position.
• tests/integration/var_ref_evaluation.rs
  • Added comprehensive integration tests to verify the functionality of <var:name> in command position.
  • Included tests for per-value type overrides and multi-word variable values.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces two powerful features: using <var:name> in the command position and allowing per-value type overrides for variables. The implementation is well-structured, with thorough updates to documentation, schema, and tests.

I have one main concern regarding a subtle correctness issue in how command-position variables are matched. The current implementation greedily matches the first value from the variable's definition, which can lead to incorrect behavior if multiple values could match the start of a command. I've provided suggestions to address this by collecting all possible matches, making the feature more robust and predictable.