herolib/lib/core/code/improvements.md

Code Review and Improvement Plan for HeroLib Code Module

Overview

The HeroLib code module provides utilities for parsing and generating V language code. It's designed to be a lightweight alternative to v.ast for code analysis and generation across multiple languages. While the module has good foundational structure, there are several areas that need improvement.

Issues Identified

1. Incomplete TypeScript Generation Support

• The typescript() method exists in some models but lacks comprehensive implementation
• Missing TypeScript generation for complex types (arrays, maps, results)
• No TypeScript interface generation for structs

2. Template System Issues

• Some templates are empty (e.g., templates/function/method.py, templates/comment/comment.py)
• Template usage is inconsistent across the codebase
• No clear separation between V and other language templates

3. Missing Parser Documentation Examples

• README.md mentions codeparser but doesn't show how to use the parser from this module
• No clear examples of parsing V files or modules

4. Incomplete Type Handling

• The parse_type function doesn't handle all V language types comprehensively
• Missing support for function types, sum types, and complex generics
• No handling of optional types (?Type)

5. Code Structure and Consistency

• Some functions lack proper error handling
• Inconsistent naming conventions in test files
• Missing documentation for several key functions

Improvement Plan

1. Complete TypeScript Generation Implementation

What needs to be done:

• Implement comprehensive TypeScript generation in model_types.v
• Add TypeScript generation for all type variants
• Create proper TypeScript interface generation in model_struct.v

Specific fixes:

// In model_types.v, improve the typescript() method:
pub fn (t Type) typescript() string {
  return match t {
    Map { 'Record<string, ${t.typ.typescript()}>' }
    Array { '${t.typ.typescript()}[]' }
    Object { t.name }
    Result { 'Promise<${t.typ.typescript()}>' } // Better representation for async operations
    Boolean { 'boolean' }
    Integer { 'number' }
    Alias { t.name }
    String { 'string' }
    Function { '(...args: any[]) => any' } // More appropriate for function types
    Void { 'void' }
  }
}

// In model_struct.v, improve the typescript() method:
pub fn (s Struct) typescript() string {
  name := texttools.pascal_case(s.name)
  fields := s.fields.map(it.typescript()).join('\n  ')
  return 'export interface ${name} {\n  ${fields}\n}'
}

2. Fix Template System

What needs to be done:

• Remove empty Python template files
• Ensure all templates are properly implemented
• Add template support for other languages

Specific fixes:

• Delete templates/function/method.py and templates/comment/comment.py if they're not needed
• Add proper TypeScript templates for struct and interface generation
• Create consistent template naming conventions

3. Improve Parser Documentation

What needs to be done:

• Add clear examples in README.md showing how to use the parser
• Document the parsing functions with practical examples

Specific fixes: Add to README.md:

## Parsing V Code

The code module provides utilities to parse V code into structured models:

```v
import freeflowuniverse.herolib.core.code

// Parse a V file
content := os.read_file('example.v') or { panic(err) }
vfile := code.parse_vfile(content) or { panic(err) }

// Access parsed information
println('Module: ${vfile.mod}')
println('Number of functions: ${vfile.functions().len}')
println('Number of structs: ${vfile.structs().len}')

// Parse individual components
function := code.parse_function(fn_code_string) or { panic(err) }
struct_ := code.parse_struct(struct_code_string) or { panic(err) }

4. Complete Type Handling

What needs to be done:

• Extend parse_type to handle more complex V types
• Add support for optional types (?Type)
• Improve generic type parsing

Specific fixes:

// In model_types.v, enhance parse_type function:
pub fn parse_type(type_str string) Type {
  mut type_str_trimmed := type_str.trim_space()
  
  // Handle optional types
  if type_str_trimmed.starts_with('?') {
    return Optional{parse_type(type_str_trimmed.all_after('?'))}
  }
  
  // Handle function types
  if type_str_trimmed.starts_with('fn ') {
    // Parse function signature
    return Function{}
  }
  
  // Handle sum types
  if type_str_trimmed.contains('|') {
    types := type_str_trimmed.split('|').map(parse_type(it.trim_space()))
    return Sum{types}
  }
  
  // Existing parsing logic...
}

5. Code Structure Improvements

What needs to be done:

• Add proper error handling to all parsing functions
• Standardize naming conventions
• Improve documentation consistency

Specific fixes:

• Add error checking in parse_function, parse_struct, and other parsing functions
• Ensure all public functions have clear documentation comments
• Standardize test function names

Module Generation to Other Languages

Current Implementation

The current code shows basic TypeScript generation support, but it's incomplete. The generation should:

1. Support multiple languages: The code structure allows for multi-language generation, but only TypeScript has partial implementation
2. Use templates consistently: All language generation should use the template system
3. Separate language-specific code: Each language should have its own generation module

What Needs to Move to Other Modules

TypeScript Generation Module:

• Move all TypeScript-specific generation code to a new typescript module
• Create TypeScript templates for structs, interfaces, and functions
• Add proper TypeScript formatting support

Example Structure:

lib/core/code/
├── model_types.v          # Core type models (language agnostic)
├── model_struct.v         # Core struct/function models (language agnostic)
└── typescript/            # TypeScript-specific generation
    ├── generator.v        # TypeScript generation logic
    └── templates/         # TypeScript templates

Parser Usage Examples (to add to README.md)

// Parse a V file into a structured representation
content := os.read_file('mymodule/example.v') or { panic(err) }
vfile := code.parse_vfile(content)!

// Extract all functions
functions := vfile.functions()
println('Found ${functions.len} functions')

// Extract all structs
structs := vfile.structs()
for s in structs {
  println('Struct: ${s.name}')
  for field in s.fields {
    println('  Field: ${field.name} (${field.typ.symbol()})')
  }
}

// Find a specific function
if greet_fn := vfile.get_function('greet') {
  println('Found function: ${greet_fn.name}')
  println('Parameters: ${greet_fn.params.map(it.name)}')
  println('Returns: ${greet_fn.result.typ.symbol()}')
}

// Parse a function from string
fn_code := '
pub fn add(a int, b int) int {
  return a + b
}
'
function := code.parse_function(fn_code)!
println('Parsed function: ${function.name}')

Summary of Required Actions

1. Implement complete TypeScript generation across all model types
2. Remove empty template files and organize templates properly
3. Enhance type parsing to handle optional types, function types, and sum types
4. Add comprehensive parser documentation with practical examples to README.md
5. Create language-specific generation modules to separate concerns
6. Improve error handling in all parsing functions
7. Standardize documentation and naming conventions across the module

These improvements will make the code module more robust, easier to use, and better prepared for multi-language code generation.