Hierarchy expansion rule implementation

[sshenzha]

When filtering on drug_concept_id or condition_concept_id, it MUST use the concept_ancestor table to capture all descendants (child concepts). A single concept_id (e.g., "Metformin") misses specific formulations (Metformin 500mg, Metformin XR, etc.). By implementing this rule, Hierarchy expansion ensures complete capture.

[sshenzha]

This pull request introduces a new semantic validation rule to ensure SQL queries filtering on drug or condition concepts in OMOP datasets properly use the concept_ancestor table for hierarchy expansion. This prevents queries from missing descendant concepts (such as specific drug formulations or condition subtypes). The changes include the implementation of the rule, updates to the rule registry, and comprehensive tests to validate correct and incorrect usage scenarios.

New Semantic Rule: Hierarchy Expansion

• Added HierarchyExpansionRule in src/fastssv/rules/semantic/hierarchy_expansion.py to enforce that queries filtering on drug_concept_id or condition_concept_id must use the concept_ancestor table to capture all descendant concepts. The rule checks for both direct filters and IN clauses, and verifies correct join direction.
• Registered the new rule in src/fastssv/rules/semantic/__init__.py, updated the module import and __all__ list.

Test Coverage for Hierarchy Expansion

• Added HierarchyExpansionTests to tests/test_semantic_validation.py with cases for correct and incorrect usage, including: missing hierarchy expansion, correct use of concept_ancestor, exemption for unmapped concepts (concept_id = 0), and warnings for incorrect join direction.
• Updated existing tests and CTE examples to reflect the requirement for hierarchy expansion, ensuring queries now join with concept_ancestor and filter on ancestor_concept_id when using clinical concepts. [1] [2]

These changes collectively enforce best practices for semantic filtering in OMOP SQL queries and provide robust automated validation for hierarchy expansion requirements.