I'll research the epic and merge request you provided to help you create detailed issues and an epic description for the Ruby parser implementation.

Based on the research findings and the established patterns from the Ruby parser epic, here's a comprehensive issue for the foundational library work:

Issue: Create Initial Library Infrastructure

Title: Create Initial Library Infrastructure

Description:

Goal

Establish the foundational infrastructure for the gitlab-code-parser library that will serve as the base for all language-specific parsers. This issue focuses on creating the core parsing framework, rule loading system, and common utilities that will be shared across all language implementations (Ruby, Python, JavaScript/TypeScript, etc.).

Scope

This issue encompasses the essential building blocks needed before any language-specific parsing can begin:

Core Library Components:

• Parser Core Module: Base traits and structures for language parsers
• Rule Loading System: Infrastructure for loading and managing ast-grep rules from YAML files
• AST Utilities: Common AST traversal and manipulation functions
• FQN Resolution Framework: Base structures and utilities for computing Fully Qualified Names
• Error Handling: Standardized error types and handling patterns
• Configuration Management: System for parser configuration and options

Integration Points:

• Tree-sitter Integration: Wrapper utilities for tree-sitter grammar integration
• ast-grep Integration: Core functionality for pattern matching and rule execution
• Output Standardization: Common data structures for definitions, references, and imports across all languages

Expected Usage

The library will be used as follows:

Loading syntax highlighting...

Technical Approach: ast-grep and Rule System

Based on the patterns established in the Ruby parser MR, the library will leverage ast-grep as the primary tool for pattern matching and code extraction:

Rule-Based Architecture:

Loading syntax highlighting...

Rule Loading and Execution:

• Rules will be organized by language in dedicated directories (rules/ruby/, rules/python/, etc.)
• Each rule file will contain patterns for specific entity types (definitions, references, imports)
• The core library will provide a RuleLoader that can dynamically load rules for any supported language
• Rules will be compiled and cached for performance

AST Processing Pipeline:

1. Parse: Use tree-sitter to generate language-specific AST
2. Match: Apply ast-grep rules to identify entities
3. Extract: Convert matched nodes to structured data
4. Resolve: Compute FQNs using scope tracking
5. Output: Return standardized ParseResult

Implementation Considerations

Performance:

• Rule compilation and caching to avoid repeated parsing of YAML files
• Efficient AST traversal patterns to minimize memory usage
• Lazy loading of language-specific components

Extensibility:

• Plugin-like architecture for adding new languages
• Configurable rule sets (e.g., strict vs. permissive parsing)
• Hooks for custom post-processing logic

Error Handling:

• Graceful degradation when encountering malformed code
• Detailed error reporting with source location information
• Recovery strategies for partial parsing success

Testing Infrastructure:

• Test harness for validating rule correctness
• Fixture management for language-specific test cases
• Performance benchmarking utilities

File Structure

crates/parser-core/
├── src/
│   ├── lib.rs                 # Main library exports
│   ├── parser.rs              # Core Parser trait and implementation
│   ├── rules/
│   │   ├── mod.rs            # Rule loading and management
│   │   ├── loader.rs         # YAML rule file loader
│   │   └── executor.rs       # ast-grep rule execution
│   ├── ast/
│   │   ├── mod.rs            # AST utilities
│   │   ├── traversal.rs      # Common traversal patterns
│   │   └── scope.rs          # Scope tracking for FQN resolution
│   ├── entities/
│   │   ├── mod.rs            # Entity definitions
│   │   ├── definition.rs     # Definition structures
│   │   ├── reference.rs      # Reference structures
│   │   └── import.rs         # Import structures
│   ├── fqn/
│   │   ├── mod.rs            # FQN resolution framework
│   │   └── resolver.rs       # Base FQN resolution logic
│   └── error.rs              # Error types and handling
├── rules/                     # Language-specific rule files
│   ├── ruby/
│   │   ├── definitions.yaml
│   │   ├── references.yaml
│   │   └── imports.yaml
│   └── python/
│       ├── definitions.yaml
│       ├── references.yaml
│       └── imports.yaml
└── tests/
    ├── fixtures/             # Test code samples
    └── integration/          # Integration tests

Acceptance Criteria

• Core Parser trait and base implementation
• Rule loading system that can parse YAML rule files
• Integration with ast-grep for pattern matching
• Common data structures for definitions, references, and imports
• Basic FQN resolution framework
• Error handling and reporting system
• Comprehensive test suite with fixtures
• Documentation and usage examples
• Performance benchmarks for rule loading and execution

Dependencies

• tree-sitter - For language-specific AST generation
• ast-grep - For pattern matching and code extraction
• serde - For YAML rule file parsing
• thiserror - For structured error handling
• tracing - For logging and debugging

This foundational work will enable rapid development of language-specific parsers by providing a consistent, well-tested framework that handles the common concerns of parsing, rule management, and entity extraction.