Add comprehensive function definition × call catalog

[ekohilas]

Summary

This PR introduces a comprehensive, verdict-free catalog of Python function definitions and calls. The catalog serves as a shared test-case corpus for argument-related lint rules, organizing cases along orthogonal dimensions (parameter kinds, callable kinds, argument forms, etc.) without prescribing pass/fail verdicts.

Key Changes

• New catalog/ package with 8 category modules covering distinct aspects of function definitions and calls:

  • param_kinds.py — parameter shapes (positional-only, keyword-only, *args, **kwargs, etc.)
  • callable_kinds.py — callable types (module functions, methods, classmethods, lambdas, properties, etc.)
  • arg_forms.py — argument expressions at call sites (literals, variables, attributes, unpacking, etc.)
  • unpacking.py — iterable/mapping unpacking (*seq, **mapping) and inferability
  • arity_and_ordering.py — argument count and ordering (exact, defaults-omitted, too-few, reordered, etc.)
  • call_target_forms.py — how callables are referenced (bare names, attributes, subscripts, etc.)
  • source_and_inferability.py — definition source and astroid inference capability
  • defaults_and_annotations.py — parameter defaults and type annotations
  • cross_cutting.py — combinations that span multiple axes (redundant keywords, shadowing builtins, etc.)

• Schema and validation (_schema.py):

  • Case dataclass pairing definition and call snippets with dimension tags
  • Controlled vocabulary for all tag values
  • validate() function for structural integrity checks
  • marked_source() helper for astroid node extraction

• Test harness (test/test_catalog.py):

  • Validates all cases parse correctly under astroid
  • Checks ID uniqueness and well-formedness
  • Records (but does not assert) inferability and plugin behavior

• Documentation (catalog/README.md):

  • Explains the verdict-free design philosophy
  • Documents the 10 orthogonal dimensions
  • Provides guidance for rule authors using the catalog

• Configuration (pyproject.toml):

  • Added pytest configuration to make the catalog package importable during tests

Notable Design Details

• Verdict-free: Cases carry only dimension tags and notes, never pass/fail verdicts. This allows one corpus to serve multiple rules.
• Orthogonal dimensions: Each category isolates one axis while holding others canonical (e.g., arg_forms.py varies argument expressions while keeping signature shape, source, and inferability constant).
• Inferability tracking: Cases record whether astroid can fully/partially/not infer the callable, enabling rules to bail safely on uninferable targets.
• Real-world coverage: Includes edge cases like conditional defs with ambiguous signatures, multiplicity of inference, C builtins, and stub-only definitions.
• Runnable validation: All cases are validated to parse and execute under the real astroid toolchain, ensuring the corpus stays in sync with the linter.

https://claude.ai/code/session_01LRN8aXwbrHyqZ15QyZHSFM