fix(shell,perl): args-counting for languages with no formal parameter-list syntax

[squid-protocol]

Summary

Bash functions and traditional Perl subs have no formal parameter-list syntax at all, permanently, by grammar -- args arrive via body-level idioms instead ($1/$2/"$@" in bash; my (...) = @_ / shift in perl). This measured 0/3 (shell) and 137/937 (perl, 14.6%) on args_exact_match, reading as "GitGalaxy's args regex is badly broken." It wasn't -- both the ground-truth measurement and the engine had real, fixable gaps.

Ground truth (tests/tools/tree_sitter_accuracy_audit.py): _get_param_count only ever checked the declaration for a formal parameter field, found nothing (correctly -- there is none), and reported real=0 regardless of true arity. New _count_shell_real_positional_max / _count_perl_real_args walk the same body idiom GitGalaxy reads, using tree-sitter's own real parse.

Engine (detector.py + language_standards.py):

• shell: args-counting only ever took the first $N/"$@" match in a function, silently dropping every reference after it. New _args_findall_max_groups routing scans the whole block and takes the max positional index referenced.
• perl: only counted the first my (...) = @_ or shift statement, missing the extremely common "shift the invocant, then unpack the rest" multi-statement pattern (e.g. bugzilla/Bug.pm::ValidateDependencies, 3 sequential shifts). New _args_findall_sum_groups routing sums every matching statement across the block. Tightened the bare shift alternative to exclude shift @other/shift(@other) (shifting a DIFFERENT array, not @_). Added the bare my @array = @_ variadic catch-all idiom, previously unrecognized entirely.

args_exact_match: shell 0/3 → 3/3 (100%), perl 137/937 → 769/937 (82.1%).

Why this isn't "GitGalaxy loses to tree-sitter"

New doc: docs/why_gitgalaxy_beats_ast_here.md, linked from README.md's "One Graph, Not Five Separate Tools" section. For this one signal, in this one circumstance (no formal signature exists), a declaration-only AST read has nothing to count and can only ever report 0 -- correct, but useless for coupling/complexity scoring. GitGalaxy's body-aware read is the more informative measurement here, not a lower-precision tradeoff. Scoped narrowly -- doesn't apply to languages with real formal signatures, where tree-sitter's ground truth is still the fair, correct comparison (see the six prior fixes cited in the same doc).

Two related findings, filed separately, not fixed here

• perl func_start block-slicing: _line (mojo/Template.pm) swallows 432 extra lines through the CLI pipeline but not via direct _function_slice #1517 -- perl func_start block-slicing bug: mojo/Template.pm::_line (a real 4-line sub) measures as spanning 437 lines through the full galaxyscope pipeline, but correctly as 4 lines via a direct _function_slice() call. Confirmed pre-existing (present in main's committed golden master before this PR) and unrelated to args-counting -- this PR's fix just made its symptom more visible (the phantom-huge block's args count jumped from a plausible-looking 1 to a clearly-wrong 13, since summing now scans the whole -- wrongly huge -- block). Root cause not pinned; likely candidate is prism.py's string-shielding for the qq{...@{[expr]}...} delimiter-collision shape, not confirmed.
• Nested anonymous Perl sub overcounting (documented in _count_perl_real_args's own docstring and issue perl args: traditional subs have no formal signature -- ground truth only checked the declaration, and GitGalaxy's own shift/my@_ counting only saw the first statement #1519): a closure's own my (...) = @_ gets summed into the OUTER sub's count too, since the engine's flat regex scan has no real block-nesting awareness the ground-truth walker has. Known, accepted limitation.

Verification

tests/extraction/languages/test_shell.py, test_shell_strict.py, test_perl.py, test_perl_strict.py
  -- 260/260 passed (new tests added: shift-vs-shift-other-array exclusion, bare array
  catch-all + ReDoS, multi-statement findall-sum arity via StructuralExtractor, shell
  findall-max via StructuralExtractor)
python -m pytest tests/ -- 6901 passed, 2 skipped, 11 xfailed, 3 xpassed (full suite, clean)
tree_sitter_accuracy_audit --lang shell/perl --regenerate  -- baselines blessed
tree_sitter_accuracy_audit --all --ci  -- 31 languages, zero cross-language regressions
  (both new routing flags are opt-in per-language, gated behind new rules-dict keys)
tests/tools/crucible_check.py --mode both  -- PASS/PASS (golden masters re-blessed; drift is
  real+expected -- perl/shell Function Analysis numbers changed, plus the usual small global
  PageRank/spatial-coordinate ripple across the whole corpus)
tests/tools/audit_check.py --ci  -- ruff/mypy/dead-key/ast-accuracy all clean

Fixes #1518, #1519.

🤖 Generated with Claude Code

[github-actions]

🐦‍⬛ Muninn Security Scan

✅ No security issues found.

🐦‍⬛ Powered by Muninn · Skald Lab