valaq/architecture-plan.md

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

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

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

{
  "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

{
  "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

{
  "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

{
  "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

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

# 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.