@loadmap/cli 0.5.0 → 0.7.0

package/README.md

@@ -3,14 +3,17 @@
 ```bash
 npx @loadmap/cli check shop.loadmap          # exit 1 when an expect line fails; GitHub annotations under Actions
 npx @loadmap/cli fmt shop.loadmap            # lays it out the one way; --check exits 1 instead (for CI)
-npx @loadmap/cli record shop.loadmap --out shop.gif --caption
-npx @loadmap/cli record http://localhost:5173/ --out poster.png --poster
+
+npm i -D @loadmap/cli playwright && npx playwright install chromium   # once, to record
+npx loadmap record shop.loadmap --out shop.gif --caption
+npx loadmap record http://localhost:5173/ --out poster.png --poster
 ```
 
 `loadmap check` compiles each `.loadmap` and tests its `expect` lines on the pessimistic edge (every capacity at its
 low bound). `loadmap fmt` rewrites each file laid out the one way (two spaces a block, a statement a line, one space
 around operators; numbers, texts and formulas as written), `--check` only names the ones that are not, `-` reads
 standard input. `loadmap record` draws a `.loadmap` (or opens a page that calls `expose()` from `@loadmap/export`) in
-headless Chromium and records it on a fixed clock: the same options give the same file. Recording needs Chromium
-once: `npx playwright install chromium`. `loadmap --help` lists every option.
+headless Chromium and records it on a fixed clock: the same options give the same file. Only recording needs
+Playwright and its Chromium, installed next to the command (`npx @loadmap/cli record` alone cannot find them);
+`check` and `fmt` run without them. `loadmap --help` lists every option.
 Docs: https://jaim3r0jas.github.io/loadmap/ · MIT

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as main } from "./src-BQW6xKGu.js";
+import { n as main } from "./src-KVw61wOu.js";
 // src/bin.ts
 main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
 	console.error(err instanceof Error ? err.message : err);

package/dist/index.d.ts

@@ -40,7 +40,7 @@ interface FmtOptions {
  * file has a syntax error, cannot be read, or (with --check) needs formatting; 2 for a usage mistake.
  */
 export declare function fmt(argv: string[], o?: FmtOptions): Promise<number>;
-export declare const USAGE = "loadmap check <file.loadmap>… [--format text|github]\nloadmap fmt <file.loadmap>… [--check] | loadmap fmt -\nloadmap record <url | file.loadmap> --out <file.gif|.webm|.mp4|.png|.svg> [options]\n\ncheck compiles each definition and tests its expect lines on the pessimistic edge (every capacity at its low\nbound). It exits 1 when a definition has an error or an expectation fails, 0 when everything holds.\n\n  --format <f>          text, or github to add annotations on the lines (the default under GitHub Actions)\n\nfmt lays each definition out the one way, in place: two spaces a block, a statement a line, one space around\noperators; numbers, texts and formulas stay as written. A file with a syntax error is left alone (exit 1).\n\n  --check               change nothing; exit 1 when a file is not laid out so (for CI)\n  -                     read standard input, write standard output\n\nrecord opens the page in headless Chromium, finds the loadmap it exposes (expose() from @loadmap/export) and\nrecords it on a fixed clock, so the same options give the same file. A .loadmap file is drawn by the viewer that\ncomes with the command.\n\n  --out <file>          the extension picks the format: gif, webm, mp4, png or svg\n  --script <file.json>  [{ \"at\": 0, \"set\": { \"load\": 5 } }, { \"at\": 3, \"scenario\": \"Proposed\" }, …]\n                        or { \"seconds\", \"fps\", \"script\": […] }\n  --scenario <label>    start from a scenario's values (--set goes on top)\n  --set <key=value>     a value before recording starts; repeatable (--set load=30 --set pods=6)\n  --caption             the title, scenario and load above the board, the verdict below it\n  --story               play the definition's story, a step at a time (with --caption, its text below the board)\n  --poster              with .png: the board, the verdict, the limits and the scenarios compared\n  --seconds <n>         length of a video or GIF (default 8, or the script's)\n  --fps <n>             frames per second (default 30; GIF 15, at most 50)\n  --scale <n>           pixels per diagram unit (default 1, PNG 2)\n  --seed <n>            the sim's seed (default 1)\n  --name <name>         which exposed loadmap, when the page has several (default \"default\")\n  --width <px>          the browser window (default 1280; below 640 the diagram runs top to bottom)\n  --color-scheme <s>    light or dark, for a page that follows the system theme (default light)";
+export declare const USAGE = "loadmap check <file.loadmap>… [--format text|github]\nloadmap fmt <file.loadmap>… [--check] | loadmap fmt -\nloadmap record <url | file.loadmap> --out <file.gif|.webm|.mp4|.png|.svg> [options]\n\ncheck compiles each definition and tests its expect lines on the pessimistic edge (every capacity at its low\nbound). It exits 1 when a definition has an error or an expectation fails, 0 when everything holds.\n\n  --format <f>          text, or github to add annotations on the lines (the default under GitHub Actions)\n\nfmt lays each definition out the one way, in place: two spaces a block, a statement a line, one space around\noperators; numbers, texts and formulas stay as written. A file with a syntax error is left alone (exit 1).\n\n  --check               change nothing; exit 1 when a file is not laid out so (for CI)\n  -                     read standard input, write standard output\n\nrecord opens the page in headless Chromium, finds the loadmap it exposes (expose() from @loadmap/export) and\nrecords it on a fixed clock, so the same options give the same file. A .loadmap file is drawn by the viewer that\ncomes with the command. It needs Playwright next to the command: npm i -D playwright, then npx playwright install\nchromium (check and fmt run without it).\n\n  --out <file>          the extension picks the format: gif, webm, mp4, png or svg\n  --script <file.json>  [{ \"at\": 0, \"set\": { \"load\": 5 } }, { \"at\": 3, \"scenario\": \"Proposed\" }, …]\n                        or { \"seconds\", \"fps\", \"script\": […] }\n  --scenario <label>    start from a scenario's values (--set goes on top)\n  --set <key=value>     a value before recording starts; repeatable (--set load=30 --set pods=6)\n  --caption             the title, scenario and load above the board, the verdict below it\n  --story               play the definition's story, a step at a time (with --caption, its text below the board)\n  --poster              with .png: the board, the verdict, the limits and the scenarios compared\n  --seconds <n>         length of a video or GIF (default 8, or the script's)\n  --fps <n>             frames per second (default 30; GIF 15, at most 50)\n  --scale <n>           pixels per diagram unit (default 1, PNG 2)\n  --seed <n>            the sim's seed (default 1)\n  --name <name>         which exposed loadmap, when the page has several (default \"default\")\n  --width <px>          the browser window (default 1280; below 640 the diagram runs top to bottom)\n  --color-scheme <s>    light or dark, for a page that follows the system theme (default light)";
 export interface RecordArgs {
   /** A page that calls expose(); empty with `file`. */
   url: string;

package/dist/index.js

@@ -1 +1 @@
-export { t as USAGE, o as check, a as fmt, s as github, n as main, r as parseRecord, i as record } from "./src-BQW6xKGu.js";
+export { t as USAGE, o as check, a as fmt, s as github, n as main, r as parseRecord, i as record } from "./src-KVw61wOu.js";

package/dist/{src-BQW6xKGu.js → src-KVw61wOu.js}

@@ -2,7 +2,6 @@ import { readFile, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import { extname, join, normalize } from "node:path";
 import { parseArgs } from "node:util";
-import { chromium } from "playwright";
 // ../core/src/capacity.ts
 /** A capacity read off a dashboard or a load test. */
 function measured(value, unit, o) {
@@ -154,6 +153,13 @@ function dateAt(g, multiple) {
 	const at = Date.UTC(y, mo, Math.min(start.getUTCDate(), days));
 	return new Date(at + (months - whole) * days * 864e5);
 }
+// ../core/src/internal.ts
+const blamed = /* @__PURE__ */ new WeakMap();
+/** The flow an error was raised computing: by that flow itself, not by a component or another flow it read. */
+const flowOf = (err) => typeof err === "object" && err !== null ? blamed.get(err) : void 0;
+function blame(err, flow) {
+	if (typeof err === "object" && err !== null && !blamed.has(err)) blamed.set(err, flow);
+}
 // ../core/src/params.ts
 const p = {
 	/** The load, as a multiple of today. One per model; it drives the limits. */
@@ -721,14 +727,25 @@ function defineModel(def) {
 function context(def, values, bound, pinned, fixed) {
 	const cache = /* @__PURE__ */ new Map();
 	const stack = [];
-	const memo = (key, f) => {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const memo = (key, f, flow) => {
 		if (cache.has(key)) return cache.get(key);
-		if (stack.includes(key)) throw new Error(`loadmap: ${[...stack.slice(stack.indexOf(key)), key].join(" → ")} is a loop`);
+		if (stack.includes(key)) {
+			const loop = /* @__PURE__ */ new Error(`loadmap: ${[...stack.slice(stack.indexOf(key)), key].join(" → ")} is a loop`);
+			seen.add(loop);
+			throw loop;
+		}
 		stack.push(key);
 		try {
 			const v = f();
 			cache.set(key, v);
 			return v;
+		} catch (err) {
+			if (typeof err === "object" && err !== null && !seen.has(err)) {
+				seen.add(err);
+				if (flow) blame(err, flow);
+			}
+			throw err;
 		} finally {
 			stack.pop();
 		}
@@ -765,11 +782,15 @@ function context(def, values, bound, pinned, fixed) {
 		if (r.budget != null && !(r.budget >= 0 && Number.isFinite(r.budget))) throw new Error(`loadmap: flow "${f}" needs a retry budget of 0 or more, not ${r.budget}`);
 		return r.times > 0 && r.budget !== 0 ? r : void 0;
 	};
-	const rate = (f) => memo(`rate of ${f}`, () => def.flows[f].rate(ctx));
+	const rateOf = (f) => {
+		const r = def.flows[f].rate;
+		return typeof r === "function" ? r(ctx) : r;
+	};
+	const rate = (f) => memo(`rate of ${f}`, () => rateOf(f), f);
 	ctx.flows = table(flowIds, (f) => memo(`flow ${f}`, () => {
 		if (fixed && Object.hasOwn(fixed, f)) return fixed[f];
-		return retryOf(f) ? retries()[f].attempts : def.flows[f].rate(ctx);
-	}));
+		return retryOf(f) ? retries()[f].attempts : rateOf(f);
+	}, f));
 	/** The share a stage turns away: past its component's `full`, what is above it. */
 	const rejects = (s) => memo(`rejects at ${s}`, () => {
 		const st = stages[s];
@@ -2237,11 +2258,25 @@ const STAGES = [
 /** A formula failed while the model ran: where, and why. */
 var FormulaError = class extends Error {
 	span;
-	constructor(span, message) {
+	hint;
+	constructor(span, message, hint) {
 		super(message);
 		this.span = span;
+		this.hint = hint;
 	}
 };
+const ISSUES = "https://github.com/jaim3r0jas/loadmap/issues";
+/**
+* A run-time error in the definition's words: core's own (`loadmap: …`) as written; a TypeError or ReferenceError, which
+* no definition can cause, as a bug in loadmap, its text kept for the report.
+*/
+function failure(err, what = "this formula") {
+	if (err instanceof TypeError || err instanceof ReferenceError) return {
+		message: `${what} could not be computed: a bug in loadmap`,
+		hint: `Please report it at ${ISSUES} (${err.name}: ${err.message})`
+	};
+	return { message: err instanceof Error ? err.message.replace(/^loadmap: /, "") : String(err) };
+}
 const num = (f) => f;
 /** Functions renamed before 0.1: a definition from before says what to write instead. */
 const RENAMED = { kfmt: "compact" };
@@ -2593,11 +2628,21 @@ var Compiler$1 = class {
 			};
 		}
 		const host = own(this.names.functions, name);
-		if (host) return {
-			type: "any",
-			constant: false,
-			run: (c, l) => host(...runs.map((r) => r(c, l)))
-		};
+		if (host) {
+			const run = (c, l) => {
+				const args = runs.map((r) => r(c, l));
+				try {
+					return host(...args);
+				} catch (err) {
+					throw new Error(`${name}(…) failed: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			};
+			return {
+				type: "any",
+				constant: false,
+				run
+			};
+		}
 		const known = [
 			...Object.keys(BUILTINS),
 			...this.names.fits.keys(),
@@ -2685,15 +2730,16 @@ var Compiler$1 = class {
 };
 /**
 * Wraps a formula for the model: it takes the context, and any error it throws carries the formula's place. An error
-* already placed (from a formula this one read) keeps its place: the innermost formula is the one to fix.
+* already placed (from a formula or a flow this one read) keeps its place: the innermost one is the one to fix.
 */
 function placed(span, run) {
 	return (ctx, local) => {
 		try {
 			return run(ctx, local);
 		} catch (err) {
-			if (err instanceof FormulaError) throw err;
-			throw new FormulaError(span, err instanceof Error ? err.message.replace(/^loadmap: /, "") : String(err));
+			if (err instanceof FormulaError || flowOf(err)) throw err;
+			const { message, hint } = failure(err);
+			throw new FormulaError(span, message, hint);
 		}
 	};
 }
@@ -3111,7 +3157,13 @@ var Parser = class {
 			from: chain[0].from,
 			to: chain.at(-1).to
 		};
-		if (this.eat(":")) {
+		if (this.is(":") && this.is("{", 1)) {
+			const colon = this.next();
+			e.colon = {
+				from: colon.from,
+				to: colon.to
+			};
+		} else if (this.eat(":")) {
 			if (this.endsStatement()) this.fail(this.peek(), "expected a value after \":\"");
 			e.value = this.expr();
 			e.to = e.value.to;
@@ -3444,7 +3496,10 @@ function compile(source, o = {}) {
 			};
 		});
 	} catch (err) {
-		if (err instanceof FormulaError) report.error(err.span, err.message);
+		if (err instanceof FormulaError || flowOf(err) || err instanceof Error && err.message.startsWith("loadmap: ")) c.runError(err, {
+			from: 0,
+			to: 0
+		});
 		else if (!(err instanceof Bail)) report.error({
 			from: 0,
 			to: 0
@@ -3626,6 +3681,7 @@ var Compiler = class {
 		for (const b of flows) {
 			const id = b.args.id;
 			if (!id) continue;
+			this.flowAt.set(id.name, id);
 			const label = this.text(b.args.label);
 			const def = {};
 			if (label != null) def.label = label;
@@ -3674,7 +3730,7 @@ var Compiler = class {
 		}
 		for (const [id, s] of stageOf) if (!reached.has(id) && s.block.keyword !== "fanout") this.report.warning(s.block.args.id ?? s.block.at, `no flow passes the stage "${id}"`);
 		const used = new Set(Object.values(stageDefs).map((d) => d.component));
-		for (const [id, c] of Object.entries(componentDefs)) if (!c.demand && !used.has(id)) this.report.error(componentNames.get(id), `the component "${id}" needs "demand: …": no stage uses it`, COMPONENT_PROPS.demand.doc);
+		for (const [id, c] of Object.entries(componentDefs)) if (!c.demand && !used.has(id) && !this.plainBoxes.has(id)) this.report.error(componentNames.get(id), `the component "${id}" needs "demand: …": no stage uses it`, COMPONENT_PROPS.demand.doc);
 		const calibration = {};
 		for (const f of fits) {
 			const fit = f.args.id && this.fits.get(f.args.id.name);
@@ -3751,7 +3807,7 @@ var Compiler = class {
 			model = defineModel(modelDef);
 			view = defineView(model, viewDef);
 		} catch (err) {
-			this.report.error(top, err instanceof Error ? err.message.replace(/^loadmap: /, "") : String(err));
+			this.runError(err, top);
 			return;
 		}
 		const runs = [{
@@ -3774,7 +3830,7 @@ var Compiler = class {
 				at: b.at
 			});
 		}
-		for (const { values, at } of runs) try {
+		for (const [i, { values, at }] of runs.entries()) try {
 			const ev = model.evaluate(values);
 			labelsAt(view, ev);
 			for (const k of Object.keys(modelDef.derived ?? {})) ev.ctx.derived[k];
@@ -3788,8 +3844,7 @@ var Compiler = class {
 			for (const e of viewDef.edges) e.when?.(ev.ctx);
 			for (const f of model.flowIds) if (!Number.isFinite(ev.flows[f])) this.report.warning(this.flowRate.get(f) ?? at, `the rate of "${f}" is ${ev.flows[f]} here`);
 		} catch (err) {
-			if (err instanceof FormulaError) this.report.error(err.span, err.message);
-			else this.report.error(at, err instanceof Error ? err.message.replace(/^loadmap: /, "") : String(err));
+			this.runError(err, at, i === 0);
 		}
 		if (this.report.failed) return void 0;
 		return {
@@ -3798,7 +3853,19 @@ var Compiler = class {
 			options
 		};
 	}
+	/**
+	* What running the model threw, where it came from: its formula, else its flow, else `at`. A preset or a scenario
+	* keeps `at` (`onFlow` false): the flow is fine at the defaults, the preset is what breaks it.
+	*/
+	runError(err, at, onFlow = true) {
+		if (err instanceof FormulaError) return this.report.error(err.span, err.message, err.hint);
+		const flow = flowOf(err);
+		const { message, hint } = failure(err, flow ? `the flow "${flow}"` : "the model");
+		this.report.error(onFlow && flow && this.flowAt.get(flow) || at, message, hint);
+	}
 	flowRate = /* @__PURE__ */ new Map();
+	flowAt = /* @__PURE__ */ new Map();
+	plainBoxes = /* @__PURE__ */ new Set();
 	shape(keyword, spec, stmts, at, decl) {
 		const b = {
 			keyword,
@@ -3934,6 +4001,15 @@ var Compiler = class {
 			component
 		};
 	}
+	/** A box with only a component's optional lines (`describe`, `name`, …) was meant as a plain box: one error, the fix. */
+	plainBox(b) {
+		const [k, p] = Object.keys(COMPONENT_PROPS).flatMap((k) => b.props.has(k) ? [[k, this.prop(b, k)]] : []).sort((x, y) => x[1].key.from - y[1].key.from)[0];
+		let hint = "give the box capacity and over lines, or drop it";
+		const sub = b.args.sub;
+		const noSub = (!sub || sub.t === "str" && sub.value === "") && !b.props.has("sub");
+		if (k === "describe" && p.value.t === "str" && noSub) hint = b.args.label ? `for a line under a plain box, put it on the first line: ${b.keyword} ${b.args.id.name} ${this.slice(b.args.label)} ${this.slice(p.value)}` : `for a line under a plain box, write sub: ${this.slice(p.value)}`;
+		this.report.error(p.key, `"${k}" belongs to a component, and this box has no capacity`, hint);
+	}
 	slice(s) {
 		return this.source.slice(s.from, s.to);
 	}
@@ -3962,7 +4038,8 @@ var Compiler = class {
 		try {
 			return f.run(void 0);
 		} catch (err) {
-			this.report.error(e, err instanceof Error ? err.message : String(err));
+			const { message, hint } = failure(err);
+			this.report.error(e, message, hint);
 			return;
 		}
 	}
@@ -4363,7 +4440,14 @@ var Compiler = class {
 			o[k] = this.dyn(prop.value, want, "ctx", check);
 		}
 		const at = box ? box.args.id ?? box.at : b.at;
-		for (const k of ["capacity", "over"]) if (!(k in o)) this.report.error(at, `the component needs "${k}: …"`, COMPONENT_PROPS[k].doc);
+		const missing = ["capacity", "over"].filter((k) => !(k in o));
+		const nested = b.children.some((c) => c.keyword === "component");
+		if (b === box && !nested && missing.length === 2 && !("demand" in o)) {
+			this.plainBoxes.add(b.args.id.name);
+			this.plainBox(b);
+			return o;
+		}
+		for (const k of missing) this.report.error(at, `the component needs "${k}: …"`, COMPONENT_PROPS[k].doc);
 		return o;
 	}
 	stage(b, box, components, resolve, flows, reached) {
@@ -4458,6 +4542,10 @@ var Compiler = class {
 					if (!flows.has(f.name)) this.report.error(f, `unknown flow "${f.name}"`, didYouMean(f.name, flows.keys()));
 					const stage = resolve(s, "stage");
 					if (stage) reached.add(stage);
+					if (e.colon) {
+						this.report.error(e.colon, "a branch takes its copies after \":\", not a block", `${f.name} -> ${s.name}: 1`);
+						continue;
+					}
 					if (!e.value) this.report.error(e, "how many copies per unit?", `${f.name} -> ${s.name}: 1`);
 					if (e.body) this.report.error(e.bodySpan ?? e, "a branch has no block");
 					if (stage && e.value && flows.has(f.name)) branches.push([
@@ -4531,6 +4619,7 @@ var Compiler = class {
 		};
 	}
 	edges(e, boxes) {
+		if (e.colon) this.report.error(e.colon, "drop the \":\" before a { … } block", `${e.chain.map((c) => c.name).join(" -> ")} { ${e.chain.length > 2 ? "" : "label: …; "}when: … }`);
 		for (const n of e.chain) if (!boxes.has(n.name)) this.report.error(n, `unknown node "${n.name}"`, didYouMean(n.name, boxes.keys()));
 		const props = /* @__PURE__ */ new Map();
 		for (const s of e.body ?? []) {
@@ -4918,6 +5007,20 @@ async function readStdin() {
 	for await (const c of process.stdin) chunks.push(c);
 	return Buffer.concat(chunks).toString("utf8");
 }
+// src/playwright.ts
+/**
+* Playwright, loaded only to record: `check`, `fmt` and `--help` run without it, so a CI step that never draws does
+* not install a browser driver. Missing, it says how to add it.
+*/
+async function playwright(load = () => import("playwright")) {
+	try {
+		return await load();
+	} catch (err) {
+		const e = err;
+		if ((e.code === "ERR_MODULE_NOT_FOUND" || e.code === "MODULE_NOT_FOUND") && /['"]playwright['"]/.test(e.message ?? "")) throw new Error("loadmap record needs Playwright: npm i -D playwright, then npx playwright install chromium");
+		throw err;
+	}
+}
 // src/index.ts
 const USAGE = `loadmap check <file.loadmap>… [--format text|github]
 loadmap fmt <file.loadmap>… [--check] | loadmap fmt -
@@ -4936,7 +5039,8 @@ operators; numbers, texts and formulas stay as written. A file with a syntax err
 
 record opens the page in headless Chromium, finds the loadmap it exposes (expose() from @loadmap/export) and
 records it on a fixed clock, so the same options give the same file. A .loadmap file is drawn by the viewer that
-comes with the command.
+comes with the command. It needs Playwright next to the command: npm i -D playwright, then npx playwright install
+chromium (check and fmt run without it).
 
   --out <file>          the extension picks the format: gif, webm, mp4, png or svg
   --script <file.json>  [{ "at": 0, "set": { "load": 5 } }, { "at": 3, "scenario": "Proposed" }, …]
@@ -5059,7 +5163,8 @@ async function record(a, o = {}) {
 		"png",
 		"svg"
 	].includes(format)) throw new Error(`--out must end in .gif, .webm, .mp4, .png or .svg`);
-	if (!a.file) return recordPage(a, format);
+	const { chromium } = await playwright();
+	if (!a.file) return recordPage(a, format, chromium);
 	const source = await readFile(a.file, "utf8");
 	const r = compile(source);
 	if (!r.ok) throw new Error(r.diagnostics.map((d) => formatDiagnostic(d, source, a.file)).join("\n"));
@@ -5068,7 +5173,7 @@ async function record(a, o = {}) {
 		return await recordPage({
 			...a,
 			url: server.url
-		}, format);
+		}, format, chromium);
 	} finally {
 		await server.close();
 	}
@@ -5105,7 +5210,7 @@ async function serve(source, dir) {
 		close: () => new Promise((done) => server.close(() => done()))
 	};
 }
-async function recordPage(a, format) {
+async function recordPage(a, format, chromium) {
 	const browser = await chromium.launch();
 	try {
 		const page = await browser.newPage({