@esportsplus/typescript 0.31.0 → 0.32.0

package/build/probe/kernel/types.d.ts

@@ -0,0 +1,134 @@
+import type * as ts from '../adapter.js';
+export type FunctionLike = ts.FunctionDeclaration | ts.FunctionExpression | ts.ArrowFunction | ts.MethodDeclaration | ts.GetAccessorDeclaration | ts.SetAccessorDeclaration | ts.ConstructorDeclaration;
+type FunctionInfo = {
+    readonly id: string;
+    readonly node: FunctionLike;
+    readonly sourceFile: ts.SourceFile;
+    readonly name: string;
+    readonly fileName: string;
+    readonly pos: number;
+};
+type Summary<V> = {
+    readonly value: V;
+    readonly fromCallbacks: ReadonlySet<number>;
+};
+export type Dispatch = 'optimist' | 'pessimist';
+type CalleeResolution = {
+    readonly targets: ReadonlyArray<FunctionInfo>;
+    readonly overlay: OverlayLookup | undefined;
+    readonly functionArgs: ReadonlyMap<number, ReadonlyArray<FunctionInfo>>;
+    readonly unresolved: boolean;
+};
+type OverlayLookup = {
+    readonly pkg: string;
+    readonly symbol: string;
+    readonly entry: unknown;
+};
+type TransferContext<V> = {
+    readonly checker: ts.TypeChecker;
+    readonly fn: FunctionInfo;
+    readonly dispatch: Dispatch;
+    readonly channelConfig: unknown;
+    readonly sinks: ReadonlyArray<SinkConfig>;
+    summaryOf(fn: FunctionInfo): Summary<V>;
+    resolveCall(call: ts.CallExpression | ts.NewExpression): CalleeResolution;
+    resolveCallFor(channel: string, call: ts.CallExpression | ts.NewExpression): CalleeResolution;
+    peerSummaryValue(channel: string, fnId: string): unknown;
+};
+type DiagnoseContext<V> = {
+    readonly checker: ts.TypeChecker;
+    readonly fn: FunctionInfo;
+    readonly dispatch: Dispatch;
+    readonly channelConfig: unknown;
+    readonly sinks: ReadonlyArray<SinkConfig>;
+    readonly isBoundary: boolean;
+    summaryOf(fn: FunctionInfo): Summary<V>;
+    resolveCall(call: ts.CallExpression | ts.NewExpression): CalleeResolution;
+    resolveCallFor(channel: string, call: ts.CallExpression | ts.NewExpression): CalleeResolution;
+    peerSummaryValue(channel: string, fnId: string): unknown;
+    pathToBoundary(fn: FunctionInfo): ReadonlyArray<FunctionInfo>;
+    roots(): ReadonlyArray<FunctionInfo>;
+};
+type Channel<V> = {
+    readonly name: string;
+    readonly dependsOn?: ReadonlyArray<string>;
+    bottom(): V;
+    equals(a: V, b: V): boolean;
+    widen(prev: V, next: V, round: number): V;
+    transfer(ctx: TransferContext<V>): Summary<V>;
+    diagnose(ctx: DiagnoseContext<V>): ReadonlyArray<Diagnostic>;
+};
+type SourceLocation = {
+    readonly fileName: string;
+    readonly line: number;
+    readonly column: number;
+    readonly pos: number;
+    readonly end: number;
+};
+type DiagnosticRelated = {
+    readonly message: string;
+    readonly location: SourceLocation;
+};
+type DiagnosticEdit = {
+    readonly fileName: string;
+    readonly pos: number;
+    readonly end: number;
+    readonly newText: string;
+};
+type DiagnosticFix = {
+    readonly title: string;
+    readonly edits: ReadonlyArray<DiagnosticEdit>;
+};
+type Diagnostic = {
+    readonly channel: string;
+    readonly message: string;
+    readonly location: SourceLocation;
+    readonly related: ReadonlyArray<DiagnosticRelated>;
+    readonly fixes?: ReadonlyArray<DiagnosticFix>;
+};
+type HandlerBoundary = {
+    readonly callee: string;
+    readonly callbackArgs: ReadonlyArray<number>;
+};
+type SinkConfig = {
+    readonly callee: string;
+    readonly absorbs: ReadonlyArray<string> | undefined;
+};
+type ChannelConfig = {
+    readonly enabled: boolean;
+    readonly dispatch: Dispatch;
+    readonly options: unknown;
+};
+type AnalyzeConfig = {
+    readonly projectRoot: string;
+    readonly tsconfigPath: string;
+    readonly entryPoints: ReadonlyArray<string>;
+    readonly handlerBoundaries: ReadonlyArray<HandlerBoundary>;
+    readonly sinks: ReadonlyArray<SinkConfig>;
+    readonly presets: ReadonlyArray<string>;
+    readonly overlays: ReadonlyArray<string>;
+    readonly channels: Readonly<Record<string, ChannelConfig>>;
+    readonly failOnFindings: boolean;
+    readonly severity: 'error' | 'warning';
+};
+type OverlaySet = {
+    lookup(symbol: ts.Symbol, channel: string): OverlayLookup | undefined;
+};
+type CallGraph = {
+    reachedFunctions(): ReadonlyArray<FunctionInfo>;
+    boundaries(): ReadonlySet<string>;
+    calleesOf(fn: FunctionInfo): ReadonlyArray<FunctionInfo>;
+    resolveCall(call: ts.CallExpression | ts.NewExpression, channel: string): CalleeResolution;
+    resolveFunctionValue(expr: ts.Expression): ReadonlyArray<FunctionInfo>;
+};
+type SummaryStore<V> = {
+    get(id: string): Summary<V>;
+};
+type Analysis = {
+    readonly program: ts.Program;
+    readonly checker: ts.TypeChecker;
+    readonly config: AnalyzeConfig;
+    readonly overlays: OverlaySet;
+    readonly graph: CallGraph;
+};
+export { type Analysis, type AnalyzeConfig, type CallGraph, type CalleeResolution, type Channel, type ChannelConfig, type DiagnoseContext, type Diagnostic, type DiagnosticEdit, type DiagnosticFix, type DiagnosticRelated, type FunctionInfo, type HandlerBoundary, type OverlayLookup, type OverlaySet, type SinkConfig, type SourceLocation, type Summary, type SummaryStore, type TransferContext };

package/build/probe/kernel/types.js

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

package/build/probe/overlay/base/async.jsonc

@@ -0,0 +1,13 @@
+// Base async-channel overlay bundle. The "async" section maps a lib symbol (see
+// load.ts overlayKey) to an async entry. Cancellable leaves accept an
+// `AbortSignal` and should be forwarded any signal the calling function holds:
+//   { "cancellable": true }   - awaiting this without the held signal is a finding
+{
+  "overlay": {
+    "async": {
+      "lib.dom": {
+        "fetch": { "cancellable": true }
+      }
+    }
+  }
+}

package/build/probe/overlay/base/exceptions.jsonc

@@ -0,0 +1,54 @@
+// Base exceptions-channel overlay. Top-level keys are lib sections; each section
+// maps an overlay key (see load.ts overlayKey) to an exceptions entry:
+//   { "exceptions": ["SyntaxError"] }   - the error types the leaf may throw
+//   { "exceptionsFromCallbacks": [0] }  - inherits whatever the arg at that index throws
+//   { "exceptions": [] }                - modeled as non-throwing (so it is not logged)
+// This whole file is the "exceptions" channel section (channel is implicit here).
+{
+  "lib.es5": {
+    "JSON.parse": { "exceptions": ["SyntaxError"] },
+    "JSON.stringify": { "exceptions": [] },
+
+    "decodeURI": { "exceptions": ["URIError"] },
+    "decodeURIComponent": { "exceptions": ["URIError"] },
+    "encodeURI": { "exceptions": ["URIError"] },
+    "encodeURIComponent": { "exceptions": ["URIError"] },
+
+    "RegExp": { "exceptions": ["SyntaxError"] },
+
+    "Number.parseInt": { "exceptions": [] },
+    "Number.parseFloat": { "exceptions": [] },
+    "parseInt": { "exceptions": [] },
+    "parseFloat": { "exceptions": [] },
+
+    "Array#map": { "exceptionsFromCallbacks": [0] },
+    "Array#forEach": { "exceptionsFromCallbacks": [0] },
+    "Array#filter": { "exceptionsFromCallbacks": [0] },
+    "Array#reduce": { "exceptionsFromCallbacks": [0] },
+    "Array#reduceRight": { "exceptionsFromCallbacks": [0] },
+    "Array#some": { "exceptionsFromCallbacks": [0] },
+    "Array#every": { "exceptionsFromCallbacks": [0] },
+    "Array#find": { "exceptionsFromCallbacks": [0] },
+    "Array#findIndex": { "exceptionsFromCallbacks": [0] },
+    "Array#sort": { "exceptionsFromCallbacks": [0] }
+  },
+
+  "lib.es2015": {
+    "Map#forEach": { "exceptionsFromCallbacks": [0] },
+    "Set#forEach": { "exceptionsFromCallbacks": [0] }
+  },
+
+  "lib.es2019": {
+    "Array#flatMap": { "exceptionsFromCallbacks": [0] }
+  },
+
+  "lib.es2020": {
+    "BigInt": { "exceptions": ["RangeError", "SyntaxError", "TypeError"] }
+  },
+
+  "lib.dom": {
+    "URL": { "exceptions": ["TypeError"] },
+    "URLSearchParams": { "exceptions": ["TypeError"] },
+    "structuredClone": { "exceptions": ["DataCloneError"] }
+  }
+}

package/build/probe/overlay/base/resources.jsonc

@@ -0,0 +1,57 @@
+// Base resources-channel overlay. A BUNDLE file: the `overlay.resources` section
+// maps lib/module sections to an overlay key (see load.ts overlayKey) to a
+// resources entry:
+//   { "acquires": "Interval", "releasedBy": "clearInterval" }   - free-function release
+//   { "acquires": "FileHandle", "releasedBy": "#close" }        - method release on the value
+//   { "acquires": "Listener", "releasedBy": "removeEventListener", "pairKey": [0, 1] }
+//                                                               - receiver-keyed pair release
+//   { "acquires": "AbortController", "informational": true }    - modeled, not obligation-bearing
+{
+    "overlay": {
+        "resources": {
+            "lib.dom": {
+                "setInterval": { "acquires": "Interval", "releasedBy": "clearInterval" },
+                "setTimeout": { "acquires": "Timeout", "releasedBy": "clearTimeout" },
+
+                "EventTarget#addEventListener": { "acquires": "Listener", "releasedBy": "removeEventListener", "pairKey": [0, 1] },
+                "Element#addEventListener": { "acquires": "Listener", "releasedBy": "removeEventListener", "pairKey": [0, 1] },
+                "HTMLElement#addEventListener": { "acquires": "Listener", "releasedBy": "removeEventListener", "pairKey": [0, 1] },
+                "Window#addEventListener": { "acquires": "Listener", "releasedBy": "removeEventListener", "pairKey": [0, 1] },
+                "Document#addEventListener": { "acquires": "Listener", "releasedBy": "removeEventListener", "pairKey": [0, 1] },
+                "AbortSignal#addEventListener": { "acquires": "Listener", "releasedBy": "removeEventListener", "pairKey": [0, 1] },
+
+                "ResizeObserver": { "acquires": "ResizeObserver", "releasedBy": "#disconnect" },
+                "MutationObserver": { "acquires": "MutationObserver", "releasedBy": "#disconnect" },
+                "WebSocket": { "acquires": "WebSocket", "releasedBy": "#close" },
+                "AbortController": { "acquires": "AbortController", "informational": true }
+            },
+
+            "node:timers": {
+                "setInterval": { "acquires": "Interval", "releasedBy": "clearInterval" },
+                "setTimeout": { "acquires": "Timeout", "releasedBy": "clearTimeout" }
+            },
+
+            "node:fs/promises": {
+                "open": { "acquires": "FileHandle", "releasedBy": "#close" }
+            },
+
+            "node:fs": {
+                "createReadStream": { "acquires": "ReadStream", "releasedBy": "#destroy" },
+                "createWriteStream": { "acquires": "WriteStream", "releasedBy": "#destroy" }
+            },
+
+            "node:worker_threads": {
+                "Worker": { "acquires": "Worker", "releasedBy": "#terminate" }
+            },
+
+            "node:net": {
+                "Socket": { "acquires": "Socket", "releasedBy": "#destroy" },
+                "Server#listen": { "acquires": "Server", "releasedBy": "#close" }
+            },
+
+            "node:http": {
+                "Server#listen": { "acquires": "Server", "releasedBy": "#close" }
+            }
+        }
+    }
+}

package/build/probe/overlay/load.d.ts

@@ -0,0 +1,18 @@
+import type { HandlerBoundary, OverlaySet, AnalyzeConfig } from '../kernel/types.js';
+type SectionTable = Map<string, unknown>;
+type ChannelTable = Map<string, SectionTable>;
+type MergedOverlay = {
+    readonly channels: ReadonlyMap<string, ChannelTable>;
+    readonly boundaries: ReadonlyArray<HandlerBoundary>;
+    entry(channel: string, section: string, key: string): unknown;
+};
+type LoadedOverlays = OverlaySet & {
+    boundariesFromPresets(): ReadonlyArray<HandlerBoundary>;
+};
+declare function mergeOverlayData(files: ReadonlyArray<{
+    name: string;
+    text: string;
+}>): MergedOverlay;
+declare function overlayKey(parentName: string | undefined, memberName: string, isNamespace: boolean): string;
+declare function loadOverlays(config: AnalyzeConfig): LoadedOverlays;
+export { loadOverlays, mergeOverlayData, overlayKey, type LoadedOverlays, type MergedOverlay };

package/build/probe/overlay/load.js

@@ -0,0 +1,302 @@
+import * as NodeFS from 'node:fs';
+import * as NodePath from 'node:path';
+import * as NodeURL from 'node:url';
+import * as ts from '../adapter.js';
+import { stripJsonc } from '../../jsonc.js';
+const KNOWN_NAMESPACES = new Set([
+    'JSON',
+    'Math',
+    'Object',
+    'Reflect',
+    'Number',
+    'Console',
+    'console',
+]);
+function legacyStripJsonc(text) {
+    let out = '';
+    let i = 0;
+    const n = text.length;
+    let inString = false;
+    let quote = '';
+    while (i < n) {
+        const ch = text[i];
+        const next = i + 1 < n ? text[i + 1] : '';
+        if (inString) {
+            out += ch;
+            if (ch === '\\') {
+                out += next;
+                i += 2;
+                continue;
+            }
+            if (ch === quote) {
+                inString = false;
+            }
+            i += 1;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inString = true;
+            quote = ch;
+            out += ch;
+            i += 1;
+            continue;
+        }
+        if (ch === '/' && next === '/') {
+            while (i < n && text[i] !== '\n') {
+                i += 1;
+            }
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            i += 2;
+            while (i < n && !(text[i] === '*' && text[i + 1] === '/')) {
+                i += 1;
+            }
+            i += 2;
+            continue;
+        }
+        out += ch;
+        i += 1;
+    }
+    return out.replace(/,(\s*[}\]])/g, '$1');
+}
+void legacyStripJsonc;
+function parseJsonc(name, text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stripJsonc(text));
+    }
+    catch (error) {
+        throw new Error(`analyze overlay: invalid JSONC in ${name}: ${error.message}`, {
+            cause: error,
+        });
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        Array.isArray(parsed)) {
+        throw new Error(`analyze overlay: ${name} must be a JSON object`);
+    }
+    return parsed;
+}
+function isSectionMap(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function mergeSections(into, sections) {
+    for (const [section, keys] of Object.entries(sections)) {
+        if (!isSectionMap(keys)) {
+            continue;
+        }
+        let table = into.get(section);
+        if (!table) {
+            table = new Map();
+            into.set(section, table);
+        }
+        for (const [key, entry] of Object.entries(keys)) {
+            table.set(key, entry);
+        }
+    }
+}
+function readBoundaries(name, raw) {
+    if (raw === undefined) {
+        return [];
+    }
+    if (!Array.isArray(raw)) {
+        throw new Error(`analyze overlay: ${name} handlerBoundaries must be an array`);
+    }
+    return raw.map((item, index) => {
+        if (typeof item !== 'object' || item === null) {
+            throw new Error(`analyze overlay: ${name} handlerBoundaries[${index}] must be an object`);
+        }
+        const obj = item;
+        const callee = obj['callee'];
+        const callbackArgs = obj['callbackArgs'];
+        if (typeof callee !== 'string') {
+            throw new Error(`analyze overlay: ${name} handlerBoundaries[${index}].callee must be a string`);
+        }
+        if (!Array.isArray(callbackArgs) ||
+            callbackArgs.some((v) => typeof v !== 'number' || !Number.isInteger(v))) {
+            throw new Error(`analyze overlay: ${name} handlerBoundaries[${index}].callbackArgs must be an array of integers`);
+        }
+        return { callee, callbackArgs: callbackArgs };
+    });
+}
+function mergeOverlayData(files) {
+    return mergeParsedOverlayData(files.map((file) => ({
+        name: file.name,
+        root: parseJsonc(file.name, file.text),
+    })));
+}
+function mergeParsedOverlayData(files) {
+    const channels = new Map();
+    const boundaries = [];
+    const channelFor = (channel) => {
+        let table = channels.get(channel);
+        if (!table) {
+            table = new Map();
+            channels.set(channel, table);
+        }
+        return table;
+    };
+    for (const file of files) {
+        const root = file.root;
+        const isBundle = 'overlay' in root || 'handlerBoundaries' in root;
+        if (isBundle) {
+            boundaries.push(...readBoundaries(file.name, root['handlerBoundaries']));
+            const overlay = root['overlay'];
+            if (overlay !== undefined) {
+                if (!isSectionMap(overlay)) {
+                    throw new Error(`analyze overlay: ${file.name} overlay must be an object`);
+                }
+                for (const [channel, sections] of Object.entries(overlay)) {
+                    if (isSectionMap(sections)) {
+                        mergeSections(channelFor(channel), sections);
+                    }
+                }
+            }
+        }
+        else {
+            mergeSections(channelFor('exceptions'), root);
+        }
+    }
+    return {
+        channels,
+        boundaries,
+        entry(channel, section, key) {
+            return channels.get(channel)?.get(section)?.get(key);
+        },
+    };
+}
+function overlayKey(parentName, memberName, isNamespace) {
+    if (!parentName) {
+        return memberName;
+    }
+    return isNamespace
+        ? `${parentName}.${memberName}`
+        : `${parentName}#${memberName}`;
+}
+function stripConstructor(name) {
+    return name.endsWith('Constructor')
+        ? name.slice(0, -'Constructor'.length)
+        : name;
+}
+function declaredParentName(symbol) {
+    for (const decl of ts.symbolDeclarations(symbol)) {
+        const parent = decl.parent;
+        if (parent &&
+            (ts.isInterfaceDeclaration(parent) || ts.isClassDeclaration(parent))) {
+            return parent.name?.text;
+        }
+    }
+    return undefined;
+}
+function sourceHint(symbol) {
+    for (const decl of ts.symbolDeclarations(symbol)) {
+        const file = decl.getSourceFile().fileName;
+        const base = NodePath.basename(file);
+        const libMatch = /^(lib(?:\.[a-z0-9]+){1,})\.d\.ts$/.exec(base);
+        if (libMatch) {
+            const parts = libMatch[1].split('.');
+            return { kind: 'lib', section: parts.slice(0, 2).join('.') };
+        }
+        const normalized = file.replace(/\\/g, '/');
+        if (normalized.includes('@types/node/') ||
+            normalized.includes('/node_modules/node/')) {
+            return {
+                kind: 'node',
+                section: `node:${base.replace(/\.d\.ts$/, '')}`,
+            };
+        }
+    }
+    return { kind: 'other', section: undefined };
+}
+function keyFor(symbol) {
+    const parent = declaredParentName(symbol);
+    const stripped = parent ? stripConstructor(parent) : undefined;
+    const isNamespace = stripped ? KNOWN_NAMESPACES.has(stripped) : false;
+    return overlayKey(stripped, symbol.name, isNamespace);
+}
+function findInSections(channel, key, accept, preferred) {
+    if (preferred) {
+        const table = channel.get(preferred);
+        if (table && table.has(key)) {
+            return { pkg: preferred, symbol: key, entry: table.get(key) };
+        }
+    }
+    for (const [section, table] of channel) {
+        if (section === preferred || !accept(section)) {
+            continue;
+        }
+        if (table.has(key)) {
+            return { pkg: section, symbol: key, entry: table.get(key) };
+        }
+    }
+    return undefined;
+}
+const HERE = NodePath.dirname(NodeURL.fileURLToPath(import.meta.url));
+const shippedOverlayCache = new Map();
+const userOverlayCache = new Map();
+function readShippedOverlay(file) {
+    let cached = shippedOverlayCache.get(file);
+    if (!cached) {
+        cached = {
+            name: file,
+            root: parseJsonc(file, NodeFS.readFileSync(file, 'utf8')),
+        };
+        shippedOverlayCache.set(file, cached);
+    }
+    return cached;
+}
+function readUserOverlay(file) {
+    const mtimeMs = NodeFS.statSync(file).mtimeMs;
+    const cached = userOverlayCache.get(file);
+    if (!cached || cached.mtimeMs !== mtimeMs) {
+        const fresh = {
+            name: file,
+            root: parseJsonc(file, NodeFS.readFileSync(file, 'utf8')),
+        };
+        userOverlayCache.set(file, { mtimeMs, file: fresh });
+        return fresh;
+    }
+    return cached.file;
+}
+function loadOverlays(config) {
+    const files = [];
+    files.push(readShippedOverlay(NodePath.join(HERE, 'base', 'async.jsonc')));
+    files.push(readShippedOverlay(NodePath.join(HERE, 'base', 'exceptions.jsonc')));
+    files.push(readShippedOverlay(NodePath.join(HERE, 'base', 'resources.jsonc')));
+    for (const preset of config.presets) {
+        const presetPath = NodePath.join(HERE, 'presets', `${preset}.jsonc`);
+        if (!NodeFS.existsSync(presetPath)) {
+            throw new Error(`analyze overlay: unknown preset "${preset}" (no file at ${presetPath})`);
+        }
+        files.push(readShippedOverlay(presetPath));
+    }
+    for (const overlay of config.overlays) {
+        if (!NodeFS.existsSync(overlay)) {
+            throw new Error(`analyze overlay: overlay file not found: ${overlay}`);
+        }
+        files.push(readUserOverlay(overlay));
+    }
+    const merged = mergeParsedOverlayData(files);
+    return {
+        boundariesFromPresets() {
+            return merged.boundaries;
+        },
+        lookup(symbol, channel) {
+            const table = merged.channels.get(channel);
+            if (!table) {
+                return undefined;
+            }
+            const key = keyFor(symbol);
+            const hint = sourceHint(symbol);
+            if (hint.kind === 'lib') {
+                return findInSections(table, key, (s) => s.startsWith('lib.'), hint.section);
+            }
+            if (hint.kind === 'node') {
+                return findInSections(table, key, (s) => s.startsWith('node:'), hint.section);
+            }
+            return findInSections(table, key, (s) => !s.startsWith('lib.'), undefined);
+        },
+    };
+}
+export { loadOverlays, mergeOverlayData, overlayKey };

package/build/probe/overlay/presets/express.jsonc

@@ -0,0 +1,25 @@
+// Express preset bundle. `handlerBoundaries` promote route callbacks to
+// analysis boundaries (loadOverlays exposes them via boundariesFromPresets()).
+// `overlay` follows the channel -> section -> key shape.
+{
+  "handlerBoundaries": [
+    { "callee": "express.Router#get", "callbackArgs": [1] },
+    { "callee": "express.Router#post", "callbackArgs": [1] },
+    { "callee": "express.Router#put", "callbackArgs": [1] },
+    { "callee": "express.Router#patch", "callbackArgs": [1] },
+    { "callee": "express.Router#delete", "callbackArgs": [1] },
+    { "callee": "express.Router#all", "callbackArgs": [1] },
+    { "callee": "express.Router#use", "callbackArgs": [0, 1] },
+    { "callee": "express.Application#get", "callbackArgs": [1] },
+    { "callee": "express.Application#post", "callbackArgs": [1] },
+    { "callee": "express.Application#use", "callbackArgs": [0, 1] }
+  ],
+  "overlay": {
+    "exceptions": {
+      "express": {
+        "Response#json": { "exceptions": ["TypeError"] },
+        "Response#sendFile": { "exceptions": ["TypeError"] }
+      }
+    }
+  }
+}

package/build/probe/overlay/presets/node.jsonc

@@ -0,0 +1,17 @@
+// Node preset bundle. `overlay` is keyed by channel, then section (module),
+// then overlay key. A couple of node:fs / node:path throwers prove the shape.
+{
+  "overlay": {
+    "exceptions": {
+      "node:fs": {
+        "readFileSync": { "exceptions": ["Error"] },
+        "writeFileSync": { "exceptions": ["Error"] },
+        "mkdirSync": { "exceptions": ["Error"] }
+      },
+      "node:path": {
+        "relative": { "exceptions": ["TypeError"] },
+        "resolve": { "exceptions": ["TypeError"] }
+      }
+    }
+  }
+}

package/build/probe/resources/channel.d.ts

@@ -0,0 +1,4 @@
+import type { Channel } from '../kernel/types.js';
+import { type ResourcesValue } from './value.js';
+declare const createResourcesChannel: (channelConfig: unknown, onDegrade?: (message: string) => void) => Channel<ResourcesValue>;
+export { createResourcesChannel };