@sheetxl/runner 0.8.0-beta.1 → 0.8.0-beta.10

package/README.md

@@ -19,7 +19,19 @@ npm i -D @sheetxl/runner
 ## Using  the runner
 
 ``` ts
-export type Runner = (workbook: IWorkbook, target: RunTarget | RunTarget[], options?: RunOptions) => Promise<void>;
+export type Runner = (workbook: IWorkbook | null, args: ArgV | undefined, options: RunOptions) => Promise<IWorkbook | any | void>;
+```
+
+The two data inputs are positional — the workbook and the args. Everything else is host wiring and
+lives in `RunOptions`, `target` included.
+
+`run` hands back whatever the script returned: a tally, a range, nothing. A returned `IWorkbook` is
+also the workbook the run ended on — the one to write for `--save`/`--out` — so a host that needs it
+reads it off the result:
+
+```ts
+const result = await Runner.run(wb, args, { target: 'scripts/transform.ts' });
+const ended = (result as IWorkbook)?.isIWorkbook ? result as IWorkbook : wb;
 ```
 
 ``` ts
@@ -28,8 +40,8 @@ import { Runner } from '@sheetxl/runner';
 
 const wb = new Workbook();
 
-await Runner.run(wb, 'scripts/transform.ts', {
-  args: ['region=EU']
+await Runner.run(wb, { raw: ['--region', 'EU'], kv: { region: 'EU' }, _: [] }, {
+  target: 'scripts/transform.ts'
 });
 
 ```

package/node/esm/index.mjs

@@ -1,5 +1,5 @@
 /**
-* @license @sheetxl/runner - SheetXL - Programmatic execution for SheetXL scripts - v0.8.0-beta.1
+* @license @sheetxl/runner - SheetXL - Programmatic execution for SheetXL scripts - v0.8.0-beta.10
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
 * License: The license can be found at https://www.sheetxl.com/license.
@@ -7,14 +7,14 @@
 import t from "node:path";
 import e from "node:fs";
 import { pathToFileURL as n } from "node:url";
-import { createLogChannels as r } from "@sheetxl/utils";
+import { createLogChannels as r, resolveLogTimeout as s } from "@sheetxl/utils";
 var i = Object.defineProperty;
-function s(e, n = "SHEETXL_IN") {
+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 o = ((t, e) => {
+var a = ((t, e) => {
 	let n = {};
 	for (var r in t) i(n, r, {
 		get: t[r],
@@ -22,22 +22,23 @@ var o = ((t, e) => {
 	});
 	return e || i(n, Symbol.toStringTag, { value: "Module" }), n;
 })({
-	DEFAULT_DESCRIPTION: () => g,
-	classify: () => m,
-	prepare: () => y
-}), a = null;
-function c() {
-	return a || (a = (async () => {
+	DEFAULT_DESCRIPTION: () => v,
+	classify: () => w,
+	prepare: () => T,
+	toSnippetOffset: () => b
+}), c = null;
+function l() {
+	return c || (c = (async () => {
 		try {
 			const t = await import("typescript");
 			return t.default ?? t;
 		} catch {
 			return null;
 		}
-	})()), a;
+	})()), c;
 }
-async function l(t) {
-	const e = await c();
+async function u(t) {
+	const e = await l();
 	if (!e) return null;
 	const n = e.createSourceFile("snippet.ts", t, e.ScriptTarget.Latest, !1, e.ScriptKind.TS);
 	return (n.parseDiagnostics?.length ?? 0) > 0 ? null : {
@@ -45,154 +46,310 @@ async function l(t) {
 		sf: n
 	};
 }
-function u(t, e) {
-	return t.text.slice(e.getStart(t), e.end);
-}
-function f(t) {
-	return t.endsWith(";") ? t : `${t};`;
-}
 function p(t) {
 	let e = 0;
 	for (let n = 0; n < t.length; n++) "\n" === t[n] && e++;
 	return e;
 }
-function d(t, e) {
-	const n = e.getStart(t);
-	let r = t.text.slice(n, e.end);
-	const i = e.declarationList.declarations;
-	for (let e = i.length - 1; e >= 0; e--) {
-		const s = i[e].initializer;
-		if (!s) continue;
-		const o = s.getStart(t) - n, a = s.end - n;
-		r = `${r.slice(0, o)}await (${r.slice(o, a)})${r.slice(a)}`;
+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 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 f = class {
+	constructor(t) {
+		this._code = t, this.spans = [], this._parts = [], this._length = 0;
+	}
+	add(t) {
+		this._parts.push(t), this._length += t.length;
+	}
+	copy(t, e) {
+		e <= t || (this.spans.push({
+			at: this._length,
+			from: t,
+			length: e - t
+		}), this.add(this._code.slice(t, e)));
+	}
+	terminate() {
+		this._parts[this._parts.length - 1]?.endsWith(";") || this.add(";");
+	}
+	toString() {
+		return this._parts.join("");
+	}
+}, 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--;
+	if (r < 0) return null;
+	const s = n[r];
+	if ((t.isExpressionStatement(s) || t.isExportAssignment(s) && !s.isExportEquals) && ((e) => {
+		for (; t.isParenthesizedExpression(e);) e = e.expression;
+		return t.isArrowFunction(e) || t.isFunctionExpression(e);
+	})(s.expression)) return {
+		index: r,
+		from: s.expression.getStart(e),
+		to: s.expression.end
+	};
+	if (t.isFunctionDeclaration(s) && s.body) {
+		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];
+				if (s.kind !== t.SyntaxKind.EmptyStatement && !t.isImportDeclaration(s) && !t.isImportEqualsDeclaration(s)) {
+					if (-1 !== n) return -1;
+					n = r;
+				}
+			}
+			return n;
+		}(t, e) === r) {
+			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: i,
+				to: s.end
+			};
+		}
 	}
-	return f(r);
+	return null;
 }
-async function m(t) {
-	const e = await l(t);
-	return e ? function(t, e) {
+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);
+	}(t) ? "script" : "snippet";
+	const { ts: n, sf: r } = e;
+	return function(t, e) {
 		for (const n of e.statements) {
 			if (t.isExportAssignment(n) && !n.isExportEquals) return !0;
 			if (t.canHaveModifiers(n) && t.getModifiers(n)?.some((e) => e.kind === t.SyntaxKind.DefaultKeyword)) return !0;
 			if (t.isExportDeclaration(n) && n.exportClause && t.isNamedExports(n.exportClause) && n.exportClause.elements.some((t) => "default" === t.name.text)) return !0;
 		}
 		return !1;
-	}(e.ts, e.sf) ? "script" : "snippet" : function(t) {
-		return /^\s*export\s+default\b/m.test(t) || /^\s*export\s*\{[^}]*\bas\s+default\b/m.test(t);
-	}(t) ? "script" : "snippet";
+	}(n, r) && !function(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, g = "Run Snippet", h = (t, e, n = [], r) => [
-	...n,
-	...r ? [r] : [],
-	"export default async function __snippet(ctx: SheetXL.IScript.ScriptContext): Promise<void> {",
-	"  const { wb, log, warn, error, args } = ctx as any;",
-	"  let __result: any = undefined;",
-	t,
-	"  ;",
-	e,
-	"};"
-].join("\n");
-async function y(t, e) {
-	const n = e?.epilogue ?? "  return __result;", r = await l(t);
+var S = 3, v = "Run Snippet", E = (t, e, n = [], r) => {
+	const s = [
+		...n,
+		...r ? [r] : [],
+		"export default async function __snippet(ctx: SheetXL.IScript.ScriptContext): Promise<void> {",
+		"  const { wb, log, warn, error, args } = ctx;",
+		"  let __result: any = undefined;"
+	].join("\n") + "\n";
+	return {
+		source: s + [
+			t,
+			"  ;",
+			e,
+			"};"
+		].join("\n"),
+		bodyStart: s.length
+	};
+};
+async function T(t, e) {
+	const n = e?.epilogue ?? "  return __result;", r = await u(t);
 	if (!r) {
-		const e = await c() ? void 0 : "TypeScript is unavailable, so this snippet ran without implicit await or a result value. Install the `typescript` peer dependency to restore them.";
+		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: h(t, n),
+			source: r,
 			kind: "verbatim",
-			lineOffset: w,
+			lineOffset: S,
+			spans: [{
+				at: s,
+				from: 0,
+				length: t.length
+			}],
+			expectsValue: !1,
 			warning: e
 		};
 	}
-	const { ts: i, sf: s } = r, o = s.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 i = n[r];
-			if (i.kind !== t.SyntaxKind.MultiLineCommentTrivia) continue;
-			const s = e.text.slice(i.pos, i.end);
-			if (s.startsWith("/**")) return s;
+			const s = n[r];
+			if (s.kind !== t.SyntaxKind.MultiLineCommentTrivia) continue;
+			const i = e.text.slice(s.pos, s.end);
+			if (i.startsWith("/**")) return i;
 		}
-	}(i, s), m = a ? p(a) + 1 : 0;
-	if (1 === o.length && i.isBlock(o[0])) return {
-		source: h(`  __result = await (\n${t}\n  );`, n, [], a),
-		kind: "expression",
-		lineOffset: w + m + 1
-	};
-	const { body: g, hoisted: y } = function(t, e, n) {
-		const r = e.text, i = e.statements;
-		let s = -1;
-		for (let e = i.length - 1; e >= 0; e--) if (i[e].kind !== t.SyntaxKind.EmptyStatement) {
-			t.isExpressionStatement(i[e]) && (s = e);
+	}(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: S + c + 1,
+			spans: [{
+				at: s + 21,
+				from: 0,
+				length: t.length
+			}],
+			expectsValue: !0
+		};
+	}
+	const { body: w, spans: v, hoisted: T, expectsValue: b } = function(t, e, n) {
+		const r = e.text, s = e.statements;
+		let i = -1;
+		for (let e = s.length - 1; e >= 0; e--) if (s[e].kind !== t.SyntaxKind.EmptyStatement) {
+			t.isExpressionStatement(s[e]) && (i = e);
 			break;
 		}
-		const o = [], a = [];
-		let c = 0;
-		for (let l = 0; l < i.length; l++) {
-			const m = i[l], w = m.getStart(e);
-			a.push(r.slice(c, w)), c = m.end;
-			const g = r.slice(w, m.end);
-			if (t.isImportDeclaration(m) || t.isImportEqualsDeclaration(m)) o.push(g), a.push("\n".repeat(p(g)));
-			else if (t.isVariableStatement(m)) a.push(d(e, m));
-			else {
-				if (t.isExpressionStatement(m)) {
-					const t = u(e, m.expression);
-					a.push(l === s ? `${n} = await (${t});` : `await (${t});`);
-					continue;
-				}
-				a.push(f(g));
+		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: m
+				}), l.add("\n".repeat(p(t)));
+				continue;
 			}
+			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 a.push(r.slice(c)), {
-			body: a.join(""),
-			hoisted: o
+		return l.copy(u, r.length), {
+			body: l.toString(),
+			spans: l.spans,
+			hoisted: c,
+			expectsValue: a
 		};
-	}(i, s, "__result"), x = y.length > 0 ? p(y.join("\n")) + y.length : 0;
+	}(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: R,
+			from: t.from,
+			length: t.text.length
+		};
+		return R += t.text.length + 1, e;
+	});
 	return {
-		source: h(g, n, y, a),
+		source: D,
 		kind: "statements",
-		lineOffset: w + x + m
+		lineOffset: S + k + c,
+		spans: [...I, ...v.map((t) => ({
+			...t,
+			at: t.at + K
+		}))],
+		expectsValue: b
 	};
 }
-async function x(t, e, n = "Runner timed out") {
+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;
+		n = r;
+	}
+	return n ? n.from + Math.min(e - n.at, n.length) : 0;
+}
+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 i = new Promise((t, i) => r = setTimeout(() => i(new Error(n)), e));
+	const s = new Promise((t, s) => r = setTimeout(() => s(new Error(n)), e));
 	try {
-		return await Promise.race([t, i]);
+		return await Promise.race([t, s]);
 	} finally {
 		clearTimeout(r);
 	}
 }
-var S = null;
-function v() {
-	return S || (S = (async () => {
+var C = null;
+function $() {
+	return C || (C = (async () => {
 		const { register: t } = await import("tsx/esm/api");
 		t({ tsconfig: !1 });
-	})()), S;
+	})()), C;
 }
-var b = "data:text/typescript,", $ = "data:text/javascript,", E = null;
-function _() {
-	return E || (E = (async () => {
-		const { registerHooks: e, stripTypeScriptTypes: r } = await import("node:module"), i = r;
+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, i) {
-				const s = r.parentURL;
-				if (s && (s.startsWith(b) || s.startsWith($))) {
-					const s = n(t.join(process.cwd(), "_inline_.ts")).href;
-					return i(e, {
+			resolve(e, r, s) {
+				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: s
+						parentURL: i
 					});
 				}
-				return i(e, r);
+				return s(e, r);
 			},
 			load(t, e, n) {
-				if (t.startsWith(b)) {
+				if (t.startsWith(L)) {
 					const e = decodeURIComponent(t.slice(21)), n = process.emitWarning;
 					let r;
 					process.emitWarning = () => {};
 					try {
-						r = i(e, { mode: "transform" });
+						r = s(e, { mode: "transform" });
 					} finally {
 						process.emitWarning = n;
 					}
@@ -205,25 +362,25 @@ function _() {
 				return n(t, e);
 			}
 		});
-	})()), E;
+	})()), W;
 }
-async function R(e) {
-	const r = "string" == typeof (i = e) ? i.startsWith("file:") ? i : n(t.resolve(process.cwd(), i)).href : i.href;
-	var i;
-	const s = t.extname(new URL(r).pathname).toLowerCase();
-	return ".ts" !== s && ".tsx" !== s || await v(), import(r);
+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 i = t.extname(new URL(r).pathname).toLowerCase();
+	return ".ts" !== i && ".tsx" !== i || await $(), import(r);
 }
-async function k(t, e) {
-	const n = e.notifier ?? (await import("@sheetxl/sdk")).Notifier, i = r({
-		debug: (t) => n.debug(t),
-		log: (t) => n.log(t),
-		info: (t) => n.log(t),
-		warn: (t) => n.warn(t),
-		error: (t) => n.error(t)
-	}, { render: e.render });
+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),
+		warn: (t) => s.warn(t),
+		error: (t) => s.error(t)
+	}, { render: n.render });
 	return {
 		ctx: {
-			args: e.args ?? {
+			args: e ?? {
 				raw: [],
 				kv: {},
 				_: []
@@ -234,56 +391,60 @@ async function k(t, e) {
 			error: i.error
 		},
 		channels: i,
-		notifier: n
+		notifier: s
 	};
 }
-var C = { run: async (n, r, i = {}) => {
-	const s = Array.isArray(r) ? r : [r], o = await Promise.all(s.map((n) => (async (n, r = {}) => {
-		let i = null;
-		const s = (t, e) => {
+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 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) i = n;
+		if ("function" == typeof n) s = n;
 		else if ("string" == typeof n || n instanceof URL) {
 			let o = null;
-			if ("string" != typeof n || /^[a-z]+:\/\//i.test(n)) o = await R(n);
+			if ("string" != typeof n || /^[a-z]+:\/\//i.test(n)) o = await A(n);
 			else {
-				const i = t.resolve(r.cwd ?? process.cwd(), n);
-				if (!e.existsSync(i)) throw new Error(`Script not found: ${i}`);
-				e.accessSync(i, e.constants.R_OK), o = await R(i);
+				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), o = await A(s);
 			}
-			i = s(o, 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 v(), await _(), e = `${b}${encodeURIComponent(n.code)}`, r = await import(e)) : (await _(), e = `${$}${encodeURIComponent(n.code)}`, r = await import(e)), i = s(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.");
-			i = n.runner;
+			s = n.runner;
 		}
-		return i;
-	})(n, i))), a = Date.now();
-	let c = n, l = null;
-	const u = o.length;
-	for (let t = 0; t < u; t++) {
-		const e = o[t], { ctx: n, channels: r, notifier: s } = await k(c, i);
-		l = s;
-		const a = Date.now();
-		let f;
+		return s;
+	})(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, g = () => Promise.resolve().then(() => e(n));
 		try {
-			f = await x(Promise.resolve().then(() => e(n)), i.timeoutMs, "Runner timed out");
+			m = await I(null !== h ? Promise.resolve(h.doBatch(g, "Run Script")) : g(), i.timeoutMs, "Runner timed out");
 		} finally {
-			await r.flush();
+			await o.flush({ timeoutMs: s(i.logTimeoutMs) });
 		}
-		const p = Date.now();
-		null != f && f.isIWorkbook && (c = f), s.debug(`Run ${1 === u ? "" : `${t + 1}/${u} `}completed in ${p - a} 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 (u > 1 && l) {
+	if (f > 1 && d) {
 		const t = Date.now();
-		l.debug(`All runs completed in ${t - a} ms.`);
+		d.debug(`All runs completed in ${t - l} ms.`);
 	}
-	return c ?? void 0;
+	return u;
+}, O = { run: async (t, e, n) => {
+	const { withScriptRuntime: r } = await import("@sheetxl/sdk");
+	return r(() => j(t, e, n));
 } };
-export { o as Snippet, C as default, s as resolvePath };
+export { a as Snippet, O as default, R as diagnoseRun, K as isExplainable, o as resolvePath };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/runner",
   "description": "SheetXL - Programmatic execution for SheetXL scripts",
-  "version": "0.8.0-beta.1",
+  "version": "0.8.0-beta.10",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -36,18 +36,18 @@
     "runner"
   ],
   "dependencies": {
-    "@sheetxl/io": "^0.8.0-beta.1",
-    "@sheetxl/primitives": "^0.8.0-beta.1",
-    "@sheetxl/scripting": "^0.8.0-beta.1",
-    "@sheetxl/sdk": "^0.8.0-beta.1",
-    "@sheetxl/utils": "^0.8.0-beta.1"
+    "@sheetxl/io": "^0.8.0-beta.10",
+    "@sheetxl/primitives": "^0.8.0-beta.10",
+    "@sheetxl/scripting": "^0.8.0-beta.10",
+    "@sheetxl/sdk": "^0.8.0-beta.10",
+    "@sheetxl/utils": "^0.8.0-beta.10"
   },
   "peerDependencies": {
     "typescript": "^5.9.0 || ^6.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
-    "tsx": "^4.23.1",
+    "@types/node": "^26.6.4",
+    "tsx": "^4.23.15",
     "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/Runner.d.ts

@@ -1,14 +1,12 @@
 import { Runner } from './Types';
-/** Core: run targets as a serial pipeline, each receiving the current workbook.
+/**
+ * Runs the pipeline with the `SheetXL` global installed.
  *
- * Pipeline semantics:
- * - Targets run **serially** in order, never in parallel.
- * - Each target receives a fresh `RunContext` built with the **current** workbook.
- * - If a target returns an `IWorkbook`, that becomes the workbook for all subsequent targets.
- * - `args` are shared across all targets — they represent pipeline-level configuration,
- *   not per-step input.  This follows the standard Unix convention where environment
- *   variables / flags are visible to every process in a pipeline.
- * - Returns the final workbook (which may differ from the one passed in).
+ * @remarks
+ * The declarations a script is written against promise `SheetXL.ISheet.Visibility.Hidden` is a
+ * VALUE. A compiled macro gets it from the macro runtime; source run here is type-stripped and
+ * imported, so nothing would define it. The install spans module LOADING too, not only the call —
+ * a script may read an enum at its top level — and is removed however the run ends.
  */
 export declare const run: Runner;
 declare const _default: {

package/types/src/Snippet.d.ts

@@ -9,7 +9,16 @@
  * contract promises two things a bare paste into an async function does not give them —
  *  1. **implicit await**: nothing in a snippet is ever written `await`, yet a promise-returning
  *     statement must have settled before the next one runs;
- *  2. **the final expression is the result**: exactly like a REPL, or `node -p`.
+ *  2. **the final expression is the result**: exactly like a REPL, or `node -p`;
+ *  3. **values are current**: calculation is asynchronous, so a formula set by one statement is
+ *     settled before the next statement runs — `setFormula('=1+1')` then `getValue()` reads `2`,
+ *     the way it reads in Excel, rather than the `null` a bare paste would see.
+ *
+ * **A snippet that is a function is called.** Its value is the function — `async ({ wb }) => …` as
+ * the final expression, or a snippet that is only `function main(ctx) { … }` — so it is called with
+ * the context, typed as a script's entry would be, and its return is the result. `export default` in
+ * front of an arrow or an anonymous function, with nothing else exported, is ceremony for the same
+ * thing and runs the same way: the script form is kept for what needs it, a named entry or exports.
  *
  * This is the same problem Node's REPL solves in `lib/internal/repl/await.js`, and it is solved the
  * same way: **parse for real, then rewrite the top-level statements from the AST.** Statement
@@ -32,9 +41,21 @@
  * context parameter) so the identical source compiles on every path: the CLI's type-stripping
  * loader ignores the annotations, and the `ScriptCompiler`'s linter requires them.
  */
+/**
+ * A run of the author's own text inside an emitted source: `length` characters that sit at `at`
+ * in the emitted text and came from `from` in the snippet.
+ */
+export interface Span {
+    at: number;
+    from: number;
+    length: number;
+}
 /** How a source will run — see the module remarks for the contract. */
 export type SourceForm = 'script' | 'snippet';
-/** `script` when the source has a top-level default export; `snippet` otherwise. */
+/**
+ * `script` when the source has a top-level default export; `snippet` otherwise — and when that
+ * export is only an entry function (`export default async ({ wb }) => …`), which runs as a snippet.
+ */
 export declare function classify(code: string): Promise<SourceForm>;
 export interface WrapOptions {
     /**
@@ -55,11 +76,19 @@ export interface Prepared {
      */
     kind: 'expression' | 'statements' | 'verbatim';
     /**
-     * Lines of wrapper prologue before the first line of user code — subtract from a compiler
-     * diagnostic's line to point back into the snippet. Exact for every kind: the rewrite emits the
-     * original trivia, so no line moves.
+     * Lines of wrapper prologue before the first line of user code. Exact for every kind: the
+     * rewrite emits the original trivia, so no line moves. It places LINES only — to point a
+     * compiler position back into the snippet, line and column, use {@link toSnippetOffset}.
      */
     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.
@@ -86,4 +115,14 @@ export declare const DEFAULT_DESCRIPTION = "Run Snippet";
  * sidesteps any position mapping — the whole snippet is the expression.
  */
 export declare function prepare(code: string, options?: WrapOptions): Promise<Prepared>;
+/**
+ * Where an offset into a prepared {@link Prepared.source} sits in the snippet the author wrote.
+ *
+ * @remarks
+ * Exact wherever the offset falls in the author's own text, which is where a compiler puts a
+ * diagnostic about it. An offset in text the wrapper added has no place in the snippet, so it
+ * answers with the nearest thing that does: the author's next character, or the end of their last
+ * text when nothing of theirs follows.
+ */
+export declare function toSnippetOffset(prepared: Prepared, offset: number): number;
 //# sourceMappingURL=Snippet.d.ts.map

package/types/src/Types.d.ts

@@ -1,5 +1,5 @@
 import { IWorkbook } from '@sheetxl/sdk';
-import { LogRenderer } from '@sheetxl/utils';
+import { LogRenderer, MaybePromise } from '@sheetxl/utils';
 export type Notifier = typeof import('@sheetxl/sdk').Notifier;
 /**
  * Arguments passed after `--` on the CLI (`sheetxl -f <script> [workbook] -- [args...]`).
@@ -48,6 +48,9 @@ export type RunContext = {
      * Variadic and value-taking, like `console.log`: `log('rows:', n)` and `log(range.getStats())`
      * both work. An SDK object renders as its markdown report when the host supplies a renderer
      * (the CLI does); otherwise it falls back to JSON.
+     *
+     * A promise is awaited and logs as its settled value, so `log(sheet.evaluate(…))` needs no
+     * `await`. Output order is still call order.
      */
     readonly log: (...args: any[]) => void;
     /** Diagnostics: something surprising but survivable. Travels separately from `log` (stderr). */
@@ -57,8 +60,19 @@ export type RunContext = {
 };
 /**
  * The function signature for a script run by the CLI or the MCP `run` tool.
+ *
+ * @remarks
+ * The return value is the run's RESULT, the same contract a snippet's final expression has, so it
+ * is deliberately unconstrained — a tally, an `ICellRange`, a `getStats()` object. Returning
+ * nothing is normal: a run whose output is its `log` has no answer to hand back.
+ *
+ * An `IWorkbook` is the one return that is also *structural*: it becomes the workbook the next
+ * stage runs against, on top of being the result. Nothing else is inspected — an array is just an
+ * array.
+ *
+ * Sync or async, both real: `function main(ctx): number[]` is as valid as the `async` spelling.
  */
-export type RunFunction = (ctx: RunContext) => Promise<void | IWorkbook>;
+export type RunFunction = (ctx: RunContext) => MaybePromise<IWorkbook | any | void>;
 /**
  * Possible targets for the runner to execute
  */
@@ -69,7 +83,17 @@ export type RunTarget = string | URL | {
     runner: RunFunction;
 };
 export interface RunOptions {
-    args?: ArgV;
+    /**
+     * What to run — a path, a URL, inline code, or a function.
+     *
+     * @remarks
+     * An array runs as a serial pipeline: each stage gets the workbook the one before it left, and
+     * the run answers with the LAST stage's return value. That makes a chain lossy in one corner —
+     * an early stage that swapped the workbook is only visible if the last stage hands it back — so
+     * a host that needs per-stage reporting calls `run` once per target instead, which is what the
+     * CLI does (it owns the error report for the target that failed).
+     */
+    target: RunTarget | RunTarget[];
     /** The host's output sink (toasts on a UI host, the console on the CLI). Not exposed to scripts. */
     notifier?: Notifier;
     /**
@@ -82,6 +106,18 @@ export interface RunOptions {
     render?: LogRenderer;
     signal?: AbortSignal;
     timeoutMs?: number;
+    /**
+     * How long a finished stage waits for what it logged to settle, in milliseconds. `0` waits
+     * indefinitely.
+     *
+     * @remarks
+     * `log(promise)` prints what the promise settles to, so a stage is not done until its log is. A
+     * value still unsettled when this elapses prints as `[pending]`; nothing is thrown and the rest
+     * of the log is kept. Independent of `timeoutMs`, which bounds the script itself.
+     *
+     * @defaultValue `DEFAULT_LOG_TIMEOUT_MS` (10 seconds)
+     */
+    logTimeoutMs?: number;
     cwd?: string;
     ts?: {
         enabled?: boolean;
@@ -90,6 +126,24 @@ export interface RunOptions {
 }
 /**
  * Run any RunFunction with a built in context.
+ *
+ * @remarks
+ * The two data inputs are positional — the workbook the run is against, and the args it was given.
+ * Everything else is host wiring and lives in {@link RunOptions}, including `target`, which is why
+ * the options are required rather than optional.
+ *
+ * **Hands back exactly what the entry returned**, undisturbed — see {@link RunFunction}. A host
+ * that also needs the workbook the run ended on reads it off that value when it is one:
+ *
+ * ```ts
+ * const result = await run(wb, args, { target: 'transform.ts' });
+ * const ended = (result as IWorkbook)?.isIWorkbook ? result as IWorkbook : wb;
+ * ```
+ *
+ * Always a promise, even for a sync entry: resolving a target loads modules.
+ *
+ * `args` is spelled `ArgV | undefined` rather than `args?` because TypeScript will not let an
+ * optional parameter precede a required one — a run with no args passes `undefined` for it.
  */
-export type Runner = (workbook: IWorkbook | null, target: RunTarget | RunTarget[], options?: RunOptions) => Promise<void | IWorkbook>;
+export type Runner = (workbook: IWorkbook | null, args: ArgV | undefined, options: RunOptions) => Promise<IWorkbook | any | void>;
 //# sourceMappingURL=Types.d.ts.map

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