@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/script/check/service.js

@@ -0,0 +1,195 @@
+/**
+ * The TypeScript language service behind script checking and editing (spec §Type-checking).
+ *
+ * Each script model gets a service of its own over two virtual files: the declarations (the API and
+ * the request's generated types) and the script. Services cannot share a program, because each
+ * model's declarations are ambient globals that would clash; they share a document registry, so the
+ * standard library is parsed once. Models are kept most-recently-used first, and the oldest is
+ * dropped past {@link MAX_MODELS}.
+ *
+ * Options: `strict`, no emit, ES2023 with no DOM, no `@types`, and `erasableSyntaxOnly`, so that
+ * whatever passes the check can be stripped (`../strip.ts`) and run as it is.
+ */
+import { dirname } from 'node:path';
+import ts from 'typescript';
+/** Most script models kept at once. */
+export const MAX_MODELS = 32;
+/** The file names each model's two files have. */
+const DECLARATIONS = '/wb/types.d.ts';
+const SCRIPT_TS = '/wb/script.ts';
+const SCRIPT_JS = '/wb/script.js';
+export const COMPILER_OPTIONS = {
+    strict: true,
+    noEmit: true,
+    target: ts.ScriptTarget.ES2023,
+    lib: ['lib.es2023.d.ts'],
+    types: [],
+    erasableSyntaxOnly: true,
+    allowJs: true,
+    checkJs: false,
+    noLib: false,
+    skipLibCheck: true,
+};
+const registry = ts.createDocumentRegistry();
+const models = new Map();
+function scriptFile(model) {
+    return model.api === 'postman' ? SCRIPT_JS : SCRIPT_TS;
+}
+function createService(entry) {
+    const libDir = dirname(ts.getDefaultLibFilePath(COMPILER_OPTIONS));
+    const host = {
+        getCompilationSettings: () => COMPILER_OPTIONS,
+        getScriptFileNames: () => [DECLARATIONS, scriptFile(entry().model)],
+        getScriptVersion: () => String(entry().version),
+        getScriptSnapshot: (name) => {
+            const { model } = entry();
+            if (name === DECLARATIONS)
+                return ts.ScriptSnapshot.fromString(model.declarations);
+            if (name === SCRIPT_TS || name === SCRIPT_JS)
+                return ts.ScriptSnapshot.fromString(model.source);
+            const text = ts.sys.readFile(name);
+            return text === undefined ? undefined : ts.ScriptSnapshot.fromString(text);
+        },
+        getCurrentDirectory: () => '/wb',
+        getDefaultLibFileName: (options) => ts.getDefaultLibFilePath(options),
+        // Only the virtual files and the standard library exist; nothing else on disk is read.
+        fileExists: (name) => name === DECLARATIONS || name === SCRIPT_TS || name === SCRIPT_JS || name.startsWith(libDir),
+        readFile: (name) => (name.startsWith(libDir) ? ts.sys.readFile(name) : undefined),
+        readDirectory: () => [],
+        directoryExists: (name) => name === '/wb' || name.startsWith(libDir),
+        getDirectories: () => [],
+    };
+    return ts.createLanguageService(host, registry);
+}
+/** Sets a model's text, creating its service if it is new. */
+export function updateModel(id, model) {
+    const existing = models.get(id);
+    if (existing !== undefined) {
+        models.delete(id);
+        const same = existing.model.source === model.source &&
+            existing.model.declarations === model.declarations &&
+            existing.model.api === model.api;
+        if (!same) {
+            existing.model = model;
+            existing.version += 1;
+        }
+        models.set(id, existing);
+        return;
+    }
+    const entry = { model, version: 1, service: undefined };
+    entry.service = createService(() => entry);
+    models.set(id, entry);
+    while (models.size > MAX_MODELS) {
+        const oldest = models.keys().next().value;
+        if (oldest === undefined)
+            break;
+        models.get(oldest)?.service.dispose();
+        models.delete(oldest);
+    }
+}
+export function removeModel(id) {
+    models.get(id)?.service.dispose();
+    models.delete(id);
+}
+function entryOf(id) {
+    const entry = models.get(id);
+    if (entry === undefined)
+        throw new Error(`No script model "${id}"`);
+    return entry;
+}
+function lineColumn(source, offset) {
+    let line = 1;
+    let lastBreak = -1;
+    for (let i = 0; i < offset && i < source.length; i++) {
+        if (source.charCodeAt(i) === 10) {
+            line += 1;
+            lastBreak = i;
+        }
+    }
+    return { line, column: offset - lastBreak };
+}
+function offsetOf(source, line, column) {
+    let offset = 0;
+    for (let current = 1; current < line; current++) {
+        const next = source.indexOf('\n', offset);
+        if (next === -1)
+            return source.length;
+        offset = next + 1;
+    }
+    return Math.min(source.length, offset + column - 1);
+}
+/**
+ * The script's diagnostics. A Postman script (JavaScript) gets only its syntax errors; a typed one
+ * gets syntax and type errors. Errors in the declarations themselves are not the script's and are
+ * left out.
+ */
+export function diagnosticsOf(id) {
+    const { model, service } = entryOf(id);
+    const file = scriptFile(model);
+    const found = [
+        ...service.getSyntacticDiagnostics(file),
+        ...(model.api === 'postman' ? [] : service.getSemanticDiagnostics(file)),
+    ];
+    return found.map((d) => {
+        const start = d.start ?? 0;
+        const from = lineColumn(model.source, start);
+        const to = lineColumn(model.source, start + (d.length ?? 0));
+        return {
+            line: from.line,
+            column: from.column,
+            endLine: to.line,
+            endColumn: to.column,
+            message: ts.flattenDiagnosticMessageText(d.messageText, '\n'),
+            code: d.code,
+            severity: d.category === ts.DiagnosticCategory.Error ? 'error' : 'warning',
+        };
+    });
+}
+/** Completions at a 1-based position, at most 200. */
+export function completionsAt(id, line, column) {
+    const { model, service } = entryOf(id);
+    const info = service.getCompletionsAtPosition(scriptFile(model), offsetOf(model.source, line, column), {
+        includeCompletionsWithInsertText: true,
+    });
+    return (info?.entries ?? [])
+        .filter((entry) => !entry.name.startsWith('__') && !entry.name.startsWith('Wb'))
+        .slice(0, 200)
+        .map((entry) => ({ name: entry.name, kind: entry.kind }));
+}
+export function quickInfoAt(id, line, column) {
+    const { model, service } = entryOf(id);
+    const info = service.getQuickInfoAtPosition(scriptFile(model), offsetOf(model.source, line, column));
+    if (info === undefined)
+        return undefined;
+    const documentation = ts.displayPartsToString(info.documentation);
+    return {
+        text: ts.displayPartsToString(info.displayParts),
+        ...(documentation !== '' ? { documentation } : {}),
+    };
+}
+export function signatureHelpAt(id, line, column) {
+    const { model, service } = entryOf(id);
+    const help = service.getSignatureHelpItems(scriptFile(model), offsetOf(model.source, line, column), undefined);
+    const item = help?.items[help.selectedItemIndex];
+    if (help === undefined || item === undefined)
+        return undefined;
+    const parameters = item.parameters.map((p) => ts.displayPartsToString(p.displayParts));
+    const documentation = ts.displayPartsToString(item.documentation);
+    return {
+        label: `${ts.displayPartsToString(item.prefixDisplayParts)}${parameters.join(ts.displayPartsToString(item.separatorDisplayParts))}${ts.displayPartsToString(item.suffixDisplayParts)}`,
+        parameters,
+        activeParameter: help.argumentIndex,
+        ...(documentation !== '' ? { documentation } : {}),
+    };
+}
+/** One-shot check of a script against declarations, without keeping a model. */
+export function checkOnce(model) {
+    const id = `once:${String(Math.random())}`;
+    updateModel(id, model);
+    try {
+        return diagnosticsOf(id);
+    }
+    finally {
+        removeModel(id);
+    }
+}

package/dist/script/check/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/script/check/worker.js

@@ -0,0 +1,40 @@
+/**
+ * Entry point run inside a `node:worker_threads` Worker by {@link createScriptChecker}. Each message
+ * is one request (`{ id, request }`) answered with `{ id, result }` or `{ id, error }`, one at a time.
+ */
+import { parentPort } from 'node:worker_threads';
+import { checkOnce, completionsAt, diagnosticsOf, quickInfoAt, removeModel, signatureHelpAt, updateModel, } from './service.js';
+function answer(request) {
+    switch (request.op) {
+        case 'check':
+            return checkOnce(request.model);
+        case 'remove':
+            removeModel(request.modelId);
+            return null;
+        case 'diagnostics':
+            updateModel(request.modelId, request.model);
+            return diagnosticsOf(request.modelId);
+        case 'completions':
+            updateModel(request.modelId, request.model);
+            return completionsAt(request.modelId, request.line, request.column);
+        case 'quickInfo':
+            updateModel(request.modelId, request.model);
+            return quickInfoAt(request.modelId, request.line, request.column) ?? null;
+        case 'signatureHelp':
+            updateModel(request.modelId, request.model);
+            return signatureHelpAt(request.modelId, request.line, request.column) ?? null;
+    }
+}
+/* v8 ignore start -- runs only inside a real worker thread; covered end to end by check.test.ts. */
+if (parentPort !== null) {
+    const port = parentPort;
+    port.on('message', ({ id, request }) => {
+        try {
+            port.postMessage({ id, result: answer(request) });
+        }
+        catch (error) {
+            port.postMessage({ id, error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+}
+/* v8 ignore stop */

package/dist/script/index.d.ts

@@ -0,0 +1,16 @@
+/** Typed scripting (#63): the sandbox, the checker, the API's types and a request's scripts in a send. */
+export { createScriptSandbox, clampTimeout, SCRIPT_QUEUE_LIMIT } from './sandbox/host.js';
+export type { ScriptSandbox, ScriptSandboxOptions } from './sandbox/host.js';
+export { SCRIPT_LIMITS } from './sandbox/model.js';
+export type { SandboxLog, ScriptPosition } from './sandbox/model.js';
+export { createScriptChecker, CHECK_DEADLINE_MS, ScriptCheckerError } from './check/host.js';
+export type { ScriptChecker, ScriptCheckerOptions, ScriptCompletion, ScriptDiagnostic, ScriptModel, ScriptQuickInfo, ScriptSignatureHelp, } from './check/host.js';
+export { isScriptFileOf, SCRIPT_OUTPUT_LIMITS, scriptFileName } from './model.js';
+export type { HeaderPair, RequestScripts, ScriptApi, ScriptErrorCode, ScriptFailure, ScriptLog, ScriptOutcome, ScriptPhase, ScriptSource, ScriptTest, ScriptValue, } from './model.js';
+export { activeScripts, assertScriptsUsable, RequestScripting, scriptError, typeCheckError, } from './request-scripts.js';
+export type { RequestScriptingOptions, RequestScriptTypes, ScriptedRequest, ScriptRunValues, } from './request-scripts.js';
+export { SecretPlaceholders } from './send.js';
+export { scriptProperties } from './props.js';
+export { apiDeclarations, apiReference, scriptDeclarations, secretNameType } from './types/api.js';
+export type { ApiReferenceSection } from './types/api.js';
+export { stripTypes, StripError } from './strip.js';

package/dist/script/index.js

@@ -0,0 +1,10 @@
+/** Typed scripting (#63): the sandbox, the checker, the API's types and a request's scripts in a send. */
+export { createScriptSandbox, clampTimeout, SCRIPT_QUEUE_LIMIT } from './sandbox/host.js';
+export { SCRIPT_LIMITS } from './sandbox/model.js';
+export { createScriptChecker, CHECK_DEADLINE_MS, ScriptCheckerError } from './check/host.js';
+export { isScriptFileOf, SCRIPT_OUTPUT_LIMITS, scriptFileName } from './model.js';
+export { activeScripts, assertScriptsUsable, RequestScripting, scriptError, typeCheckError, } from './request-scripts.js';
+export { SecretPlaceholders } from './send.js';
+export { scriptProperties } from './props.js';
+export { apiDeclarations, apiReference, scriptDeclarations, secretNameType } from './types/api.js';
+export { stripTypes, StripError } from './strip.js';

package/dist/script/lookup.d.ts

@@ -0,0 +1,10 @@
+import type { ProtocolScripting } from '../protocol/module.js';
+import type { ProtocolRegistry } from '../protocol/registry.js';
+/** The scripting facet of `protocol` in `registry` (the built-in one when absent), if it has one. */
+export declare function scriptingOf(protocol: string, registry?: ProtocolRegistry): ProtocolScripting | undefined;
+/**
+ * A facet as given, or the facet of the protocol a `kind` names.
+ *
+ * @throws WirebenchError `script-unsupported` when the protocol has no scripting facet
+ */
+export declare function requireScripting(scripting: ProtocolScripting | string, registry?: ProtocolRegistry): ProtocolScripting;

package/dist/script/lookup.js

@@ -0,0 +1,23 @@
+/** Finds the scripting facet of a protocol (spec §5.5). */
+import { WirebenchError } from '../errors.js';
+import { defaultRegistry } from '../protocols.js';
+/** The scripting facet of `protocol` in `registry` (the built-in one when absent), if it has one. */
+export function scriptingOf(protocol, registry = defaultRegistry()) {
+    return registry.find(protocol)?.scripting;
+}
+/**
+ * A facet as given, or the facet of the protocol a `kind` names.
+ *
+ * @throws WirebenchError `script-unsupported` when the protocol has no scripting facet
+ */
+export function requireScripting(scripting, registry) {
+    if (typeof scripting !== 'string')
+        return scripting;
+    const found = scriptingOf(scripting, registry);
+    if (found === undefined) {
+        throw new WirebenchError('script-unsupported', `Requests of the "${scripting}" protocol cannot have scripts`, {
+            details: { protocol: scripting },
+        });
+    }
+    return found;
+}

package/dist/script/model.d.ts

@@ -0,0 +1,82 @@
+/**
+ * What a script sees and hands back (spec §API). A request and a response cross into the sandbox as
+ * a JSON snapshot; a pre-request script hands back the snapshot it changed, which the host checks and
+ * applies (`apply.ts`) — nothing a script returns is trusted as it stands.
+ */
+import type { RequestSnapshotBase } from '../protocol/module.js';
+import type { ScriptPosition } from './sandbox/model.js';
+export type ScriptPhase = 'pre' | 'post';
+/** Which API a script is written against: the typed one, or the Postman layer (§Postman). */
+export type ScriptApi = 'wirebench' | 'postman';
+/** A header or metadata entry, in order; names may repeat. */
+export type HeaderPair = readonly [name: string, value: string];
+/** One `test(...)` a script recorded. */
+export interface ScriptTest {
+    readonly name: string;
+    readonly passed: boolean;
+    readonly message?: string;
+}
+/** One `vars.set(...)` a script made. Held to ADR-0015 wherever it is used. */
+export interface ScriptValue {
+    readonly name: string;
+    readonly value: string;
+    readonly secret: boolean;
+}
+export type ScriptErrorCode = 'script-error' | 'script-timeout' | 'script-memory' | 'script-syntax-error' | 'script-origin-change' | 'script-value-invalid' | 'script-secret-denied' | 'script-unsupported';
+export interface ScriptFailure {
+    readonly code: ScriptErrorCode;
+    readonly message: string;
+    readonly position?: ScriptPosition;
+}
+export interface ScriptLog {
+    readonly lines: readonly string[];
+    readonly truncated: boolean;
+}
+/** What running one script produced. `request` is set only for a pre-request script that succeeded. */
+export type ScriptOutcome = {
+    readonly ok: true;
+    readonly request?: RequestSnapshotBase;
+    readonly tests: readonly ScriptTest[];
+    readonly values: readonly ScriptValue[];
+    readonly log: ScriptLog;
+} | {
+    readonly ok: false;
+    readonly error: ScriptFailure;
+    readonly tests: readonly ScriptTest[];
+    readonly values: readonly ScriptValue[];
+    readonly log: ScriptLog;
+};
+/** Caps on what a script hands back (spec §Sandbox). */
+export declare const SCRIPT_OUTPUT_LIMITS: {
+    readonly tests: 1000;
+    readonly values: 100;
+    readonly valueBytes: number;
+};
+/** A script file as loaded. `problem` is set when it could not be used; such a request refuses to send. */
+export interface ScriptSource {
+    readonly text: string;
+    readonly problem?: 'script-file-missing' | 'script-too-large';
+}
+/**
+ * A request's scripts (spec §Storage): the `scripts` key of a SOAP, REST or gRPC request file, with
+ * the text of each script file beside it.
+ */
+export interface RequestScripts {
+    readonly pre?: ScriptSource;
+    readonly post?: ScriptSource;
+    readonly api: ScriptApi;
+    /** False keeps the scripts but runs none of them; the Postman importer writes false (§Postman). */
+    readonly enabled: boolean;
+    /** The secrets a script may read with `secrets.get` (§Secrets). */
+    readonly secrets: readonly string[];
+    /** Per script; absent means {@link SCRIPT_LIMITS.defaultTimeoutMs}. */
+    readonly timeoutMs?: number;
+}
+/**
+ * The file a request's script lives in, beside the request file: `<slug>.pre.ts` for the typed API,
+ * `<slug>.pre.js` for the Postman layer. Always derived from the slug, never read from the request
+ * file, so a hand-edited name cannot point outside the request's directory.
+ */
+export declare function scriptFileName(slug: string, phase: ScriptPhase, api: ScriptApi): string;
+/** True for `<slug>.pre.ts`, `<slug>.post.ts`, `<slug>.pre.js` or `<slug>.post.js` of this slug. */
+export declare function isScriptFileOf(name: string, slug: string): boolean;

package/dist/script/model.js

@@ -0,0 +1,18 @@
+/** Caps on what a script hands back (spec §Sandbox). */
+export const SCRIPT_OUTPUT_LIMITS = {
+    tests: 1_000,
+    values: 100,
+    valueBytes: 64 * 1024,
+};
+/**
+ * The file a request's script lives in, beside the request file: `<slug>.pre.ts` for the typed API,
+ * `<slug>.pre.js` for the Postman layer. Always derived from the slug, never read from the request
+ * file, so a hand-edited name cannot point outside the request's directory.
+ */
+export function scriptFileName(slug, phase, api) {
+    return `${slug}.${phase}.${api === 'postman' ? 'js' : 'ts'}`;
+}
+/** True for `<slug>.pre.ts`, `<slug>.post.ts`, `<slug>.pre.js` or `<slug>.post.js` of this slug. */
+export function isScriptFileOf(name, slug) {
+    return /^\.(pre|post)\.(ts|js)$/.test(name.startsWith(slug) ? name.slice(slug.length) : '');
+}

package/dist/script/props.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The properties a script's `props.get` reads (spec §API): every name the `${name}` shorthand can
+ * reach, resolved as the shorthand would resolve it, with secrets left out. A property whose value
+ * is, or leads to, a secret does not resolve without the secrets, so it is simply absent: a script
+ * reads a secret only through `secrets.get`, and only when its request lists it.
+ */
+import { type PropertyScopes } from '../project/properties.js';
+export declare function scriptProperties(scopes: PropertyScopes): Record<string, string>;

package/dist/script/props.js

@@ -0,0 +1,28 @@
+/**
+ * The properties a script's `props.get` reads (spec §API): every name the `${name}` shorthand can
+ * reach, resolved as the shorthand would resolve it, with secrets left out. A property whose value
+ * is, or leads to, a secret does not resolve without the secrets, so it is simply absent: a script
+ * reads a secret only through `secrets.get`, and only when its request lists it.
+ */
+import { expand } from '../project/properties.js';
+/** At most this many properties are handed to a script. */
+const MAX_PROPERTIES = 2_000;
+export function scriptProperties(scopes) {
+    const withoutSecrets = { ...scopes, secrets: {} };
+    const names = new Set();
+    for (const map of [scopes.env, scopes.workspace, scopes.project, scopes.global]) {
+        for (const name of Object.keys(map ?? {}))
+            names.add(name);
+    }
+    const out = {};
+    for (const name of names) {
+        if (Object.keys(out).length >= MAX_PROPERTIES)
+            break;
+        if (!/^[A-Za-z_][\w.-]*$/.test(name))
+            continue;
+        const result = expand(`\${${name}}`, withoutSecrets);
+        if (result.unresolved.length === 0)
+            out[name] = result.text;
+    }
+    return out;
+}

package/dist/script/request-scripts.d.ts

@@ -0,0 +1,83 @@
+import { WirebenchError } from '../errors.js';
+import type { RequestSnapshotBase, ResponseSnapshotBase } from '../protocol/module.js';
+import type { ProtocolRegistry } from '../protocol/registry.js';
+import type { ScriptChecker, ScriptDiagnostic } from './check/host.js';
+import { type RequestScripts, type ScriptFailure, type ScriptOutcome, type ScriptPhase } from './model.js';
+import type { ScriptSandbox } from './sandbox/host.js';
+/** The generated half of a request's script types, and what its module needs for typed views. */
+export interface RequestScriptTypes {
+    readonly generated: string;
+    /**
+     * Opaque to everything but the module that produced it, which reads it back in its scripting
+     * facet's `views` (SOAP: `SoapScriptBinding`).
+     */
+    readonly binding?: unknown;
+}
+/** The scripts of a request that will run: none when there are none or they are switched off. */
+export declare function activeScripts(scripts: RequestScripts | undefined): RequestScripts | undefined;
+/**
+ * Refuses a request whose script file is missing or too large: sending it without that script
+ * would be sending something other than what the request says.
+ *
+ * @throws WirebenchError `script-file-missing` | `script-too-large`
+ */
+export declare function assertScriptsUsable(scripts: RequestScripts, path: string): void;
+/** A script failure as the error a send reports, with the script's file and position in it. */
+export declare function scriptError(failure: ScriptFailure, filename: string): WirebenchError;
+/** A type-check failure: every error, as `file:line:column: message`. */
+export declare function typeCheckError(path: string, errors: readonly {
+    file: string;
+    diagnostic: ScriptDiagnostic;
+}[]): WirebenchError;
+export interface RequestScriptingOptions {
+    readonly sandbox: ScriptSandbox;
+    /** Absent: scripts run without a type check (a host that checks them another way). */
+    readonly checker?: ScriptChecker;
+    /** Told every secret value a script may read, before it runs. */
+    readonly onSecretValue?: (value: string) => void;
+    /** Where a request's protocol is looked up; the built-in registry when absent. */
+    readonly registry?: ProtocolRegistry;
+}
+/** One request's scripts, with the facts every run of them shares. */
+export interface ScriptedRequest {
+    readonly protocol: string;
+    /** The request's path, for messages. */
+    readonly path: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly scripts: RequestScripts;
+    readonly types: RequestScriptTypes;
+}
+export interface ScriptRunValues {
+    readonly vars: Readonly<Record<string, string>>;
+    readonly props: Readonly<Record<string, string>>;
+    /** The values of the secrets `scripts.secrets` lists. */
+    readonly secrets: Readonly<Record<string, string>>;
+}
+/** Runs requests' scripts, caching each script's type check by its text and its types. */
+export declare class RequestScripting {
+    private readonly options;
+    private readonly checked;
+    constructor(options: RequestScriptingOptions);
+    private filename;
+    private diagnostics;
+    /**
+     * Type-checks a request's scripts (syntax only for a Postman one).
+     *
+     * @throws WirebenchError `script-type-error` (or `script-syntax-error` for a Postman script)
+     */
+    check(request: ScriptedRequest): Promise<void>;
+    private run;
+    /**
+     * The pre-request script's outcome. A failure is thrown: the request is not sent.
+     *
+     * @throws WirebenchError with the script's error code
+     */
+    pre(request: ScriptedRequest, snapshot: RequestSnapshotBase, values: ScriptRunValues, layer?: string): Promise<Extract<ScriptOutcome, {
+        ok: true;
+    }>>;
+    /** The post-response script's outcome; a failure is returned, since the response is kept. */
+    post(request: ScriptedRequest, sent: RequestSnapshotBase, response: ResponseSnapshotBase, values: ScriptRunValues, layer?: string): Promise<ScriptOutcome>;
+    /** The file name errors in a phase's script are reported against. */
+    fileOf(request: ScriptedRequest, phase: ScriptPhase): string;
+}