Lang spec v3

.codex/skills/clava-scripting/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: clava-scripting
+description: Create, update, and explain Clava/LARA scripts in TypeScript using Clava-JS and Lara-JS APIs, including Query/Selector usage, joinpoint selection and filters, and AST transformations. Use for Clava script authoring, joinpoint queries, or refactoring code via Clava/Lara weaver APIs.
+---
+
+# Clava Scripting
+
+## Overview
+
+Write and modify Clava scripts in TypeScript using Clava/Lara APIs for joinpoint selection and AST transformations.
+
+## Quick Start
+
+Use ESM imports with `.js` extensions, select joinpoints with `Query`, and transform with Clava APIs.
+
+```ts
+import Query from "@specs-feup/lara/api/weaver/Query.js";
+import { FunctionJp } from "@specs-feup/clava/api/Joinpoints.js";
+
+const $fn = Query.search(FunctionJp, { isImplementation: true }).first();
+if ($fn) $fn.clone(`${$fn.name}_clone`);
+```
+
+## Workflow
+
+1. Identify joinpoints and attributes.
+Use the generated joinpoint wrappers in `@specs-feup/clava/api/Joinpoints.js` and check `Joinpoints.ts` for default attributes and available fields.
+
+2. Select joinpoints with Query/Selector.
+Use `Query.search`, `Query.searchFrom`, `Query.searchFromInclusive`, `Query.childrenFrom`, and `Selector.scope`. Filters accept strings, regex, predicate functions, or objects keyed by attributes. `Selector` is iterable and methods like `.get()`, `.first()`, and `.chain()` consume the current selection.
+
+3. Transform and emit code.
+Use joinpoint methods like `.clone()`, `.replaceWith()`, `.addParam()`, `.setReturnType()`, and factories in `ClavaJoinPoints` for new nodes. Use `Query.root().code` or `Clava.writeCode()` to inspect or emit output.
+
+## References
+
+- `references/query-api.md` for Query/Selector behavior and filters.
+- `references/clava-apis.md` for key Clava/Lara API entry points and file locations.
+- `references/examples.md` for real scripts and test patterns.

.codex/skills/clava-scripting/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Clava Scripting"
+  short_description: "Write and edit Clava/Lara scripts"
+  default_prompt: "Use $clava-scripting to draft a Clava TypeScript script that queries joinpoints and applies a transformation."

.codex/skills/clava-scripting/references/clava-apis.md

@@ -0,0 +1,33 @@
+# Clava and Lara API Entry Points
+
+Use this to locate the right TypeScript APIs and understand where functionality lives.
+
+## Clava-JS APIs (this repo)
+
+- Joinpoint wrappers (generated): `Clava-JS/src-api/Joinpoints.ts`
+- Joinpoint factories/utilities: `Clava-JS/src-api/clava/ClavaJoinPoints.ts`
+- Core Clava utilities and AST stack: `Clava-JS/src-api/clava/Clava.ts`
+- Common passes/opts built on Query: `Clava-JS/src-api/clava/opt`, `Clava-JS/src-api/clava/pass`
+
+Imports typically use:
+- `@specs-feup/clava/api/Joinpoints.js`
+- `@specs-feup/clava/api/clava/ClavaJoinPoints.js`
+- `@specs-feup/clava/api/clava/Clava.js`
+
+## Lara-JS APIs (sibling repo)
+
+- Query API: `../lara/Lara-JS/src-api/weaver/Query.ts`
+- Selector behavior and filters: `../lara/Lara-JS/src-api/weaver/Selector.ts`
+- Weaver utilities: `../lara/Lara-JS/src-api/weaver/Weaver.ts`
+
+If the Lara-JS repo is not a sibling of Clava, search for `Lara-JS/src-api/weaver/Query.ts`.
+
+Imports typically use:
+- `@specs-feup/lara/api/weaver/Query.js`
+- `@specs-feup/lara/api/weaver/Weaver.js`
+
+## Notes
+
+- Joinpoint wrappers expose attributes and methods specific to each type.
+- `ClavaJoinPoints` provides factory helpers for types, statements, expressions, and declarations.
+- Use `.code` on joinpoints (or `Query.root().code`) to inspect generated code quickly.

.codex/skills/clava-scripting/references/examples.md

@@ -0,0 +1,28 @@
+# Script Examples and Patterns
+
+Use these files for concrete patterns and idioms.
+
+## Weaver tests (JS, but patterns apply to TS)
+
+- `ClavaWeaver/resources/clava/test/weaver/Function2.js`
+  - Select function, clone it, change return type, replace body, add param.
+
+- `ClavaWeaver/resources/clava/test/weaver/Clone.js`
+  - Clone all functions with definitions and print file code.
+
+- `ClavaWeaver/resources/clava/test/weaver/Field.js`
+  - Navigate record fields and read attributes like `isPublic`.
+
+- `ClavaWeaver/resources/clava/test/issues/Issue168.js`
+  - Normalize loops and decompose statements using `NormalizeToSubset` and `StatementDecomposer`.
+
+- `ClavaWeaver/resources/clava/test/issues/Issue_aiq_1.js`
+  - Filter loops by kind, inspect condition relation.
+
+## API tests
+
+- `ClavaWeaver/resources/clava/test/api/ClavaJoinPointsTest.js`
+  - Large catalog of `ClavaJoinPoints` factory helpers.
+
+- `Clava-JS/src-api/Query.test.ts`
+  - Query chaining, `.scope()`, `.chain()`, and regex selection.

.codex/skills/clava-scripting/references/query-api.md

@@ -0,0 +1,47 @@
+# Query and Selector API
+
+Use this when writing or debugging joinpoint selection logic.
+
+## Primary sources
+
+- Query API: `../lara/Lara-JS/src-api/weaver/Query.ts` (sibling worktree)
+- Selector behavior: `../lara/Lara-JS/src-api/weaver/Selector.ts` (sibling worktree)
+- Query usage tests: `Clava-JS/src-api/Query.test.ts`
+
+If the Lara-JS repo is not a sibling of Clava, search for `Lara-JS/src-api/weaver/Query.ts`.
+
+## Core patterns
+
+- `Query.root()` returns the root joinpoint.
+- `Query.search(Type, filter?, traversal?)` starts from root.
+- `Query.searchFrom($base, Type?, filter?, traversal?)` searches below a base node (exclusive).
+- `Query.searchFromInclusive($base, Type?, filter?, traversal?)` includes the base node.
+- `Query.childrenFrom($base, Type?, filter?)` searches direct children.
+- `Selector.scope(Type?, filter?)` searches inside the scope of the previously selected nodes.
+
+## Filters
+
+Filters accept:
+- A string or regex applied to the default attribute for that joinpoint type.
+- A predicate function `(jp) => boolean`.
+- An object with attribute names as keys and values of string/regex/predicate.
+
+Default attributes are defined in the joinpoint wrappers and can be resolved via `Weaver.getDefaultAttribute()`.
+
+## Selector consumption
+
+`Selector` is iterable and is consumed by `for..of`, `.get()`, `.first()`, and `.chain()`.
+Use `.chain()` when you need the full chain map (e.g., `loop`, `loop_0`, `loop_1`).
+
+## Minimal examples
+
+```ts
+for (const $fn of Query.search(FunctionJp, { isImplementation: true })) {
+  // $fn is a joinpoint instance
+}
+
+const chains = Query.search(FunctionJp, "query_loop")
+  .search(Loop)
+  .search(Loop)
+  .chain();
+```

.github/workflows/ant-lara-2.0-legacy.yml

@@ -50,7 +50,7 @@ jobs:
     - name: Generate build.xml
       run: | 
         wget -q -N http://specs.fe.up.pt/tools/eclipse-build.jar
-        java -jar eclipse-build.jar https://github.com/specs-feup/specs-java-libs https://github.com/specs-feup/lara-framework?commit=lara-2.0-legacy ./
+        java -jar eclipse-build.jar https://github.com/specs-feup/specs-java-libs?commit=lara-2.0-legacy https://github.com/specs-feup/lara-framework?commit=lara-2.0-legacy ./
         wget -N -O /usr/share/ant/lib/ivy-2.5.0.jar specs.fe.up.pt/libs/ivy-2.5.0.jar
     - name: Build with Ant
       run: |

.github/workflows/copilot-setup-steps.yml

@@ -117,3 +117,29 @@ jobs:
           repository: specs-feup/specs-java-libs
           path: specs-java-libs
           ref: ${{ steps.repo-refs.outputs.specs_ref }}
+
+      - name: Build Weaver
+        run: |
+          cd clava/ClavaWeaver
+          gradle installDist
+
+      - name: Setup java-binaries symlink
+        run: |
+          cd clava/Clava-JS
+          ln -s ../ClavaWeaver/build/install/ClavaWeaver/ java-binaries
+
+
+      - name: Setup JS workspace
+        run: |
+          echo '{ "name": "SPeCS Workspace", "type": "module", "workspaces": [ "clava/Clava-JS", "lara-framework/Lara-JS" ] }' > package.json
+          npm install
+
+      - name: Build Lara-JS
+        run: |
+          cd lara-framework/Lara-JS
+          npm run build
+
+      - name: Build Clava-JS
+        run: |
+          cd clava/Clava-JS
+          npm run build

.github/workflows/nightly.yml

@@ -234,10 +234,9 @@ jobs:
                     TIMESTAMP=$(date +"%Y%m%d%H%M")
                     npm version prerelease --preid="$TIMESTAMP"
                     npm publish --tag staging --access public
-                # Not updating automatically the version since this would make the staging branch diverge from the main branch
-                #elif [ "${{ github.ref }}" == "refs/heads/master" ]; then
-                #    echo "Publishing from main, assumes version was changed before publishing"
-                #    npm publish
+                elif [ "${{ github.ref }}" == "refs/heads/master" ]; then
+                    echo "Publishing from main, assumes version was changed before publishing"
+                    npm publish
                 else
                     echo "Not master or staging branches, not publishing even if it is a push event"
                 fi

Clava-JS/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specs-feup/clava",
-  "version": "3.5.0",
+  "version": "3.5.1",
   "description": "A C/C++ source-to-source compiler written in Typescript",
   "type": "module",
   "files": [