@mantaq/viz 0.0.0 → 0.1.0

package/dist/routing-BNJN5Oiu.mjs

@@ -0,0 +1,759 @@
+import { Either } from "@mantaq/utils";
+// src/schema.ts
+/**
+* Viz document schema. Bump `VIZ_SCHEMA_VERSION` on any breaking change.
+* Everything not observable at runtime is `null`, never guessed.
+*/
+const VIZ_SCHEMA_VERSION = 7;
+/**
+* Edge source of an `onAny` registration: any non-final state of the machine,
+* or `region.*` inside a region. Never listed in `states`.
+*/
+const ANY_STATE = "*";
+/** Region prefix of a state id (`""` at the root). */
+function scopeOf(id) {
+	const cut = id.lastIndexOf(".");
+	return cut === -1 ? "" : id.slice(0, cut);
+}
+function isAnyState(id) {
+	return id === "*" || id.endsWith(`.*`);
+}
+/** True when `stateId` is one of the states an `anyId` source stands for. */
+function coveredByAny(anyId, stateId) {
+	return isAnyState(anyId) && !isAnyState(stateId) && scopeOf(anyId) === scopeOf(stateId);
+}
+// src/validate-read.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function report(reader, issue) {
+	reader.issues.push(issue);
+}
+function fail(reader, at, context) {
+	report(reader, {
+		path: `${at.path}.${at.key}`,
+		message: context.message
+	});
+	return context.fallback;
+}
+function readString(reader, at) {
+	const value = at.record[at.key];
+	return typeof value === "string" ? value : fail(reader, at, {
+		message: "expected string",
+		fallback: ""
+	});
+}
+function readNullableString(reader, at) {
+	return at.record[at.key] === null ? null : readString(reader, at);
+}
+function readBoolean(reader, at) {
+	const value = at.record[at.key];
+	return typeof value === "boolean" ? value : fail(reader, at, {
+		message: "expected boolean",
+		fallback: false
+	});
+}
+function readInteger(reader, at) {
+	const value = at.record[at.key];
+	return typeof value === "number" && Number.isInteger(value) ? value : fail(reader, at, {
+		message: "expected integer",
+		fallback: 0
+	});
+}
+function readStrings(reader, at) {
+	const value = at.record[at.key];
+	if (Array.isArray(value) && value.every((item) => typeof item === "string")) return value.filter((item) => typeof item === "string");
+	return fail(reader, at, {
+		message: "expected string[]",
+		fallback: []
+	});
+}
+function readNullableStrings(reader, at) {
+	return at.record[at.key] === null ? null : readStrings(reader, at);
+}
+function readEnum(reader, at, allowed) {
+	const value = at.record[at.key];
+	const match = allowed.find((candidate) => candidate === value);
+	if (match !== void 0) return match;
+	return fail(reader, at, {
+		message: `expected one of ${allowed.join(", ")}`,
+		fallback: void 0
+	});
+}
+function readCoverage(reader, at) {
+	const value = at.record[at.key];
+	if (value === null) return null;
+	const hits = isRecord(value) ? value["hits"] : void 0;
+	if (typeof hits === "number" && Number.isInteger(hits)) return { hits };
+	return fail(reader, at, {
+		message: "expected null or { hits: integer }",
+		fallback: null
+	});
+}
+function toJson(value) {
+	if (value === null || typeof value === "boolean" || typeof value === "string") return value;
+	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+	if (Array.isArray(value)) {
+		const items = value.map(toJson);
+		return items.every((item) => item !== void 0) ? items.filter((item) => item !== void 0) : void 0;
+	}
+	if (!isRecord(value)) return void 0;
+	const entries = Object.entries(value).map(([key, child]) => [key, toJson(child)]);
+	if (entries.some(([, child]) => child === void 0)) return void 0;
+	return Object.fromEntries(entries.flatMap(([key, child]) => child === void 0 ? [] : [[key, child]]));
+}
+function readJson(reader, at) {
+	const value = toJson(at.record[at.key]);
+	return value === void 0 ? fail(reader, at, {
+		message: "expected JSON value",
+		fallback: null
+	}) : value;
+}
+function readList(reader, at, item) {
+	const value = at.record[at.key];
+	if (!Array.isArray(value)) return fail(reader, at, {
+		message: "expected array",
+		fallback: []
+	});
+	return value.flatMap((entry, index) => {
+		const path = `${at.path}.${at.key}[${index}]`;
+		if (isRecord(entry)) return [item(entry, path)];
+		report(reader, {
+			path,
+			message: "expected object"
+		});
+		return [];
+	});
+}
+// src/validate-explanation.ts
+const OPERATORS = [
+	"<",
+	"<=",
+	">",
+	">=",
+	"===",
+	"!==",
+	"==",
+	"!="
+];
+const SOURCES = ["payload", "context"];
+function readLocation(reader, record, path) {
+	return {
+		file: readString(reader, {
+			record,
+			key: "file",
+			path
+		}),
+		line: readInteger(reader, {
+			record,
+			key: "line",
+			path
+		}),
+		column: readInteger(reader, {
+			record,
+			key: "column",
+			path
+		})
+	};
+}
+function readNullableLocation(reader, record, path) {
+	const value = record["location"];
+	if (value === null) return null;
+	if (isRecord(value)) return readLocation(reader, value, `${path}.location`);
+	report(reader, {
+		path: `${path}.location`,
+		message: "expected null or object"
+	});
+	return null;
+}
+function readTarget(reader, record, path) {
+	const value = record["target"];
+	const at = `${path}.target`;
+	if (!isRecord(value)) {
+		report(reader, {
+			path: at,
+			message: "expected object"
+		});
+		return { kind: "stay" };
+	}
+	const kind = readEnum(reader, {
+		record: value,
+		key: "kind",
+		path: at
+	}, [
+		"state",
+		"stay",
+		"unresolved"
+	]);
+	if (kind === "state") return {
+		kind,
+		state: readString(reader, {
+			record: value,
+			key: "state",
+			path: at
+		})
+	};
+	if (kind === "unresolved") return {
+		kind,
+		text: readString(reader, {
+			record: value,
+			key: "text",
+			path: at
+		})
+	};
+	return { kind: "stay" };
+}
+function readBranch(reader, record, path) {
+	return {
+		conditions: readStrings(reader, {
+			record,
+			key: "conditions",
+			path
+		}),
+		target: readTarget(reader, record, path)
+	};
+}
+function readComparison(reader, record, path) {
+	const literal = record["literal"];
+	const valid = typeof literal === "number" || typeof literal === "string" || typeof literal === "boolean";
+	if (!valid) report(reader, {
+		path: `${path}.literal`,
+		message: "expected number, string or boolean"
+	});
+	return {
+		source: readEnum(reader, {
+			record,
+			key: "source",
+			path
+		}, SOURCES) ?? "payload",
+		path: readString(reader, {
+			record,
+			key: "path",
+			path
+		}),
+		operator: readEnum(reader, {
+			record,
+			key: "operator",
+			path
+		}, OPERATORS) ?? "===",
+		literal: valid ? literal : 0
+	};
+}
+function readLiterals(reader, record, path) {
+	const value = record["literals"];
+	if (Array.isArray(value) && value.every((item) => typeof item === "number" || typeof item === "string")) return value.filter((item) => typeof item === "number" || typeof item === "string");
+	report(reader, {
+		path: `${path}.literals`,
+		message: "expected (number | string)[]"
+	});
+	return [];
+}
+function readAnalyzed(reader, record, path) {
+	const location = record["location"];
+	return {
+		status: "analyzed",
+		location: isRecord(location) ? readLocation(reader, location, `${path}.location`) : readLocation(reader, {}, `${path}.location`),
+		registration: readEnum(reader, {
+			record,
+			key: "registration",
+			path
+		}, ["on", "onAny"]) ?? "on",
+		branches: readList(reader, {
+			record,
+			key: "branches",
+			path
+		}, (item, at) => readBranch(reader, item, at)),
+		payloadReads: readStrings(reader, {
+			record,
+			key: "payloadReads",
+			path
+		}),
+		contextReads: readStrings(reader, {
+			record,
+			key: "contextReads",
+			path
+		}),
+		contextWrites: readStrings(reader, {
+			record,
+			key: "contextWrites",
+			path
+		}),
+		readsActorState: readBoolean(reader, {
+			record,
+			key: "readsActorState",
+			path
+		}),
+		comparisons: readList(reader, {
+			record,
+			key: "comparisons",
+			path
+		}, (item, at) => readComparison(reader, item, at)),
+		literals: readLiterals(reader, record, path)
+	};
+}
+function readExplanation(reader, at) {
+	const value = at.record["explanation"];
+	const path = `${at.path}.explanation`;
+	if (value === null) return null;
+	if (!isRecord(value)) {
+		report(reader, {
+			path,
+			message: "expected null or object"
+		});
+		return null;
+	}
+	if (readEnum(reader, {
+		record: value,
+		key: "status",
+		path
+	}, ["analyzed", "not_analyzed"]) === "analyzed") return readAnalyzed(reader, value, path);
+	return {
+		status: "not_analyzed",
+		location: readNullableLocation(reader, value, path),
+		reason: readString(reader, {
+			record: value,
+			key: "reason",
+			path
+		}),
+		snippet: readNullableString(reader, {
+			record: value,
+			key: "snippet",
+			path
+		})
+	};
+}
+// src/validate-fuzz.ts
+function readStep(reader, record, path) {
+	if (record["kind"] === "advance") return {
+		kind: "advance",
+		ms: readInteger(reader, {
+			record,
+			key: "ms",
+			path
+		})
+	};
+	if (record["kind"] !== "event") report(reader, {
+		path: `${path}.kind`,
+		message: "expected event or advance"
+	});
+	return {
+		kind: "event",
+		event: readString(reader, {
+			record,
+			key: "event",
+			path
+		}),
+		payload: readJson(reader, {
+			record,
+			key: "payload",
+			path
+		})
+	};
+}
+function readSteps(reader, record, path) {
+	return readList(reader, {
+		record,
+		key: "steps",
+		path
+	}, (item, at) => readStep(reader, item, at));
+}
+function readSequence(reader, record, path) {
+	return {
+		steps: readSteps(reader, record, path),
+		discovered: readStrings(reader, {
+			record,
+			key: "discovered",
+			path
+		})
+	};
+}
+function readError(reader, record, path) {
+	return {
+		from: readString(reader, {
+			record,
+			key: "from",
+			path
+		}),
+		event: readString(reader, {
+			record,
+			key: "event",
+			path
+		}),
+		message: readString(reader, {
+			record,
+			key: "message",
+			path
+		}),
+		steps: readSteps(reader, record, path)
+	};
+}
+function readFuzz(reader, at) {
+	const value = at.record["fuzz"];
+	if (value === null) return null;
+	const path = `${at.path}.fuzz`;
+	if (!isRecord(value)) {
+		report(reader, {
+			path,
+			message: "expected null or object"
+		});
+		return null;
+	}
+	return {
+		seed: readInteger(reader, {
+			record: value,
+			key: "seed",
+			path
+		}),
+		iterations: readInteger(reader, {
+			record: value,
+			key: "iterations",
+			path
+		}),
+		corpus: readList(reader, {
+			record: value,
+			key: "corpus",
+			path
+		}, (item, itemPath) => readSequence(reader, item, itemPath)),
+		errors: readList(reader, {
+			record: value,
+			key: "errors",
+			path
+		}, (item, itemPath) => readError(reader, item, itemPath))
+	};
+}
+// src/validate.ts
+const EDGE_KINDS = [
+	"initial",
+	"transition",
+	"effect",
+	"stay"
+];
+const EDGE_ORIGINS = [
+	"declared",
+	"probe",
+	"fuzz"
+];
+function readState(reader, record, path) {
+	return {
+		id: readString(reader, {
+			record,
+			key: "id",
+			path
+		}),
+		label: readString(reader, {
+			record,
+			key: "label",
+			path
+		}),
+		region: readNullableString(reader, {
+			record,
+			key: "region",
+			path
+		}),
+		initial: readBoolean(reader, {
+			record,
+			key: "initial",
+			path
+		}),
+		final: readBoolean(reader, {
+			record,
+			key: "final",
+			path
+		}),
+		effects: readList(reader, {
+			record,
+			key: "effects",
+			path
+		}, (item, at) => ({
+			name: readString(reader, {
+				record: item,
+				key: "name",
+				path: at
+			}),
+			sends: readNullableStrings(reader, {
+				record: item,
+				key: "sends",
+				path: at
+			})
+		})),
+		coverage: readCoverage(reader, {
+			record,
+			key: "coverage",
+			path
+		}),
+		tested: readCoverage(reader, {
+			record,
+			key: "tested",
+			path
+		})
+	};
+}
+function readEvent(reader, record, path) {
+	if (record["payloadType"] !== null) report(reader, {
+		path: `${path}.payloadType`,
+		message: "expected null"
+	});
+	return {
+		id: readString(reader, {
+			record,
+			key: "id",
+			path
+		}),
+		internal: readBoolean(reader, {
+			record,
+			key: "internal",
+			path
+		}),
+		payloadType: null
+	};
+}
+function readEdge(reader, record, path) {
+	return {
+		id: readString(reader, {
+			record,
+			key: "id",
+			path
+		}),
+		from: readString(reader, {
+			record,
+			key: "from",
+			path
+		}),
+		event: readString(reader, {
+			record,
+			key: "event",
+			path
+		}),
+		to: readNullableString(reader, {
+			record,
+			key: "to",
+			path
+		}),
+		kind: readEnum(reader, {
+			record,
+			key: "kind",
+			path
+		}, EDGE_KINDS) ?? "transition",
+		origin: readEnum(reader, {
+			record,
+			key: "origin",
+			path
+		}, EDGE_ORIGINS) ?? "probe",
+		emits: readStrings(reader, {
+			record,
+			key: "emits",
+			path
+		}),
+		contexts: readStrings(reader, {
+			record,
+			key: "contexts",
+			path
+		}),
+		explanation: readExplanation(reader, {
+			record,
+			path
+		}),
+		coverage: readCoverage(reader, {
+			record,
+			key: "coverage",
+			path
+		}),
+		tested: readCoverage(reader, {
+			record,
+			key: "tested",
+			path
+		})
+	};
+}
+/** Edge endpoints must name declared states; a dangling reference is a broken document. */
+function checkReferences(reader, machine, path) {
+	const stateIds = new Set(machine.states.map((state) => state.id));
+	const known = (id) => stateIds.has(id) || id === "__initial__" || isAnyState(id);
+	machine.edges.forEach((edge, index) => {
+		if (!known(edge.from)) report(reader, {
+			path: `${path}.edges[${index}].from`,
+			message: `unknown state ${edge.from}`
+		});
+		const anyStay = edge.kind === "stay" && edge.to === edge.from && isAnyState(edge.from);
+		if (edge.to !== null && !stateIds.has(edge.to) && !anyStay) report(reader, {
+			path: `${path}.edges[${index}].to`,
+			message: `unknown state ${edge.to}`
+		});
+	});
+	if (machine.initial !== null && !stateIds.has(machine.initial)) report(reader, {
+		path: `${path}.initial`,
+		message: `unknown state ${machine.initial}`
+	});
+}
+function readMachine(reader, record, path) {
+	const machine = {
+		id: readString(reader, {
+			record,
+			key: "id",
+			path
+		}),
+		initial: readNullableString(reader, {
+			record,
+			key: "initial",
+			path
+		}),
+		regions: readStrings(reader, {
+			record,
+			key: "regions",
+			path
+		}),
+		states: readList(reader, {
+			record,
+			key: "states",
+			path
+		}, (item, at) => readState(reader, item, at)),
+		events: readList(reader, {
+			record,
+			key: "events",
+			path
+		}, (item, at) => readEvent(reader, item, at)),
+		edges: readList(reader, {
+			record,
+			key: "edges",
+			path
+		}, (item, at) => readEdge(reader, item, at)),
+		fuzz: readFuzz(reader, {
+			record,
+			path
+		})
+	};
+	checkReferences(reader, machine, path);
+	return machine;
+}
+/**
+* Read an untrusted value (parsed JSON) as an viz document. Returns every
+* issue found, not just the first, so a broken file can be fixed in one pass.
+*/
+function validateViz(value) {
+	const reader = { issues: [] };
+	if (!isRecord(value)) return Either.left([{
+		path: "$",
+		message: "expected object"
+	}]);
+	if (value["schemaVersion"] !== 7) return Either.left([{
+		path: "$.schemaVersion",
+		message: `expected 7, got ${JSON.stringify(value["schemaVersion"])}`
+	}]);
+	const machines = readList(reader, {
+		record: value,
+		key: "machines",
+		path: "$"
+	}, (item, at) => readMachine(reader, item, at));
+	if (reader.issues.length > 0) return Either.left(reader.issues);
+	const document = {
+		schemaVersion: 7,
+		machines
+	};
+	return Either.right(document);
+}
+/** Parse JSON text and validate it. JSON syntax errors become an issue at `$`. */
+function parseViz(text) {
+	const parsed = Either.from(() => JSON.parse(text));
+	if (Either.isLeft(parsed)) {
+		const reason = parsed[0] instanceof Error ? parsed[0].message : String(parsed[0]);
+		return Either.left([{
+			path: "$",
+			message: `invalid JSON: ${reason}`
+		}]);
+	}
+	return validateViz(parsed[1]);
+}
+// src/moves.ts
+const GROUP_ORDER = {
+	input: 0,
+	effect: 1,
+	internal: 2
+};
+function targetsOf(edge, current) {
+	if (edge.kind === "stay") return [current];
+	if (edge.to !== null) return [edge.to];
+	if (edge.explanation?.status !== "analyzed") return [];
+	const targets = edge.explanation.branches.flatMap((branch) => {
+		if (branch.target.kind === "state") return [branch.target.state];
+		return branch.target.kind === "stay" ? [current] : [];
+	});
+	return [...new Set(targets)].sort();
+}
+function sendersOf(machine, state) {
+	const senders = /* @__PURE__ */ new Map();
+	const effects = machine.states.find((each) => each.id === state)?.effects ?? [];
+	for (const effect of effects) for (const sent of effect.sends ?? []) senders.set(sent, [...senders.get(sent) ?? [], effect.name]);
+	return senders;
+}
+/**
+* Every edge an event can take out of `state`: its own registrations and the
+* `onAny` ones. A final state has none: the actor has stopped.
+*/
+function movesFrom(machine, state) {
+	const current = machine.states.find((each) => each.id === state);
+	if (current === void 0 || current.final) return [];
+	const internal = new Set(machine.events.filter((each) => each.internal).map((each) => each.id));
+	const senders = sendersOf(machine, state);
+	return machine.edges.filter((edge) => (edge.kind === "transition" || edge.kind === "stay") && (edge.from === state || coveredByAny(edge.from, state))).map((edge) => {
+		const sentBy = senders.get(edge.event) ?? [];
+		const group = !internal.has(edge.event) ? "input" : sentBy.length > 0 ? "effect" : "internal";
+		return {
+			edge,
+			targets: targetsOf(edge, state),
+			group,
+			sentBy
+		};
+	}).sort((left, right) => GROUP_ORDER[left.group] - GROUP_ORDER[right.group] || left.edge.event.localeCompare(right.edge.event) || left.edge.id.localeCompare(right.edge.id));
+}
+/** Where a path ends: the last step's target, or the initial state. */
+function stateAfter(machine, path) {
+	return path.at(-1)?.to ?? machine.initial;
+}
+/** Events an effect of `state` declares in `sends` that no handler in `state` takes. */
+function unhandledSends(machine, state) {
+	const handled = new Set(movesFrom(machine, state).map((move) => move.edge.event));
+	return (machine.states.find((each) => each.id === state)?.effects ?? []).flatMap((effect) => (effect.sends ?? []).filter((event) => !handled.has(event)).map((event) => ({
+		effect: effect.name,
+		event
+	})));
+}
+/** One step as text for a URL: the edge id, plus `~target` when the edge has no single target. */
+function encodeStep(machine, step) {
+	const edge = machine.edges.find((each) => each.id === step.edge);
+	return edge !== void 0 && edge.to === null && edge.kind !== "stay" ? `${step.edge}~${step.to}` : step.edge;
+}
+/**
+* Rebuild a path from encoded steps (e.g. `?step=` in a shared link). Stops at
+* the first step the graph does not allow from where the path has got to, so
+* a link from an older document still opens at its last valid point.
+*/
+function decodePath(machine, encoded) {
+	const path = [];
+	for (const text of encoded) {
+		const cut = text.lastIndexOf("~");
+		const edgeId = cut === -1 ? text : text.slice(0, cut);
+		const from = stateAfter(machine, path);
+		const move = from === null ? void 0 : movesFrom(machine, from).find((each) => each.edge.id === edgeId);
+		const to = cut === -1 && move?.targets.length === 1 ? move.targets[0] : text.slice(cut + 1);
+		if (move === void 0 || to === void 0 || !move.targets.includes(to)) break;
+		path.push({
+			edge: edgeId,
+			to
+		});
+	}
+	return path;
+}
+// src/routing.ts
+/**
+* `onAny` handlers that pick their target from the current state. Drawn from
+* `*`, they claim every declared target from every state; per-state `m.on`
+* registrations would draw the exact source/target pairs.
+*/
+function routingWarnings(machine) {
+	return [...new Set(machine.edges.filter((edge) => isAnyState(edge.from) && edge.explanation?.status === "analyzed" && edge.explanation.readsActorState).map((edge) => edge.event))].sort().map((event) => ({
+		machine: machine.id,
+		event,
+		message: `onAny(${event}) reads actor state to pick its target, so the diagram cannot tell which state leads where. Register m.on per state instead.`
+	}));
+}
+export { stateAfter as a, validateViz as c, coveredByAny as d, isAnyState as f, movesFrom as i, ANY_STATE as l, decodePath as n, unhandledSends as o, scopeOf as p, encodeStep as r, parseViz as s, routingWarnings as t, VIZ_SCHEMA_VERSION as u };