@pleger/esa-js 0.2.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@pleger/esa-js",
+  "version": "0.2.0",
+  "description": "ESA-JS and AspectScript runtime, instrumentation, and CLI tooling",
+  "main": "aspectscript.js",
+  "types": "index.d.ts",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pleger/ESA.git"
+  },
+  "homepage": "https://github.com/pleger/ESA#readme",
+  "bugs": {
+    "url": "https://github.com/pleger/ESA/issues"
+  },
+  "keywords": [
+    "aspect-oriented-programming",
+    "esa",
+    "stateful-aspects",
+    "tracematch",
+    "aspectscript",
+    "javascript",
+    "typescript",
+    "aop",
+    "join-point"
+  ],
+  "files": [
+    "aspectscript.js",
+    "esa.js",
+    "aspectscript-cli.js",
+    "instrument.js",
+    "transform-cache.js",
+    "run-script.js",
+    "run-tests.js",
+    "run-conformance.js",
+    "index.d.ts",
+    "conformance/",
+    "README.md",
+    "GITHUB_USAGE.md",
+    "PATTERNS.md",
+    "ROADMAP_10_STEPS.md",
+    "NPM_PUBLISH.md",
+    "STEP1_TRIAGE.md"
+  ],
+  "exports": {
+    ".": "./aspectscript.js",
+    "./esa": "./esa.js",
+    "./instrument": "./instrument.js"
+  },
+  "bin": {
+    "aspectscript": "aspectscript-cli.js",
+    "esa": "aspectscript-cli.js"
+  },
+  "scripts": {
+    "test": "node run-tests.js",
+    "test:failed": "node run-tests.js --failed",
+    "test:conformance": "node run-conformance.js",
+    "run:script": "node run-script.js",
+    "cli": "node aspectscript-cli.js",
+    "pack:check": "npm_config_cache=/tmp/aspectscript-npm-cache npm pack --dry-run"
+  },
+  "dependencies": {
+    "acorn": "^8.16.0",
+    "acorn-walk": "^8.3.5",
+    "astring": "^1.9.0"
+  }
+}

package/run-conformance.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function listConformanceFiles(root, filters) {
+  const files = fs.readdirSync(root)
+    .filter((name) => name.endsWith(".js"))
+    .sort();
+  if (!filters.length) {
+    return files;
+  }
+  return files.filter((name) => filters.some((filter) => name.includes(filter)));
+}
+
+function main() {
+  const conformanceDir = path.join(__dirname, "conformance");
+  const filters = process.argv.slice(2);
+  const files = listConformanceFiles(conformanceDir, filters);
+  if (!files.length) {
+    process.stdout.write("No conformance files matched.\n");
+    return;
+  }
+
+  let failures = 0;
+  for (const file of files) {
+    const fullPath = path.join(conformanceDir, file);
+    const result = spawnSync(process.execPath, [path.join(__dirname, "run-script.js"), fullPath], {
+      cwd: __dirname,
+      encoding: "utf8",
+    });
+    if (result.status !== 0) {
+      failures += 1;
+      process.stdout.write(file + "\n");
+      if (result.stdout) {
+        process.stdout.write(result.stdout);
+      }
+      if (result.stderr) {
+        process.stdout.write(result.stderr);
+      }
+    }
+  }
+
+  process.stdout.write("Evaluated " + files.length + " conformance file(s). Failed " + failures + ".\n");
+  if (failures) {
+    process.exitCode = 1;
+  }
+}
+
+main();

package/run-script.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const vm = require("vm");
+
+const { transformProgramCached } = require("./transform-cache");
+const { createAspectScript } = require("./aspectscript");
+
+function stripLoads(source) {
+  return source
+    .split("\n")
+    .filter((line) => !/^\s*load\(/.test(line))
+    .join("\n");
+}
+
+function makeTesting(context) {
+  const flags = [];
+
+  function stringify(value) {
+    if (value && (typeof value === "object" || typeof value === "function") &&
+        typeof value.toString === "function" &&
+        value.toString !== Object.prototype.toString) {
+      return String(value);
+    }
+    return value;
+  }
+
+  function fail(message) {
+    throw new Error(message);
+  }
+
+  return {
+    flag(value) {
+      flags.push(stringify(value));
+    },
+    assert(expr) {
+      if (!vm.runInContext(String(expr), context)) {
+        fail("Assertion failed: " + expr);
+      }
+    },
+    assert2(label, condition) {
+      if (!condition) {
+        fail("Assertion " + label + " failed");
+      }
+    },
+    check(...expected) {
+      if (expected.length === 1 &&
+          typeof expected[0] === "string" &&
+          /\s/.test(expected[0]) &&
+          !/^\[.*\]$/.test(expected[0])) {
+        if (flags.length === 0) {
+          fail(expected[0]);
+        }
+        flags.length = 0;
+        return;
+      }
+      if (expected.length !== flags.length) {
+        fail("Expected: " + expected.join(" ") + " | Actual: " + flags.join(" "));
+      }
+      for (let i = 0; i < expected.length; i += 1) {
+        if (expected[i] !== flags[i]) {
+          fail("Expected: " + expected.join(" ") + " | Actual: " + flags.join(" "));
+        }
+      }
+      flags.length = 0;
+    },
+  };
+}
+
+function createContext() {
+  const sandbox = {
+    console,
+    require,
+    print: (...args) => console.log(...args),
+    load: () => {},
+    globalThis: null,
+    setTimeout,
+    clearTimeout,
+    setInterval,
+    clearInterval,
+    Date,
+    Math,
+    Array,
+    Object,
+    Function,
+    String,
+    Number,
+    Boolean,
+    RegExp,
+    Error,
+    TypeError,
+    JSON,
+  };
+
+  const context = vm.createContext({ ...sandbox });
+  context.globalThis = context;
+  context.Function = function ScopedFunction(...parts) {
+    const body = parts.length ? String(parts.pop()) : "";
+    const params = parts.map(String).join(",");
+    return vm.runInContext("(function(" + params + "){" + body + "\n})", context);
+  };
+  context.Function.prototype = Function.prototype;
+
+  const AspectScript = createAspectScript(context);
+  context.AspectScript = AspectScript;
+  context.AJS = AspectScript;
+  context.PCs = AspectScript.Pointcuts;
+  context.Testing = makeTesting(context);
+  return context;
+}
+
+function runFile(filePath, options) {
+  const source = fs.readFileSync(filePath, "utf8");
+  const transformed = transformProgramCached(stripLoads(source), {
+    cacheEnabled: options && options.cacheEnabled !== false,
+    namespace: "scripts",
+  }).code;
+  const context = createContext();
+  if (options && options.traceEnabled) {
+    context.AspectScript.tracer.enable();
+  }
+  vm.runInContext(transformed, context, { filename: filePath });
+  return context;
+}
+
+function parseArgs(argv) {
+  let target = null;
+  let traceJsonPath = null;
+  let cacheEnabled = true;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--trace-json") {
+      traceJsonPath = argv[i + 1] || null;
+      i += 1;
+      continue;
+    }
+    if (arg === "--no-cache") {
+      cacheEnabled = false;
+      continue;
+    }
+    if (!target) {
+      target = arg;
+    }
+  }
+  return { target, traceJsonPath, cacheEnabled };
+}
+
+function main() {
+  const { target, traceJsonPath, cacheEnabled } = parseArgs(process.argv.slice(2));
+  if (!target) {
+    process.stderr.write("Usage: node run-script.js <path/to/file.js> [--trace-json trace.json] [--no-cache]\n");
+    process.exitCode = 1;
+    return;
+  }
+  if (process.argv.includes("--trace-json") && !traceJsonPath) {
+    process.stderr.write("Missing value for --trace-json\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  const fullPath = path.resolve(process.cwd(), target);
+  if (!fs.existsSync(fullPath)) {
+    process.stderr.write("File not found: " + fullPath + "\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  let context = null;
+  if (traceJsonPath) {
+    const traceOut = path.resolve(process.cwd(), traceJsonPath);
+    process.stdout.write("Trace output: " + traceOut + "\n");
+  }
+  try {
+    context = runFile(fullPath, {
+      traceEnabled: Boolean(traceJsonPath),
+      cacheEnabled,
+    });
+    if (traceJsonPath) {
+      const traceOut = path.resolve(process.cwd(), traceJsonPath);
+      context.AspectScript.tracer.saveToFile(traceOut, true);
+    }
+  } catch (error) {
+    if (traceJsonPath && context) {
+      const traceOut = path.resolve(process.cwd(), traceJsonPath);
+      context.AspectScript.tracer.saveToFile(traceOut, true);
+    }
+    process.stderr.write(String(error && error.stack ? error.stack : error) + "\n");
+    process.exitCode = 1;
+  }
+}
+
+main();

package/run-tests.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const vm = require("vm");
+
+const { transformProgramCached } = require("./transform-cache");
+const LAST_FAILS_FILE = path.join(__dirname, "tests", "lastFails.txt");
+
+function parseArgs(argv) {
+  const filters = [];
+  let failedOnly = false;
+  let cacheEnabled = true;
+  let showCacheStats = false;
+  for (const arg of argv) {
+    if (arg === "-f" || arg === "--failed") {
+      failedOnly = true;
+      continue;
+    }
+    if (arg === "--no-cache") {
+      cacheEnabled = false;
+      continue;
+    }
+    if (arg === "--cache-stats") {
+      showCacheStats = true;
+      continue;
+    }
+    filters.push(arg);
+  }
+  return { failedOnly, filters, cacheEnabled, showCacheStats };
+}
+
+function listTests(root, filters, failedOnly) {
+  if (failedOnly) {
+    if (!fs.existsSync(LAST_FAILS_FILE)) {
+      return [];
+    }
+    const previousFailures = fs.readFileSync(LAST_FAILS_FILE, "utf8")
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .filter((name) => /^test.*\.js$/.test(name))
+      .filter((name) => fs.existsSync(path.join(root, name)));
+    if (!filters.length) {
+      return previousFailures;
+    }
+    return previousFailures.filter((name) => filters.some((filter) => name.startsWith(filter)));
+  }
+
+  const files = fs.readdirSync(root)
+    .filter((name) => /^test.*\.js$/.test(name))
+    .sort();
+  if (!filters.length) {
+    return files;
+  }
+  return files.filter((name) => filters.some((filter) => name.startsWith(filter)));
+}
+
+function stripLoads(source) {
+  return source
+    .split("\n")
+    .filter((line) => !/^\s*load\(/.test(line))
+    .join("\n");
+}
+
+function makeTesting(context) {
+  const flags = [];
+
+  function stringify(value) {
+    if (value && (typeof value === "object" || typeof value === "function") &&
+        typeof value.toString === "function" &&
+        value.toString !== Object.prototype.toString) {
+      return String(value);
+    }
+    return value;
+  }
+
+  function fail(message) {
+    throw new Error(message);
+  }
+
+  return {
+    flag(value) {
+      flags.push(stringify(value));
+    },
+    assert(expr) {
+      if (!vm.runInContext(String(expr), context)) {
+        fail("Assertion failed: " + expr);
+      }
+    },
+    assert2(label, condition) {
+      if (!condition) {
+        fail("Assertion " + label + " failed");
+      }
+    },
+    check(...expected) {
+      if (expected.length === 1 &&
+          typeof expected[0] === "string" &&
+          /\s/.test(expected[0]) &&
+          !/^\[.*\]$/.test(expected[0])) {
+        if (flags.length === 0) {
+          fail(expected[0]);
+        }
+        flags.length = 0;
+        return;
+      }
+      if (expected.length !== flags.length) {
+        fail("Expected: " + expected.join(" ") + " | Actual: " + flags.join(" "));
+      }
+      for (let i = 0; i < expected.length; i += 1) {
+        if (expected[i] !== flags[i]) {
+          fail("Expected: " + expected.join(" ") + " | Actual: " + flags.join(" "));
+        }
+      }
+      flags.length = 0;
+    },
+  };
+}
+
+function runTest(filePath, options) {
+  delete require.cache[require.resolve("./aspectscript")];
+  const { createAspectScript } = require("./aspectscript");
+  const source = fs.readFileSync(filePath, "utf8");
+  const transformResult = transformProgramCached(stripLoads(source), {
+    cacheEnabled: options.cacheEnabled,
+    namespace: "tests",
+  });
+  const transformed = transformResult.code;
+  const sandbox = {
+    console,
+    require,
+    print: () => {},
+    load: () => {},
+    globalThis: null,
+    setTimeout,
+    clearTimeout,
+    setInterval,
+    clearInterval,
+    Date,
+    Math,
+    Array,
+    Object,
+    Function,
+    String,
+    Number,
+    Boolean,
+    RegExp,
+    Error,
+    TypeError,
+    JSON,
+  };
+  const context = vm.createContext({
+    ...sandbox,
+  });
+  context.globalThis = context;
+  context.Function = function ScopedFunction(...parts) {
+    const body = parts.length ? String(parts.pop()) : "";
+    const params = parts.map(String).join(",");
+    return vm.runInContext("(function(" + params + "){" + body + "\n})", context);
+  };
+  context.Function.prototype = Function.prototype;
+  const AspectScript = createAspectScript(context);
+  context.AspectScript = AspectScript;
+  context.AJS = AspectScript;
+  context.PCs = AspectScript.Pointcuts;
+  context.Testing = makeTesting(context);
+  try {
+    vm.runInContext(transformed, context, { filename: filePath });
+    return { error: null, fromCache: transformResult.fromCache };
+  } catch (error) {
+    return { error, fromCache: transformResult.fromCache };
+  }
+}
+
+function summarizeError(error) {
+  const stack = String(error && error.stack ? error.stack : error || "");
+  const lines = stack.split("\n");
+  const message = lines[0] || "Error";
+  const topFrame = lines.find((line) =>
+    /:\d+:\d+\)?$/.test(line) &&
+    !line.includes("run-tests.js") &&
+    !line.includes("node:vm")) || "";
+  return { message, topFrame, stack };
+}
+
+function writeLastFailures(failedNames) {
+  const payload = failedNames.length ? failedNames.join("\n") + "\n" : "";
+  fs.writeFileSync(LAST_FAILS_FILE, payload, "utf8");
+}
+
+function main() {
+  const testDir = path.join(__dirname, "tests");
+  const { failedOnly, filters, cacheEnabled, showCacheStats } = parseArgs(process.argv.slice(2));
+  const tests = listTests(testDir, filters, failedOnly);
+  if (!tests.length) {
+    if (failedOnly) {
+      process.stdout.write("No failed tests recorded in tests/lastFails.txt.\n");
+    } else {
+      process.stdout.write("No tests matched the provided filters.\n");
+    }
+    return;
+  }
+
+  const failedNames = [];
+  let failures = 0;
+  let cacheHits = 0;
+  for (const name of tests) {
+    const filePath = path.join(testDir, name);
+    const result = runTest(filePath, { cacheEnabled });
+    const error = result.error;
+    if (result.fromCache) {
+      cacheHits += 1;
+    }
+    if (error) {
+      failures += 1;
+      failedNames.push(name);
+      const details = summarizeError(error);
+      process.stdout.write(name + "\n");
+      process.stdout.write("Summary: " + details.message + "\n");
+      if (details.topFrame) {
+        process.stdout.write("Top frame: " + details.topFrame.trim() + "\n");
+      }
+      process.stdout.write(details.stack + "\n");
+    }
+  }
+  writeLastFailures(failedNames);
+  process.stdout.write("Evaluated " + tests.length + " test(s). Failed " + failures + ".\n");
+  if (showCacheStats) {
+    process.stdout.write("Cache hits: " + cacheHits + "/" + tests.length + ".\n");
+  }
+  if (failures) {
+    process.exitCode = 1;
+  }
+}
+
+main();

package/transform-cache.js

@@ -0,0 +1,54 @@
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const { transformProgram } = require("./instrument");
+
+const CACHE_DIR = path.join(__dirname, ".aspectscript-cache");
+const instrumentSource = fs.readFileSync(path.join(__dirname, "instrument.js"), "utf8");
+const instrumentHash = crypto.createHash("sha1").update(instrumentSource).digest("hex");
+
+function cacheKey(source, namespace) {
+  return crypto
+    .createHash("sha1")
+    .update("aspectscript-transform-v1")
+    .update("\n")
+    .update(instrumentHash)
+    .update("\n")
+    .update(namespace || "default")
+    .update("\n")
+    .update(source)
+    .digest("hex");
+}
+
+function ensureCacheDir() {
+  if (!fs.existsSync(CACHE_DIR)) {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+  }
+}
+
+function transformProgramCached(source, options) {
+  const opts = options || {};
+  const cacheEnabled = opts.cacheEnabled !== false;
+  const namespace = opts.namespace || "default";
+
+  if (!cacheEnabled) {
+    return { code: transformProgram(source), fromCache: false };
+  }
+
+  ensureCacheDir();
+  const key = cacheKey(source, namespace);
+  const filePath = path.join(CACHE_DIR, namespace + "-" + key + ".js");
+  if (fs.existsSync(filePath)) {
+    return { code: fs.readFileSync(filePath, "utf8"), fromCache: true };
+  }
+
+  const transformed = transformProgram(source);
+  fs.writeFileSync(filePath, transformed, "utf8");
+  return { code: transformed, fromCache: false };
+}
+
+module.exports = {
+  CACHE_DIR,
+  transformProgramCached,
+};