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();
+```