@mantaq/inspect 0.0.0 → 0.2.0

package/dist/page-rr9IQ-4k.mjs

@@ -0,0 +1,38 @@
+import { serializeViz, standaloneHtml } from "@mantaq/viz";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { build } from "vite";
+// src/page.ts
+/** The viewer as one classic script, built from `@mantaq/viz/standalone`, plus its stylesheets. */
+async function viewerBundle() {
+	const entry = fileURLToPath(import.meta.resolve("@mantaq/viz/standalone"));
+	const output = await build({
+		configFile: false,
+		logLevel: "silent",
+		build: {
+			write: false,
+			minify: true,
+			cssCodeSplit: false,
+			lib: {
+				entry,
+				formats: ["iife"],
+				name: "MantaqViz",
+				fileName: () => "viz.js"
+			}
+		}
+	});
+	return {
+		script: (Array.isArray(output) ? output : [output]).flatMap((each) => "output" in each ? each.output : []).flatMap((file) => file.type === "chunk" ? [file.code] : []).join("\n"),
+		css: ["@mantaq/viz/viewer.css", "@mantaq/viz/page.css"].map((id) => readFileSync(fileURLToPath(import.meta.resolve(id)), "utf8")).join("\n")
+	};
+}
+/** A self-contained HTML page for `document`: open it from disk, attach it, commit it. */
+async function htmlPage(document, title) {
+	const bundle = await viewerBundle();
+	return standaloneHtml({
+		title,
+		...bundle,
+		document: serializeViz(document)
+	});
+}
+export { htmlPage as t };

package/dist/run-B5huYj_r.mjs

@@ -0,0 +1,117 @@
+import { Either } from "@mantaq/utils";
+// src/fuzz/run.ts
+const ERROR_STATE = "__error";
+function eventTypes(options, key) {
+	if (typeof options !== "object" || options === null) return [];
+	const list = Reflect.get(options, key);
+	if (!Array.isArray(list)) return [];
+	return list.flatMap((entry) => {
+		if (typeof entry !== "object" || entry === null) return [];
+		const type = Reflect.get(entry, "type");
+		return typeof type === "string" ? [type] : [];
+	});
+}
+/** Declared inputs and internal events, each sorted. */
+function eventCatalog(actor) {
+	return {
+		inputs: eventTypes(actor.options, "inputs").sort(),
+		internal: eventTypes(actor.options, "internal").sort()
+	};
+}
+/** onAny handlers live under this key in the dispatch map (core builder). */
+const ANY_KEY = "Any";
+function handles(actor, event) {
+	const transitions = actor.options?.transitions;
+	return transitions?.[actor.state.name]?.[event] !== void 0 || transitions?.[ANY_KEY]?.[event] !== void 0;
+}
+function toEvent(step) {
+	return step.payload === null ? { type: step.event } : {
+		type: step.event,
+		payload: step.payload
+	};
+}
+function messageOf(error) {
+	return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+function featuresOf(trace) {
+	const features = /* @__PURE__ */ new Set();
+	for (const state of trace.visited) features.add(`state:${state}`);
+	for (const seen of trace.observations) features.add(seen.transitioned ? `edge:${seen.from}>${seen.event}>${seen.to}` : `stay:${seen.from}>${seen.event}`);
+	for (const error of trace.errors) features.add(`error:${error.from}>${error.event}`);
+	return [...features].sort();
+}
+/** JSON text of the context, or null when it is not serializable (functions, cycles). */
+function contextText(actor) {
+	const text = Either.from(() => JSON.stringify(actor.context ?? null));
+	return Either.isRight(text) ? text[1] : null;
+}
+function parsed(text) {
+	return text === null ? null : JSON.parse(text);
+}
+/** The one step function: the fuzzer and the live driver both apply steps through it. */
+function applyStep(actor, context) {
+	const { step } = context;
+	if (step.kind === "advance") context.clock.advance(step.ms);
+	else if (context.internal.has(step.event)) {
+		if (handles(actor, step.event)) actor.inject(toEvent(step));
+	} else actor.send(toEvent(step));
+}
+/**
+* Replay steps against a fresh actor. Synchronous and deterministic: effects
+* only run via the virtual clock, and nothing here reads wall time.
+*/
+function execute(target, steps) {
+	const { actor, clock } = target.create();
+	const internal = new Set(eventCatalog(actor).internal);
+	const visited = [actor.state.name];
+	const observations = [];
+	const errors = [];
+	const contextSteps = [];
+	let index = 0;
+	actor.on("transition", { fn: ({ event, from, to, transitioned, effects }) => {
+		const context = parsed(contextText(actor));
+		observations.push({
+			from,
+			event: event.type,
+			to,
+			transitioned,
+			effects,
+			step: index,
+			payload: event.payload,
+			context
+		});
+		if (transitioned) visited.push(to);
+	} });
+	actor.on("error", { fn: (info) => {
+		errors.push({
+			from: info.state.name,
+			event: info.event.type,
+			message: messageOf(info.error),
+			step: index
+		});
+	} });
+	for (const step of steps) {
+		if (actor.state.name === ERROR_STATE) break;
+		const before = contextText(actor);
+		applyStep(actor, {
+			step,
+			clock,
+			internal
+		});
+		if (contextText(actor) !== before) contextSteps.push(index);
+		index += 1;
+	}
+	actor.dispose();
+	return {
+		visited,
+		observations,
+		errors,
+		contextSteps,
+		features: featuresOf({
+			visited,
+			observations,
+			errors
+		})
+	};
+}
+export { messageOf as a, execute as i, contextText as n, parsed as o, eventCatalog as r, applyStep as t };

package/dist/run-BLt0mwXe.d.mts

@@ -0,0 +1,60 @@
+import { VizJson, VizStep } from "@mantaq/viz";
+import { AnyActor, VirtualClock } from "@mantaq/core";
+/** A machine the fuzzer can drive: a fresh actor plus the virtual clock it runs on. */
+interface FuzzTarget {
+  id: string;
+  create(): {
+    actor: AnyActor<unknown>;
+    clock: VirtualClock;
+  };
+  /**
+   * Sample payloads per event type. Payload types are erased at runtime, so
+   * the fuzzer only mutates shapes it was given. Events without samples are
+   * sent without a payload.
+   */
+  payloads?: Readonly<Record<string, ReadonlyArray<VizJson>>>;
+}
+interface Observation {
+  from: string;
+  event: string;
+  to: string;
+  transitioned: boolean;
+  /** Names of the effects that ran on entry into `to`. */
+  effects: string[];
+  /** Index of the step that caused it. */
+  step: number;
+  /** Payload the handler received (for branch-distance guidance). */
+  payload: unknown;
+  /** JSON copy of the actor context right after the handler ran; null if not JSON. */
+  context: unknown;
+}
+interface RunError {
+  from: string;
+  event: string;
+  message: string;
+  /** Index of the step that triggered it. */
+  step: number;
+}
+interface Trace {
+  visited: string[];
+  observations: Observation[];
+  errors: RunError[];
+  /** Indices of steps after which the actor context differed: loop candidates. */
+  contextSteps: number[];
+  /**
+   * Coverage features, sorted: `state:x`, `edge:a>e>b` (state changed or
+   * re-entered), `stay:a>e` (handled, no change), `error:a>e` (handler threw).
+   */
+  features: string[];
+}
+/** Declared inputs and internal events, each sorted. */
+declare function eventCatalog(actor: AnyActor<unknown>): {
+  inputs: string[];
+  internal: string[];
+};
+/**
+ * Replay steps against a fresh actor. Synchronous and deterministic: effects
+ * only run via the virtual clock, and nothing here reads wall time.
+ */
+declare function execute(target: FuzzTarget, steps: ReadonlyArray<VizStep>): Trace;
+export { eventCatalog as a, Trace as i, Observation as n, execute as o, RunError as r, FuzzTarget as t };

package/dist/vite.d.mts

@@ -0,0 +1,11 @@
+import { t as FuzzSettings } from "./inspect-DvQtAcwv.mjs";
+import { Plugin } from "vite";
+export interface MantaqVizOptions {
+  /** Files that export machines: paths or globs, relative to the Vite root. */
+  machines: string | string[];
+  /** Where the page is served. Default `/__mantaq/`. */
+  base?: string;
+  /** `false` = structure only. Default: 500 iterations, so a save redraws quickly. */
+  fuzz?: false | FuzzSettings;
+}
+export declare function mantaqViz(options: MantaqVizOptions): Plugin[];

package/dist/vite.mjs

@@ -0,0 +1,159 @@
+import { c as projectRoot, i as runOf, l as vizDocument, n as inspectEntry, s as machineId, t as entryId, u as analyzeModule } from "./load-DOwsxTyL.mjs";
+import { UPDATE_EVENT, livePageHtml, serializeViz } from "@mantaq/viz";
+import { Either } from "@mantaq/utils";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { globSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { searchForWorkspaceRoot } from "vite";
+// src/vite.ts
+/**
+* Vite plugin: a live page of your machines on your own dev server.
+*
+*   // vite.config.ts
+*   import { mantaqViz } from "@mantaq/inspect/vite";
+*   export default defineConfig({ plugins: [mantaqViz({ machines: "src/**\/*.machine.ts" })] });
+*
+* Open `/__mantaq/` while the dev server runs. Machines load through your own
+* Vite config (aliases, tsconfig paths), are inspected on the server, and the
+* page redraws, keeping the walk, when you save a file.
+*/
+const STYLESHEETS = ["@mantaq/viz/viewer.css", "@mantaq/viz/page.css"];
+const DEV_ITERATIONS = 500;
+const TARGETS = "virtual:mantaq/targets";
+const TARGETS_RESOLVED = `\0${TARGETS}`;
+function createExpression(found, index) {
+	const callee = `m${index}[${JSON.stringify(found.name)}]`;
+	const call = found.call === "clock" ? `${callee}(VirtualClock())` : found.call === "options" ? `${callee}({ clock: VirtualClock() })` : `${callee}()`;
+	return found.unwrap === "actor" ? `${call}.actor` : call;
+}
+/**
+* Source of `virtual:mantaq/targets`: one factory per exported actor factory,
+* shaped by its type (`call`, `clock`, `options`). A bare actor export cannot
+* be recreated, so it gets none. Like the server-side inspection, plain actors
+* are skipped when a file has factories.
+*/
+function targetsSource(files) {
+	const core = fileURLToPath(import.meta.resolve("@mantaq/core"));
+	const imports = [];
+	const entries = [];
+	files.forEach((file, index) => {
+		const analysis = analyzeModule({
+			file,
+			root: projectRoot(file)
+		});
+		if (Either.isLeft(analysis)) return;
+		const factories = analysis[1].machines.filter((found) => found.call !== "instance");
+		if (factories.length === 0) return;
+		imports.push(`import * as m${index} from ${JSON.stringify(file)};`);
+		for (const found of factories) entries.push(`  ${JSON.stringify(machineId(found.name))}: () => { const actor = ${createExpression(found, index)}; return { actor, clock: actor.clock }; },`);
+	});
+	return [
+		`import { VirtualClock } from ${JSON.stringify(core)};`,
+		...imports,
+		"export const targets = {",
+		...entries,
+		"};"
+	].join("\n");
+}
+function machineFiles(root, patterns) {
+	const files = patterns.flatMap((pattern) => globSync(pattern, { cwd: root }));
+	return [...new Set(files.map((file) => isAbsolute(file) ? file : resolve(root, file)))].sort();
+}
+async function documentText(server, context) {
+	const results = [];
+	for (const file of context.files) {
+		const run = runOf(await server.ssrLoadModule(entryId(file)));
+		results.push(run === null ? {
+			machines: [],
+			warnings: [`${file}: could not load the inspector`]
+		} : await run({ fuzz: context.fuzz }));
+	}
+	return {
+		text: serializeViz(vizDocument(results.flatMap((result) => result.machines))),
+		warnings: results.flatMap((result) => result.warnings)
+	};
+}
+function mantaqViz(options) {
+	const base = (options.base ?? "/__mantaq/").replace(/\/?$/, "/");
+	const patterns = Array.isArray(options.machines) ? options.machines : [options.machines];
+	const fuzz = options.fuzz ?? { iterations: DEV_ITERATIONS };
+	const live = fileURLToPath(import.meta.resolve(import.meta.url.endsWith(".ts") ? "./live-entry.ts" : "./live-entry.mjs"));
+	const viz = dirname(dirname(fileURLToPath(import.meta.resolve("@mantaq/viz/live"))));
+	let root = process.cwd();
+	return [
+		inspectEntry(),
+		{
+			name: "mantaq-viz-targets",
+			apply: "serve",
+			configResolved: (config) => {
+				root = config.root;
+			},
+			resolveId: (id) => id === TARGETS ? TARGETS_RESOLVED : null,
+			load: (id) => id === TARGETS_RESOLVED ? targetsSource(machineFiles(root, patterns)) : null
+		},
+		{
+			name: "mantaq-viz",
+			apply: "serve",
+			config: (config) => ({ server: { fs: { allow: [
+				searchForWorkspaceRoot(config.root ?? process.cwd()),
+				dirname(dirname(live)),
+				viz
+			] } } }),
+			configureServer(server) {
+				let cached = null;
+				const build = async () => {
+					const { text, warnings } = await documentText(server, {
+						files: machineFiles(server.config.root, patterns),
+						fuzz
+					});
+					for (const warning of warnings) server.config.logger.warn(`[mantaq-viz] ${warning}`);
+					return text;
+				};
+				server.watcher.on("all", (_event, path) => {
+					if (!/\.[cm]?[jt]sx?$/.test(path)) return;
+					cached = null;
+					const generated = server.moduleGraph.getModuleById(TARGETS_RESOLVED);
+					if (generated !== void 0) server.moduleGraph.invalidateModule(generated);
+					server.environments.ssr.moduleGraph.invalidateAll();
+					server.ws.send({
+						type: "custom",
+						event: UPDATE_EVENT
+					});
+				});
+				server.middlewares.use((request, response, next) => {
+					const path = request.url?.split("?")[0];
+					if (path === `${base}viz.json`) {
+						cached ??= build();
+						cached.then((text) => {
+							response.setHeader("content-type", "application/json");
+							response.end(text);
+						}, (error) => {
+							cached = null;
+							response.statusCode = 500;
+							response.end(String(error));
+						});
+						return;
+					}
+					if (path !== base && path !== base.slice(0, -1)) {
+						next();
+						return;
+					}
+					const html = livePageHtml({
+						title: "mantaq viz",
+						source: `${base}viz.json`,
+						entry: `/@fs${live}`,
+						css: STYLESHEETS.map((id) => readFileSync(fileURLToPath(import.meta.resolve(id)), "utf8")).join("\n")
+					});
+					server.transformIndexHtml(request.url ?? base, html).then((page) => {
+						response.setHeader("content-type", "text/html");
+						response.end(page);
+					});
+				});
+				server.httpServer?.once("listening", () => {
+					server.config.logger.info(`  mantaq viz: ${base}`);
+				});
+			}
+		}
+	];
+}
+export { mantaqViz };

package/package.json

@@ -1,7 +1,55 @@
 {
   "name": "@mantaq/inspect",
-  "version": "0.0.0",
-  "description": "Placeholder to enable npm trusted publishing.",
-  "repository": { "type": "git", "url": "git+https://github.com/AndersCan/mantaq.git" },
-  "license": "MIT"
-}
+  "version": "0.2.0",
+  "description": "Turn a Mantaq machine into a viz document: structure, handler explanations (AST), fuzz and test coverage. CLI and Vite plugin included.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AndersCan/mantaq",
+    "directory": "packages/inspect"
+  },
+  "bin": {
+    "mantaq-inspect": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./drive": "./dist/drive.mjs",
+    "./live-entry": "./dist/live-entry.mjs",
+    "./vite": "./dist/vite.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "typescript": "6.0.3",
+    "@mantaq/core": "0.5.1",
+    "@mantaq/pbt": "0.0.3",
+    "@mantaq/traversal": "0.3.1",
+    "@mantaq/utils": "0.0.4",
+    "@mantaq/viz": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "happy-dom": "^21.0.4",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0",
+    "vite-plus": "1.4.0",
+    "@mantaq/sugar": "2.0.1"
+  },
+  "peerDependencies": {
+    "vite": "*"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "viz:export": "node src/examples-cli.ts export",
+    "viz:compare": "node src/examples-cli.ts compare"
+  }
+}