feat: Complete function overloading, TypeScript bindings generator, and JavaScript interop enhancements

[fcoury]

Summary

This PR implements comprehensive function overloading support, a TypeScript bindings generator (bindgen), and extensive JavaScript interoperability enhancements for Husk, including security hardening, performance optimizations, and comprehensive testing.

Major Features

1. Function Overloading with Type-Aware Resolution

• Implemented complete function overload resolution based on parameter types, not just count
• Support for first-class functions as parameters
• Proper type matching for arrays, tuples, functions, and complex nested types
• Instance method overload resolution for extern implementations

2. TypeScript Bindings Generator (husk bindgen)

• Renamed from dts2-extern to bindgen for better clarity
• Converts TypeScript .d.ts files to Husk extern declarations
• Supports both local files and HTTPS URLs with security validation
• Handles complex TypeScript features:
  • Type aliases and interface extensions
  • Namespaces and qualified types
  • Function overloading
  • Generic type parameters
  • Optional parameters

3. JavaScript Interoperability Enhancements

• js_name Attribute Validation: Validates JavaScript identifiers and prevents reserved words
• Import Aliasing: Automatic camelCase to snake_case conversion with proper aliasing
• Cross-file Extern Support: Import and use extern functions across modules
• Any Type Support: Fallback for complex TypeScript types

Security & Performance Improvements

Security Enhancements

• SSRF Protection: Comprehensive URL validation for bindgen HTTP requests
• IP Range Blocking: Prevents access to private IPs and metadata endpoints
• Content Validation: Size limits and content type checking
• Reserved Keyword Handling: Automatic escaping of JavaScript reserved words

Performance Optimizations

• Function Lookup Indexing: HashMap indexing by parameter count for O(1) lookup
• Efficient Overload Resolution: Quick filtering before type checking
• Bounds Checking: Comprehensive bounds validation for array and string operations

Testing & Quality

Comprehensive Test Coverage

• 610 tests all passing
• Function overloading with 20+ test cases
• Security validation tests for URL handling
• Error case testing for bindgen command (17 scenarios)
• Bounds checking tests for TypeScript conversion
• JavaScript identifier validation tests

Real-World Example

Complete Node.js fs module integration demonstrating:

// Generated by: husk bindgen fs.d.ts
extern mod fs {
    #[js_name = "existsSync"]
    fn exists_sync(path: string) -> bool;
    
    #[js_name = "readFileSync"]
    fn read_file_sync(path: string) -> Buffer;
    #[js_name = "readFileSync"]
    fn read_file_sync(path: string, encoding: string) -> string;
}

Technical Implementation Details

Function Overloading Architecture

• Enhanced FunctionSignature with full type information
• overloaded_functions: HashMap<String, Vec<(FunctionSignature, bool)>>
• Type-aware matching with proper conversion support (int to float)
• Clear error messages showing all available overloads

Bindgen Implementation

• SwC-based TypeScript parser integration
• Recursive type resolution with circular reference handling
• Intelligent module name inference
• Support for filter and simplify options

Parser Enhancements

• Array type syntax: int[], string[][]
• Function type syntax: (int, string) -> bool
• Extern impl parsing for instance methods
• Tuple type support in parameters

Breaking Changes

None - all changes are backwards compatible and enhance existing functionality.

Commits Summary

• ✨ Complete function overloading with type-aware resolution
• 🔧 Rename dts2-extern to bindgen command
• 🔒 Add comprehensive security validation for HTTP URLs
• ⚡ Optimize function lookup with parameter indexing
• ✅ Add extensive test coverage for all new features
• 🐛 Fix struct method call regression
• 📝 Add JavaScript identifier validation
• 🛡️ Add bounds checking for TypeScript conversion
• 🎯 Implement first-class function support

Test Plan

✅ Function Overloading

• Type-based resolution works correctly
• Error messages show all available overloads
• Cross-file usage maintains overload information
• Performance optimization doesn't affect correctness

✅ Bindgen Command

• Converts complex TypeScript definitions accurately
• Security validation prevents SSRF attacks
• Handles edge cases (BOM, circular refs, binary files)
• Generated code compiles and runs correctly

✅ JavaScript Interop

• js_name attributes validated properly
• Import aliasing generates correct JavaScript
• Reserved keywords automatically escaped
• All extern features work together seamlessly

✅ Integration Testing

• fs-example demonstrates complete workflow
• Real Node.js APIs work correctly
• No regressions in existing functionality
• All 610 tests passing

[fcoury]

@claude review this PR

[claude]

Claude finished @fcoury's task —— View job

---

PR Review: Complete JS Interop Features

Comprehensive review of JavaScript interoperability features implementation completed.

Review Checklist

• Review core semantic analysis changes (semantic.rs)
• Analyze transpiler modifications for import aliasing (transpiler.rs)
• Check attribute parsing and AST extensions (parser.rs)
• Review dts2extern converter implementation (dts/ module)
• Evaluate function overloading implementation
• Assess security implications of TypeScript integration
• Check test coverage and example quality
• Performance considerations analysis
• Code quality and best practices review
• Final review summary and recommendations

---

🔍 Review Summary

This PR implements a comprehensive JavaScript interoperability system for Husk. The implementation is well-architected and addresses a critical need for TypeScript integration. Here's my detailed analysis:

✅ Strengths

1. Solid Architecture

• Function overloading via HashMap<String, Vec<FunctionSignature>> in semantic.rs:25 is a clean approach
• Import aliasing in transpiler.rs:1276-1290 correctly handles js_name mappings
• AST extensions properly support key-value attributes: #[js_name = "actualName"]

2. Comprehensive TypeScript Integration

• dts2extern converter uses SWC parser - industry standard for TypeScript parsing
• Smart camelCase→snake_case conversion with proper acronym handling (dts/converter.rs:18-47)
• Reserved keyword sanitization prevents conflicts (dts/converter.rs:105-111)

3. Excellent Working Example

• examples/fs-example/ demonstrates real Node.js fs module integration
• Generated fs_types.husk shows proper function overloading (lines 60-68)
• Complete usage example in main.husk with proper error handling

⚠️ Issues & Recommendations

1. Function Overloading Limitations

• find_matching_function only matches by argument count (semantic.rs:162-173)
• Risk: Won't distinguish between readFile(path: string) and readFile(path: Buffer)
• Recommendation: Implement type-aware overload resolution

2. Security Concerns

• dts2extern command accepts HTTP URLs (commands/dts2extern.rs:33-49)
• Risk: Could fetch malicious TypeScript definitions
• Recommendation: Add URL validation, restrict to known registries, or add --allow-http flag

3. Error Handling Gaps

• No validation of js_name attribute values
• Missing bounds checking in TypeScript type conversion
• Recommendation: Add validation for special characters in js_name values

4. Performance Considerations

• Function lookup is O(n) through signature vectors
• Impact: Could be slow with many overloads
• Recommendation: Consider indexing by argument count for O(1) initial lookup

🧪 Test Coverage Assessment

Strong Coverage:

• Type casting transpilation tests (transpiler_js_interop_tests.rs)
• Semantic analysis for type casts (semantic_js_interop_tests.rs)
• Working fs-example integration test

Missing Coverage:

• No specific tests for function overloading resolution
• Limited error case testing for dts2extern
• No security tests for HTTP URL handling

🔒 Security Analysis

Moderate Risk Areas:

1. HTTP fetching in dts2extern without validation
2. String interpolation in generated code paths
3. No input sanitization for TypeScript identifiers

Mitigation Applied:

• Reserved keyword checking prevents code injection
• Proper escaping in generated JavaScript

💡 Specific Recommendations

High Priority:

1. Fix overload resolution: Implement type-aware matching in find_matching_function
2. Secure HTTP handling: Add URL validation or restrict to localhost/known registries
3. Add overload tests: Create comprehensive function overloading test suite

Medium Priority:

1. Optimize lookups: Index function signatures by parameter count
2. Validate js_name: Ensure attribute values are valid JavaScript identifiers
3. Better error messages: More specific errors for overload resolution failures

Code Quality:

// Consider this improvement for function resolution:
fn find_matching_function(&self, name: &str, arg_types: &[Type]) -> Option<&FunctionSignature> {
    if let Some(signatures) = self.functions.get(name) {
        // First try exact type match, then fallback to count-based matching
        signatures.iter()
            .find(|(params, _, _)| self.types_match(params, arg_types))
            .or_else(|| signatures.iter().find(|(params, _, _)| params.len() == arg_types.len()))
    } else {
        None
    }
}

🎯 Overall Assessment

Verdict: APPROVE with minor improvements

This is a well-implemented feature that significantly enhances Husk's JavaScript interoperability. The core architecture is sound, the TypeScript integration is comprehensive, and the working example demonstrates real-world usage.

The identified issues are mostly edge cases and performance optimizations rather than fundamental flaws. The security concerns are manageable with the suggested improvements.

Breaking Changes: ✅ None - purely additive functionality
Documentation: ✅ Comprehensive with working examples
Test Coverage: ⚠️ Good but could be more comprehensive for overloading
Performance: ⚠️ Acceptable but could be optimized
Security: ⚠️ Minor concerns with HTTP fetching

Recommendation: Merge after addressing the function overloading resolution and HTTP security issues.

---

[claude]

Claude finished @fcoury's task —— View job

---

Code Review: JS Interop & Function Overloading Implementation

Reviewing this comprehensive PR that implements JavaScript interoperability features, function overloading, and TypeScript integration.

Review Progress

• Analyze core language changes (parser.rs, semantic.rs, transpiler.rs)
• Review dts2extern converter implementation
• Examine function overloading logic
• Check attribute system implementation
• Review import aliasing and transpilation
• Analyze examples and test coverage
• Identify potential bugs, security issues, or performance concerns
• Assess code quality and maintainability
• Provide final review summary

---

Executive Summary

This is a substantial and well-architected PR that successfully implements comprehensive JavaScript interoperability features. The implementation is solid with good separation of concerns, but there are several important issues that should be addressed before merging.

Detailed Code Review

✅ Strengths

1. Excellent Architecture: Clean separation between parsing, semantic analysis, and transpilation phases
2. Comprehensive Feature Set: Covers the full spectrum from TypeScript parsing to JavaScript generation
3. Good Examples: The fs-example demonstrates real-world usage effectively
4. Backward Compatibility: Maintains compatibility with existing Husk code
5. Consistent Patterns: js_name extraction and usage follows consistent patterns throughout

⚠️ Critical Issues

1. Function Overload Resolution is Inadequate (src/semantic.rs:162-173)

Issue: Only matches by parameter count, not types:

signatures.iter().find(|(params, _, _)| params.len() == arg_count)

Problem: Could call wrong overload if multiple functions have same parameter count but different types.

Impact: Runtime errors and incorrect function calls.

2. No js_name Collision Detection (src/semantic.rs:579)

Issue: Multiple functions can map to the same JavaScript name:

self.extern_functions.insert(full_name.clone(), js_name.clone()); // No collision check

Problem: Last mapping wins silently, causing function calls to resolve incorrectly.

3. Overload Resolution Edge Cases (src/semantic.rs:117)

Issue: Arbitrary selection of first overload for type checking:

if let Some((params, return_type, _)) = signatures.first()

Problem: May miss better-matching overloads during semantic analysis.

🐛 Bugs & Issues

4. CamelCase Conversion Bug (src/dts/converter.rs:28-36)

Issue: Acronym handling is complex and may not handle edge cases:

if !prev_was_uppercase {
    result.push('_');
} else if let Some(&next_ch) = chars.peek() {
    if next_ch.is_lowercase() {
        result.push('_');
    }
}

Potential Problems:

• XMLParser → xml_parser ✓
• HTMLElementAPI → could become html_element_api or htmlelement_api ❓

5. Reserved Keyword Collision (src/dts/converter.rs:105-111)

Issue: Simple suffix approach may not prevent all conflicts:

fn sanitize_param_name(name: String) -> String {
    if is_reserved_keyword(&name) {
        format!("{}_", name)  // struct → struct_
    } else {
        name
    }
}

Problem: struct_ could still conflict with user-defined struct_ parameter.

6. Debug Output in Production Code (src/dts/converter.rs:182+)

Issue: Excessive eprintln! statements throughout converter:

eprintln!("[DEBUG] Starting conversion for module: {}", module_name);

Problem: Debug output will appear in production builds, cluttering user experience.

🔍 Code Quality Issues

7. Error Handling Inconsistencies

• Good error messages for overloads in some places, missing in others
• No validation for malformed js_name attributes
• Missing bounds checking for overload counts

8. Type System Gaps

• HuskType::Any used as fallback for complex TypeScript types
• No validation that js_name contains valid JavaScript identifiers
• Union types, generics marked as opaque rather than attempting conversion

9. Memory Efficiency

• Backward compatibility with_args() creates unnecessary AttributeArgument::Identifier wrappers
• Multiple allocations in camelCase conversion that could be optimized

📋 Missing Features

1. Type-based overload resolution - Critical for correctness
2. Comprehensive validation - js_name format, collision detection
3. Better TypeScript type mapping - Unions, generics partially supported
4. Error recovery - Parser fails completely on attribute errors

🧪 Test Coverage Assessment

Good Coverage:

• Basic transpilation tests exist
• Working examples demonstrate integration
• Type casting tests cover common scenarios

Missing Coverage:

• Edge cases in overload resolution
• js_name collision scenarios
• Complex TypeScript type conversions
• Error conditions and malformed attributes

Recommendations

Must Fix Before Merge:

1. Implement proper overload resolution with type matching, not just parameter count
2. Add js_name collision detection with clear error messages
3. Remove debug output from dts2extern converter
4. Add comprehensive tests for overload resolution edge cases

Should Fix:

1. Improve error handling consistency across all modules
2. Validate js_name format to ensure valid JavaScript identifiers
3. Better TypeScript type mapping for unions and generics
4. Add bounds checking and input validation

Consider for Future:

1. Performance optimization of camelCase conversion
2. Enhanced TypeScript support for complex types
3. Better error recovery in attribute parsing

Security Assessment

No security issues identified. The implementation properly handles user input and doesn't introduce any obvious vulnerabilities.

Final Verdict

This PR implements an impressive and comprehensive JavaScript interop system with solid architecture. However, the function overload resolution logic has critical correctness issues that could lead to wrong function calls at runtime.

Recommendation: Request changes to fix the overload resolution and collision detection issues before merge. The implementation is otherwise excellent and these fixes should be straightforward.

---

Files Reviewed: 37 changed files focusing on core language changes, dts2extern converter, examples, and test coverage.