@sheetxl/runner 0.8.0-beta.2 → 0.8.0-beta.21

package/LICENSE.md

@@ -1,11 +1,21 @@
-# Repository Licensing
+MIT License
 
-SheetXL contains a mix of open-source and commercially licensed packages. Each package is individually licensed and contains its own license file.
+Copyright (c) 2026-present SheetXL Inc. & Michael T. Ford
 
-For the specific terms and conditions applicable to a package, please see the `LICENSE.md` file located in that package's root directory.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-Generally, packages intended for public distribution (such as CLIs, adapters, and vanilla wrappers) are licensed under the MIT license. All other core packages are proprietary and require a commercial license for use.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-For more details on commercial licensing, please visit our website:
-
-https://www.sheetxl.com/docs/guides/licensing-pricing
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -58,7 +58,7 @@ import Runner, { type RunContext } from '@sheetxl/runner';
 
 export default async function main(ctx: RunContext) {
   const { wb, log, args } = ctx;
-  wb.getSelectedSheet().getRange('A1').setValue(args.region);
+  wb.getWorksheet().getRange('A1').setValue(args.region);
   log('updated value');
 }
 ```

package/node/esm/index.mjs

@@ -1,31 +1,31 @@
 /**
-* @license @sheetxl/runner - SheetXL - Programmatic execution for SheetXL scripts - v0.8.0-beta.2
+* @license @sheetxl/runner - SheetXL - Programmatic execution for SheetXL scripts - v0.8.0-beta.21
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
-* License: The license can be found at https://www.sheetxl.com/license.
+* License: MIT
 */
 import t from "node:path";
 import e from "node:fs";
 import { pathToFileURL as n } from "node:url";
 import { createLogChannels as r, resolveLogTimeout as s } from "@sheetxl/utils";
-var o = Object.defineProperty;
-function i(e, n = "SHEETXL_IN") {
+var i = Object.defineProperty;
+function o(e, n = "SHEETXL_IN") {
 	if (t.isAbsolute(e)) return e;
 	const r = n ? process.env[n] : void 0;
 	return t.resolve(r ?? process.cwd(), e);
 }
 var a = ((t, e) => {
 	let n = {};
-	for (var r in t) o(n, r, {
+	for (var r in t) i(n, r, {
 		get: t[r],
 		enumerable: !0
 	});
-	return e || o(n, Symbol.toStringTag, { value: "Module" }), n;
+	return e || i(n, Symbol.toStringTag, { value: "Module" }), n;
 })({
-	DEFAULT_DESCRIPTION: () => S,
-	classify: () => x,
-	prepare: () => E,
-	toSnippetOffset: () => _
+	DEFAULT_DESCRIPTION: () => v,
+	classify: () => w,
+	prepare: () => T,
+	toSnippetOffset: () => b
 }), c = null;
 function l() {
 	return c || (c = (async () => {
@@ -51,17 +51,17 @@ function p(t) {
 	for (let n = 0; n < t.length; n++) "\n" === t[n] && e++;
 	return e;
 }
-function f(t, e, n) {
+function d(t, e, n) {
 	let r = n.getStart(e);
 	for (const s of n.declarationList.declarations) {
 		const n = s.initializer;
 		if (!n) continue;
-		const o = n.getStart(e);
-		t.copy(r, o), t.add("await ("), t.copy(o, n.end), t.add(")"), r = n.end;
+		const i = n.getStart(e);
+		t.copy(r, i), t.add("await ("), t.copy(i, n.end), t.add(")"), r = n.end;
 	}
 	t.copy(r, n.end), t.terminate();
 }
-var d = class {
+var f = class {
 	constructor(t) {
 		this._code = t, this.spans = [], this._parts = [], this._length = 0;
 	}
@@ -81,8 +81,12 @@ var d = class {
 	toString() {
 		return this._parts.join("");
 	}
-}, m = "await wb?.whenCalculationReady?.(); ";
-function h(t, e) {
+}, m = /* @__PURE__ */ new Set([
+	"log",
+	"warn",
+	"error"
+]), h = "await wb?.whenCalculationReady?.(); ";
+function g(t, e) {
 	const n = e.statements;
 	let r = n.length - 1;
 	for (; r >= 0 && n[r].kind === t.SyntaxKind.EmptyStatement;) r--;
@@ -97,8 +101,8 @@ function h(t, e) {
 		to: s.expression.end
 	};
 	if (t.isFunctionDeclaration(s) && s.body) {
-		const n = t.getModifiers(s) ?? [], o = n.some((e) => e.kind === t.SyntaxKind.ExportKeyword);
-		if (n.some((e) => e.kind === t.SyntaxKind.DefaultKeyword) && !s.name || !o && function(t, e) {
+		const n = t.getModifiers(s) ?? [], i = n.some((e) => e.kind === t.SyntaxKind.ExportKeyword);
+		if (n.some((e) => e.kind === t.SyntaxKind.DefaultKeyword) && !s.name || !i && function(t, e) {
 			let n = -1;
 			for (let r = 0; r < e.statements.length; r++) {
 				const s = e.statements[r];
@@ -109,20 +113,20 @@ function h(t, e) {
 			}
 			return n;
 		}(t, e) === r) {
-			let o = s.getStart(e);
-			for (const e of n) e.kind !== t.SyntaxKind.ExportKeyword && e.kind !== t.SyntaxKind.DefaultKeyword || (o = e.end);
-			for (; o < s.end && /\s/.test(e.text[o]);) o++;
+			let i = s.getStart(e);
+			for (const e of n) e.kind !== t.SyntaxKind.ExportKeyword && e.kind !== t.SyntaxKind.DefaultKeyword || (i = e.end);
+			for (; i < s.end && /\s/.test(e.text[i]);) i++;
 			return {
 				index: r,
-				from: o,
+				from: i,
 				to: s.end
 			};
 		}
 	}
 	return null;
 }
-var y = "const __entry: (ctx: SheetXL.IScript.ScriptContext) => unknown = (", g = (t) => `); ${t} = await __entry(ctx);`;
-async function x(t) {
+var y = "const __entry: (ctx: SheetXL.IScript.ScriptContext) => unknown = (", x = (t) => `); ${t} = await __entry(ctx);`;
+async function w(t) {
 	const e = await u(t);
 	if (!e) return function(t) {
 		return /^\s*export\s+default\b/m.test(t) || /^\s*export\s*\{[^}]*\bas\s+default\b/m.test(t);
@@ -136,11 +140,11 @@ async function x(t) {
 		}
 		return !1;
 	}(n, r) && !function(t, e) {
-		const n = h(t, e);
+		const n = g(t, e);
 		return !!n && e.statements.every((e, r) => r === n.index || !t.isExportAssignment(e) && !t.isExportDeclaration(e) && !(t.canHaveModifiers(e) && t.getModifiers(e)?.some((e) => e.kind === t.SyntaxKind.ExportKeyword)));
 	}(n, r) ? "script" : "snippet";
 }
-var w = 3, S = "Run Snippet", v = (t, e, n = [], r) => {
+var S = 3, v = "Run Snippet", E = (t, e, n = [], r) => {
 	const s = [
 		...n,
 		...r ? [r] : [],
@@ -158,93 +162,103 @@ var w = 3, S = "Run Snippet", v = (t, e, n = [], r) => {
 		bodyStart: s.length
 	};
 };
-async function E(t, e) {
+async function T(t, e) {
 	const n = e?.epilogue ?? "  return __result;", r = await u(t);
 	if (!r) {
-		const e = await l() ? void 0 : "TypeScript is unavailable, so this snippet ran without implicit await or a result value. Install the `typescript` peer dependency to restore them.", { source: r, bodyStart: s } = v(t, n);
+		const e = await l() ? void 0 : "TypeScript is unavailable, so this snippet ran without implicit await or a result value. Install the `typescript` peer dependency to restore them.", { source: r, bodyStart: s } = E(t, n);
 		return {
 			source: r,
 			kind: "verbatim",
-			lineOffset: w,
+			lineOffset: S,
 			spans: [{
 				at: s,
 				from: 0,
 				length: t.length
 			}],
+			expectsValue: !1,
 			warning: e
 		};
 	}
-	const { ts: s, sf: o } = r, i = o.statements, a = function(t, e) {
+	const { ts: s, sf: i } = r, o = i.statements, a = function(t, e) {
 		if (!e.statements[0]) return;
 		const n = t.getLeadingCommentRanges(e.text, 0);
 		if (n?.length) for (let r = n.length - 1; r >= 0; r--) {
 			const s = n[r];
 			if (s.kind !== t.SyntaxKind.MultiLineCommentTrivia) continue;
-			const o = e.text.slice(s.pos, s.end);
-			if (o.startsWith("/**")) return o;
+			const i = e.text.slice(s.pos, s.end);
+			if (i.startsWith("/**")) return i;
 		}
-	}(s, o), c = a ? p(a) + 1 : 0;
-	if (1 === i.length && s.isBlock(i[0])) {
-		const { source: r, bodyStart: s } = v(`  __result = await (
+	}(s, i), c = a ? p(a) + 1 : 0;
+	if (1 === o.length && s.isBlock(o[0])) {
+		const { source: r, bodyStart: s } = E(`  __result = await (
 ${t}\n  );`, n, [], a);
 		return {
 			source: r,
 			kind: "expression",
-			lineOffset: w + c + 1,
+			lineOffset: S + c + 1,
 			spans: [{
 				at: s + 21,
 				from: 0,
 				length: t.length
-			}]
+			}],
+			expectsValue: !0
 		};
 	}
-	const { body: x, spans: S, hoisted: E } = function(t, e, n) {
+	const { body: w, spans: v, hoisted: T, expectsValue: b } = function(t, e, n) {
 		const r = e.text, s = e.statements;
-		let o = -1;
+		let i = -1;
 		for (let e = s.length - 1; e >= 0; e--) if (s[e].kind !== t.SyntaxKind.EmptyStatement) {
-			t.isExpressionStatement(s[e]) && (o = e);
+			t.isExpressionStatement(s[e]) && (i = e);
 			break;
 		}
-		const i = h(t, e), a = [], c = new d(r);
-		let l = 0, u = !1;
-		for (let d = 0; d < s.length; d++) {
-			const h = s[d], x = h.getStart(e);
-			if (c.copy(l, x), l = h.end, t.isImportDeclaration(h) || t.isImportEqualsDeclaration(h)) {
-				const t = r.slice(x, h.end);
-				a.push({
+		const o = g(t, e);
+		let a = !1;
+		if (!o && -1 !== i) {
+			const e = s[i].expression;
+			a = !(t.isCallExpression(e) && t.isIdentifier(e.expression) && m.has(e.expression.text));
+		}
+		const c = [], l = new f(r);
+		let u = 0, w = !1;
+		for (let a = 0; a < s.length; a++) {
+			const f = s[a], m = f.getStart(e);
+			if (l.copy(u, m), u = f.end, t.isImportDeclaration(f) || t.isImportEqualsDeclaration(f)) {
+				const t = r.slice(m, f.end);
+				c.push({
 					text: t,
-					from: x
-				}), c.add("\n".repeat(p(t)));
+					from: m
+				}), l.add("\n".repeat(p(t)));
 				continue;
 			}
-			u && c.add(m), u = !0, i?.index !== d ? t.isVariableStatement(h) ? f(c, e, h) : t.isExpressionStatement(h) ? (c.add(d === o ? `${n} = await (` : "await ("), c.copy(h.expression.getStart(e), h.expression.end), c.add(");")) : (c.copy(x, h.end), c.terminate()) : (c.add(y), c.copy(i.from, i.to), c.add(g(n)));
+			w && l.add(h), w = !0, o?.index !== a ? t.isVariableStatement(f) ? d(l, e, f) : t.isExpressionStatement(f) ? (l.add(a === i ? `${n} = await (` : "await ("), l.copy(f.expression.getStart(e), f.expression.end), l.add(");")) : (l.copy(m, f.end), l.terminate()) : (l.add(y), l.copy(o.from, o.to), l.add(x(n)));
 		}
-		return c.copy(l, r.length), {
-			body: c.toString(),
-			spans: c.spans,
-			hoisted: a
+		return l.copy(u, r.length), {
+			body: l.toString(),
+			spans: l.spans,
+			hoisted: c,
+			expectsValue: a
 		};
-	}(s, o, "__result"), _ = E.map((t) => t.text), b = E.length > 0 ? p(_.join("\n")) + E.length : 0, { source: k, bodyStart: K } = v(x, n, _, a);
-	let D = 0;
-	const R = E.map((t) => {
+	}(s, i, "__result"), _ = T.map((t) => t.text), k = T.length > 0 ? p(_.join("\n")) + T.length : 0, { source: D, bodyStart: K } = E(w, n, _, a);
+	let R = 0;
+	const I = T.map((t) => {
 		const e = {
-			at: D,
+			at: R,
 			from: t.from,
 			length: t.text.length
 		};
-		return D += t.text.length + 1, e;
+		return R += t.text.length + 1, e;
 	});
 	return {
-		source: k,
+		source: D,
 		kind: "statements",
-		lineOffset: w + b + c,
-		spans: [...R, ...S.map((t) => ({
+		lineOffset: S + k + c,
+		spans: [...I, ...v.map((t) => ({
 			...t,
 			at: t.at + K
-		}))]
+		}))],
+		expectsValue: b
 	};
 }
-function _(t, e) {
+function b(t, e) {
 	let n = null;
 	for (const r of t.spans) {
 		if (r.at > e) return null !== n && e < n.at + n.length ? n.from + (e - n.at) : r.from;
@@ -252,7 +266,51 @@ function _(t, e) {
 	}
 	return n ? n.from + Math.min(e - n.at, n.length) : 0;
 }
-async function b(t, e, n = "Runner timed out") {
+var _ = /* @__PURE__ */ new Set(["TS2339", "TS2551"]), k = /* @__PURE__ */ new Set([
+	..._,
+	"TS2304",
+	"TS2552",
+	"TS2448",
+	"TS2588",
+	"TS2531",
+	"TS2532",
+	"TS2533",
+	"TS18047",
+	"TS18048",
+	"TS18049",
+	"TS2349",
+	"TS2351",
+	"TS2721",
+	"TS2722",
+	"TS2723"
+]), D = /on type '(never|\{\})'/;
+function K(t) {
+	return void 0 === t || "TypeError" === t || "ReferenceError" === t;
+}
+async function R(t, e) {
+	try {
+		const n = "snippet" === await w(t) ? await T(t) : null;
+		if ("undefined" === e && !n?.expectsValue) return [];
+		const [{ ScriptCompiler: r }, { getScriptingDeclarations: s }] = await Promise.all([import("@sheetxl/scripting"), import("@sheetxl/sdk")]), { diagnostics: i } = await r.compile({
+			source: n?.source ?? t,
+			ambientTypes: await s(),
+			lenient: !0,
+			disableBundle: !0,
+			disableSourceMap: !0
+		}), o = "threw" === e ? k : _;
+		return i.filter((t) => "error" === t.severity && o.has(t.code) && !(_.has(t.code) && D.test(t.message))).map((t) => ({
+			...t,
+			start: n ? b(n, t.start) : t.start,
+			..."undefined" === e ? {
+				severity: "warning",
+				message: `${t.message} It reads as undefined.`
+			} : {}
+		}));
+	} catch {
+		return [];
+	}
+}
+async function I(t, e, n = "Runner timed out") {
 	if (!e || e <= 0) return t;
 	let r;
 	const s = new Promise((t, s) => r = setTimeout(() => s(new Error(n)), e));
@@ -262,31 +320,31 @@ async function b(t, e, n = "Runner timed out") {
 		clearTimeout(r);
 	}
 }
-var k = null;
-function K() {
-	return k || (k = (async () => {
+var C = null;
+function $() {
+	return C || (C = (async () => {
 		const { register: t } = await import("tsx/esm/api");
 		t({ tsconfig: !1 });
-	})()), k;
+	})()), C;
 }
-var D = "data:text/typescript,", R = "data:text/javascript,", I = null;
-function $() {
-	return I || (I = (async () => {
+var L = "data:text/typescript,", M = "data:text/javascript,", W = null;
+function P() {
+	return W || (W = (async () => {
 		const { registerHooks: e, stripTypeScriptTypes: r } = await import("node:module"), s = r;
 		e({
 			resolve(e, r, s) {
-				const o = r.parentURL;
-				if (o && (o.startsWith(D) || o.startsWith(R))) {
-					const o = n(t.join(process.cwd(), "_inline_.ts")).href;
+				const i = r.parentURL;
+				if (i && (i.startsWith(L) || i.startsWith(M))) {
+					const i = n(t.join(process.cwd(), "_inline_.ts")).href;
 					return s(e, {
 						...r,
-						parentURL: o
+						parentURL: i
 					});
 				}
 				return s(e, r);
 			},
 			load(t, e, n) {
-				if (t.startsWith(D)) {
+				if (t.startsWith(L)) {
 					const e = decodeURIComponent(t.slice(21)), n = process.emitWarning;
 					let r;
 					process.emitWarning = () => {};
@@ -304,16 +362,16 @@ function $() {
 				return n(t, e);
 			}
 		});
-	})()), I;
+	})()), W;
 }
-async function C(e) {
+async function A(e) {
 	const r = "string" == typeof (s = e) ? s.startsWith("file:") ? s : n(t.resolve(process.cwd(), s)).href : s.href;
 	var s;
-	const o = t.extname(new URL(r).pathname).toLowerCase();
-	return ".ts" !== o && ".tsx" !== o || await K(), import(r);
+	const i = t.extname(new URL(r).pathname).toLowerCase();
+	return ".ts" !== i && ".tsx" !== i || await $(), import(r);
 }
-async function L(t, e, n) {
-	const s = n.notifier ?? (await import("@sheetxl/sdk")).Notifier, o = r({
+async function U(t, e, n) {
+	const s = n.notifier ?? (await import("@sheetxl/sdk")).Notifier, i = r({
 		debug: (t) => s.debug(t),
 		log: (t) => s.log(t),
 		info: (t) => s.log(t),
@@ -328,65 +386,68 @@ async function L(t, e, n) {
 				_: []
 			},
 			wb: t,
-			log: o.log,
-			warn: o.warn,
-			error: o.error
+			log: i.log,
+			warn: i.warn,
+			error: i.error
 		},
-		channels: o,
+		channels: i,
 		notifier: s
 	};
 }
-var T = async (n, r, o) => {
-	const i = o.target, a = Array.isArray(i) ? i : [i], c = await Promise.all(a.map((n) => (async (n, r = {}) => {
+var j = async (n, r, i) => {
+	const o = i.target, a = Array.isArray(o) ? o : [o], c = await Promise.all(a.map((n) => (async (n, r = {}) => {
 		let s = null;
-		const o = (t, e) => {
+		const i = (t, e) => {
 			let n = t?.default;
 			if (n && "function" != typeof n && "function" == typeof n.default && (n = n.default), "function" != typeof n) throw new Error(`Script '${e}' has no runnable entry: export a default function, e.g. \`export default function main(ctx) { … }\`.`);
 			return n;
 		};
 		if ("function" == typeof n) s = n;
 		else if ("string" == typeof n || n instanceof URL) {
-			let i = null;
-			if ("string" != typeof n || /^[a-z]+:\/\//i.test(n)) i = await C(n);
+			let o = null;
+			if ("string" != typeof n || /^[a-z]+:\/\//i.test(n)) o = await A(n);
 			else {
 				const s = t.resolve(r.cwd ?? process.cwd(), n);
 				if (!e.existsSync(s)) throw new Error(`Script not found: ${s}`);
-				e.accessSync(s, e.constants.R_OK), i = await C(s);
+				e.accessSync(s, e.constants.R_OK), o = await A(s);
 			}
-			s = o(i, String(n));
+			s = i(o, String(n));
 		} else if ("code" in n) {
 			const t = n.filename ?? "inline.ts";
 			let e, r = null;
-			t.endsWith(".ts") || t.endsWith(".tsx") ? (await K(), await $(), e = `${D}${encodeURIComponent(n.code)}`, r = await import(e)) : (await $(), e = `${R}${encodeURIComponent(n.code)}`, r = await import(e)), s = o(r, t);
+			t.endsWith(".ts") || t.endsWith(".tsx") ? (await $(), await P(), e = `${L}${encodeURIComponent(n.code)}`, r = await import(e)) : (await P(), e = `${M}${encodeURIComponent(n.code)}`, r = await import(e)), s = i(r, t);
 		} else {
 			if (!("runner" in n)) throw new Error("Invalid run target specified.");
 			s = n.runner;
 		}
 		return s;
-	})(n, o))), l = Date.now();
-	let u, p = n, f = null;
-	const d = c.length;
-	for (let t = 0; t < d; t++) {
-		const e = c[t], { ctx: n, channels: i, notifier: a } = await L(p, r, o);
-		f = a;
+	})(n, i))), l = Date.now();
+	let u, p = n, d = null;
+	const f = c.length;
+	for (let t = 0; t < f; t++) {
+		const e = c[t], { ctx: n, channels: o, notifier: a } = await U(p, r, i);
+		d = a;
 		const l = Date.now();
 		let m;
-		const h = p, y = () => Promise.resolve().then(() => e(n));
+		const h = p, g = (t) => Promise.resolve().then(() => e(t));
 		try {
-			m = await b(null !== h ? Promise.resolve(h.doBatch(y, "Run Script")) : y(), o.timeoutMs, "Runner timed out");
+			m = await I(null !== h ? Promise.resolve(h.doBatch((t, e) => g({
+				...n,
+				wb: e
+			}), "Run Script")) : g(n), i.timeoutMs, "Runner timed out");
 		} finally {
-			await i.flush({ timeoutMs: s(o.logTimeoutMs) });
+			await o.flush({ timeoutMs: s(i.logTimeoutMs) });
 		}
-		const g = Date.now();
-		u = m, null != m && m.isIWorkbook && (p = m), a.debug(`Run ${1 === d ? "" : `${t + 1}/${d} `}completed in ${g - l} ms.`);
+		const y = Date.now();
+		u = m, null != m && m.isIWorkbook && (p = m), a.debug(`Run ${1 === f ? "" : `${t + 1}/${f} `}completed in ${y - l} ms.`);
 	}
-	if (d > 1 && f) {
+	if (f > 1 && d) {
 		const t = Date.now();
-		f.debug(`All runs completed in ${t - l} ms.`);
+		d.debug(`All runs completed in ${t - l} ms.`);
 	}
 	return u;
-}, W = { run: async (t, e, n) => {
+}, O = { run: async (t, e, n) => {
 	const { withScriptRuntime: r } = await import("@sheetxl/sdk");
-	return r(() => T(t, e, n));
+	return r(() => j(t, e, n));
 } };
-export { a as Snippet, W as default, i as resolvePath };
+export { a as Snippet, O as default, R as diagnoseRun, K as isExplainable, o as resolvePath };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sheetxl/runner",
   "description": "SheetXL - Programmatic execution for SheetXL scripts",
-  "version": "0.8.0-beta.2",
-  "license": "SEE LICENSE IN <LICENSE>",
+  "version": "0.8.0-beta.21",
+  "license": "MIT",
   "type": "module",
   "exports": {
     ".": {
@@ -36,18 +36,23 @@
     "runner"
   ],
   "dependencies": {
-    "@sheetxl/io": "^0.8.0-beta.2",
-    "@sheetxl/primitives": "^0.8.0-beta.2",
-    "@sheetxl/scripting": "^0.8.0-beta.2",
-    "@sheetxl/sdk": "^0.8.0-beta.2",
-    "@sheetxl/utils": "^0.8.0-beta.2"
+    "@sheetxl/io": "^0.8.0-beta.21",
+    "@sheetxl/primitives": "^0.8.0-beta.21",
+    "@sheetxl/scripting": "^0.8.0-beta.21",
+    "@sheetxl/sdk": "^0.8.0-beta.21",
+    "@sheetxl/utils": "^0.8.0-beta.21",
+    "tsx": "^4.23.15"
   },
   "peerDependencies": {
     "typescript": "^5.9.0 || ^6.0.0"
   },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@types/node": "^26.1.2",
-    "tsx": "^4.23.1",
+    "@types/node": "^26.6.4",
     "typescript": "^5.9.0 || ^6.0.0"
   }
 }

package/types/src/RunDiagnosis.d.ts

@@ -0,0 +1,33 @@
+import { Diagnostic } from '@sheetxl/scripting';
+/**
+ * What a run did that a type check may explain: it threw, or a snippet's final expression came
+ * back `undefined`.
+ *
+ * @remarks
+ * `undefined` is a symptom because the SheetXL API never returns it - `null` is the empty answer.
+ * A read that produced `undefined` read something that is not there.
+ */
+export type RunSymptom = 'threw' | 'undefined';
+/**
+ * Whether a failure is one a type check can explain, by the error's `name`. A failure with no
+ * name (a thrown string, an error that crossed a wire as its message) is checked too.
+ */
+export declare function isExplainable(errorName: string | undefined): boolean;
+/**
+ * Type-checks the source of a run that has already gone wrong, and returns the findings that can
+ * explain it.
+ *
+ * @remarks
+ * A run is never type-checked before it executes: the types are for discovery, not enforcement,
+ * and most of what a strict check reports about code written to run once (an unannotated `[]`,
+ * `catch (e)`, a field added to `{}`) runs correctly. A failed run leaves nothing behind, so
+ * running first costs nothing, and the check is paid only by a run with a symptom.
+ *
+ * The one implementation behind `sheetxl -e` and the MCP `run` tool, so both answer alike.
+ *
+ * Positions are in `source` as given - a snippet is checked in its wrapper and mapped back.
+ * A `threw` finding is an error; an `undefined` one is a warning, as the run completed.
+ * Never throws: a diagnosis that fails must not replace the failure it was diagnosing.
+ */
+export declare function diagnoseRun(source: string, symptom: RunSymptom): Promise<Diagnostic[]>;
+//# sourceMappingURL=RunDiagnosis.d.ts.map

package/types/src/Snippet.d.ts

@@ -83,6 +83,12 @@ export interface Prepared {
     lineOffset: number;
     /** Where the author's text sits within {@link source}, in source order. */
     spans: Span[];
+    /**
+     * Whether the snippet ends in an expression whose value is its answer — not a statement, not a
+     * call to `log`/`warn`/`error`, and not an entry function, which may return nothing as a script
+     * may. Such a snippet answering `undefined` read something that is not there.
+     */
+    expectsValue: boolean;
     /**
      * Set only when the contract could not be honored — no implicit await, no result. Callers should
      * surface it; a snippet quietly returning `undefined` is worse than one that failed.

package/types/src/index.d.ts

@@ -1,5 +1,6 @@
 export * from './Types';
 export * from './RunUtils';
 export * as Snippet from './Snippet';
+export * from './RunDiagnosis';
 export { default } from './Runner';
 //# sourceMappingURL=index.d.ts.map