@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/script/api/prelude.js

@@ -0,0 +1,215 @@
+import { SCRIPT_OUTPUT_LIMITS } from '../model.js';
+const COMMON = String.raw `
+const input = JSON.parse(__host.inputJson);
+const hasOwn = (object, key) => object !== null && typeof object === 'object' && Object.prototype.hasOwnProperty.call(object, key);
+const state = { tests: [], values: new Map(), request: undefined };
+
+class ScriptSecretDenied extends Error { constructor(message) { super(message); this.name = 'ScriptSecretDenied'; } }
+class ScriptValueInvalid extends Error { constructor(message) { super(message); this.name = 'ScriptValueInvalid'; } }
+class ScriptUnsupported extends Error { constructor(message) { super(message); this.name = 'ScriptUnsupported'; } }
+class ExpectationFailed extends Error { constructor(message) { super(message); this.name = 'ExpectationFailed'; } }
+
+const define = (name, value) => {
+  Object.defineProperty(globalThis, name, { value, writable: false, configurable: true, enumerable: false });
+};
+
+const show = (value) => {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'function') return '[function]';
+  try {
+    const text = JSON.stringify(value);
+    return text === undefined ? String(value) : text;
+  } catch {
+    return String(value);
+  }
+};
+
+const utf8Length = (text) => {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff) { bytes += 4; i++; }
+    else bytes += 3;
+  }
+  return bytes;
+};
+
+const writeLog = (...values) => __host.log(values.map(show).join(' '));
+define('log', writeLog);
+define('console', Object.freeze({ log: writeLog, info: writeLog, warn: writeLog, error: writeLog, debug: writeLog }));
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/;
+define('vars', Object.freeze({
+  get(name) {
+    const key = String(name);
+    if (state.values.has(key)) return state.values.get(key).value;
+    return hasOwn(input.vars, key) ? input.vars[key] : undefined;
+  },
+  set(name, value, options) {
+    const key = String(name);
+    if (!NAME.test(key)) {
+      throw new ScriptValueInvalid('A value name must start with a letter or _ and hold only letters, digits, _, . and -: "' + key + '"');
+    }
+    if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+      throw new ScriptValueInvalid('vars.set("' + key + '") takes a string, number or boolean');
+    }
+    const text = String(value);
+    if (utf8Length(text) > ${String(SCRIPT_OUTPUT_LIMITS.valueBytes)}) {
+      throw new ScriptValueInvalid('vars.set("' + key + '") is over ${String(SCRIPT_OUTPUT_LIMITS.valueBytes / 1024)} KiB');
+    }
+    if (!state.values.has(key) && state.values.size >= ${String(SCRIPT_OUTPUT_LIMITS.values)}) {
+      throw new ScriptValueInvalid('A script may set at most ${String(SCRIPT_OUTPUT_LIMITS.values)} values');
+    }
+    state.values.set(key, { value: text, secret: options !== null && typeof options === 'object' && options.secret === true });
+  },
+}));
+
+define('props', Object.freeze({
+  get(name) {
+    const key = String(name);
+    return hasOwn(input.props, key) ? input.props[key] : undefined;
+  },
+}));
+
+define('secrets', Object.freeze({
+  get(name) {
+    const key = String(name);
+    if (hasOwn(input.secrets, key)) return input.secrets[key];
+    throw new ScriptSecretDenied('The secret "' + key + '" is not listed in this request\'s scripts.secrets');
+  },
+}));
+
+define('crypto', Object.freeze({
+  hash: (algorithm, data, encoding) => __host.hash(String(algorithm), String(data), encoding === undefined ? undefined : String(encoding)),
+  hmac: (algorithm, key, data, encoding) =>
+    __host.hmac(String(algorithm), String(key), String(data), encoding === undefined ? undefined : String(encoding)),
+  randomUUID: () => __host.uuid(),
+}));
+
+define('encoding', Object.freeze({
+  base64: (text) => __host.base64(String(text)),
+  fromBase64: (text) => __host.fromBase64(String(text)),
+  base64url: (text) => __host.base64url(String(text)),
+  urlEncode: (text) => __host.urlEncode(String(text)),
+}));
+
+const deepEqual = (a, b) => {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) return a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
+  const keysA = Object.keys(a).filter((k) => a[k] !== undefined);
+  const keysB = Object.keys(b).filter((k) => b[k] !== undefined);
+  return keysA.length === keysB.length && keysA.every((k) => hasOwn(b, k) && deepEqual(a[k], b[k]));
+};
+
+const makeExpectation = (actual, negated) => {
+  const check = (passed, description) => {
+    if (passed === negated) {
+      throw new ExpectationFailed('Expected ' + show(actual) + (negated ? ' not ' : ' ') + description);
+    }
+  };
+  const matchers = {
+    toBe: (expected) => check(Object.is(actual, expected), 'to be ' + show(expected)),
+    toEqual: (expected) => check(deepEqual(actual, expected), 'to equal ' + show(expected)),
+    toBeDefined: () => check(actual !== undefined, 'to be defined'),
+    toBeUndefined: () => check(actual === undefined, 'to be undefined'),
+    toBeNull: () => check(actual === null, 'to be null'),
+    toBeTruthy: () => check(Boolean(actual), 'to be truthy'),
+    toBeFalsy: () => check(!actual, 'to be falsy'),
+    toContain: (item) =>
+      check(
+        typeof actual === 'string' ? actual.includes(String(item)) : Array.isArray(actual) && actual.some((x) => deepEqual(x, item)),
+        'to contain ' + show(item),
+      ),
+    toMatch: (pattern) =>
+      check(typeof actual === 'string' && (pattern instanceof RegExp ? pattern.test(actual) : actual.includes(String(pattern))),
+        'to match ' + String(pattern)),
+    toBeGreaterThan: (n) => check(typeof actual === 'number' && actual > n, 'to be greater than ' + show(n)),
+    toBeLessThan: (n) => check(typeof actual === 'number' && actual < n, 'to be less than ' + show(n)),
+    toHaveLength: (n) => check(actual !== null && actual !== undefined && actual.length === n, 'to have length ' + show(n)),
+    toHaveProperty: (key, ...value) => {
+      const path = Array.isArray(key) ? key : String(key).split('.');
+      let current = actual;
+      let found = true;
+      for (const part of path) {
+        if (current !== null && typeof current === 'object' && part in current) current = current[part];
+        else { found = false; break; }
+      }
+      check(found && (value.length === 0 || deepEqual(current, value[0])),
+        'to have property ' + path.join('.') + (value.length === 0 ? '' : ' equal to ' + show(value[0])));
+    },
+  };
+  return matchers;
+};
+
+define('expect', (actual) => {
+  const expectation = makeExpectation(actual, false);
+  Object.defineProperty(expectation, 'not', { value: makeExpectation(actual, true) });
+  return Object.freeze(expectation);
+});
+
+define('test', (name, check) => {
+  if (state.tests.length >= ${String(SCRIPT_OUTPUT_LIMITS.tests)}) {
+    throw new ScriptValueInvalid('A script may record at most ${String(SCRIPT_OUTPUT_LIMITS.tests)} tests');
+  }
+  try {
+    check();
+    state.tests.push({ name: String(name), passed: true });
+  } catch (error) {
+    state.tests.push({ name: String(name), passed: false, message: error instanceof Error ? error.message : show(error) });
+  }
+});
+
+const hasCrlf = (text) => /[\r\n\0]/.test(text);
+
+/** A case-insensitive view of an ordered list of [name, value] pairs. */
+const pairsApi = (pairs, writable, what) => {
+  const lower = (name) => String(name).toLowerCase();
+  const refuse = () => { throw new TypeError('The ' + what + ' of a sent request cannot be changed'); };
+  const guard = (name, value) => {
+    if (hasCrlf(name) || hasCrlf(value)) {
+      throw new ScriptValueInvalid('A ' + what + ' name or value may not hold CR, LF or NUL: "' + name + '"');
+    }
+  };
+  return Object.freeze({
+    get: (name) => { const hit = pairs.find(([n]) => lower(n) === lower(name)); return hit === undefined ? undefined : hit[1]; },
+    getAll: (name) => pairs.filter(([n]) => lower(n) === lower(name)).map(([, v]) => v),
+    has: (name) => pairs.some(([n]) => lower(n) === lower(name)),
+    list: () => pairs.map(([name, value]) => ({ name, value })),
+    toObject: () => Object.fromEntries(pairs.map(([n, v]) => [n, v])),
+    set: writable ? (name, value) => {
+      const n = String(name); const v = String(value); guard(n, v);
+      const at = pairs.findIndex(([x]) => lower(x) === lower(n));
+      for (let i = pairs.length - 1; i >= 0; i--) if (lower(pairs[i][0]) === lower(n)) pairs.splice(i, 1);
+      pairs.splice(at === -1 ? pairs.length : at, 0, [n, v]);
+    } : refuse,
+    add: writable ? (name, value) => { const n = String(name); const v = String(value); guard(n, v); pairs.push([n, v]); } : refuse,
+    delete: writable ? (name) => { for (let i = pairs.length - 1; i >= 0; i--) if (lower(pairs[i][0]) === lower(name)) pairs.splice(i, 1); } : refuse,
+  });
+};
+
+const deepFreeze = (value) => {
+  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const key of Object.keys(value)) deepFreeze(value[key]);
+  }
+  return value;
+};
+`;
+const FINISH = String.raw `
+globalThis.__finish = () => ({
+  tests: state.tests,
+  values: [...state.values.entries()].map(([name, entry]) => ({ name, value: entry.value, secret: entry.secret })),
+  request: state.request === undefined ? undefined : state.request(),
+});
+`;
+/**
+ * The prelude for one script: the common API, the protocol's `request`/`response` from its
+ * scripting facet, any extra layer and `__finish`.
+ */
+export function buildPrelude(scripting, phase, api, layer = '') {
+    return `'use strict';\n(() => {\n${COMMON}\n${scripting.prelude(phase)}\n${api === 'postman' ? layer : ''}\n${FINISH}\n})();\n`;
+}

package/dist/script/apply.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Checks what a pre-request script changed before any of it is sent (spec §What a pre-request
+ * script can change; ADR-0016).
+ *
+ * The request a script hands back is untrusted input: a script can call `__finish` itself and
+ * return any shape. So it is parsed against its protocol's schema first, then held to the rules.
+ * The rules are the same for every protocol. A module says what its snapshot holds
+ * (`ProtocolScripting.inspect`) and this file decides, so a module cannot forget a rule:
+ *
+ * 1. the value parses against the module's `requestSchema` and keeps its `protocol`
+ *    (`script-error`);
+ * 2. no single-line value holds CR, LF or NUL (`script-value-invalid`);
+ * 3. the destination keeps its scheme, host and port, and one that is not a URL stays exactly as it
+ *    was (`script-origin-change`);
+ * 4. what the module calls fixed comes back unchanged (`script-error`);
+ * 5. no header or metadata pair holds CR, LF or NUL (`script-value-invalid`);
+ * 6. no `${secret:…}` reference appears that the request's own text did not already hold
+ *    (`script-secret-denied`) — otherwise a script could read any secret by naming it;
+ * 7. the module's own rules (`validate`), when it has any.
+ *
+ * The order is fixed for every protocol, so a request that breaks two rules at once is reported the
+ * same way whatever its protocol. It is not quite the order of 2.x: REST used to check first that
+ * the method is an HTTP method, and that check now runs last, in its `validate` (spec R5).
+ */
+import { z } from 'zod';
+import type { ProtocolScripting, RequestSnapshotBase, ResponseSnapshotBase } from '../protocol/module.js';
+import type { ScriptFailure } from './model.js';
+/** A header or metadata pair as a script hands it back; every module's `requestSchema` uses it. */
+export declare const headerPairSchema: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+/** The checked request a pre-request script hands back, or why it is refused. */
+export type ApplyResult<Q extends RequestSnapshotBase = RequestSnapshotBase> = {
+    readonly ok: true;
+    readonly request: Q;
+} | {
+    readonly ok: false;
+    readonly error: ScriptFailure;
+};
+/** Every `${secret:name}` that `texts` name: a module's `inspect(snapshot).texts`. */
+export declare function secretReferencesIn(texts: readonly string[]): Set<string>;
+/**
+ * The checked request a pre-request script hands back, or why it is refused. `scripting` is the
+ * facet of the protocol `before` belongs to.
+ */
+export declare function applyRequestChanges<Q extends RequestSnapshotBase, R extends ResponseSnapshotBase>(scripting: ProtocolScripting<Q, R>, before: Q, returned: unknown): ApplyResult<Q>;

package/dist/script/apply.js

@@ -0,0 +1,120 @@
+/**
+ * Checks what a pre-request script changed before any of it is sent (spec §What a pre-request
+ * script can change; ADR-0016).
+ *
+ * The request a script hands back is untrusted input: a script can call `__finish` itself and
+ * return any shape. So it is parsed against its protocol's schema first, then held to the rules.
+ * The rules are the same for every protocol. A module says what its snapshot holds
+ * (`ProtocolScripting.inspect`) and this file decides, so a module cannot forget a rule:
+ *
+ * 1. the value parses against the module's `requestSchema` and keeps its `protocol`
+ *    (`script-error`);
+ * 2. no single-line value holds CR, LF or NUL (`script-value-invalid`);
+ * 3. the destination keeps its scheme, host and port, and one that is not a URL stays exactly as it
+ *    was (`script-origin-change`);
+ * 4. what the module calls fixed comes back unchanged (`script-error`);
+ * 5. no header or metadata pair holds CR, LF or NUL (`script-value-invalid`);
+ * 6. no `${secret:…}` reference appears that the request's own text did not already hold
+ *    (`script-secret-denied`) — otherwise a script could read any secret by naming it;
+ * 7. the module's own rules (`validate`), when it has any.
+ *
+ * The order is fixed for every protocol, so a request that breaks two rules at once is reported the
+ * same way whatever its protocol. It is not quite the order of 2.x: REST used to check first that
+ * the method is an HTTP method, and that check now runs last, in its `validate` (spec R5).
+ */
+import { z } from 'zod';
+/** A header or metadata pair as a script hands it back; every module's `requestSchema` uses it. */
+export const headerPairSchema = z.tuple([z.string(), z.string()]);
+const CONTROL = /[\r\n\0]/;
+const SECRET_OPEN = '${secret:';
+const refuse = (code, message) => ({ ok: false, error: { code, message } });
+/** Every `${secret:name}` that `texts` name: a module's `inspect(snapshot).texts`. */
+export function secretReferencesIn(texts) {
+    const names = new Set();
+    for (const text of texts) {
+        addSecretNames(text, names);
+    }
+    return names;
+}
+/**
+ * Adds the name of every `${secret:name}` in `text` to `names`: the text from each `${secret:` to
+ * the first `}` after it. A scan rather than a regex, so text a server chose — many `${secret:`
+ * with no closing brace — costs linear time, never quadratic.
+ */
+function addSecretNames(text, names) {
+    let from = 0;
+    for (;;) {
+        const open = text.indexOf(SECRET_OPEN, from);
+        if (open === -1)
+            return;
+        const start = open + SECRET_OPEN.length;
+        const close = text.indexOf('}', start);
+        // No `}` after this opening means none after any later one either.
+        if (close === -1)
+            return;
+        names.add(text.slice(start, close));
+        from = close + 1;
+    }
+}
+function badPair(pairs) {
+    return pairs.find(([name, value]) => CONTROL.test(name) || CONTROL.test(value))?.[0];
+}
+/**
+ * The origin of a destination that is a URL with a host; undefined for anything else. A gRPC
+ * `host:port` target parses as a scheme and a path with no host, and so does `localhost:8080/x`:
+ * neither has an origin a path could change under, so both have to stay exactly as they were.
+ */
+function originOf(destination) {
+    let url;
+    try {
+        url = new URL(destination);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.host === '')
+        return undefined;
+    // A non-special scheme (`grpc:`) has an opaque `origin` of "null"; host and port still say where
+    // the request goes.
+    return url.origin !== 'null' ? url.origin : `${url.protocol}//${url.host}`;
+}
+function sameDestination(before, after) {
+    const was = originOf(before);
+    return was === undefined ? before === after : was === originOf(after);
+}
+/**
+ * The checked request a pre-request script hands back, or why it is refused. `scripting` is the
+ * facet of the protocol `before` belongs to.
+ */
+export function applyRequestChanges(scripting, before, returned) {
+    const parsed = scripting.requestSchema.safeParse(returned);
+    if (!parsed.success || parsed.data.protocol !== before.protocol) {
+        return refuse('script-error', 'The script handed back a request the engine cannot read');
+    }
+    const after = parsed.data;
+    const was = scripting.inspect(before);
+    const now = scripting.inspect(after);
+    if (now.lines.some((line) => CONTROL.test(line))) {
+        return refuse('script-value-invalid', 'A single-line value of the request may not hold CR, LF or NUL');
+    }
+    if (!sameDestination(was.destination, now.destination)) {
+        return refuse('script-origin-change', 'A script cannot change the scheme, host or port the request is sent to');
+    }
+    if (JSON.stringify(now.fixed) !== JSON.stringify(was.fixed)) {
+        return refuse('script-error', 'A script cannot change a part of the request that is fixed');
+    }
+    const pair = badPair(now.pairs);
+    if (pair !== undefined) {
+        return refuse('script-value-invalid', `The header or metadata entry "${pair}" may not hold CR, LF or NUL`);
+    }
+    const allowed = secretReferencesIn(was.texts);
+    const added = [...secretReferencesIn(now.texts)].filter((name) => !allowed.has(name));
+    if (added.length > 0) {
+        return refuse('script-secret-denied', `A script cannot add a reference to a secret the request does not already use: ${added.join(', ')}`);
+    }
+    const failure = scripting.validate?.(before, after);
+    if (failure !== undefined) {
+        return { ok: false, error: failure };
+    }
+    return { ok: true, request: after };
+}

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

@@ -0,0 +1,41 @@
+import type { ScriptCompletion, ScriptDiagnostic, ScriptModel, ScriptQuickInfo, ScriptSignatureHelp } from './service.js';
+export type { ScriptCompletion, ScriptDiagnostic, ScriptModel, ScriptQuickInfo, ScriptSignatureHelp, } from './service.js';
+/** One request to the checker worker. */
+export type CheckerRequest = {
+    readonly op: 'check';
+    readonly model: ScriptModel;
+} | {
+    readonly op: 'remove';
+    readonly modelId: string;
+} | {
+    readonly op: 'diagnostics';
+    readonly modelId: string;
+    readonly model: ScriptModel;
+} | {
+    readonly op: 'completions' | 'quickInfo' | 'signatureHelp';
+    readonly modelId: string;
+    readonly model: ScriptModel;
+    readonly line: number;
+    readonly column: number;
+};
+/** How long one request may take, a fresh worker's start-up included. */
+export declare const CHECK_DEADLINE_MS = 20000;
+export interface ScriptCheckerOptions {
+    readonly deadlineMs?: number;
+    readonly workerUrl?: URL;
+}
+export interface ScriptChecker {
+    /** Checks a script once, keeping no model. */
+    check(model: ScriptModel): Promise<readonly ScriptDiagnostic[]>;
+    diagnostics(modelId: string, model: ScriptModel): Promise<readonly ScriptDiagnostic[]>;
+    completions(modelId: string, model: ScriptModel, line: number, column: number): Promise<readonly ScriptCompletion[]>;
+    quickInfo(modelId: string, model: ScriptModel, line: number, column: number): Promise<ScriptQuickInfo | undefined>;
+    signatureHelp(modelId: string, model: ScriptModel, line: number, column: number): Promise<ScriptSignatureHelp | undefined>;
+    /** Drops a model the editor closed. */
+    remove(modelId: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+/** Thrown by a checker request that could not be answered (overrun, a stopped checker, a crash). */
+export declare class ScriptCheckerError extends Error {
+}
+export declare function createScriptChecker(options?: ScriptCheckerOptions): ScriptChecker;

package/dist/script/check/host.js

@@ -0,0 +1,143 @@
+/**
+ * Script type-checking and editor help off the calling thread (spec §Type-checking).
+ *
+ * The TypeScript language service is heavy, so it runs on one long-lived worker, one request at a
+ * time, each with a deadline. A worker that overruns is terminated and replaced, and the request
+ * fails. Every request that concerns a model carries the model, so a replaced worker loses nothing:
+ * the next request rebuilds it. The pattern is the sandbox host's (`../sandbox/host.ts`).
+ */
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+/** How long one request may take, a fresh worker's start-up included. */
+export const CHECK_DEADLINE_MS = 20_000;
+const QUEUE_LIMIT = 64;
+/** Thrown by a checker request that could not be answered (overrun, a stopped checker, a crash). */
+export class ScriptCheckerError extends Error {
+}
+function defaultWorkerUrl() {
+    const sibling = new URL('./worker.js', import.meta.url);
+    if (existsSync(fileURLToPath(sibling))) {
+        return sibling;
+    }
+    const fallback = import.meta.url.replace(/\/src\/script\/check\/host\.ts$/, '/dist/script/check/worker.js');
+    /* v8 ignore next 3 -- only reachable when the engine package has never been built */
+    if (fallback === import.meta.url) {
+        throw new Error('script checker worker not found: build the engine package first');
+    }
+    return new URL(fallback);
+}
+export function createScriptChecker(options = {}) {
+    const deadlineMs = options.deadlineMs ?? CHECK_DEADLINE_MS;
+    let url = options.workerUrl;
+    let worker;
+    let disposed = false;
+    let nextId = 0;
+    let current;
+    let timer;
+    const queue = [];
+    const settle = (outcome) => {
+        const job = current;
+        if (job === undefined)
+            return;
+        current = undefined;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        if ('error' in outcome)
+            job.reject(new ScriptCheckerError(outcome.error));
+        else
+            job.resolve(outcome.result);
+        pump();
+    };
+    const discard = () => {
+        const dead = worker;
+        worker = undefined;
+        if (dead !== undefined) {
+            dead.removeAllListeners();
+            dead.on('error', () => undefined);
+            void dead.terminate();
+        }
+    };
+    const spawn = () => {
+        url ??= defaultWorkerUrl();
+        const next = new Worker(url);
+        next.unref();
+        next.on('message', (answer) => {
+            if (current?.id !== answer.id)
+                return;
+            settle(answer.error !== undefined ? { error: answer.error } : { result: answer.result });
+        });
+        const broken = (why) => {
+            if (worker !== next)
+                return;
+            discard();
+            settle({ error: why });
+        };
+        next.on('error', (error) => broken(`The checker stopped: ${error instanceof Error ? error.message : String(error)}`));
+        next.on('exit', () => broken('The checker stopped unexpectedly'));
+        return next;
+    };
+    function pump() {
+        if (current !== undefined || disposed)
+            return;
+        const job = queue.shift();
+        if (job === undefined)
+            return;
+        current = job;
+        try {
+            worker ??= spawn();
+            worker.postMessage({ id: job.id, request: job.request });
+        }
+        catch (error) {
+            discard();
+            settle({ error: `The checker could not start: ${error instanceof Error ? error.message : String(error)}` });
+            return;
+        }
+        timer = setTimeout(() => {
+            discard();
+            settle({ error: `The check took longer than ${String(deadlineMs)} ms` });
+        }, deadlineMs);
+        timer.unref?.();
+    }
+    const send = (request) => {
+        if (disposed)
+            return Promise.reject(new ScriptCheckerError('The checker was stopped'));
+        if (queue.length >= QUEUE_LIMIT)
+            return Promise.reject(new ScriptCheckerError('Too many checks waiting'));
+        return new Promise((resolve, reject) => {
+            nextId += 1;
+            queue.push({ id: nextId, request, resolve: resolve, reject });
+            pump();
+        });
+    };
+    return {
+        check: (model) => send({ op: 'check', model }),
+        diagnostics: (modelId, model) => send({ op: 'diagnostics', modelId, model }),
+        completions: (modelId, model, line, column) => send({ op: 'completions', modelId, model, line, column }),
+        quickInfo: async (modelId, model, line, column) => (await send({ op: 'quickInfo', modelId, model, line, column })) ?? undefined,
+        signatureHelp: async (modelId, model, line, column) => (await send({ op: 'signatureHelp', modelId, model, line, column })) ?? undefined,
+        remove: async (modelId) => {
+            await send({ op: 'remove', modelId });
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            const dead = worker;
+            worker = undefined;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+            const waiting = [...(current !== undefined ? [current] : []), ...queue.splice(0)];
+            current = undefined;
+            for (const job of waiting)
+                job.reject(new ScriptCheckerError('The checker was stopped'));
+            if (dead !== undefined) {
+                dead.removeAllListeners();
+                dead.on('error', () => undefined);
+                await dead.terminate();
+            }
+        },
+    };
+}

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

@@ -0,0 +1,52 @@
+import ts from 'typescript';
+import type { ScriptApi } from '../model.js';
+/** Most script models kept at once. */
+export declare const MAX_MODELS = 32;
+export interface ScriptDiagnostic {
+    /** 1-based. */
+    readonly line: number;
+    /** 1-based. */
+    readonly column: number;
+    readonly endLine: number;
+    readonly endColumn: number;
+    readonly message: string;
+    readonly code: number;
+    readonly severity: 'error' | 'warning';
+}
+export interface ScriptCompletion {
+    readonly name: string;
+    readonly kind: string;
+    readonly detail?: string;
+}
+export interface ScriptQuickInfo {
+    readonly text: string;
+    readonly documentation?: string;
+}
+export interface ScriptSignatureHelp {
+    readonly label: string;
+    readonly parameters: readonly string[];
+    readonly activeParameter: number;
+    readonly documentation?: string;
+}
+/** What a model holds: the script and the declarations it is checked against. */
+export interface ScriptModel {
+    readonly source: string;
+    readonly declarations: string;
+    readonly api: ScriptApi;
+}
+export declare const COMPILER_OPTIONS: ts.CompilerOptions;
+/** Sets a model's text, creating its service if it is new. */
+export declare function updateModel(id: string, model: ScriptModel): void;
+export declare function removeModel(id: string): void;
+/**
+ * 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 declare function diagnosticsOf(id: string): ScriptDiagnostic[];
+/** Completions at a 1-based position, at most 200. */
+export declare function completionsAt(id: string, line: number, column: number): ScriptCompletion[];
+export declare function quickInfoAt(id: string, line: number, column: number): ScriptQuickInfo | undefined;
+export declare function signatureHelpAt(id: string, line: number, column: number): ScriptSignatureHelp | undefined;
+/** One-shot check of a script against declarations, without keeping a model. */
+export declare function checkOnce(model: ScriptModel): ScriptDiagnostic[];