@agiledigital/pingone-aic-script-tester 0.1.0

package/dist/src/harness/vitest.js

@@ -0,0 +1,155 @@
+import { relative } from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, expect } from "vitest";
+import { AicFileLease } from "../aic/file-lease.js";
+import { chainFromRunResult } from "../aic/conform.js";
+import { clearAicTrace, takeAicTrace } from "../aic/trace.js";
+import { projectRoot } from "../project.js";
+import { RhinoRunner } from "../runner.js";
+import { recordFailureIfAny } from "./failures.js";
+import { Lease, } from "./lease.js";
+/** The env var that opts a run into the tenant lane. */
+export const AIC_LANE_ENV = "AIC_SCRIPT_TESTER_AIC";
+/**
+ * Spread into `useLease` options to run both lanes when `AIC_SCRIPT_TESTER_AIC=1`.
+ *
+ * Off by default, deliberately. The tenant lane needs an unlocked agent and
+ * network, which CI has neither of, and a checkout without them should still
+ * be able to run the whole suite offline — so opting in is a per-invocation
+ * decision, not a property of the file:
+ *
+ *     npm test                      # local lane only, as before
+ *     AIC_SCRIPT_TESTER_AIC=1 npm test    # both lanes, against the sandbox
+ *
+ * `id` must be unique per file: it seeds the deterministic resource ids, and
+ * one AIC lease per file is enforced.
+ */
+export function aicWhenEnabled(id, realm = "alpha") {
+    return process.env[AIC_LANE_ENV] === "1" ? { aic: { id, realm } } : {};
+}
+const aicLeaseByFile = new Map();
+/**
+ * Take a lease for one test file, and register its own lifecycle.
+ *
+ * The hooks are registered here rather than left to the author because
+ * forgetting teardown is the one mistake that leaks tenant state, and it
+ * leaks silently — the suite still passes. Owning the hooks makes the leak
+ * impossible to cause by omission. The same applies to failure records: the
+ * author must not have to remember to write the transaction id down.
+ */
+export function useLease(suite, options = {}) {
+    let runner;
+    let aicLease;
+    const lane = options.aic === undefined
+        ? undefined
+        : {
+            run: ({ result, source, hooks }) => {
+                if (aicLease === undefined) {
+                    throw new Error("rhino-local: AIC lease used before beforeAll completed");
+                }
+                return aicLease.run({ ...chainFromRunResult(result), source, hooks });
+            },
+            endTest: () => aicLease?.endTest() ?? Promise.resolve(),
+        };
+    const lease = new Lease(suite.spec, {
+        get runner() {
+            if (runner === undefined) {
+                throw new Error("rhino-local: lease used before beforeAll ran — call useLease() at describe scope, not inside a test");
+            }
+            return runner;
+        },
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.allowResidue !== undefined ? { allowResidue: options.allowResidue } : {}),
+        ...(lane === undefined ? {} : { lane }),
+        ...(options.aic === undefined ? {} : { realm: options.aic.realm ?? "alpha" }),
+        testName: () => expect.getState().currentTestName ?? suite.spec.name,
+    });
+    // Vitest 5 requires fixture destructuring before the suite argument.
+    // eslint-disable-next-line no-empty-pattern
+    beforeAll(async ({}, scope) => {
+        runner = await RhinoRunner.spawn();
+        lease.open();
+        if (options.aic !== undefined) {
+            claimAicLeaseForFile(vitestFilePath(scope), options.aic.id);
+            aicLease = new AicFileLease({
+                id: options.aic.id,
+                suiteName: suite.spec.name,
+                source: suite.spec.script,
+                outcomes: suite.spec.outcomes,
+                ...(options.aic.realm === undefined ? {} : { realm: options.aic.realm }),
+                ...(options.aic.tenant === undefined ? {} : { tenant: options.aic.tenant }),
+                ...(options.aic.project === undefined ? {} : { project: options.aic.project }),
+                ...(options.aic.provider === undefined ? {} : { provider: options.aic.provider }),
+                ...(options.aic.unsupported === undefined
+                    ? {}
+                    : { unsupported: options.aic.unsupported }),
+                ...(options.aicIo === undefined ? {} : { io: options.aicIo }),
+                ...(options.aicStateDir === undefined
+                    ? {}
+                    : { stateDir: options.aicStateDir }),
+            });
+            await aicLease.open();
+        }
+    }, options.spawnTimeoutMs ?? 60_000);
+    beforeEach((context) => {
+        clearAicTrace();
+        context.onTestFailed(async () => {
+            const trace = takeAicTrace();
+            try {
+                await recordFailureIfAny({
+                    trace,
+                    testName: expect.getState().currentTestName ?? context.task.name,
+                    file: relative(projectRoot(), context.task.file.filepath),
+                    suite: suite.spec.name,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                process.emitWarning(`rhino-local: could not record failure for show-log: ${message}`);
+            }
+        });
+    });
+    afterEach(async () => {
+        await lease.endTest();
+    });
+    afterAll(async () => {
+        const errors = [];
+        try {
+            await aicLease?.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await lease.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await runner?.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length > 0) {
+            throw new AggregateError(errors, "rhino-local lease teardown failed");
+        }
+    }, 30_000);
+    return lease;
+}
+export function claimAicLeaseForFile(file, id) {
+    const existing = aicLeaseByFile.get(file);
+    if (existing !== undefined) {
+        throw new Error(`rhino-local: test file already has AIC lease ${JSON.stringify(existing)}; split ${JSON.stringify(id)} into another file`);
+    }
+    aicLeaseByFile.set(file, id);
+}
+export function releaseAicLeaseForFile(file, id) {
+    if (id === undefined || aicLeaseByFile.get(file) === id) {
+        aicLeaseByFile.delete(file);
+    }
+}
+function vitestFilePath(scope) {
+    return "filepath" in scope ? scope.filepath : scope.file.filepath;
+}

package/dist/src/idents.d.ts

@@ -0,0 +1,4 @@
+export declare function assertIdent(name: string, what: string): string;
+export declare function pascal(name: string): string;
+export declare function tsParamName(name: string): string;
+export declare function tsType(jsType: string): string;

package/dist/src/idents.js

@@ -0,0 +1,42 @@
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const TS_PARAM_RENAMES = {
+    arguments: "args",
+};
+export function assertIdent(name, what) {
+    if (!IDENT.test(name)) {
+        throw new Error(`rhino-local: ${what} is not a JS identifier: ${JSON.stringify(name)}`);
+    }
+    return name;
+}
+export function pascal(name) {
+    const ident = assertIdent(name, "type name");
+    const first = ident.charAt(0);
+    if (!first) {
+        throw new Error(`rhino-local: empty identifier`);
+    }
+    return first.toUpperCase() + ident.slice(1);
+}
+export function tsParamName(name) {
+    const renamed = TS_PARAM_RENAMES[name] ?? name;
+    return assertIdent(renamed, "parameter name");
+}
+export function tsType(jsType) {
+    switch (jsType) {
+        case "string":
+            return "string";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "array":
+            return "unknown[]";
+        case "object":
+            return "object";
+        case "void":
+            return "void";
+        case "unknown":
+            return "unknown";
+        default:
+            throw new Error(`rhino-local: no TS mapping for javaScriptType ${jsType}`);
+    }
+}

package/dist/src/jvm.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Where the runner's JVM comes from.
+ *
+ * - `host` — a Java 25 on this machine. The default: an 8GB laptop should not
+ *   need the ~850MB AM image to run a unit test.
+ * - `container` — the JVM inside the AM image. The reference `host` is
+ *   compared against; CI runs it, developers need not.
+ * - `both` — every job on both, failing on any difference. This is how the
+ *   whole suite doubles as the host-vs-image conformance test.
+ */
+export type JvmLane = "host" | "container" | "both";
+export declare const JVM_LANE_ENV = "AIC_SCRIPT_TESTER_JVM";
+export declare function laneFromEnv(env?: NodeJS.ProcessEnv): JvmLane;
+/**
+ * The Rhino AM 8.1.1 ships. MEASURED 2026-09-28: the jar in
+ * `WEB-INF/lib` of the AM image is byte-identical to this Maven Central
+ * artefact (same SHA-1 as the `.sha1` Central publishes), so there is no Ping
+ * code to extract and nothing about Rhino that needs the image.
+ */
+export declare const RHINO_JAR: {
+    readonly fileName: "rhino-1.7.14.1.jar";
+    readonly url: "https://repo1.maven.org/maven2/org/mozilla/rhino/1.7.14.1/rhino-1.7.14.1.jar";
+    readonly sha256: "407d4af6521494061d86b208e99804e0bf5c2fa38449c48f24b2f5a7154b4d8d";
+    readonly bytes: 1389188;
+};
+/**
+ * The AM image the `container` lane runs, pinned by digest so the reference
+ * cannot move under a re-pushed tag; override to calibrate another image.
+ */
+export declare const DEFAULT_AM_IMAGE: string;
+/**
+ * The JVM AM runs, as the AM image reports it (MEASURED 2026-09-28):
+ * Temurin-25.0.4+7, `/etc/localtime` → `Etc/UTC`, `LANG=en_US.UTF-8`. The
+ * runner reports what it actually got at startup, and {@link checkEnvironment}
+ * refuses a JVM that differs in anything a script could observe.
+ */
+export declare const EXPECTED_ENVIRONMENT: {
+    readonly javaFeature: 25;
+    readonly timezone: "Etc/UTC";
+    readonly locale: "en-US";
+    readonly charset: "UTF-8";
+    readonly rhino: "Rhino 1.7.14.1";
+};
+/**
+ * Flags for the host lane only. The properties pin what the AM image's JVM
+ * gets from its OS (UTC, en_US.UTF-8), which a host would otherwise take from
+ * its own settings. The heap cap, serial collector and C1-only JIT are what
+ * keep a runner small on an 8GB box.
+ *
+ * The container lane gets **none** of these: it is the reference, so it runs
+ * the image's JVM on the image's defaults, as the old launcher did. That makes
+ * `both` compare the constrained host against an unconstrained AM JVM, so a
+ * script that only works with more heap or a faster JIT shows up as a
+ * divergence rather than agreeing with itself.
+ */
+export declare const HOST_JVM_FLAGS: readonly string[];
+export interface RunnerEnvironment {
+    javaFeature: number;
+    javaVersion: string;
+    javaVendorVersion: string | null;
+    timezone: string;
+    locale: string;
+    charset: string;
+    rhino: string;
+}
+export declare function parseEnvironment(readyLine: string): RunnerEnvironment;
+/**
+ * Every field a script can observe must match AM's. The Java patch level and
+ * vendor are not checked here: they are what the `both` lane measures, and a
+ * developer's Temurin 25.0.4.1 is not wrong merely for not being 25.0.4.
+ */
+export declare function checkEnvironment(env: RunnerEnvironment, lane: "host" | "container"): void;
+export declare const JAVA_HOME_ENV = "AIC_SCRIPT_TESTER_JAVA_HOME";
+/** `bin/<tool>` under AIC_SCRIPT_TESTER_JAVA_HOME, then JAVA_HOME, else the bare name for PATH lookup. */
+export declare function javaTool(tool: "java" | "javac", env?: NodeJS.ProcessEnv): string;
+export declare function cacheDir(env?: NodeJS.ProcessEnv): string;
+export type Fetcher = (url: string) => Promise<Uint8Array>;
+/** A local copy of {@link RHINO_JAR} to use instead of the cache or a download. */
+export declare const RHINO_JAR_ENV = "AIC_SCRIPT_TESTER_RHINO_JAR";
+/**
+ * The Rhino jar, verified by SHA-256 every time it is used, not only when
+ * downloaded: a cache is a file anyone can overwrite, and a different Rhino
+ * would make every verdict in this harness a claim about the wrong engine.
+ */
+export declare function ensureRhinoJar(cache?: string, fetcher?: Fetcher, env?: NodeJS.ProcessEnv): Promise<string>;
+/**
+ * The runner classes to launch. First the package's prebuilt classes, when
+ * their manifest names these exact sources and every class still hashes as
+ * recorded — an installed package, which may have no `javac` at all. Otherwise
+ * classes compiled here, keyed by the Java sources, the compiler and the jar
+ * they compile against, so an edit to a `.java` file cannot run stale
+ * bytecode. Each compile goes to a scratch directory and is renamed to a
+ * **fresh** `<digest>-<uuid>` name, never to a shared one: Vitest spawns
+ * runners from several workers at once, and a name that is never reused
+ * cannot be replaced or moved after another worker has validated and returned
+ * it. Two cold workers may both publish; the copies are identical and the
+ * lowest valid name wins from then on.
+ */
+export declare function ensureRunnerClasses(jar: string, options?: {
+    cache?: string;
+    javac?: string;
+    sources?: string;
+    prebuilt?: string;
+}): Promise<string>;
+/**
+ * Compile the classes a package ships (`npm run build`). Their manifest is
+ * keyed by the sources alone, not the compiler: the consumer running them has
+ * no `javac` to key by, and `--release` fixes the class-file target.
+ */
+export declare function buildPrebuiltClasses(options?: {
+    out?: string;
+    javac?: string;
+    sources?: string;
+    cache?: string;
+}): Promise<string>;
+export interface Launch {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    /** Set for the container lane, so a crash can `docker rm -f` it. */
+    containerName?: string;
+}
+export declare function hostLaunch(classes: string, jar: string, env?: NodeJS.ProcessEnv): Launch;
+export declare function containerLaunch(classes: string, jar: string, env?: NodeJS.ProcessEnv): Launch;