# Valaq CLI Application - Architecture Plan

## 1. Overview

The `valaq` CLI application is a tool for querying and exploring VAPI (Vala API) files. It provides hierarchical navigation of symbols within VAPI files with support for both human-readable and JSON output formats.

## 2. Core Application Components

### 2.1 Main Components

1. **CLI Interface Layer** - Handles command-line argument parsing and user interaction
2. **VAPI Parser Engine** - Uses libvala to parse and analyze VAPI files
3. **Symbol Navigator** - Manages hierarchical symbol traversal and filtering
4. **Output Formatter** - Generates both human-readable and JSON output
5. **File System Interface** - Handles VAPI file discovery and access

### 2.2 Component Architecture

```
┌─────────────────┐
│   CLI Interface │
└─────────┬───────┘
          │
┌─────────▼───────┐
│ Symbol Navigator│
└─────────┬───────┘
          │
┌─────────▼───────┐
│ VAPI Parser     │
│ (libvala)       │
└─────────┬───────┘
          │
┌─────────▼───────┐
│ File System     │
│ Interface       │
└─────────────────┘
```

## 3. Project File Structure

```
valaq/
├── src/
│   ├── main.vala              # Application entry point
│   ├── cli/
│   │   ├── argument-parser.vala    # Command-line argument parsing
│   │   └── command-handler.vala   # Command processing logic
│   ├── core/
│   │   ├── vapi-parser.vala        # VAPI file parsing using libvala
│   │   ├── symbol-navigator.vala   # Symbol hierarchy navigation
│   │   └── symbol-model.vala       # Data models for symbols
│   ├── output/
│   │   ├── formatter.vala          # Output formatting interface
│   │   ├── text-formatter.vala     # Human-readable output
│   │   └── json-formatter.vala     # JSON output formatting
│   └── utils/
│       ├── file-utils.vala         # File system operations
│       └── error-handling.vala     # Error handling utilities
├── tests/
│   ├── test-vapi-parser.vala
│   ├── test-symbol-navigator.vala
│   └── test-output-formatters.vala
├── meson.build               # Build configuration
└── README.md
```

## 4. Key Classes and Responsibilities

### 4.1 Main Application Classes

#### `ValaqApplication`
- **Responsibility**: Main application entry point and initialization
- **Key Methods**: 
  - `main(string[] args)` - Application entry point
  - `run()` - Main application loop

#### `ArgumentParser`
- **Responsibility**: Parse and validate command-line arguments
- **Key Methods**:
  - `parse(string[] args)` - Parse command line arguments
  - `get_vapi_path()` - Get VAPI file path from arguments
  - `get_symbol_path()` - Get symbol navigation path
  - `is_json_output()` - Check if JSON output requested

#### `VapiParser`
- **Responsibility**: Parse VAPI files using libvala
- **Key Methods**:
  - `parse_file(string path)` - Parse a VAPI file
  - `get_root_symbols()` - Get top-level symbols
  - `get_symbol_details(Symbol symbol)` - Get detailed symbol information

#### `SymbolNavigator`
- **Responsibility**: Navigate symbol hierarchy and filter results
- **Key Methods**:
  - `navigate_to_path(string[] path)` - Navigate to symbol path
  - `get_child_symbols(Symbol parent)` - Get child symbols
  - `find_symbol_by_name(string name)` - Find symbol by name

#### `TextFormatter` / `JsonFormatter`
- **Responsibility**: Format output in different formats
- **Key Methods**:
  - `format_symbol_list(Symbol[] symbols)` - Format symbol list
  - `format_symbol_details(Symbol symbol)` - Format symbol details

### 4.2 Data Model Classes

#### `Symbol`
- Base class for all symbol types
- **Properties**: name, symbol_type, access_modifier, parent, children

#### `Class`, `Interface`, `Struct`, `Enum`, `Delegate`, `Method`, `Property`, `Field`
- Specialized symbol types extending base Symbol class
- **Specific Properties**: return_type, parameters, etc.

## 5. Data Flow

### 5.1 Application Flow

```mermaid
graph TD
    A[CLI Arguments] --> B[ArgumentParser]
    B --> C{No parameters?}
    C -->|Yes| D[List VAPI files]
    C -->|No| E{VAPI file only?}
    E -->|Yes| F[List toplevel symbols]
    E -->|No| G[Navigate to symbol path]
    G --> H[Display symbol details]
    D --> I[Output Formatter]
    F --> I
    H --> I
    I --> J[Display Results]
```

### 5.2 VAPI Parsing Flow

```mermaid
graph TD
    A[VAPI File] --> B[VapiParser]
    B --> C[libvala CodeContext]
    C --> D[Symbol Resolution]
    D --> E[Build Symbol Tree]
    E --> F[SymbolNavigator]
    F --> G[Query/Navigation]
    G --> H[Output Formatter]
```

## 6. VAPI Parsing Strategy Using libvala

### 6.1 libvala Integration
- Use `Vala.CodeContext` as the main parsing context
- Leverage `Vala.SourceFile` for VAPI file loading
- Utilize `Vala.SymbolResolver` for symbol resolution
- Access `Vala.Namespace` and other symbol types through the API

### 6.2 Parsing Process
1. Initialize `CodeContext` with appropriate reporter
2. Add VAPI file to context using `add_source_file()`
3. Run the parser and symbol resolver
4. Extract symbols from the root namespace
5. Build internal symbol model for navigation

### 6.3 Symbol Type Mapping
- Map libvala symbol types to internal model:
  - `Vala.Class` → `Class` model
  - `Vala.Interface` → `Interface` model
  - `Vala.Method` → `Method` model
  - `Vala.Property` → `Property` model
  - etc.

## 7. JSON Output Format Design

### 7.1 Top-level Structure
```json
{
  "vapi_file": "path/to/file.vapi",
  "query_path": ["symbol1", "symbol2"],
  "result_type": "symbol_list|symbol_details|file_list",
  "symbols": [...],
  "metadata": {
    "vala_version": "0.56",
    "timestamp": "2023-..."
  }
}
```

### 7.2 Symbol Representation
```json
{
  "name": "symbol_name",
  "type": "class|interface|method|property|enum|delegate|field|constant",
  "access": "public|private|protected|internal",
  "return_type": "ReturnType",
  "parameters": [
    {
      "name": "param_name",
      "type": "ParamType",
      "direction": "in|out|ref",
      "default_value": "optional"
    }
  ],
  "properties": [...],
  "methods": [...],
  "fields": [...],
  "base_types": ["BaseClass1", "Interface1"],
  "source_location": {
    "file": "file.vapi",
    "line": 123
  },
  "documentation": "Symbol documentation comment"
}
```

### 7.3 File List Format
```json
{
  "result_type": "file_list",
  "vapi_directory": "/usr/share/vala-0.56/vapi",
  "files": [
    {
      "name": "gtk+-3.0.vapi",
      "path": "/usr/share/vala-0.56/vapi/gtk+-3.0.vapi",
      "size": 123456,
      "modified": "2023-..."
    }
  ]
}
```

## 8. Error Handling Strategy

### 8.1 Error Types
- **File System Errors**: Missing VAPI files, permission issues
- **Parsing Errors**: Invalid VAPI syntax, libvala parsing failures
- **Navigation Errors**: Invalid symbol paths, symbol not found
- **Output Errors**: JSON formatting issues

### 8.2 Error Response Format
```json
{
  "error": {
    "type": "file_not_found|parse_error|navigation_error",
    "message": "Human readable error message",
    "details": {
      "file_path": "path/to/file.vapi",
      "symbol_path": ["symbol1", "symbol2"],
      "line_number": 123
    }
  }
}
```

## 9. Performance Considerations

### 9.1 Caching Strategy
- Cache parsed VAPI files in memory during session
- Consider persistent caching for frequently accessed files
- Lazy loading of symbol details when drilling down

### 9.2 Memory Management
- Efficient symbol tree representation
- Proper cleanup of libvala resources
- Streamlined JSON output generation

## 10. Extensibility Points

### 10.1 Plugin Architecture
- Pluggable output formatters
- Custom symbol filters
- Additional VAPI source locations

### 10.2 Future Enhancements
- Symbol search functionality
- Cross-reference analysis
- Documentation generation
- Integration with IDEs

## 11. Build System Configuration

### 11.1 Meson Build Requirements
- Vala compiler (valac)
- libvala-0.56 dependency
- JSON-GLib for JSON output
- POSIX system for file operations

### 11.2 Build Targets
- `valaq` executable
- Unit tests
- Documentation generation
- Installation scripts

## 12. Testing Strategy

### 12.1 Unit Tests
- VAPI parser testing with sample files
- Symbol navigation logic
- Output formatter validation
- Error handling scenarios

### 12.2 Integration Tests
- End-to-end CLI testing
- Real VAPI file testing
- Performance benchmarks
- JSON output validation

## 13. Security Considerations

### 13.1 File System Access
- Validate file paths to prevent directory traversal
- Check file permissions before access
- Limit access to intended VAPI directories

### 13.2 Input Validation
- Sanitize command-line arguments
- Validate symbol paths
- Prevent injection attacks in JSON output

## 14. Deployment and Distribution

### 14.1 Packaging
- System package integration (deb, rpm, etc.)
- Standalone binary distribution
- Container image options

### 14.2 Installation
- Default VAPI path detection
- Configuration file support
- Environment variable handling

## 15. Sample Meson Build Configuration

### 15.1 Main meson.build
```meson
project('valaq', 'vala', 'c',
  version: '1.0.0',
  license: 'GPLv3',
  default_options: ['warning_level=2', 'werror=false'],
)

# Dependencies
glib_dep = dependency('glib-2.0', version: '>= 2.56')
gobject_dep = dependency('gobject-2.0', version: '>= 2.56')
json_glib_dep = dependency('json-glib-1.0', version: '>= 1.0')
libvala_dep = dependency('libvala-0.56', version: '>= 0.56.0')

# Source files
sources = files(
  'src/main.vala',
  'src/cli/argument-parser.vala',
  'src/cli/command-handler.vala',
  'src/core/vapi-parser.vala',
  'src/core/symbol-navigator.vala',
  'src/core/symbol-model.vala',
  'src/output/formatter.vala',
  'src/output/text-formatter.vala',
  'src/output/json-formatter.vala',
  'src/utils/file-utils.vala',
  'src/utils/error-handling.vala',
)

# Vala compilation flags
vala_args = [
  '--target-glib=2.56',
  '--pkg', 'glib-2.0',
  '--pkg', 'gobject-2.0',
  '--pkg', 'json-glib-1.0',
  '--pkg', 'libvala-0.56',
]

# Executable
executable('valaq',
  sources,
  dependencies: [glib_dep, gobject_dep, json_glib_dep, libvala_dep],
  vala_args: vala_args,
  install: true,
)

# Test configuration
test_dependencies = [glib_dep, gobject_dep, json_glib_dep, libvala_dep]

test_sources = files(
  'tests/test-vapi-parser.vala',
  'tests/test-symbol-navigator.vala',
  'tests/test-output-formatters.vala',
)

foreach test_file : test_sources
  test_name = test_file.split('/')[-1].split('.')[0]
  test(test_name,
    executable(test_name,
      test_file,
      dependencies: test_dependencies,
      vala_args: vala_args,
    )
endforeach
```

### 15.2 Build Requirements
- Vala compiler 0.56 or later
- Meson build system 0.50 or later
- Ninja build system
- Required development packages:
  - libglib2.0-dev
  - libjson-glib-dev
  - libvala-0.56-dev
  - pkg-config

### 15.3 Build Commands
```bash
# Setup build directory
meson setup builddir

# Compile
meson compile -C builddir

# Run tests
meson test -C builddir

# Install
meson install -C builddir
```

## 16. Implementation Roadmap

### 16.1 Phase 1: Core Foundation
1. **Project Setup**
   - Initialize Meson build system
   - Create basic directory structure
   - Set up dependencies and compilation

2. **Basic VAPI Parsing**
   - Implement VapiParser class using libvala
   - Create basic Symbol model classes
   - Test with simple VAPI files

3. **CLI Framework**
   - Implement ArgumentParser for command-line handling
   - Create basic CommandHandler
   - Add simple file listing functionality

### 16.2 Phase 2: Navigation and Output
1. **Symbol Navigation**
   - Implement SymbolNavigator for hierarchical traversal
   - Add symbol path resolution logic
   - Implement filtering and search capabilities

2. **Output Formatters**
   - Create TextFormatter for human-readable output
   - Implement JsonFormatter for structured output
   - Add error handling and validation

### 16.3 Phase 3: Advanced Features
1. **Performance Optimization**
   - Implement caching mechanisms
   - Optimize memory usage
   - Add lazy loading for large VAPI files

2. **Testing and Validation**
   - Comprehensive unit test suite
   - Integration tests with real VAPI files
   - Performance benchmarking

3. **Documentation and Distribution**
   - User documentation and examples
   - Packaging for distribution
   - CI/CD pipeline setup

## 17. Summary

The `valaq` CLI application architecture provides a solid foundation for building a comprehensive VAPI file exploration tool. The key architectural decisions include:

1. **libvala Integration**: Leveraging the official Vala library ensures accurate and reliable VAPI parsing without reinventing the wheel.

2. **Modular Design**: Clear separation of concerns between CLI interface, parsing, navigation, and output formatting makes the codebase maintainable and extensible.

3. **Hierarchical Navigation**: The symbol navigator provides intuitive traversal of VAPI file structures, supporting both simple listing and deep exploration.

4. **Flexible Output**: Support for both human-readable and JSON output formats makes the tool suitable for interactive use and programmatic integration.

5. **Performance Considerations**: Caching and lazy loading strategies ensure good performance even with large VAPI files.

6. **Extensibility**: The plugin architecture and modular design allow for future enhancements without major refactoring.

This architecture plan provides a comprehensive roadmap for implementing the `valaq` CLI application, addressing all the specified requirements while maintaining flexibility for future enhancements.