@sdxc/spec 0.0.0-pre.1

package/dist/project-config.d.ts

@@ -0,0 +1,163 @@
+/**
+ * The suite's project configuration file, `spec/config.jsonc`: the CLI-internal
+ * machinery that reads it, decides which declared plugins the caller authorized
+ * to launch, and connects the authorized ones over the stdio transport. The
+ * file's `plugins` key maps a namespace to its launch command; launching one
+ * runs project-declared code, so it is deny-by-default — a plugin starts only
+ * when `--allow-plugins` grants it. `config.jsonc` is the suite's general
+ * configuration home; its `permissions` key is parsed here too.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { ConfigPermissionEntry } from "./permissions.js";
+import type { Plugin } from "./plugin.js";
+import type { LoadedSuite } from "./sources.js";
+import { SpecError } from "./errors.js";
+/**
+ * Whether, and how far, the caller authorized launching declared plugins.
+ * Absent `--allow-plugins` leaves it `denied`; a bare flag is `all`; a scoped
+ * `--allow-plugins=a,b` names the namespaces allowed to launch.
+ */
+export type PluginLaunchGrant = {
+    mode: "denied";
+} | {
+    mode: "all";
+} | {
+    mode: "scoped";
+    namespaces: string[];
+};
+/** One plugin a project declares: its namespace and the command to launch it. */
+export interface PluginDeclaration {
+    /** The namespace the plugin's tools live under, e.g. `"demo"`. */
+    namespace: string;
+    /**
+     * The argv that launches the plugin. Relative path arguments (those starting
+     * with `.`) are already resolved absolute against the config file's
+     * directory, so the command runs the same from any working directory.
+     */
+    command: string[];
+}
+/**
+ * A parsed `spec/config.jsonc`: the suite's project configuration. The
+ * `plugins` key lists the plugins a project declares, in file order; the
+ * `permissions` key declares the grants that stay inert until `--allow-config`.
+ */
+export interface ProjectConfig {
+    /** The declared plugins; empty when no config exists or it declares none. */
+    plugins: PluginDeclaration[];
+    /** The suite's declared permission requirements; inert without `--allow-config`. */
+    permissions: PermissionsConfig;
+}
+/**
+ * The `permissions` key of `spec/config.jsonc`: a suite's declared grant
+ * requirements. Deny-by-default is preserved — these are inert until the caller
+ * passes `--allow-config`, so a cloned repo cannot self-grant.
+ */
+export interface PermissionsConfig {
+    /** The declared grants, in file order; empty when none are declared. */
+    allow: ConfigPermissionEntry[];
+}
+/** Splitting the config's declared plugins into those to launch and those refused. */
+export interface LaunchPlan {
+    /** Declarations the grant authorized, to be connected. */
+    launch: PluginDeclaration[];
+    /** Namespaces declared but not authorized to launch. */
+    deniedNamespaces: string[];
+}
+/**
+ * Extract the `--allow-plugins` grant from a raw argument list, leaving the
+ * remaining arguments for the permission parser to handle. Plugin launch sits
+ * outside the four `--allow-*` capability families, so it gets its own parse here.
+ *
+ * @param args - The raw CLI arguments after `run`.
+ * @returns The launch grant plus the arguments that were not `--allow-plugins`.
+ */
+export declare function parsePluginGrant(args: string[]): Result<{
+    grant: PluginLaunchGrant;
+    remaining: string[];
+}, SpecError>;
+/**
+ * Read the `spec/config.jsonc` that governs a suite directory (JSONC, so
+ * comments and trailing commas are tolerated), trying `config.jsonc` before
+ * `config.json`. A missing file simply declares no plugins.
+ *
+ * @param suiteRoot - The suite directory `spec run` was pointed at.
+ * @returns The parsed config, or the failure that made it unreadable.
+ */
+export declare function loadProjectConfig(suiteRoot: string): Promise<Result<ProjectConfig, SpecError>>;
+/**
+ * Split the config's declarations into the ones the grant authorizes and the
+ * namespaces it refuses. An unimported refusal stays harmless — only
+ * {@link deniedReferences} turns a refusal the suite depends on into a failure.
+ *
+ * @param config - The parsed project config.
+ * @param grant - The caller's `--allow-plugins` grant.
+ * @returns The plugins to launch and the namespaces refused.
+ */
+export declare function planPluginLaunch(config: ProjectConfig, grant: PluginLaunchGrant): LaunchPlan;
+/**
+ * Which refused namespaces the suite actually imports with `use` — a denied
+ * declaration only matters when a spec depends on it. The result drives the
+ * deny-by-default diagnostic, naming exactly the grant a caller is missing.
+ *
+ * @param suite - The loaded suite, for its files' `use` imports.
+ * @param deniedNamespaces - The namespaces refused by {@link planPluginLaunch}.
+ * @returns The refused namespaces the suite imports, in first-seen order.
+ */
+export declare function deniedReferences(suite: LoadedSuite, deniedNamespaces: string[]): string[];
+/**
+ * Build the deny-by-default diagnostic for a suite that imports plugins it was
+ * not authorized to launch, shaped like every other refused capability: code
+ * `permission-denied` with a `--allow-plugins` remedy.
+ *
+ * @param namespaces - The imported-but-unauthorized namespaces.
+ * @returns The error the CLI reports before any test runs.
+ */
+export declare function launchDeniedError(namespaces: string[]): SpecError;
+/**
+ * Connect the authorized plugins over the stdio transport, in declaration
+ * order, each spawning its command and completing the describe handshake. A
+ * failure disposes every plugin already connected, so a launch never leaks a child.
+ *
+ * @param launch - The declarations {@link planPluginLaunch} authorized.
+ * @returns The connected plugins, ready to pass to `runSuite`, or the failure.
+ */
+export declare function connectDeclaredPlugins(launch: PluginDeclaration[]): Promise<Result<Plugin[], SpecError>>;
+/**
+ * Dispose a set of connected plugins, best-effort. Used to unwind a partial
+ * launch and by the CLI when a run never reaches the runner's own teardown;
+ * a throwing or absent `dispose` is ignored, exactly as the runner treats it.
+ *
+ * @param plugins - The plugins to release.
+ */
+export declare function disposeAll(plugins: Plugin[]): Promise<void>;
+/**
+ * The plugin launch grant a config's `permissions.allow` declares: a bare
+ * `"plugins"` entry authorizes every plugin, a `["plugins", ...]` tuple names
+ * the namespaces, applied under `--allow-config` and unioned with `--allow-plugins`.
+ *
+ * @param entries - The validated allow-list entries.
+ * @returns The launch grant the config declares.
+ */
+export declare function pluginGrantFromConfig(entries: readonly ConfigPermissionEntry[]): PluginLaunchGrant;
+/**
+ * Union two plugin launch grants, widening `base` by whatever `extra` adds —
+ * the launch-grant analogue of the capability-grant union, used to fold a
+ * config's declared `plugins` grant into the caller's `--allow-plugins` grant.
+ *
+ * @param base - The caller's `--allow-plugins` grant.
+ * @param extra - The config's declared plugin launch grant.
+ * @returns The unioned launch grant.
+ */
+export declare function mergePluginGrants(base: PluginLaunchGrant, extra: PluginLaunchGrant): PluginLaunchGrant;
+/**
+ * Whether a plugin launch grant authorizes launching a namespace — exposed so
+ * the CLI can decide the `--allow-config` hint for a plugin-launch denial.
+ *
+ * @param grant - The launch grant to test.
+ * @param namespace - The namespace being launched.
+ * @returns Whether the grant admits it.
+ */
+export declare function pluginGrantAdmits(grant: PluginLaunchGrant, namespace: string): boolean;

package/dist/project-config.js

@@ -0,0 +1,497 @@
+/**
+ * The suite's project configuration file, `spec/config.jsonc`: the CLI-internal
+ * machinery that reads it, decides which declared plugins the caller authorized
+ * to launch, and connects the authorized ones over the stdio transport. The
+ * file's `plugins` key maps a namespace to its launch command; launching one
+ * runs project-declared code, so it is deny-by-default — a plugin starts only
+ * when `--allow-plugins` grants it. `config.jsonc` is the suite's general
+ * configuration home; its `permissions` key is parsed here too.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { failure, isFailure, success } from "@sdxc/result";
+import { LoadError, SpecError, ToolError } from "./errors.js";
+import { connectStdioPlugin } from "./transport-stdio.js";
+/** The permission families a `spec/config.jsonc` `permissions.allow` may name. */
+const PERMISSION_FAMILIES = new Set([
+    "run",
+    "net",
+    "env",
+    "host-fs",
+    "plugins",
+]);
+/** Conventional config file names, tried in this order under the suite dir. */
+const CONFIG_NAMES = ["config.jsonc", "config.json"];
+/** The `--allow-plugins` flag and its scoped form, parsed CLI-side. */
+const ALLOW_PLUGINS_FLAG = "--allow-plugins";
+/**
+ * Namespaces the runtime provides itself; the config's `plugins` key may not
+ * claim one of them, because a declared plugin sharing the name would silently
+ * shadow the built-in in the registry.
+ */
+const BUILT_IN_NAMESPACES = new Set([
+    "fs",
+    "cli",
+    "http",
+    "browser",
+    "db",
+    "url",
+    "jwt",
+    "env",
+]);
+/**
+ * Extract the `--allow-plugins` grant from a raw argument list, leaving the
+ * remaining arguments for the permission parser to handle. Plugin launch sits
+ * outside the four `--allow-*` capability families, so it gets its own parse here.
+ *
+ * @param args - The raw CLI arguments after `run`.
+ * @returns The launch grant plus the arguments that were not `--allow-plugins`.
+ */
+export function parsePluginGrant(args) {
+    let grant = { mode: "denied" };
+    let remaining = [];
+    for (let argument of args) {
+        if (argument === ALLOW_PLUGINS_FLAG) {
+            grant = grant.mode === "all" ? grant : { mode: "all" };
+            continue;
+        }
+        if (!argument.startsWith(`${ALLOW_PLUGINS_FLAG}=`)) {
+            remaining.push(argument);
+            continue;
+        }
+        let namespaces = argument
+            .slice(ALLOW_PLUGINS_FLAG.length + 1)
+            .split(",")
+            .map((namespace) => namespace.trim())
+            .filter((namespace) => namespace.length > 0);
+        if (namespaces.length === 0) {
+            return failure(new SpecError("usage-error", `${ALLOW_PLUGINS_FLAG}= expects a comma-separated namespace list, e.g. ${ALLOW_PLUGINS_FLAG}=demo.`));
+        }
+        grant = widenLaunchGrant(grant, namespaces);
+    }
+    return success({ grant, remaining });
+}
+/**
+ * Read the `spec/config.jsonc` that governs a suite directory (JSONC, so
+ * comments and trailing commas are tolerated), trying `config.jsonc` before
+ * `config.json`. A missing file simply declares no plugins.
+ *
+ * @param suiteRoot - The suite directory `spec run` was pointed at.
+ * @returns The parsed config, or the failure that made it unreadable.
+ */
+export async function loadProjectConfig(suiteRoot) {
+    let directory = resolve(suiteRoot);
+    for (let name of CONFIG_NAMES) {
+        let path = resolve(directory, name);
+        if (!existsSync(path))
+            continue;
+        let text;
+        try {
+            text = await readFile(path, "utf8");
+        }
+        catch (error) {
+            return failure(new LoadError("load-error", `Cannot read spec/config.jsonc ${path}: ${errorMessage(error)}`));
+        }
+        let parsed = parseJsonc(text, path);
+        if (isFailure(parsed))
+            return parsed;
+        return validateConfig(parsed.data, directory, path);
+    }
+    return success({ plugins: [], permissions: { allow: [] } });
+}
+/**
+ * Split the config's declarations into the ones the grant authorizes and the
+ * namespaces it refuses. An unimported refusal stays harmless — only
+ * {@link deniedReferences} turns a refusal the suite depends on into a failure.
+ *
+ * @param config - The parsed project config.
+ * @param grant - The caller's `--allow-plugins` grant.
+ * @returns The plugins to launch and the namespaces refused.
+ */
+export function planPluginLaunch(config, grant) {
+    let launch = [];
+    let deniedNamespaces = [];
+    for (let declaration of config.plugins) {
+        if (grantAdmits(grant, declaration.namespace))
+            launch.push(declaration);
+        else
+            deniedNamespaces.push(declaration.namespace);
+    }
+    return { launch, deniedNamespaces };
+}
+/**
+ * Which refused namespaces the suite actually imports with `use` — a denied
+ * declaration only matters when a spec depends on it. The result drives the
+ * deny-by-default diagnostic, naming exactly the grant a caller is missing.
+ *
+ * @param suite - The loaded suite, for its files' `use` imports.
+ * @param deniedNamespaces - The namespaces refused by {@link planPluginLaunch}.
+ * @returns The refused namespaces the suite imports, in first-seen order.
+ */
+export function deniedReferences(suite, deniedNamespaces) {
+    if (deniedNamespaces.length === 0)
+        return [];
+    let denied = new Set(deniedNamespaces);
+    let referenced = [];
+    let seen = new Set();
+    for (let file of suite.files) {
+        for (let use of file.uses) {
+            if (denied.has(use.namespace) && !seen.has(use.namespace)) {
+                seen.add(use.namespace);
+                referenced.push(use.namespace);
+            }
+        }
+    }
+    return referenced;
+}
+/**
+ * Build the deny-by-default diagnostic for a suite that imports plugins it was
+ * not authorized to launch, shaped like every other refused capability: code
+ * `permission-denied` with a `--allow-plugins` remedy.
+ *
+ * @param namespaces - The imported-but-unauthorized namespaces.
+ * @returns The error the CLI reports before any test runs.
+ */
+export function launchDeniedError(namespaces) {
+    let list = namespaces.join(", ");
+    let plural = namespaces.length === 1 ? "namespace" : "namespaces";
+    let error = new SpecError("permission-denied", `Plugin launch denied: the suite imports the plugin ${plural} ${list}, declared in spec/config.jsonc but not authorized to launch. Launching a declared plugin executes the command the project declares for it, so it is denied unless you allow it.`);
+    error.remedy = `spec run ${ALLOW_PLUGINS_FLAG}=${namespaces.join(",")}`;
+    return error;
+}
+/**
+ * Connect the authorized plugins over the stdio transport, in declaration
+ * order, each spawning its command and completing the describe handshake. A
+ * failure disposes every plugin already connected, so a launch never leaks a child.
+ *
+ * @param launch - The declarations {@link planPluginLaunch} authorized.
+ * @returns The connected plugins, ready to pass to `runSuite`, or the failure.
+ */
+export async function connectDeclaredPlugins(launch) {
+    let connected = [];
+    for (let declaration of launch) {
+        let result = await connectStdioPlugin(declaration.command, declaration.namespace);
+        if (isFailure(result)) {
+            await disposeAll(connected);
+            return failure(new ToolError(`Failed to load plugin "${declaration.namespace}" from its spec/config.jsonc command "${declaration.command.join(" ")}": ${result.error.message}`));
+        }
+        connected.push(result.data);
+    }
+    return success(connected);
+}
+/**
+ * Dispose a set of connected plugins, best-effort. Used to unwind a partial
+ * launch and by the CLI when a run never reaches the runner's own teardown;
+ * a throwing or absent `dispose` is ignored, exactly as the runner treats it.
+ *
+ * @param plugins - The plugins to release.
+ */
+export async function disposeAll(plugins) {
+    for (let plugin of plugins) {
+        if (plugin.dispose === undefined)
+            continue;
+        try {
+            await plugin.dispose();
+        }
+        catch { }
+    }
+}
+/** Merge one `--allow-plugins=` occurrence into the grant so far. */
+function widenLaunchGrant(current, namespaces) {
+    if (current.mode === "all")
+        return current;
+    if (current.mode === "denied")
+        return { mode: "scoped", namespaces: [...namespaces] };
+    let merged = [...current.namespaces];
+    for (let namespace of namespaces) {
+        if (!merged.includes(namespace))
+            merged.push(namespace);
+    }
+    return { mode: "scoped", namespaces: merged };
+}
+function grantAdmits(grant, namespace) {
+    if (grant.mode === "all")
+        return true;
+    if (grant.mode === "scoped")
+        return grant.namespaces.includes(namespace);
+    return false;
+}
+/** Parse config text as JSONC, tolerating comments and trailing commas. */
+function parseJsonc(text, path) {
+    try {
+        return success(JSON.parse(stripTrailingCommas(stripComments(text))));
+    }
+    catch (error) {
+        return failure(new LoadError("load-error", `spec/config.jsonc ${path} is not valid JSONC: ${errorMessage(error)}`));
+    }
+}
+/**
+ * Shape a parsed config object into a {@link ProjectConfig}, rejecting every
+ * malformed declaration with a `load-error` that names the offending plugin.
+ * Relative command paths are resolved absolute against the config directory.
+ */
+function validateConfig(parsed, directory, path) {
+    if (!isRecord(parsed)) {
+        return failure(new LoadError("load-error", `spec/config.jsonc ${path} must be a JSON object.`));
+    }
+    let permissions = validatePermissions(parsed.permissions, path);
+    if (isFailure(permissions))
+        return permissions;
+    let pluginsField = parsed.plugins;
+    if (pluginsField === undefined)
+        return success({ plugins: [], permissions: permissions.data });
+    if (!isRecord(pluginsField)) {
+        return failure(new LoadError("load-error", `spec/config.jsonc ${path} must map "plugins" to an object of namespace → { command }.`));
+    }
+    let plugins = [];
+    for (let [namespace, declaration] of Object.entries(pluginsField)) {
+        let validated = validateDeclaration(namespace, declaration, directory, path);
+        if (isFailure(validated))
+            return validated;
+        plugins.push(validated.data);
+    }
+    return success({ plugins, permissions: permissions.data });
+}
+/**
+ * Validate the `permissions` key into a {@link PermissionsConfig}. An absent
+ * key declares nothing; every malformed entry becomes a `usage-error` naming
+ * it, checked at config load time regardless of `--allow-config`.
+ *
+ * @param field - The raw `permissions` value from the parsed config.
+ * @param path - The config file path, for diagnostics.
+ * @returns The validated permission entries, or the first malformed one.
+ */
+function validatePermissions(field, path) {
+    if (field === undefined)
+        return success({ allow: [] });
+    if (!isRecord(field)) {
+        return failure(new SpecError("usage-error", `spec/config.jsonc ${path} must map "permissions" to an object with an "allow" list.`));
+    }
+    let allowField = field.allow;
+    if (allowField === undefined)
+        return success({ allow: [] });
+    if (!Array.isArray(allowField)) {
+        return failure(new SpecError("usage-error", `spec/config.jsonc ${path} must map "permissions.allow" to a list of grants.`));
+    }
+    let allow = [];
+    for (let entry of allowField) {
+        let validated = validatePermissionEntry(entry, path);
+        if (isFailure(validated))
+            return validated;
+        allow.push(validated.data);
+    }
+    return success({ allow });
+}
+/**
+ * Validate one `permissions.allow` entry: a bare family string (whole-family
+ * grant) or a `[family, ...scopes]` tuple with at least one non-empty scope,
+ * the family always one the runtime knows, else a `usage-error` naming it.
+ */
+function validatePermissionEntry(entry, path) {
+    if (typeof entry === "string") {
+        if (!PERMISSION_FAMILIES.has(entry))
+            return failure(unknownFamily(entry, path));
+        return success({ family: entry, scopes: [] });
+    }
+    if (Array.isArray(entry)) {
+        let family = entry[0];
+        if (typeof family !== "string" || !PERMISSION_FAMILIES.has(family)) {
+            return failure(unknownFamily(describeEntry(entry), path));
+        }
+        let scopes = entry.slice(1);
+        if (scopes.length === 0 ||
+            !scopes.every((scope) => typeof scope === "string" && scope.length > 0)) {
+            return failure(new SpecError("usage-error", `spec/config.jsonc ${path} declares a malformed grant ${describeEntry(entry)}: a tuple is [family, ...non-empty string scopes].`));
+        }
+        return success({
+            family: family,
+            scopes: scopes,
+        });
+    }
+    return failure(new SpecError("usage-error", `spec/config.jsonc ${path} declares a malformed grant ${describeEntry(entry)}: each allow entry is a family string or a [family, ...scopes] tuple.`));
+}
+/** A `usage-error` for an allow entry that names an unrecognized family. */
+function unknownFamily(entry, path) {
+    return new SpecError("usage-error", `spec/config.jsonc ${path} declares an unknown permission family ${entry}: known families are run, net, env, host-fs, plugins.`);
+}
+/** Render an allow entry for a diagnostic, quoting strings and JSON-ing the rest. */
+function describeEntry(entry) {
+    if (typeof entry === "string")
+        return `"${entry}"`;
+    try {
+        return JSON.stringify(entry);
+    }
+    catch {
+        return String(entry);
+    }
+}
+/**
+ * The plugin launch grant a config's `permissions.allow` declares: a bare
+ * `"plugins"` entry authorizes every plugin, a `["plugins", ...]` tuple names
+ * the namespaces, applied under `--allow-config` and unioned with `--allow-plugins`.
+ *
+ * @param entries - The validated allow-list entries.
+ * @returns The launch grant the config declares.
+ */
+export function pluginGrantFromConfig(entries) {
+    let grant = { mode: "denied" };
+    for (let entry of entries) {
+        if (entry.family !== "plugins")
+            continue;
+        grant = entry.scopes.length === 0 ? { mode: "all" } : widenLaunchGrant(grant, entry.scopes);
+    }
+    return grant;
+}
+/**
+ * Union two plugin launch grants, widening `base` by whatever `extra` adds —
+ * the launch-grant analogue of the capability-grant union, used to fold a
+ * config's declared `plugins` grant into the caller's `--allow-plugins` grant.
+ *
+ * @param base - The caller's `--allow-plugins` grant.
+ * @param extra - The config's declared plugin launch grant.
+ * @returns The unioned launch grant.
+ */
+export function mergePluginGrants(base, extra) {
+    if (extra.mode === "denied")
+        return base;
+    if (extra.mode === "all")
+        return { mode: "all" };
+    return widenLaunchGrant(base, extra.namespaces);
+}
+/**
+ * Whether a plugin launch grant authorizes launching a namespace — exposed so
+ * the CLI can decide the `--allow-config` hint for a plugin-launch denial.
+ *
+ * @param grant - The launch grant to test.
+ * @param namespace - The namespace being launched.
+ * @returns Whether the grant admits it.
+ */
+export function pluginGrantAdmits(grant, namespace) {
+    return grantAdmits(grant, namespace);
+}
+/** Validate one namespace → declaration entry from the config's `plugins` key. */
+function validateDeclaration(namespace, declaration, directory, path) {
+    if (namespace.length === 0 || namespace.includes(".")) {
+        return failure(new LoadError("load-error", `spec/config.jsonc ${path} declares an invalid namespace "${namespace}": a namespace is non-empty and contains no dot.`));
+    }
+    if (BUILT_IN_NAMESPACES.has(namespace)) {
+        return failure(new LoadError("load-error", `spec/config.jsonc ${path} declares the namespace "${namespace}", which is a built-in capability and cannot be overridden.`));
+    }
+    if (!isRecord(declaration) || !Array.isArray(declaration.command)) {
+        return failure(new LoadError("load-error", `Plugin "${namespace}" in ${path} must be an object with a "command" array, e.g. { "command": ["bun", "./plugin.ts"] }.`));
+    }
+    let command = declaration.command;
+    if (command.length === 0 || !command.every((part) => typeof part === "string")) {
+        return failure(new LoadError("load-error", `Plugin "${namespace}" in ${path} needs a non-empty "command" array of strings.`));
+    }
+    let resolved = command.map((part) => resolveCommandPart(part, directory));
+    return success({ namespace, command: resolved });
+}
+/**
+ * Resolve one command argument. An argument starting with `.` is a config-
+ * relative path, made absolute against the config directory so the command
+ * runs identically from any working directory; anything else is left verbatim.
+ */
+function resolveCommandPart(part, directory) {
+    if (part.startsWith("."))
+        return resolve(directory, part);
+    if (isAbsolute(part))
+        return part;
+    return part;
+}
+/** Whether a value is a non-null, non-array object. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Remove `//` line and block comments from JSONC text without touching comment
+ * markers that appear inside string literals.
+ */
+function stripComments(source) {
+    let out = "";
+    let inString = false;
+    let escaped = false;
+    let index = 0;
+    while (index < source.length) {
+        let char = source[index];
+        if (inString) {
+            out += char;
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                inString = false;
+            index += 1;
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            out += char;
+            index += 1;
+            continue;
+        }
+        if (char === "/" && source[index + 1] === "/") {
+            index += 2;
+            while (index < source.length && source[index] !== "\n")
+                index += 1;
+            continue;
+        }
+        if (char === "/" && source[index + 1] === "*") {
+            index += 2;
+            while (index < source.length && !(source[index] === "*" && source[index + 1] === "/")) {
+                index += 1;
+            }
+            index += 2;
+            continue;
+        }
+        out += char;
+        index += 1;
+    }
+    return out;
+}
+/**
+ * Remove commas that immediately precede a `}` or `]` (ignoring whitespace),
+ * again leaving string contents untouched — the second half of JSONC leniency.
+ */
+function stripTrailingCommas(source) {
+    let out = "";
+    let inString = false;
+    let escaped = false;
+    for (let index = 0; index < source.length; index++) {
+        let char = source[index];
+        if (inString) {
+            out += char;
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            out += char;
+            continue;
+        }
+        if (char === ",") {
+            let ahead = index + 1;
+            while (ahead < source.length && /\s/.test(source[ahead] ?? ""))
+                ahead += 1;
+            let next = source[ahead];
+            if (next === "}" || next === "]")
+                continue;
+        }
+        out += char;
+    }
+    return out;
+}
+/** Render an unknown thrown value as a one-line message. */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}