atomctl/specs/002-refactor-ast-gen/data-model.md

Phase 1: Data Model Design

Overview

This document defines the core data models and contracts for the refactored AST route generation system, following the component-based architecture pattern established in the provider module.

Core Entities

1. RouteDefinition

Represents a complete route definition extracted from source code annotations.

type RouteDefinition struct {
    // Basic Information
    StructName    string              // Name of the handler struct
    FilePath      string              // Source file path
    PackageName   string              // Go package name

    // Route Configuration
    Path          string              // HTTP path pattern
    Methods       []string           // HTTP methods (GET, POST, etc.)
    Name          string              // Route name for identification

    // Dependencies & Imports
    Imports       map[string]string  // Package path -> alias mapping
    Parameters    []ParamDefinition  // Route parameters
    Middleware    []string           // Middleware chain

    // Code Generation
    HandlerFunc   string              // Handler function name
    ReturnType    string              // Return type specification
    ProviderGroup string              // Dependency injection group

    // Metadata
    Location      SourceLocation      // Source location for error reporting
    Annotations   map[string]string   // Additional annotations
}

2. ParamDefinition

Represents a parameter binding from different sources.

type ParamDefinition struct {
    // Parameter Identification
    Name          string              // Parameter name
    Position      ParamPosition       // Parameter location (path, query, etc.)
    Type          string              // Parameter type
    Source        string              // Source annotation text

    // Type Information
    BaseType      string              // Base type without pointer
    IsPointer     bool                // Is pointer type
    IsSlice       bool                // Is slice type
    IsMap         bool                // Is map type

    // Model Information (for structured parameters)
    ModelName     string              // Model name for model() binding
    ModelField    string              // Target field in model
    ModelType     string              // Model field type

    // Validation & Constraints
    Required      bool                // Is required parameter
    DefaultValue  string              // Default value
    Validation    []ValidationRule    // Validation rules

    // Code Generation
    ParamToken    string              // Template token for generation
    ImportPath    string              // Import path for type
}

3. ParamPosition

Parameter position enumeration.

type ParamPosition string

const (
    ParamPositionPath   ParamPosition = "path"   // URL path parameters
    ParamPositionQuery  ParamPosition = "query"  // Query string parameters
    ParamPositionBody   ParamPosition = "body"   // Request body
    ParamPositionHeader ParamPosition = "header" // HTTP headers
    ParamPositionCookie ParamPosition = "cookie" // Cookies
    ParamPositionLocal  ParamPosition = "local"  // Local context values
    ParamPositionFile   ParamPosition = "file"   // File uploads
)

4. ValidationRule

Parameter validation rule definition.

type ValidationRule struct {
    Type        ValidationType // Validation type (required, min, max, etc.)
    Value       string         // Validation value
    Message     string         // Error message
    Constraint  string         // Constraint expression
}

5. SourceLocation

Source code location information.

type SourceLocation struct {
    File   string // Source file path
    Line   int    // Line number
    Column int    // Column position
}

Component Interfaces

1. RouteParser Interface

Main coordinator interface for route parsing.

type RouteParser interface {
    ParseFile(filePath string) ([]RouteDefinition, error)
    ParseDir(dirPath string) ([]RouteDefinition, error)
    ParseString(code string) ([]RouteDefinition, error)

    // Configuration
    SetConfig(config *RouteParserConfig) error
    GetConfig() *RouteParserConfig

    // Context & Diagnostics
    GetContext() *ParserContext
    GetDiagnostics() []Diagnostic
}

2. CommentParser Interface

Handles annotation parsing from source comments.

type CommentParser interface {
    ParseRouteComment(comment string) (*RouteAnnotation, error)
    ParseBindComment(comment string) (*BindAnnotation, error)
    IsRouteComment(comment string) bool
    IsBindComment(comment string) bool
}

3. ImportResolver Interface

Manages import resolution and dependencies.

type ImportResolver interface {
    ResolveFileImports(node *ast.File, filePath string) (*ImportContext, error)
    ResolveImportPath(alias string) (string, error)
    AddImport(imports map[string]string, path, alias string) error
}

4. RouteBuilder Interface

Constructs route definitions from parsed components.

type RouteBuilder interface {
    BuildFromTypeSpec(typeSpec *ast.TypeSpec, decl *ast.GenDecl, context *BuilderContext) (RouteDefinition, error)
    BuildFromComment(comment string, context *BuilderContext) (RouteDefinition, error)
    ValidateDefinition(def *RouteDefinition) error
}

5. RouteValidator Interface

Validates route definitions and configurations.

type RouteValidator interface {
    ValidateRoute(def *RouteDefinition) error
    ValidateParameters(params []ParamDefinition) error
    ValidateImports(imports map[string]string) error
    GetValidationRules() []ValidationRule
}

6. RouteRenderer Interface

Handles template rendering and code generation.

type RouteRenderer interface {
    Render(routes []RouteDefinition, outputPath string) error
    RenderToFile(route RouteDefinition, outputPath string) error
    SetTemplate(template *template.Template) error
    GetTemplate() *template.Template
}

Supporting Data Structures

1. RouteAnnotation

Parsed route annotation information.

type RouteAnnotation struct {
    Path    string   // Route path
    Methods []string // HTTP methods
    Name    string   // Route name
    Options  map[string]string // Additional options
}

2. BindAnnotation

Parsed bind annotation information.

type BindAnnotation struct {
    Name      string         // Parameter name
    Position  ParamPosition  // Parameter position
    Key       string         // Source key
    Model     *ModelInfo     // Model binding info (optional)
    Options   map[string]string // Additional options
}

3. ModelInfo

Model binding information.

type ModelInfo struct {
    Name     string // Model name
    Field    string // Target field
    Type     string // Field type
    Required bool   // Is required
}

4. ImportContext

Import resolution context.

type ImportContext struct {
    FileImports    map[string]*ImportResolution // Alias -> Resolution
    ImportPaths    map[string]string            // Path -> Alias
    ModuleInfo     map[string]string            // Module path -> module name
    WorkingDir     string                       // Current working directory
    ModuleName     string                       // Current module name
    ProcessedFiles map[string]bool              // Track processed files
}

5. ImportResolution

Individual import resolution information.

type ImportResolution struct {
    Path     string // Import path
    Alias    string // Import alias
    Type     ImportType // Import type
    Used     bool   // Whether import is used
}

6. BuilderContext

Context for route building process.

type BuilderContext struct {
    FilePath       string              // Current file path
    PackageName    string              // Package name
    ImportContext  *ImportContext      // Import information
    ASTFile        *ast.File           // AST node
    ProcessedTypes map[string]bool     // Processed types cache
    Errors         []error             // Error collection
    Warnings       []string            // Warning collection
    Config         *BuilderConfig      // Builder configuration
}

Configuration Structures

1. RouteParserConfig

Configuration for route parser behavior.

type RouteParserConfig struct {
    // Parsing Options
    ParseComments     bool           // Parse comments (default: true)
    StrictMode        bool           // Strict validation mode
    SourceLocations   bool           // Include source locations

    // File Processing
    SkipTestFiles     bool           // Skip test files (default: true)
    SkipGenerated     bool           // Skip generated files (default: true)
    AllowedPatterns   []string       // Allowed file patterns

    // Validation Options
    EnableValidation  bool           // Enable validation (default: true)
    ValidationLevel   ValidationLevel // Validation strictness

    // Performance Options
    CacheEnabled      bool           // Enable parsing cache
    ParallelProcessing bool           // Enable parallel processing
}

2. BuilderConfig

Configuration for route builder.

type BuilderConfig struct {
    EnableValidation          bool          // Enable validation
    StrictMode                bool          // Strict validation mode
    DefaultParamPosition      ParamPosition // Default parameter position
    AutoGenerateReturnTypes  bool          // Auto-generate return types
    ResolveImportDependencies bool          // Resolve import dependencies
}

3. ValidationLevel

Validation strictness levels.

type ValidationLevel int

const (
    ValidationLevelNone    ValidationLevel = iota // No validation
    ValidationLevelBasic                         // Basic validation
    ValidationLevelStrict                        // Strict validation
    ValidationLevelPedantic                      // Pedantic validation
)

Error Handling

1. RouteError

Route-specific error type.

type RouteError struct {
    Code      ErrorCode     // Error code
    Message   string        // Error message
    File      string        // File path
    Line      int           // Line number
    Column    int           // Column number
    Context   string        // Error context
    Severity  ErrorSeverity // Error severity
    Inner     error         // Inner error
}

2. ErrorCode

Error code enumeration.

type ErrorCode string

const (
    ErrCodeInvalidSyntax      ErrorCode = "INVALID_SYNTAX"
    ErrCodeMissingAnnotation  ErrorCode = "MISSING_ANNOTATION"
    ErrCodeInvalidParameter   ErrorCode = "INVALID_PARAMETER"
    ErrCodeDuplicateRoute     ErrorCode = "DUPLICATE_ROUTE"
    ErrCodeImportResolution   ErrorCode = "IMPORT_RESOLUTION"
    ErrCodeValidation         ErrorCode = "VALIDATION_ERROR"
    ErrCodeTemplateError      ErrorCode = "TEMPLATE_ERROR"
)

3. Diagnostic

Rich diagnostic information.

type Diagnostic struct {
    Level     DiagnosticLevel // Diagnostic level
    Code      ErrorCode       // Error code
    Message   string          // Diagnostic message
    File      string          // File path
    Location  SourceLocation  // Source location
    Context   string          // Additional context
    Suggestions []string      // Suggested fixes
}

Summary

This data model design provides a comprehensive foundation for the refactored route generation system. Key features include:

1. Clear separation of concerns: Each component has well-defined interfaces and responsibilities
2. Comprehensive error handling: Structured error types with rich diagnostic information
3. Extensible validation: Configurable validation system with multiple levels
4. Type safety: Strong typing throughout the system
5. Configuration management: Flexible configuration system for different use cases
6. Backward compatibility: Designed to support existing annotation formats

The design follows SOLID principles and provides a solid foundation for implementing the refactored route generation system.