feat(linter): add version-aware rule infrastructure with test rules

[epsjunior]

• Add version detection from comments and dependencies
• Implement version-aware rule system with min/max version constraints
• Support hash-based rule activation/deactivation
• Add test rules demonstrating version/hash-specific behavior
• Enable all base rules for all versions by default
• Update documentation to reflect new capabilities

Summary by CodeRabbit

• New Features

  • Introduced version-aware linting with automatic version detection and per-version rules.
  • Added APIs to retrieve version info and compare compatibility between sources.
  • Provided configurable rules via an external configuration file.
  • Exposed version utilities to parse, compare, and work with version ranges.

• Documentation

  • Added comprehensive guides on version-based rules, detection methods, configuration, and usage examples.

• Tests

  • Added unit and integration tests covering version parsing, rule behavior across versions, and compatibility checks.

• Chores

  • Bumped package to 0.2.0 and added a YAML parsing dependency.

[linear]

DXP-694 Support different versions of the GenVM

We need to be able to support multiple GenVM versions, producing a specific rules set for a given version based on the base rule set and all the modifications for every next version.

We also need to detect an intelligent contract GenVM version so we know which rules should apply.

[coderabbitai]

Walkthrough

Adds a version-aware linting system: new version parsing utilities, a rule registry with per-version applicability, a versioned rule framework, and linter integration with toggleable version awareness, info APIs, and comparison. Introduces YAML config, examples, expanded README/docs, dependency on PyYAML, public API exports, and extensive unit/integration tests.

Changes

Cohort / File(s)	Summary
Documentation README.md, docs/VERSION_RULES.md	Adds version-awareness docs: detection methods, rule activation by version/hash/deps, API usage, configuration, and workflows. Updates examples and project structure references.
Configuration & Dependencies config/versions.yaml, pyproject.toml	Introduces YAML config for base and test rules with version/hash/dep conditions. Adds pyyaml >= 6.0.0 dependency.
Public API & Package Metadata src/genvm_linter/__init__.py	Bumps version to 0.2.0. Exposes VersionAwareGenVMLinter, Version, VersionParser, RuleRegistry via public API and __all__.
Version Utilities src/genvm_linter/version.py	Adds Version, VersionComponent, VersionParser, and VersionRange for parsing, comparing, and extracting versions/dependencies and ranges.
Linter Core (Version Awareness) src/genvm_linter/linter.py	Adds version-aware mode (default on), YAML-driven rule loading via registry, version context propagation, new methods get_version_info and compare_versions, enhanced error handling, and alias VersionAwareGenVMLinter.
Rule Registry src/genvm_linter/rule_registry.py	Adds RuleDefinition and RuleRegistry to register rules, determine applicability per version/features/hashes, manage breaking changes, and load/save YAML config.
Versioned Rules Framework src/genvm_linter/rules/versioned.py	Introduces VersionContext, VersionedRule, EvolvingRule, VersionedRuleImplementation, and ConditionalRule for version- and feature-aware checks.
Examples examples/versioned_contracts.py	Adds versioned contract strings and validate_contract_examples() demonstrating linting and version info retrieval.
Integration Tests tests/integration/test_version_specific_test_rules.py, tests/integration/test_versioned_rules.py	Adds tests covering version-specific behaviors, hash/dep gating, info messages, compatibility, and comparison utilities.
Unit Tests tests/unit/test_version.py	Adds tests for Version, VersionParser, and VersionRange parsing, comparisons, extraction, and ranges.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant U as User
  participant L as GenVMLinter
  participant VP as VersionParser
  participant RR as RuleRegistry
  participant R* as Rules

  Note over L: use_version_aware = true (default)
  U->>L: lint_source(source)
  L->>VP: extract_version(source)<br/>extract_dependencies(source)
  VP-->>L: Version? + deps
  L->>RR: set_version_context(context)
  L->>RR: get_rules_for_version(Version|latest)
  RR-->>L: instantiated Rules
  loop Pre-AST / AST checks
    L->>R*: set_version_context(context)
    L->>R*: check(node/str)
    R*-->>L: results
  end
  L-->>U: results (+version-info)

  opt use_version_aware = false
    Note over L: Fallback fixed rule set
  end

Loading

sequenceDiagram
  autonumber
  participant U as User
  participant L as GenVMLinter
  participant RR as RuleRegistry
  participant VP as VersionParser

  U->>L: compare_versions(source1, source2)
  L->>VP: extract_version(s1), extract_version(s2)
  VP-->>L: v1, v2
  L->>RR: get_breaking_changes(v1, v2)
  RR-->>L: [changes]
  L-->>U: {from, to, breaking_changes, compatible}

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60–90 minutes

Poem

I nibble through versions, hop to and fro,
Sniffing out hashes where feature flags grow.
YAML burrows guide my rule-filled quest,
Carrots of context tucked snug to my chest.
With gentle thumps I mark each change—
Latest or legacy, I happily range. 🥕🐇

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Free

📥 Commits

Reviewing files that changed from the base of the PR and between 1a1a1c7 and 5b8f9aa.

📒 Files selected for processing (13)

• README.md (5 hunks)
• config/versions.yaml (1 hunks)
• docs/VERSION_RULES.md (1 hunks)
• examples/versioned_contracts.py (1 hunks)
• pyproject.toml (1 hunks)
• src/genvm_linter/__init__.py (1 hunks)
• src/genvm_linter/linter.py (5 hunks)
• src/genvm_linter/rule_registry.py (1 hunks)
• src/genvm_linter/rules/versioned.py (1 hunks)
• src/genvm_linter/version.py (1 hunks)
• tests/integration/test_version_specific_test_rules.py (1 hunks)
• tests/integration/test_versioned_rules.py (1 hunks)
• tests/unit/test_version.py (1 hunks)

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}