@pleger/esa-js 0.2.0

package/GITHUB_USAGE.md

@@ -0,0 +1,121 @@
+# AspectScript on GitHub
+
+This guide explains how to use the repository from the command line and GitHub.
+
+Repository:
+- https://github.com/pleger/aspectscript
+
+Playground (GitHub Pages):
+- https://pleger.github.io/aspectscript/
+
+## 1) Setup
+
+Clone and install dependencies:
+
+```bash
+git clone https://github.com/pleger/aspectscript.git
+cd aspectscript
+npm install
+```
+
+## 2) Run scripts or examples from CLI
+
+Use the script runner:
+
+```bash
+npm run run:script -- tests/test-ex.js
+```
+
+You can run any `.js` file with AspectScript support (AJS, PCs, Testing):
+
+```bash
+npm run run:script -- path/to/your-script.js
+```
+
+Notes:
+- `load(...)` lines are ignored automatically (for compatibility with legacy test files).
+- The runner instruments JavaScript before execution, then runs it in an AspectScript-enabled VM context.
+
+Export join point trace as machine-readable JSON:
+
+```bash
+npm run run:script -- tests/test-ex.js --trace-json trace.json
+```
+
+Disable transform cache:
+
+```bash
+npm run run:script -- tests/test-ex.js --no-cache
+```
+
+## 3) Use the AspectScript CLI command
+
+You can also use the packaged CLI:
+
+```bash
+npx aspectscript run tests/test-ex.js
+npx aspectscript run tests/test-ex.js --trace-json trace.json
+npx aspectscript run tests/test-ex.js --no-cache
+npx aspectscript test
+npx aspectscript test --cache-stats
+npx aspectscript test --failed
+```
+
+## 4) Run tests from CLI
+
+Run all tests:
+
+```bash
+npm test
+```
+
+Run tests by prefix:
+
+```bash
+node run-tests.js testDS
+node run-tests.js testRee
+node run-tests.js test21
+node run-tests.js --cache-stats
+node run-tests.js --no-cache
+```
+
+## 5) Run only failed tests
+
+After a test run, failed tests are written to `tests/lastFails.txt`.
+
+Re-run only those failed tests:
+
+```bash
+npm run test:failed
+```
+
+Equivalent direct command:
+
+```bash
+node run-tests.js --failed
+```
+
+## 6) Diagnostics
+
+Runtime errors now include an AspectScript context line, for example:
+
+```text
+[AspectScript] join point: [exec: move] | level: 0 | receiver: Point
+```
+
+This helps identify where failures happen in advice/pointcut execution.
+
+## 7) Citation
+
+This implementation is based on:
+
+Rodolfo Toledo, Paul Leger, and Eric Tanter. *AspectScript: Expressive Aspects for the Web*. AOSD'10, March 15-19, 2010, Rennes and St. Malo, France. ACM.
+
+## 8) Conformance Suite
+
+Run paper-aligned conformance scenarios:
+
+```bash
+npm run test:conformance
+node run-conformance.js
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Leger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NPM_PUBLISH.md

@@ -0,0 +1,51 @@
+# npm Publish Readiness
+
+This project is configured for npm packaging, with:
+- `main` entry (`aspectscript.js`)
+- `types` entry (`index.d.ts`)
+- `bin` command (`aspectscript`)
+
+Current state:
+- `package.json` is publish-ready (`"private": false`).
+
+## Checklist
+
+1. Set package metadata
+
+```json
+{
+  "name": "@pleger/esa-js",
+  "version": "0.2.0",
+  "description": "ESA-JS and AspectScript runtime and tooling",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pleger/ESA.git"
+  }
+}
+```
+
+2. Dry run package contents
+
+```bash
+npm pack --dry-run
+```
+
+3. Verify commands
+
+```bash
+npm test
+npm run test:conformance
+npx aspectscript --help
+```
+
+4. Publish
+
+```bash
+npm publish --access public
+```
+
+## Optional hardening
+
+- Add `"files"` in `package.json` to control published artifacts explicitly.
+- Add CI workflow for `npm test` + `npm run test:conformance` before release.

package/PATTERNS.md

@@ -0,0 +1,85 @@
+# AspectScript Patterns
+
+This document gives practical patterns you can copy and adapt.
+
+## 1) Logging all executions of a function
+
+```js
+function service() {
+  return 42;
+}
+
+AJS.before(PCs.exec("service"), function (jp) {
+  console.log("[before]", String(jp), "args:", jp.args);
+});
+
+service();
+```
+
+## 2) Enforce a simple authorization rule
+
+```js
+const session = { role: "guest" };
+
+function deleteRecord() {
+  return "deleted";
+}
+
+AJS.around(PCs.exec("deleteRecord"), function (jp) {
+  if (session.role !== "admin") {
+    throw new Error("Not authorized");
+  }
+  return jp.proceed();
+});
+```
+
+## 3) Prevent recursive self-triggering with `noBR`
+
+```js
+function tick(n) {
+  if (n > 0) {
+    tick(n - 1);
+  }
+}
+
+AJS.before(PCs.noBR(PCs.exec("tick")), function () {
+  console.log("advice once per recursion chain");
+});
+```
+
+## 4) Add explicit domain events
+
+```js
+AJS.before(PCs.event("save"), function (jp) {
+  console.log("save event", jp.recordId);
+});
+
+AJS.event("save", { recordId: 42 }, function () {
+  // protected block
+});
+```
+
+## 5) Export trace data for tooling
+
+```js
+AJS.tracer.enable();
+
+function runFlow() {
+  // your code
+}
+
+runFlow();
+console.log(AJS.tracer.toJSON(true));
+```
+
+Node CLI equivalent:
+
+```bash
+npx aspectscript run your-script.js --trace-json trace.json
+```
+
+## 6) Pitfalls to avoid
+
+- Do not mutate shared join point fields expecting cross-advice visibility; ordering matters and tests rely on deterministic behavior.
+- Use `AJS.down(...)` intentionally; lowering levels can re-introduce loops in badly scoped pointcuts.
+- Prefer specific pointcuts (`PCs.exec("name")`) over catch-all predicates in performance-sensitive code.

package/README.md

@@ -0,0 +1,160 @@
+# ESA / AspectScript
+
+An implementation of ESA-JS (Expressive Stateful Aspects) and AspectScript for JavaScript.
+
+## Quick start (npm)
+
+Install:
+
+```bash
+npm install @pleger/esa-js
+```
+
+### JavaScript example
+
+```js
+const AJS = require("@pleger/esa-js");
+const PCs = AJS.Pointcuts;
+
+AJS.before(PCs.event("purchase"), function (jp) {
+  console.log("purchase observed:", jp.orderId, jp.total);
+});
+
+AJS.event("purchase", { orderId: "A-100", total: 42 }, function () {
+  console.log("inside purchase block");
+});
+```
+
+### TypeScript example
+
+```ts
+import AspectScript = require("@pleger/esa-js");
+
+const AJS = AspectScript;
+const PCs = AJS.Pointcuts;
+
+AJS.around(PCs.event("audit"), (jp) => {
+  console.log("audit event:", jp.action);
+  return jp.proceed();
+});
+
+AJS.event("audit", { action: "DELETE_USER" }, () => {
+  console.log("business logic");
+});
+```
+
+### Running instrumented scripts (`exec`, `call`, `get`, `set`, ...)
+
+Use the CLI runner so your file is instrumented automatically:
+
+```bash
+npx esa run your-script.js
+```
+
+### ESA stateful example
+
+```js
+const AJS = require("@pleger/esa-js");
+const ESA = AJS.ESA;
+const PTs = ESA.Pointcuts;
+
+function a(v) {}
+function b() {}
+
+const callA = PTs.call(a).and((jp, env) => env.bind("value", jp.args[0]));
+
+const handler = ESA.deploy({
+  kind: ESA.BEFORE,
+  pattern: PTs.repeatUntil(callA, PTs.call(b)),
+  advice: (jp, env) => console.log("values:", env.value),
+});
+```
+
+## What is included
+
+- A runtime and source instrumenter for AspectScript and ESA-JS.
+- A Node-based test runner that executes the original `tests/test*.js` suite while ignoring legacy `load(...)` lines.
+- A CLI command (`aspectscript`) for running scripts and tests.
+- TypeScript type definitions (`index.d.ts`).
+- A static playground in `docs/` with ESA-focused examples and:
+  - editable examples
+  - execution output
+  - join point tracing
+
+## Local usage
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+Run with cache statistics:
+
+```bash
+node run-tests.js --cache-stats
+```
+
+Run only failed tests from the previous run:
+
+```bash
+npm run test:failed
+```
+
+Run any script/example file with AspectScript runtime + instrumentation:
+
+```bash
+npm run run:script -- tests/test-ex.js
+```
+
+Run and export execution trace as JSON:
+
+```bash
+npm run run:script -- tests/test-ex.js --trace-json trace.json
+```
+
+Disable transform cache for a run:
+
+```bash
+npm run run:script -- tests/test-ex.js --no-cache
+node run-tests.js --no-cache
+```
+
+Run paper-aligned conformance examples:
+
+```bash
+npm run test:conformance
+```
+
+Use the CLI command:
+
+```bash
+npx esa run tests/test-ex.js
+npx esa test
+npx esa test --failed
+```
+
+Serve the playground locally from `docs/`:
+
+```bash
+cd docs
+python3 -m http.server 4173
+```
+
+Then open `http://127.0.0.1:4173`.
+
+## GitHub guide
+
+For a full command-line and GitHub usage guide, see [GITHUB_USAGE.md](./GITHUB_USAGE.md).
+For practical examples/patterns, see [PATTERNS.md](./PATTERNS.md).
+For package publishing readiness, see [NPM_PUBLISH.md](./NPM_PUBLISH.md).
+
+## Current test status
+
+The current implementation passes the full legacy suite plus ESA split-case tests.

package/ROADMAP_10_STEPS.md

@@ -0,0 +1,14 @@
+# AspectScript 10-Step Roadmap Status
+
+Last updated: March 17, 2026
+
+1. Semantic parity with paper/tests: **Done** (`105/105` passing)
+2. Reentrancy and advice-order hardening: **Done**
+3. Scoping strategies explicit and testable: **Done** (runtime fixes + passing DS/DD tests)
+4. Source-focused diagnostics: **Done** (runtime errors include join point/level/receiver context)
+5. Machine-readable trace format: **Done** (`AJS.tracer.toJSON`, `AJS.tracer.saveToFile`, CLI `--trace-json`)
+6. TypeScript typings: **Done** (`index.d.ts`)
+7. npm package + CLI workflow: **In Progress** (`aspectscript` CLI ready; publish checklist added in `NPM_PUBLISH.md`)
+8. Instrumentation/performance caching: **Done** (`.aspectscript-cache`, `--no-cache`, `--cache-stats`)
+9. Conformance suite from paper examples: **Done** (`conformance/`, `run-conformance.js`, `npm run test:conformance`)
+10. Practical docs and patterns: **Done** (`PATTERNS.md` + README/GitHub guide updates)

package/STEP1_TRIAGE.md

@@ -0,0 +1,139 @@
+# Step 1 Baseline and Triage (March 17, 2026)
+
+This document captures the Step 1 deliverable of the plan:
+- baseline run
+- failure clustering by semantic root cause
+- paper-backed expectations to guide fixes
+
+Reference paper used for Step 1:
+- `/Users/pleger/Downloads/1-s2.0-S0167642313002244-main.pdf`
+- Tanter, Figueroa, Tabareau. *Execution levels for aspect-oriented programming* (Science of Computer Programming 80, 2014).
+
+## 1) Baseline
+
+Command:
+
+```bash
+node run-tests.js
+```
+
+Result:
+- Evaluated: `105`
+- Failed: `11`
+
+Current failing tests:
+- `test-ctx.js`
+- `test-dd-03.js`
+- `test-ss.js`
+- `test15.js`
+- `test21-modifyingJPData.js`
+- `testDS06.js`
+- `testRee01.js`
+- `testRee02.js`
+- `testRee03.js`
+- `testRee04.js`
+- `testRee16-jpOrder.js`
+
+`tests/lastFails.txt` now reflects this baseline.
+
+## 2) Paper-Guided Semantic Baseline
+
+From the paper (used as guidance for expected behavior in this codebase):
+- Execution levels are stratified; join points are emitted one level above current computation.
+- Aspects affect join points one level below their deployment level.
+- The default should defensively reduce regression risk.
+- In AspectScript specifically, execution levels + reentrancy control should allow safe `down` usage without reintroducing loops.
+- Control-flow reasoning should be level-sensitive (avoid conflating base computation and aspect/meta computation).
+
+These principles map directly to current failing clusters around:
+- reentrancy (`noBR`, `down`)
+- cflow / parent-chain visibility
+- scoping strategy and deployment propagation
+
+## 3) Failure Clusters
+
+### Cluster A: Deployment Scope and Join-Point Visibility
+
+Tests:
+- `test-ctx.js`
+- `test-ss.js`
+- `test15.js`
+- `testDS06.js`
+- `test-dd-03.js`
+
+Observed symptoms:
+- Missing expected `pr`/`call` join points in object-scoped scenarios.
+- Unexpected extra matches in propagated/deployed contexts.
+- Missing matches for interface-driven call pointcuts.
+- Duplicate or leaked match in dynamic call/deployment path.
+
+Primary hotspots in runtime:
+- `currentVisibleAspects`, `aspectsFromLexicalContexts` in `aspectscript.js`
+- frame construction in `wrap(...)` (lexical object/function visibility)
+- propagation path (`computePropagation`, `pendingCalls`)
+- strategy gates (`c`, `d`, `f`) in deployment evaluation
+
+Working hypothesis:
+- Aspect visibility and propagation across call/exec boundaries is inconsistent between lexical and dynamic paths, especially for `deployOn(...)` and strategy arrays.
+
+### Cluster B: Advice Order and JP Data Isolation
+
+Tests:
+- `test21-modifyingJPData.js`
+- `testRee16-jpOrder.js`
+
+Observed symptoms:
+- Advice ordering mismatch (`before` behaves as LIFO where tests expect FIFO).
+- cflow/order interaction includes join point `z` when it should be excluded.
+
+Primary hotspots in runtime:
+- chain construction loop in `weave(...)` for `before`/`around`
+- cflow parent traversal and ordering assumptions
+
+Working hypothesis:
+- Advice chain composition order is inverted for `before`.
+- Parent/cflow timing around `before` advice execution may conflate pre-body advice activity with function execution context.
+
+### Cluster C: Reentrancy and Execution Levels (`noBR` + `down`)
+
+Tests:
+- `testRee01.js`
+- `testRee02.js`
+- `testRee03.js`
+- `testRee04.js`
+
+Observed symptoms:
+- Expected advice does not fire at all (over-suppression).
+- `noBR(...)` and `down(...)` interplay blocks legitimate first matches.
+- Context-aware `noBR(pc, ctx)` case suppresses all hits instead of one-per-context behavior.
+
+Primary hotspots in runtime:
+- `Pointcuts.noBR(...)`
+- `down(...)` and `isSuppressed(...)`
+- level bookkeeping (`state.currentLevel`, `state.downStack`)
+
+Working hypothesis:
+- Reentrancy suppression tokening and/or stack scanning is too aggressive.
+- Level suppression may be applied before initial legitimate match is recorded.
+
+## 4) Step 2 Entry Strategy (from this triage)
+
+Recommended fix order:
+1. Fix deterministic advice ordering in `weave(...)` (lowest-risk, unblocks JP-order tests).
+2. Fix `noBR`/`down` suppression semantics (Ree cluster).
+3. Fix deployment propagation and strategy visibility (`deployOn`, `c/d/f`, lexical vs dynamic environments).
+
+Validation workflow:
+
+```bash
+node run-tests.js --failed
+node run-tests.js testRee
+node run-tests.js test-ctx
+node run-tests.js test-ss
+node run-tests.js test-dd-03
+node run-tests.js testDS06
+```
+
+Exit criteria for Step 2 start:
+- each cluster has one targeted failing test used as a guard during implementation
+- full suite run after each cluster fix

package/aspectscript-cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function runNodeScript(scriptName, args) {
+  const scriptPath = path.join(__dirname, scriptName);
+  const result = spawnSync(process.execPath, [scriptPath].concat(args), {
+    stdio: "inherit",
+  });
+  if (typeof result.status === "number") {
+    process.exitCode = result.status;
+  } else {
+    process.exitCode = 1;
+  }
+}
+
+function usage() {
+  process.stdout.write(
+    "AspectScript CLI\n" +
+    "\n" +
+    "Usage:\n" +
+    "  aspectscript run <file.js> [--trace-json trace.json] [--no-cache]\n" +
+    "  aspectscript test [--failed|-f] [--cache-stats] [--no-cache] [testPrefix...]\n" +
+    "\n" +
+    "Examples:\n" +
+    "  aspectscript run tests/test-ex.js\n" +
+    "  aspectscript run tests/test-ex.js --trace-json trace.json\n" +
+    "  aspectscript run tests/test-ex.js --no-cache\n" +
+    "  aspectscript test\n" +
+    "  aspectscript test --cache-stats\n" +
+    "  aspectscript test --failed\n" +
+    "  aspectscript test testRee\n"
+  );
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === "-h" || command === "--help") {
+    usage();
+    return;
+  }
+
+  if (command === "run") {
+    runNodeScript("run-script.js", args.slice(1));
+    return;
+  }
+
+  if (command === "test") {
+    runNodeScript("run-tests.js", args.slice(1));
+    return;
+  }
+
+  process.stderr.write("Unknown command: " + command + "\n\n");
+  usage();
+  process.exitCode = 1;
+}
+
+main();