Lara dsl deprecation

.github/copilot-instructions.md

@@ -0,0 +1,321 @@
+# LARA Framework - Copilot Instructions
+
+## Project Overview
+
+The LARA Framework is a sophisticated **source-to-source compiler framework** designed for building domain-specific language (DSL) compilers and weavers. It provides tools and APIs to develop custom source-to-source transformations for programming languages, with a particular focus on C/C++ and other systems programming languages.
+
+### Key Capabilities
+- **Source-to-source compilation**: Transform code from one representation to another while preserving semantics
+- **Metaprogramming support**: Enable automated code generation and transformation
+- **Language-agnostic architecture**: Define custom AST specifications for any target language
+- **DSL development**: Build domain-specific languages with integrated tooling
+
+### Target Audience
+- Compiler developers
+- Research teams working on code optimization and transformation
+- Tool developers building code analysis and transformation systems
+- Academic researchers in programming languages and compilers
+
+## Development Environment & Setup
+
+- **Java Version:** 17+ (required for all Java components)
+- **Node.js Version:** 20 or 22 (minimum 20.0.0 for JavaScript components)
+- **Build System:** Gradle for Java modules, npm for TypeScript/JavaScript
+- **IDE:** VSCode is recommended for development
+
+## Architecture Overview
+
+The LARA framework follows a modular architecture with clear separation of concerns:
+
+```
+lara-framework/
+├── Lara-JS/                   # JavaScript/TypeScript driver/entrypoint and API collection for transformations and analyses
+├── LanguageSpecification/     # XML-based AST specification system
+├── WeaverGenerator/           # Automatic weaver code generation
+├── LARAI/                     # LARA Interpreter
+├── DefaultWeaver/             # Reference weaver implementation
+├── WeaverInterface/           # Core weaver interfaces
+├── WeaverOptionsManager/      # Configuration management
+└── LaraUtils/                 # Shared utilities
+```
+
+### Technology Stack
+- **Backend**: Java 17+ with Gradle build system
+- **Frontend**: TypeScript/JavaScript with Node.js 20 or 22
+- **Specification**: XML with XSD schema validation
+- **Testing**: Jest (JS), JUnit (Java)
+- **Interoperability**: Java-JavaScript bridge via `java` npm package
+
+### Related Projects
+- **clava**: C/C++ source-to-source compiler built on LARA framework
+- **kadabra**: Java source-to-source compiler built on LARA framework
+- **specs-java-libs**: Core Java utility libraries (SpecsUtils, jOptions, etc.)
+
+## Core Concepts
+
+### 1. Join Point Model
+Join points represent nodes in an Abstract Syntax Tree (AST) with associated attributes and actions:
+
+```typescript
+// Example: A function join point with attributes and actions
+class FunctionJoinPoint extends LaraJoinPoint {
+  // Attributes (read-only properties)
+  get name(): string { /* function name */ }
+  get params(): VariableJoinPoint[] { /* parameters */ }
+  get body(): StatementJoinPoint { /* function body */ }
+
+  // Actions (methods that transform the AST)
+  replaceWith(newFunction: FunctionJoinPoint): void { /* replace implementation */ }
+  insertBefore(statement: StatementJoinPoint): void { /* insert before this function */ }
+}
+```
+
+These are defined in the `joinPointModel.xml` file, which specifies the hierarchy and relationships between different join point types.
+You can then run the following command to generate the TypeScript interfaces for the join points:
+
+```bash
+# Generate TypeScript interfaces from XML specifications
+cd Lara-JS
+npm run build-interfaces
+```
+
+### 2. Weaver Pattern
+Weavers are the core transformation engines that implement source-to-source compilation:
+
+```java
+public class CustomWeaver extends AWeaverEngine {
+    @Override
+    public List<Class<? extends AJoinPoint>> getJoinPointClasses() {
+        // Return available join point types
+    }
+
+    @Override
+    public boolean handlesApplication(File source) {
+        // Determine if this weaver can process the source
+    }
+}
+```
+
+A lot of their code is automatically generated by the `WeaverGenerator` module, which creates boilerplate code based on the XML specifications of the joinpoints.
+It is run automatically during the build process.
+
+### 3. Language Specification System
+The framework uses XML-based specifications to define:
+
+- **joinPointModel.xml**: AST node hierarchy and relationships
+- **actionModel.xml**: Available methods/actions on join points  
+- **artifacts.xml**: Attributes and properties of join points
+
+```xml
+<!-- Example join point definition -->
+<joinpoint class="function" extends="executable">
+    <select class="var" alias="param"/>
+    <select class="statement" alias="body"/>
+</joinpoint>
+```
+
+### 4. Java-JavaScript Interoperability
+The Lara-JS module provides seamless integration between Java weavers and JavaScript transformation scripts:
+
+```typescript
+// Access Java weaver functionality from JavaScript
+const weaverEngine = Weaver.getWeaverEngine();
+const rootJoinPoint = weaverEngine.getRootJoinPoint();
+
+// Transform AST using JavaScript
+for (const func of Query.search('function')) {
+    if (func.name.startsWith('old_')) {
+        func.replaceWith(modernizeFunction(func));
+    }
+}
+```
+
+## Module Details
+
+### Lara-JS (`@specs-feup/lara`)
+**Purpose**: TypeScript/JavaScript implementation providing modern API and better compatibility
+
+**Key Components**:
+- `src-api/`: Public API for weaver development
+- `src-code/`: Core weaver functionality and launchers  
+- `scripts/`: Build and interface generation tools
+
+**Entry Points**:
+- `core.ts`: Global imports and initialization
+- `weaver/Weaver.ts`: Main weaver utilities
+- `LaraJoinPoint.ts`: Base join point implementation
+
+### LanguageSpecification
+**Purpose**: Formal XML-based specification system for defining AST structures
+
+**Key Files**:
+- `language/*.xml`: Core language specifications
+- `resources/schemas/*.xsd`: XML Schema definitions for validation
+- `DOCUMENTATION.md`: Comprehensive specification guide
+
+**Usage**: Define custom AST nodes, attributes, and actions for new target languages
+
+### WeaverGenerator  
+**Purpose**: Automatically generate Java weaver implementations from language specifications
+
+**Capabilities**:
+- Generate join point classes from XML specifications
+- Create weaver boilerplate code
+- Validate specification consistency
+
+### LARAI
+**Purpose**: LARA Interpreter for executing transformation scripts
+
+**Key Class**: `LaraI.java` - Main interpreter entry point with thread-local weaver management
+
+## Development Guidelines
+
+### Code Organization Patterns
+
+1. **Join Point Hierarchy**: Follow inheritance patterns defined in `joinPointModel.xml`
+2. **Attribute Naming**: Use camelCase for JavaScript, snake_case for internal representations
+3. **Action Methods**: Prefix with verb (e.g., `replace`, `insert`, `remove`)
+4. **Type Safety**: Leverage TypeScript for API definitions, Java generics for backend
+
+### Common Development Scenarios
+
+#### Adding a New Join Point Type
+1. Update `LanguageSpecification/language/joinPointModel.xml`
+2. Define attributes in `artifacts.xml` 
+3. Add actions in `actionModel.xml`
+4. Regenerate interfaces using WeaverGenerator (gradle should handle this automatically)
+5. Implement concrete classes in target weaver
+
+#### Creating a Custom Weaver
+1. Extend `AWeaverEngine` in Java backend
+2. Implement required abstract methods
+3. Define language-specific join points
+4. Create JavaScript API wrapper in Lara-JS
+5. Add configuration options via WeaverOptionsManager
+
+### Build System
+
+The project uses Gradle multi-project build:
+
+```bash
+# Build all modules
+./gradle build
+
+# Build specific module  
+./gradle :Lara-JS:build
+
+# Run tests
+./gradle test
+```
+
+### Testing Approach
+
+- **Unit Tests**: Jest for TypeScript, JUnit for Java
+- **Integration Tests**: End-to-end weaver execution tests
+- **Specification Tests**: XML schema validation and parsing tests
+
+## API Reference Summary
+
+### Core Classes (Java)
+- `WeaverEngine`: Main weaver execution engine
+- `AJoinPoint`: Base class for all join points
+- `LaraI`: Interpreter and execution context
+- `LanguageSpecification`: XML specification parser
+
+### Core Classes (TypeScript)
+- `LaraJoinPoint`: Base join point with JavaScript API
+- `Weaver`: Utility methods for weaver interaction
+- `Query`: AST querying and selection
+- `DataStore`: Configuration and state management
+
+### Common Usage Patterns
+
+```typescript
+// 1. Querying AST
+const functions = Query.searchFrom($root, 'function');
+const loops = Query.searchFrom($function, 'loop');
+
+// 2. Accessing attributes
+console.log($function.name, $function.numParams);
+
+// 3. Applying transformations  
+$loop.setKind('unroll');
+$statement.insertBefore(newStatement);
+
+// 4. Weaver utilities
+const isJP = Weaver.isJoinPoint($node);
+const defaultAttr = Weaver.getDefaultAttribute('function');
+```
+
+## Integration Points
+
+### For Weaver Developers
+- Implement `WeaverEngine` interface
+- Define join point specifications in XML
+- Create transformation APIs
+
+### For Language Researchers  
+- Extend language specifications
+- Add new join point types and attributes
+- Implement domain-specific transformations
+
+### For Tool Builders
+- Use Lara-JS APIs for tool integration
+- Leverage parallel execution capabilities
+- Build on weaver launcher infrastructure
+
+## Dependencies and Requirements
+
+### Runtime Requirements
+- **Java**: JDK 17 or higher
+- **Node.js**: Version 20 or 22 (minimum 20.0.0)
+- **Build**: Gradle 6.0+ for Java modules
+
+### Key Dependencies
+- `java`: Node.js-Java bridge
+- `cytoscape`: Graph visualization
+- `yargs`: Command-line argument parsing
+- `chokidar`: File system watching
+
+## Common Troubleshooting
+
+### Java-JavaScript Interop Issues
+- Ensure compatible Java and Node.js versions
+- Check `java` npm package installation
+- Verify JAVA_HOME environment variable
+
+### Specification Validation Errors
+- Validate XML against XSD schemas
+- Check join point inheritance consistency  
+- Verify action parameter types
+
+### Build Issues
+- Clean and rebuild with `./gradle clean build`
+- Check Gradle wrapper compatibility
+- Ensure all subprojects build independently
+
+## References
+
+- **Main Repository**: https://github.com/specs-feup/lara-framework
+- **Language Specification Guide**: `LanguageSpecification/DOCUMENTATION.md`
+
+## Contributing
+
+When working with this codebase:
+
+1. **Follow established patterns** for join point definitions and weaver implementations
+2. **Update specifications** when adding new AST node types
+3. **Maintain compatibility** between Java and JavaScript APIs  
+4. **Add comprehensive tests** for new functionality
+5. **Document new join point types** and transformation capabilities
+
+The LARA framework is designed for extensibility - most common development tasks involve extending existing patterns rather than creating entirely new architectures.
+
+---
+
+**For LLMs:**
+- Follow established patterns for join point definitions and weaver implementations
+- Update specifications when adding new AST node types
+- Maintain compatibility between Java and JavaScript APIs
+- Add comprehensive tests for new functionality
+- Document new join point types and transformation capabilities