@wirebench/engine 2.1.1

package/dist/xml/tolerant-tree.js

@@ -0,0 +1,134 @@
+/**
+ * A tolerant XML tokenizer shared by the pretty printer and the envelope transforms.
+ *
+ * "Tolerant" means: it never throws, it recognises every construct a serializer would
+ * normally lose (comments, CDATA, processing instructions, the XML declaration, DOCTYPE),
+ * and it reports failure by returning `undefined` rather than by raising — the callers are
+ * text transforms that must return their input unchanged when they cannot understand it.
+ *
+ * Every token carries its `[start, end)` offsets into the original text, so a transform can
+ * splice ranges out of the source instead of re-serializing a tree (which would silently
+ * rewrite attribute spacing and quoting).
+ */
+const TOKEN_RE = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<\?[\s\S]*?\?>|<!DOCTYPE(?:[^[>]|\[[^\]]*\])*>|<\/(?:[^<>"']|"[^"]*"|'[^']*')*>|<[^!?/](?:[^<>"']|"[^"]*"|'[^']*')*>|[^<]+/g;
+/** Normalises CRLF/CR line endings to `\n`. */
+export function normalizeLineEndings(text) {
+    return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+/** The local part of a possibly prefixed name. */
+export function localNameOf(name) {
+    const colon = name.indexOf(':');
+    return colon === -1 ? name : name.slice(colon + 1);
+}
+/**
+ * Tokenizes `text`. Returns `undefined` when the tokens do not contiguously cover the whole
+ * string (i.e. the markup is malformed enough that a transform must leave it alone).
+ */
+export function tokenizeXml(text) {
+    const tokens = [];
+    const re = new RegExp(TOKEN_RE);
+    let match;
+    let cursor = 0;
+    while ((match = re.exec(text)) !== null) {
+        const raw = match[0];
+        const start = match.index;
+        if (start !== cursor) {
+            return undefined;
+        }
+        const end = start + raw.length;
+        cursor = end;
+        if (raw.startsWith('<!--')) {
+            tokens.push({ kind: 'comment', raw, start, end });
+        }
+        else if (raw.startsWith('<![CDATA[')) {
+            tokens.push({ kind: 'cdata', raw, start, end });
+        }
+        else if (raw.startsWith('<?')) {
+            tokens.push({ kind: 'pi', raw, start, end });
+        }
+        else if (/^<!DOCTYPE/i.test(raw)) {
+            tokens.push({ kind: 'doctype', raw, start, end });
+        }
+        else if (raw.startsWith('</')) {
+            const nameMatch = /^<\/\s*([^\s>]+)\s*>$/.exec(raw);
+            if (nameMatch?.[1] === undefined) {
+                return undefined;
+            }
+            tokens.push({ kind: 'close', raw, start, end, name: nameMatch[1] });
+        }
+        else if (raw.startsWith('<')) {
+            const selfClosing = /\/>$/.test(raw);
+            const nameMatch = /^<([^\s/>]+)/.exec(raw);
+            if (nameMatch?.[1] === undefined) {
+                return undefined;
+            }
+            const name = nameMatch[1];
+            const attrsEnd = raw.length - (selfClosing ? 2 : 1);
+            const rawAttrs = raw.slice(1 + name.length, attrsEnd).trim();
+            tokens.push({ kind: 'open', raw, start, end, name, rawAttrs, selfClosing });
+        }
+        else {
+            tokens.push({ kind: 'text', raw, start, end });
+        }
+    }
+    return cursor === text.length ? tokens : undefined;
+}
+/**
+ * Builds an element tree over `tokens`, keeping source ranges. Returns `undefined` when tags
+ * are unbalanced or mismatched — again, a signal to leave the document alone.
+ */
+export function buildRangeTree(tokens) {
+    const roots = [];
+    const stack = [];
+    const top = () => stack[stack.length - 1];
+    const push = (node) => {
+        (top()?.children ?? roots).push(node);
+    };
+    for (const token of tokens) {
+        if (token.kind === 'open') {
+            if (token.selfClosing === true) {
+                push({
+                    name: token.name ?? '',
+                    rawAttrs: token.rawAttrs ?? '',
+                    selfClosing: true,
+                    start: token.start,
+                    end: token.end,
+                    innerStart: token.end,
+                    innerEnd: token.end,
+                    children: [],
+                    leafTokens: [],
+                });
+                continue;
+            }
+            stack.push({
+                name: token.name ?? '',
+                rawAttrs: token.rawAttrs ?? '',
+                start: token.start,
+                innerStart: token.end,
+                children: [],
+                leafTokens: [],
+            });
+            continue;
+        }
+        if (token.kind === 'close') {
+            const frame = stack.pop();
+            if (frame === undefined || frame.name !== token.name) {
+                return undefined;
+            }
+            push({
+                name: frame.name,
+                rawAttrs: frame.rawAttrs,
+                selfClosing: false,
+                start: frame.start,
+                end: token.end,
+                innerStart: frame.innerStart,
+                innerEnd: token.start,
+                children: frame.children,
+                leafTokens: frame.leafTokens,
+            });
+            continue;
+        }
+        top()?.leafTokens.push(token);
+    }
+    return stack.length === 0 ? roots : undefined;
+}

package/dist/xpath/evaluate-async.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Time-bounded wrapper around {@link evaluate}: runs the (synchronous, potentially pathological)
+ * XPath/XQuery evaluation inside a `node:worker_threads` Worker so a runaway expression
+ * (`1 to 100000000`, an infinite FLWOR, …) cannot freeze the Electron main process. Callers get
+ * a `{kind: 'error', code: 'xpath-timeout'}` result instead of a hang once `timeoutMs` elapses.
+ */
+import type { EvaluateOptions, QueryResult } from './evaluate.js';
+/** Options accepted by {@link evaluateWithTimeout}. */
+export interface EvaluateWithTimeoutOptions {
+    /** Milliseconds to wait before terminating the worker and reporting `xpath-timeout`. */
+    readonly timeoutMs?: number;
+    /**
+     * Which document `text` is. Defaults to `xml`.
+     *
+     * The timeout, the worker and the result shape are identical either way — only the evaluator on
+     * the far side differs — so a JSON query gets the same runaway-expression protection for free.
+     */
+    readonly kind?: 'xml' | 'json';
+}
+/**
+ * Evaluates `expression` against `xml` on a worker thread, resolving to the same
+ * {@link QueryResult} shape {@link evaluate} returns synchronously, but bounded by `timeoutMs`
+ * (default 5000ms). Never throws or rejects: a timeout, a worker crash, or an evaluation error
+ * are all reported as `{kind: 'error'}`.
+ *
+ * @param xml the document to query
+ * @param expression the XPath or XQuery source
+ * @param options language and namespace bindings, forwarded to `evaluate`
+ * @param timeoutOptions `{timeoutMs}`, default 5000
+ */
+export declare function evaluateWithTimeout(text: string, expression: string, options: EvaluateOptions, timeoutOptions?: EvaluateWithTimeoutOptions): Promise<QueryResult>;

package/dist/xpath/evaluate-async.js

@@ -0,0 +1,81 @@
+/**
+ * Time-bounded wrapper around {@link evaluate}: runs the (synchronous, potentially pathological)
+ * XPath/XQuery evaluation inside a `node:worker_threads` Worker so a runaway expression
+ * (`1 to 100000000`, an infinite FLWOR, …) cannot freeze the Electron main process. Callers get
+ * a `{kind: 'error', code: 'xpath-timeout'}` result instead of a hang once `timeoutMs` elapses.
+ */
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+/** Default time budget for one evaluation, matching the brief's 5s ceiling for the scratchpad. */
+const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * Resolves the compiled worker entry point.
+ *
+ * `worker.ts` must run as plain JavaScript in a Worker (no TS loader is an approved dependency
+ * here — `tsx` is only ever an optional peer of `vite`, not installed). `tsc -b` (run by
+ * `pnpm typecheck`, which `pnpm check` and `pnpm build` both depend on) always emits
+ * `dist/xpath/worker.js` alongside this file's own compiled output, so the common case is just
+ * "the sibling `worker.js` next to wherever this module itself is running from". The only time
+ * that sibling doesn't exist is running this module directly from `src` (e.g.
+ * `vitest run packages/engine/test/unit/xpath` on its own, before a build) — in that case fall
+ * back to the package's `dist/xpath/worker.js`, computed from this file's own `src/xpath/…`
+ * location.
+ */
+function workerUrl() {
+    const sibling = new URL('./worker.js', import.meta.url);
+    if (existsSync(fileURLToPath(sibling))) {
+        return sibling;
+    }
+    const fallback = import.meta.url.replace(/\/src\/xpath\/evaluate-async\.ts$/, '/dist/xpath/worker.js');
+    /* v8 ignore next 3 -- only reachable when the engine package has genuinely never been built */
+    if (fallback === import.meta.url) {
+        throw new Error('xpath worker not found: build the engine package (pnpm --filter @wirebench/engine build) first');
+    }
+    return new URL(fallback);
+}
+/**
+ * Evaluates `expression` against `xml` on a worker thread, resolving to the same
+ * {@link QueryResult} shape {@link evaluate} returns synchronously, but bounded by `timeoutMs`
+ * (default 5000ms). Never throws or rejects: a timeout, a worker crash, or an evaluation error
+ * are all reported as `{kind: 'error'}`.
+ *
+ * @param xml the document to query
+ * @param expression the XPath or XQuery source
+ * @param options language and namespace bindings, forwarded to `evaluate`
+ * @param timeoutOptions `{timeoutMs}`, default 5000
+ */
+export function evaluateWithTimeout(text, expression, options, timeoutOptions) {
+    const timeoutMs = timeoutOptions?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const kind = timeoutOptions?.kind ?? 'xml';
+    return new Promise((resolve) => {
+        let settled = false;
+        const worker = new Worker(workerUrl(), { workerData: { text, kind, expression, options } });
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            worker.removeAllListeners();
+            void worker.terminate();
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            finish({
+                kind: 'error',
+                code: 'xpath-timeout',
+                message: `Query timed out after ${timeoutMs}ms`,
+            });
+        }, timeoutMs);
+        timer.unref?.();
+        worker.once('message', (result) => finish(result));
+        worker.once('error', (error) => finish({ kind: 'error', message: error instanceof Error ? error.message : String(error) }));
+        worker.once('exit', (code) => {
+            /* v8 ignore next 3 -- normal completion always finishes via the 'message' listener first */
+            if (!settled) {
+                finish({ kind: 'error', message: `xpath worker exited unexpectedly (code ${code})` });
+            }
+        });
+    });
+}

package/dist/xpath/evaluate.d.ts

@@ -0,0 +1,98 @@
+/**
+ * XPath 3.1 / XQuery 3.1 evaluation against a response, for the response Query scratchpad. Where
+ * classic SOAP workbenches limit querying to XPath 2.0 inside assertions, this runs both languages
+ * over the actual bytes the server returned, ahead of any assertion.
+ *
+ * A JSON response is queried by the same two languages ({@link evaluateJson}) rather than by a third
+ * one: XPath 3.1 has maps, arrays and the `?` lookup operator, so `?items?*[?status = "open"]?id`
+ * needs no new dependency and no second expression syntax for users to learn. The context item is
+ * the parsed document itself.
+ */
+import type { LinePosition } from '../xml/positions.js';
+import type { TextRange } from '../xsd/locate.js';
+/** One node-shaped query result. */
+export interface QueryNodeItem {
+    /** The node serialised back to text (an element/comment/PI/document), or an attribute's value. */
+    readonly text: string;
+    readonly nodeKind: 'element' | 'attribute' | 'text' | 'document' | 'comment' | 'pi';
+    /** Offsets of this node in the original `xml` text, when they could be recovered. */
+    readonly range?: TextRange;
+    /**
+     * A simple `/a/b[2]`-shaped path to the node from the document root, with a 1-based index
+     * among same-named siblings at every step.
+     *
+     * Only elements have steps of their own. A text, comment or processing-instruction result is
+     * reported at the path of the nearest enclosing element — the place to look for it in the
+     * document — and an attribute result appends `/@name` to its owning element's path. A result
+     * with no element at or above it (the document node itself) is reported as `/`.
+     */
+    readonly path: string;
+}
+/** One atomic-value query result (a string, number, boolean, map, or array). */
+export interface QueryValueItem {
+    readonly text: string;
+    /** A type label: `xs:string`, `xs:integer`, `map`, `array`, … */
+    readonly type: string;
+    /**
+     * Where the value was found, when the evaluator knows.
+     *
+     * Only JSONPath fills this in (`$['items'][0]['id']`): it walks a document and can say where it
+     * landed, so a multi-match result stays readable. An XPath or XQuery expression computes a value
+     * rather than locating one — `count(//*)` has no path — so it leaves this absent.
+     */
+    readonly path?: string;
+}
+/** The outcome of running one XPath/XQuery expression against a document. */
+export type QueryResult = {
+    readonly kind: 'nodes';
+    readonly items: readonly QueryNodeItem[];
+    readonly truncated: boolean;
+} | {
+    readonly kind: 'values';
+    readonly items: readonly QueryValueItem[];
+    readonly truncated: boolean;
+} | {
+    readonly kind: 'empty';
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+    readonly code?: string;
+    readonly position?: LinePosition;
+};
+/** The languages the Query view offers. `jsonpath` is JSON-only, and only
+ * {@link evaluateJson} accepts it — see `rest/jsonpath.ts`. */
+export type QueryLanguage = 'xpath' | 'xquery' | 'jsonpath';
+/** Options accepted by {@link evaluate}. */
+export interface EvaluateOptions {
+    readonly language: QueryLanguage;
+    /** Prefix to namespace URI, used to resolve `prefix:local` names in the expression. */
+    readonly namespaces?: Readonly<Record<string, string>>;
+}
+/**
+ * Evaluates an XPath 3.1 or XQuery 3.1 `expression` against `xml`.
+ *
+ * Never throws: parse failures, unresolved namespace prefixes, and runtime errors are all
+ * reported as `{kind: 'error'}` results instead, since a scratchpad query is expected to be
+ * wrong sometimes and the caller (the Query view) needs a value to render either way.
+ *
+ * @param xml the document to query (typically a response envelope)
+ * @param expression the XPath or XQuery source
+ * @param options language and namespace bindings
+ */
+export declare function evaluate(xml: string, expression: string, options: EvaluateOptions): QueryResult;
+/**
+ * Evaluates `expression` against a JSON document.
+ *
+ * The parsed JSON *is* the context item, so a lookup starts at `?`: `?name` reads a field of a
+ * top-level object, `?*` every member of an array, and `?items?*[?status = "open"]?id` filters and
+ * projects in one expression. Results are always values — JSON has no nodes — so nothing here needs
+ * the document's text, and a result carries no source range.
+ *
+ * A `language` of `jsonpath` is delegated to {@link evaluateJsonPath} instead, which answers in this same
+ * result shape — so one caller, and one result renderer, covers all three languages.
+ *
+ * @param json the response body as text
+ * @param expression the XPath, XQuery or JSONPath source
+ * @param options language (namespaces are accepted and unused: JSON has no names to qualify)
+ */
+export declare function evaluateJson(json: string, expression: string, options: EvaluateOptions): QueryResult;