@temelj/workflow 0.0.0-alpha.1

package/dist/vite/plugin.d.mts

@@ -0,0 +1,7 @@
+import { VitePluginOptions, WorkflowPluginOptions } from "../types/vite.mjs";
+//#region src/vite/plugin.d.ts
+declare const workflowPlugin: import("unplugin").UnpluginInstance<WorkflowPluginOptions | undefined, false>;
+/** Creates the Vite plugin that compiles workflow and step directives. */
+declare const workflow: (options?: VitePluginOptions) => ReturnType<typeof workflowPlugin.vite>;
+//#endregion
+export { type VitePluginOptions, type WorkflowPluginOptions, workflow, workflowPlugin };

package/dist/vite/plugin.mjs

@@ -0,0 +1,190 @@
+import { stripQuery } from "./source.mjs";
+import { parseWorkflowSource } from "./ast.mjs";
+import { transformWorkflowSource } from "./transform.mjs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createUnplugin } from "unplugin";
+//#region src/vite/plugin.ts
+const workflowUnpluginFactory = (options = {}) => {
+	const include = options.include?.map((pattern) => new RegExp(pattern));
+	const exclude = options.exclude?.map((pattern) => new RegExp(pattern));
+	const manifests = /* @__PURE__ */ new Map();
+	const manifestFileById = /* @__PURE__ */ new Map();
+	const loadingManifests = /* @__PURE__ */ new Set();
+	return {
+		name: "temelj-workflow",
+		enforce: "pre",
+		transformInclude(id) {
+			return matchesFilters(id, include, exclude);
+		},
+		async transform(code, id) {
+			await loadWorkflowImportManifests({
+				context: this,
+				code,
+				id,
+				options,
+				include,
+				exclude,
+				manifests,
+				manifestFileById,
+				loadingManifests
+			});
+			const result = transformAndStoreWorkflowManifest(code, id, options, manifests, manifestFileById);
+			if (result === void 0) return null;
+			return {
+				code: result.code,
+				...result.map === void 0 ? {} : { map: toUnpluginSourceMap(result.map) }
+			};
+		},
+		vite: { handleHotUpdate(context) {
+			if (!matchesFilters(context.file, include, exclude)) return;
+			const modules = context.modules.filter((module) => module.id !== null);
+			if (modules.length === 0) return;
+			return modules;
+		} }
+	};
+};
+const JS_TS_EXTENSION_PATTERN = /\.[cm]?[jt]sx?$/;
+function toUnpluginSourceMap(map) {
+	return map;
+}
+const workflowPlugin = createUnplugin(workflowUnpluginFactory);
+/** Creates the Vite plugin that compiles workflow and step directives. */
+const workflow = workflowPlugin.vite;
+async function loadWorkflowImportManifests({ context, code, id, options, include, exclude, manifests, manifestFileById, loadingManifests }) {
+	if (!hasWorkflowManifestCandidate(code) || loadingManifests.has(id)) return;
+	loadingManifests.add(id);
+	try {
+		for (const source of collectRelativeImportSources(code, id)) if (canLoadWorkflowImportManifests(context)) {
+			const resolved = await context.resolve(source, id, { skipSelf: true });
+			if (resolved === null || !matchesFilters(resolved.id, include, exclude)) continue;
+			await context.load({ id: resolved.id });
+			await preloadWorkflowImportFile({
+				context,
+				id: resolved.id,
+				options,
+				include,
+				exclude,
+				manifests,
+				manifestFileById,
+				loadingManifests
+			});
+		} else {
+			const resolved = await resolveRelativeImportFile(source, id);
+			if (resolved === void 0 || !matchesFilters(resolved, include, exclude)) continue;
+			await preloadWorkflowImportFile({
+				context,
+				id: resolved,
+				options,
+				include,
+				exclude,
+				manifests,
+				manifestFileById,
+				loadingManifests
+			});
+		}
+	} finally {
+		loadingManifests.delete(id);
+	}
+}
+async function preloadWorkflowImportFile({ context, id, options, include, exclude, manifests, manifestFileById, loadingManifests }) {
+	const cleanId = stripQuery(id);
+	const importedCode = await fs.readFile(cleanId, "utf8").catch(() => void 0);
+	if (importedCode === void 0) return;
+	await loadWorkflowImportManifests({
+		context,
+		code: importedCode,
+		id: cleanId,
+		options,
+		include,
+		exclude,
+		manifests,
+		manifestFileById,
+		loadingManifests
+	});
+	transformAndStoreWorkflowManifest(importedCode, cleanId, options, manifests, manifestFileById);
+}
+function transformAndStoreWorkflowManifest(code, id, options, manifests, manifestFileById) {
+	const result = transformWorkflowSource(code, id, {
+		...options,
+		manifests: [...options.manifests ?? [], ...manifests.values()]
+	});
+	if (result === void 0) {
+		manifests.delete(id);
+		const previousFile = manifestFileById.get(id);
+		if (previousFile !== void 0) {
+			manifests.delete(previousFile);
+			manifestFileById.delete(id);
+		}
+		return;
+	}
+	manifests.set(id, result.manifest);
+	manifests.set(result.manifest.file, result.manifest);
+	manifestFileById.set(id, result.manifest.file);
+	return result;
+}
+function canLoadWorkflowImportManifests(context) {
+	return typeof context.resolve === "function" && typeof context.load === "function";
+}
+function hasWorkflowManifestCandidate(code) {
+	return code.includes("\"use workflow\"") || code.includes("'use workflow'") || code.includes("\"use step\"") || code.includes("'use step'") || code.includes(" from ");
+}
+function collectRelativeImportSources(code, id) {
+	if (!JS_TS_EXTENSION_PATTERN.test(stripQuery(id))) return [];
+	const sourceFile = parseWorkflowSource(id, code);
+	const sources = /* @__PURE__ */ new Set();
+	for (const statement of sourceFile.program.body) if ((statement.type === "ImportDeclaration" || statement.type === "ExportNamedDeclaration" || statement.type === "ExportAllDeclaration") && statement.source !== null && isRelativeImportSource(statement.source.value)) sources.add(statement.source.value);
+	return [...sources];
+}
+function isRelativeImportSource(source) {
+	return source.startsWith("./") || source.startsWith("../");
+}
+const RELATIVE_IMPORT_EXTENSIONS = [
+	"",
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs",
+	"/index.ts",
+	"/index.tsx",
+	"/index.mts",
+	"/index.cts",
+	"/index.js",
+	"/index.jsx",
+	"/index.mjs",
+	"/index.cjs"
+];
+async function resolveRelativeImportFile(source, importer) {
+	const cleanImporter = stripQuery(importer);
+	const base = path.resolve(path.dirname(cleanImporter), source);
+	for (const candidate of relativeImportCandidates(base)) if ((await fs.stat(candidate).catch(() => void 0))?.isFile() === true) return candidate;
+}
+function relativeImportCandidates(base) {
+	const candidates = RELATIVE_IMPORT_EXTENSIONS.map((extension) => `${base}${extension}`);
+	const extension = path.extname(base);
+	const mappedExtensions = ESM_SOURCE_EXTENSION_BY_IMPORT_EXTENSION.get(extension);
+	if (mappedExtensions === void 0) return candidates;
+	const withoutExtension = base.slice(0, -extension.length);
+	return [
+		base,
+		...mappedExtensions.map((mappedExtension) => `${withoutExtension}${mappedExtension}`),
+		...candidates.slice(1)
+	];
+}
+const ESM_SOURCE_EXTENSION_BY_IMPORT_EXTENSION = /* @__PURE__ */ new Map([
+	[".js", [".ts", ".tsx"]],
+	[".jsx", [".tsx"]],
+	[".mjs", [".mts"]],
+	[".cjs", [".cts"]]
+]);
+function matchesFilters(id, include, exclude) {
+	if (exclude?.some((pattern) => pattern.test(id)) === true) return false;
+	if (include !== void 0 && !include.some((pattern) => pattern.test(id))) return false;
+	return true;
+}
+//#endregion
+export { workflow, workflowPlugin };

package/dist/vite/safety.d.mts

@@ -0,0 +1,12 @@
+import { FunctionBody, Program } from "oxc-parser";
+//#region src/vite/safety.d.ts
+interface WorkflowSafetyTarget {
+  readonly name: string;
+  readonly body: FunctionBody;
+}
+declare function rejectObviousNondeterministicGlobals(entry: WorkflowSafetyTarget, sourceFile: {
+  readonly text: string;
+  readonly program: Program;
+}): void;
+//#endregion
+export { rejectObviousNondeterministicGlobals };

package/dist/vite/safety.mjs

@@ -0,0 +1,96 @@
+import { lineAndColumnOfPosition, visitWorkflowNode } from "./ast.mjs";
+import { WorkflowTransformError } from "./error.mjs";
+import { builtinModules } from "node:module";
+//#region src/vite/safety.ts
+const unsafeGlobalCallNames = /* @__PURE__ */ new Set([
+	"Date",
+	"fetch",
+	"setTimeout",
+	"setInterval",
+	"setImmediate",
+	"queueMicrotask"
+]);
+function rejectObviousNondeterministicGlobals(entry, sourceFile) {
+	const unsafeImports = collectUnsafeWorkflowImportBindings(sourceFile.program);
+	visitWorkflowNode(entry.body, (node) => {
+		if (isIdentifier(node) && unsafeImports.has(node.name)) throwNondeterministicGlobalError(entry.name, unsafeImports.get(node.name), node, sourceFile);
+		if (isNewExpression(node) && isIdentifier(node.callee) && node.callee.name === "Date") throwNondeterministicGlobalError(entry.name, "Date", node, sourceFile);
+		if (isCallExpression(node) && isIdentifier(node.callee) && unsafeGlobalCallNames.has(node.callee.name)) throwNondeterministicGlobalError(entry.name, node.callee.name, node, sourceFile);
+		if (isStaticMemberExpression(node)) {
+			const unsafeGlobal = unsafeGlobalPropertyAccessName(node);
+			if (unsafeGlobal !== void 0) throwNondeterministicGlobalError(entry.name, unsafeGlobal, node, sourceFile);
+		}
+	});
+}
+function collectUnsafeWorkflowImportBindings(sourceFile) {
+	const bindings = /* @__PURE__ */ new Map();
+	for (const statement of sourceFile.body) {
+		if (statement.type !== "ImportDeclaration") continue;
+		const specifier = statement.source.value;
+		if (!isNodeBuiltinSpecifier(specifier)) continue;
+		for (const importSpecifier of statement.specifiers) {
+			if (importSpecifier.type === "ImportDefaultSpecifier") {
+				bindings.set(importSpecifier.local.name, specifier);
+				continue;
+			}
+			if (importSpecifier.type === "ImportNamespaceSpecifier") {
+				bindings.set(importSpecifier.local.name, specifier);
+				continue;
+			}
+			bindings.set(importSpecifier.local.name, `${specifier}.${importName(importSpecifier)}`);
+		}
+	}
+	return bindings;
+}
+function importName(importSpecifier) {
+	if (importSpecifier.type !== "ImportSpecifier") return importSpecifier.local.name;
+	return importSpecifier.imported.type === "Literal" ? String(importSpecifier.imported.value) : importSpecifier.imported.name;
+}
+function isNodeBuiltinSpecifier(specifier) {
+	const normalized = specifier.startsWith("node:") ? specifier.slice(5) : specifier;
+	const root = normalized.split("/", 1)[0];
+	return builtinModules.includes(normalized) || builtinModules.includes(root);
+}
+function throwNondeterministicGlobalError(workflowName, globalName, node, sourceFile) {
+	const position = lineAndColumnOfPosition(sourceFile.text, node.start);
+	WorkflowTransformError.nondeterministicGlobal(workflowName, globalName, position.line, position.column);
+}
+function unsafeGlobalPropertyAccessName(node) {
+	const path = propertyAccessPath(node);
+	if (path === void 0) return;
+	const normalized = stripGlobalQualifier(path);
+	if (normalized === "Date.now" || normalized === "Math.random" || normalized === "process.env" || normalized === "crypto.randomUUID" || normalized === "crypto.getRandomValues" || normalized === "performance.now" || normalized === "import.meta.env") return normalized;
+	if (normalized === "setTimeout" || normalized === "setInterval" || normalized === "setImmediate" || normalized === "queueMicrotask") return normalized;
+}
+function propertyAccessPath(node) {
+	const left = propertyAccessExpressionPath(node.object);
+	return left === void 0 ? void 0 : `${left}.${node.property.name}`;
+}
+function propertyAccessExpressionPath(expression) {
+	if (isIdentifier(expression)) return expression.name;
+	if (isMetaProperty(expression)) return `${expression.meta.name}.${expression.property.name}`;
+	if (isStaticMemberExpression(expression)) return propertyAccessPath(expression);
+}
+function stripGlobalQualifier(path) {
+	if (path.startsWith("globalThis.")) return path.slice(11);
+	if (path.startsWith("global.")) return path.slice(7);
+	if (path.startsWith("window.")) return path.slice(7);
+	return path;
+}
+function isIdentifier(node) {
+	return node.type === "Identifier";
+}
+function isCallExpression(node) {
+	return node.type === "CallExpression";
+}
+function isNewExpression(node) {
+	return node.type === "NewExpression";
+}
+function isMetaProperty(node) {
+	return node.type === "MetaProperty";
+}
+function isStaticMemberExpression(node) {
+	return node.type === "MemberExpression" && node.computed === false;
+}
+//#endregion
+export { rejectObviousNondeterministicGlobals };

package/dist/vite/source-edit.d.mts

@@ -0,0 +1,12 @@
+//#region src/vite/source-edit.d.ts
+/** Small source rewriting helper for AST-position based transforms. */
+declare class SourceEditor {
+  #private;
+  constructor(source: string);
+  remove(start: number, end: number): void;
+  replace(start: number, end: number, text: string): void;
+  read(start: number, end: number): string;
+  toString(): string;
+}
+//#endregion
+export { SourceEditor };

package/dist/vite/source-edit.mjs

@@ -0,0 +1,44 @@
+import { WorkflowTransformError } from "./error.mjs";
+//#region src/vite/source-edit.ts
+/** Small source rewriting helper for AST-position based transforms. */
+var SourceEditor = class {
+	#source;
+	#replacements = [];
+	constructor(source) {
+		this.#source = source;
+	}
+	remove(start, end) {
+		this.replace(start, end, "");
+	}
+	replace(start, end, text) {
+		if (start < 0 || end < start || end > this.#source.length) WorkflowTransformError.invalidSourceReplacementRange(start, end);
+		this.#replacements.push({
+			start,
+			end,
+			text
+		});
+	}
+	read(start, end) {
+		if (start < 0 || end < start || end > this.#source.length) WorkflowTransformError.invalidSourceReadRange(start, end);
+		return this.#source.slice(start, end);
+	}
+	toString() {
+		let result = this.#source;
+		for (const replacement of this.#sortedReplacements()) result = `${result.slice(0, replacement.start)}${replacement.text}${result.slice(replacement.end)}`;
+		return result;
+	}
+	#sortedReplacements() {
+		const replacements = [...this.#replacements].sort((left, right) => {
+			if (left.start !== right.start) return right.start - left.start;
+			return right.end - left.end;
+		});
+		for (let index = 1; index < replacements.length; index++) {
+			const previous = replacements[index - 1];
+			const current = replacements[index];
+			if (current.end > previous.start) WorkflowTransformError.overlappingSourceReplacementRanges(current.start, current.end, previous.start, previous.end);
+		}
+		return replacements;
+	}
+};
+//#endregion
+export { SourceEditor };

package/dist/vite/source-map.d.mts

@@ -0,0 +1,11 @@
+//#region src/vite/source-map.d.ts
+interface GeneratedSourceMapOptions {
+  readonly id: string;
+  readonly originalCode: string;
+  readonly generatedCode: string;
+  readonly generatedSource: string;
+  readonly sourceText: string;
+}
+declare function createGeneratedSourceMap(options: GeneratedSourceMapOptions): unknown;
+//#endregion
+export { GeneratedSourceMapOptions, createGeneratedSourceMap };

package/dist/vite/source-map.mjs

@@ -0,0 +1,53 @@
+import { stripQuery } from "./source.mjs";
+//#region src/vite/source-map.ts
+function createGeneratedSourceMap(options) {
+	return {
+		version: 3,
+		file: stripQuery(options.id),
+		sources: [stripQuery(options.id)],
+		sourcesContent: [options.originalCode],
+		names: [],
+		mappings: createWorkflowTransformMappings(options)
+	};
+}
+function createWorkflowTransformMappings(options) {
+	const generatedLines = options.generatedCode.split("\n");
+	const sourceStart = options.sourceText === "" ? -1 : options.generatedSource.indexOf(options.sourceText);
+	const generatedStart = options.sourceText === "" ? -1 : options.generatedCode.indexOf(options.sourceText);
+	if (sourceStart < 0 || generatedStart < 0) return generatedLines.map(() => "").join(";");
+	const sourceStartLine = lineIndexAt(options.generatedSource, sourceStart);
+	const generatedStartLine = lineIndexAt(options.generatedCode, generatedStart);
+	const sourceLineCount = options.sourceText.split("\n").length;
+	let previousSourceLine = 0;
+	return generatedLines.map((_line, generatedLine) => {
+		if (generatedLine < generatedStartLine || generatedLine >= generatedStartLine + sourceLineCount) return "";
+		const sourceLine = sourceStartLine + generatedLine - generatedStartLine;
+		const segment = [
+			encodeSourceMapVlq(0),
+			encodeSourceMapVlq(0),
+			encodeSourceMapVlq(sourceLine - previousSourceLine),
+			encodeSourceMapVlq(0)
+		].join("");
+		previousSourceLine = sourceLine;
+		return segment;
+	}).join(";");
+}
+function lineIndexAt(text, offset) {
+	let line = 0;
+	for (let index = 0; index < offset; index++) if (text[index] === "\n") line++;
+	return line;
+}
+const SOURCE_MAP_BASE64_DIGITS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function encodeSourceMapVlq(value) {
+	let vlq = value < 0 ? (-value << 1) + 1 : value << 1;
+	let result = "";
+	do {
+		let digit = vlq & 31;
+		vlq >>>= 5;
+		if (vlq > 0) digit |= 32;
+		result += SOURCE_MAP_BASE64_DIGITS[digit];
+	} while (vlq > 0);
+	return result;
+}
+//#endregion
+export { createGeneratedSourceMap };

package/dist/vite/source.d.mts

@@ -0,0 +1,7 @@
+//#region src/vite/source.d.ts
+/** Removes a URL or Vite query suffix from an ID. */
+declare function stripQuery(id: string): string;
+type WorkflowSourceKind = "js" | "json" | "ts" | "tsx";
+declare function workflowSourceKindForId(id: string): WorkflowSourceKind;
+//#endregion
+export { WorkflowSourceKind, stripQuery, workflowSourceKindForId };

package/dist/vite/source.mjs

@@ -0,0 +1,14 @@
+//#region src/vite/source.ts
+/** Removes a URL or Vite query suffix from an ID. */
+function stripQuery(id) {
+	return id.split("?", 1)[0];
+}
+function workflowSourceKindForId(id) {
+	const cleanId = stripQuery(id);
+	if (cleanId.endsWith(".tsx") || cleanId.endsWith(".jsx")) return "tsx";
+	if (cleanId.endsWith(".js") || cleanId.endsWith(".mjs") || cleanId.endsWith(".cjs")) return "js";
+	if (cleanId.endsWith(".json")) return "json";
+	return "ts";
+}
+//#endregion
+export { stripQuery, workflowSourceKindForId };

package/dist/vite/transform.d.mts

@@ -0,0 +1,7 @@
+import { DirectiveKind, TransformManifest, TransformManifestFunction, TransformManifestImportEdge, TransformMetadata, TransformMetadataEntry, TransformOptions, TransformResult } from "../types/vite.mjs";
+import { WorkflowTransformError } from "./error.mjs";
+//#region src/vite/transform.d.ts
+/** Transforms one TypeScript module containing workflow or step directives. */
+declare function transformWorkflowSource(code: string, id: string, options?: TransformOptions): TransformResult | undefined;
+//#endregion
+export { type DirectiveKind, type TransformManifest, type TransformManifestFunction, type TransformManifestImportEdge, type TransformMetadata, type TransformMetadataEntry, type TransformOptions, type TransformResult, WorkflowTransformError, transformWorkflowSource };