feat: add usage-flag-naming lint rule (#13)#66
Open
olavostauros wants to merge 5 commits into
Open
Conversation
- Extracts flag names, placeholders, and usage_* env var names - Functions: usage_flag_name, usage_placeholder, usage_env_name, parse_usage_flags, discover_task_files - Reusable by sibling rules (KnickKnackLabs#35, KnickKnackLabs#39, KnickKnackLabs#43)
…r mismatches Scans .mise/tasks/** for #USAGE flag directives where the flag name and arg placeholder produce different usage_* env var names. When they differ, the flag silently does nothing (real bug from codebase#12). - Two-phase detection: parse #USAGE directives, compare env var names - Skips boolean flags (no placeholder), short-only (no long name) - Respects inline and file-level codebase:ignore - 16 BATS tests, 10 fixture directories - Reuses lib/usage-parser.sh for directive parsing
The USAGE flag directive declared '--exclude <excludes>' but mise exports usage_exclude (from the flag name), not usage_excludes. The task code correctly reads , but the placeholder was misleading. Caught by the new usage-flag-naming self-hosting check.
olavostauros
force-pushed
the
feat/usage-flag-naming
branch
from
June 24, 2026 13:32
1fb8b72 to
ce33002
Compare
This was referenced Jun 24, 2026
This was referenced Jun 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
lint:usage-flag-namingrule that detects #USAGE flag directives where the flag name and arg placeholder produce differentusage_*env var names — the flag silently does nothing (real bug from codebase#12, found in thescantask).Fixes #13
Detection
Two-phase file-scan with shared
lib/usage-parser.sh:--exclude) and placeholder (<exclude>)usage_*names derived from each; flag if they differ--exclude <excludes>→ usage_exclude vs usage_excludes--verbose→ skip-e→ skipFiles changed
lib/usage-parser.sh.mise/tasks/lint/usage-flag-namingtest/lint/usage-flag-naming/usage-flag-naming.batstest/lint/usage-flag-naming/fixtures/.mise/tasks/scan<excludes>→<exclude>to match flag nameAGENTS.mdCommits
feat(lib): add shared usage-parser.sh for #USAGE directive parsingfeat(lint): add usage-flag-naming rule — detect USAGE flag/placeholder mismatchesfix: align scan USAGE placeholder with flag name --excludedocs: add usage-flag-naming to AGENTS.md lint rules tableValidation
mise run test— 234/234 tests pass (16 new tests at indices 168–183, zero regressions)codebase lint:usage-flag-naming .— self-hosting clean (15 files, 0 violations) — fixed the pre-existing mismatch in.mise/tasks/scanbash -n .mise/tasks/lint/usage-flag-naming— syntax validbash -n lib/usage-parser.sh— syntax validgit diff --check— no whitespace errors