@shivaedev/build 0.0.0 → 0.1.1

package/src/adapters/objectForm.ts

@@ -0,0 +1,74 @@
+import ts from "typescript";
+import { isReadonlyProperty } from "#adapters/isReadonlyProperty.ts";
+import { declaredClass, isSchemaClass, type TypeReading } from "#adapters/typeReading.ts";
+import { unionForm } from "#adapters/unionForm.ts";
+import type { Field, WireForm } from "#facts.ts";
+
+type Read = (type: ts.Type, path: string) => WireForm | undefined;
+
+export function classForm(reading: TypeReading, type: ts.Type, symbol: ts.Symbol, path: string): WireForm | undefined {
+	if (!isSchemaClass(reading, symbol)) {
+		return reading.refuse(type, path, "return a plain object, or make the class a Schema class");
+	}
+	const declared = declaredClass(reading, symbol);
+	if (declared?.exportName === undefined) {
+		return reading.refuse(type, path, `export the Schema class ${symbol.name} from its module`);
+	}
+	return { declared, form: "class" };
+}
+
+// An exact optional property's only undefined member is the one optionality adds: TypeScript merges a written undefined
+// into it, and the property is then not exact.
+function optionalForm(reading: TypeReading, type: ts.Type, path: string, read: Read): WireForm | undefined {
+	const members = type.isUnion() ? type.types.filter((member) => !(member.flags & ts.TypeFlags.Undefined)) : [type];
+	const [only] = members;
+	if (only === undefined) {
+		return reading.refuse(type, path, "give the optional property a type besides undefined, or drop it");
+	}
+	return members.length === 1 ? read(only, path) : unionForm(reading, type, members, path, read);
+}
+
+function fieldOf(reading: TypeReading, property: ts.Symbol, exact: ReadonlySet<ts.Symbol>, path: string, read: Read): Field | undefined {
+	const optional = (property.flags & ts.SymbolFlags.Optional) !== 0;
+	const type = reading.checker.getTypeOfSymbol(property);
+	if (optional && !exact.has(property)) {
+		return reading.refuse(type, path, `drop undefined from the optional property ${property.name}, so an absent key is the only way to leave it out`);
+	}
+	const form = optional ? optionalForm(reading, type, path, read) : read(type, path);
+	return form === undefined ? undefined : { form, mutable: !isReadonlyProperty(property), name: property.name, optional };
+}
+
+function recordForm(reading: TypeReading, type: ts.Type, path: string, read: Read): WireForm | undefined {
+	const [index, ...others] = reading.checker.getIndexInfosOfType(type);
+	if (index === undefined || others.length > 0 || !(index.keyType.flags & ts.TypeFlags.String)) {
+		return reading.refuse(type, path, "use string keys only");
+	}
+	const value = read(index.type, `${path}[string]`);
+	return value === undefined ? undefined : { form: "record", mutable: !index.isReadonly, value };
+}
+
+export function objectForm(reading: TypeReading, type: ts.Type, path: string, read: Read): WireForm | undefined {
+	if (type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0) {
+		return reading.refuse(type, path, "return data, not a function");
+	}
+	const symbol = type.getSymbol();
+	const builtIn =
+		symbol !== undefined
+		&& symbol.flags & ts.SymbolFlags.Interface
+		&& symbol.declarations?.some((declaration) => reading.program.isSourceFileDefaultLibrary(declaration.getSourceFile()));
+	if (builtIn === true) {
+		return reading.refuse(type, path, "return a plain object, an array or a string-keyed record");
+	}
+	const properties = reading.checker.getPropertiesOfType(type);
+	const indexes = reading.checker.getIndexInfosOfType(type);
+	if (indexes.length > 0) {
+		return properties.length === 0 ? recordForm(reading, type, path, read) : reading.refuse(type, path, "use either fixed properties or a record");
+	}
+	const methods = properties.filter((property) => reading.checker.getTypeOfSymbol(property).getCallSignatures().length > 0);
+	if (methods.length > 0 || properties.some((property) => property.name.startsWith("__@"))) {
+		return reading.refuse(type, path, "return plain data, without methods or symbol keys");
+	}
+	const exact = new Set(reading.checker.getExactOptionalProperties(type));
+	const fields = properties.map((property) => fieldOf(reading, property, exact, `${path}.${property.name}`, read));
+	return fields.every((field) => field !== undefined) ? { fields, form: "struct" } : undefined;
+}

package/src/adapters/operationFacts.ts

@@ -0,0 +1,85 @@
+import ts from "typescript";
+import { copiedCode } from "#adapters/copiedCode.ts";
+import { failuresOf } from "#adapters/failuresOf.ts";
+import { initializerOf, propertyOf } from "#adapters/moduleCalls.ts";
+import { type TypeReading, typeArguments } from "#adapters/typeReading.ts";
+import { wireForm } from "#adapters/wireForm.ts";
+import type { CodePart, OperationFacts } from "#facts.ts";
+
+export interface OperationReading {
+	readonly moduleName: string;
+	readonly reading: (label: string) => TypeReading;
+	readonly refuse: (message: string) => void;
+}
+
+function declarationOf(checker: ts.TypeChecker, element: ts.Expression) {
+	const symbol = checker.getSymbolAtLocation(element);
+	const target = symbol !== undefined && symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+	const declaration = target?.valueDeclaration;
+	const call = declaration !== undefined && ts.isVariableDeclaration(declaration) ? declaration.initializer : undefined;
+	const literal = call !== undefined && ts.isCallExpression(call) ? call.arguments[1] : undefined;
+	return declaration === undefined || literal === undefined || !ts.isObjectLiteralExpression(literal) ? undefined : { declaration, literal };
+}
+
+// What an Effect-returning property of the operation succeeds and fails with.
+function effectArguments(checker: ts.TypeChecker, owner: ts.Type, property: string, at: ts.Node): readonly ts.Type[] {
+	const symbol = owner.getProperty(property);
+	const [signature] = symbol === undefined ? [] : checker.getTypeOfSymbolAtLocation(symbol, at).getCallSignatures();
+	return signature === undefined ? [] : typeArguments(checker, signature.getReturnType());
+}
+
+function textOf(checker: ts.TypeChecker, owner: ts.Type, property: string): string | undefined {
+	const symbol = owner.getProperty(property);
+	const value = symbol === undefined ? undefined : checker.getTypeOfSymbol(symbol);
+	return value?.isStringLiteral() === true ? value.value : undefined;
+}
+
+// Without run's types the operation did not compile; a run returning any is the common cause, and gets its own message.
+function refuseUnread(context: OperationReading, label: string, literal: ts.ObjectLiteralExpression) {
+	const reading = context.reading(label);
+	const run = propertyOf(literal, "run");
+	const signature = run !== undefined && ts.isMethodDeclaration(run) ? reading.checker.getSignatureFromDeclaration(run) : undefined;
+	const returned = signature === undefined ? undefined : typeArguments(reading.checker, signature.getReturnType())[1];
+	if (returned !== undefined && returned.flags & ts.TypeFlags.Any) {
+		reading.refuse(returned, "success", "decode the value with a schema, or give it a type");
+	} else {
+		context.refuse(`${label}: run's result cannot be read; fix the compile errors on the operation first`);
+	}
+}
+
+export function operationFacts(context: OperationReading, element: ts.Expression): OperationFacts | undefined {
+	const reading = context.reading(context.moduleName);
+	const found = declarationOf(reading.checker, element);
+	if (found === undefined) {
+		context.refuse(`${context.moduleName}: ${element.getText()} in operations is not a const built by query or command with an object literal`);
+		return undefined;
+	}
+	const type = reading.checker.getTypeAtLocation(found.declaration);
+	const name = textOf(reading.checker, type, "name") ?? element.getText();
+	const kind = textOf(reading.checker, type, "kind") === "command" ? "command" : "query";
+	const label = `${context.moduleName}.${name}`;
+	const [success, runError] = effectArguments(reading.checker, type, "run", found.declaration);
+	if (success === undefined) {
+		refuseUnread(context, label, found.literal);
+	}
+	const [, policyError] = kind === "query" ? effectArguments(reading.checker, type, "readPolicy", found.declaration) : [];
+	const literal = found.literal;
+	function copy(field: string, member: boolean): readonly CodePart[] | undefined {
+		const property = propertyOf(literal, field);
+		const node = member ? property : initializerOf(property);
+		return node === undefined ? undefined : copiedCode({ checker: reading.checker, label: `${label} ${field}`, refuse: context.refuse }, node);
+	}
+	return {
+		failures: failuresOf(
+			context.reading(label),
+			[runError, policyError].flatMap((error) => error ?? []),
+		),
+		invalidates: copy("invalidates", true),
+		kind,
+		name,
+		payload: copy("payload", false),
+		reads: copy("reads", true),
+		readsCollections: copy("readsCollections", true),
+		success: success === undefined ? undefined : wireForm(context.reading(label), success, "success"),
+	};
+}

package/src/adapters/runNode.ts

@@ -0,0 +1,15 @@
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Cause, Effect, Exit, Layer } from "effect";
+
+const services = Layer.mergeAll(NodeServices.layer, NodeCrypto.layer);
+
+// Runs a generator effect for a tool that awaits a Promise, failing it with the effect's own error.
+export async function runNode<A, E>(effect: Effect.Effect<A, E, Layer.Success<typeof services>>): Promise<A> {
+	const exit = await Effect.runPromiseExit(Effect.provide(effect, services));
+	if (Exit.isSuccess(exit)) {
+		return exit.value;
+	}
+	const failure = Cause.squash(exit.cause);
+	throw failure instanceof Error ? failure : new Error(String(failure), { cause: failure });
+}

package/src/adapters/typeReading.ts

@@ -0,0 +1,63 @@
+import ts from "typescript";
+import type { DeclaredClass, Literal } from "#facts.ts";
+
+export interface TypeReading {
+	readonly checker: ts.TypeChecker;
+	readonly program: ts.Program;
+	// Refuses the type at a path with what to write instead, and returns undefined so a caller can stop there.
+	readonly refuse: (type: ts.Type, path: string, instead: string) => undefined;
+}
+
+export function declaredIn(type: ts.Type, module: string): boolean {
+	const pattern = new RegExp(`[/\\\\]effect[/\\\\](?:dist|src)[/\\\\]${module}\\.(?:d\\.)?ts$`, "u");
+	return (type.aliasSymbol ?? type.getSymbol())?.declarations?.some((declaration) => pattern.test(declaration.getSourceFile().fileName)) === true;
+}
+
+export function isLibraryType(reading: TypeReading, type: ts.Type, name: string): boolean {
+	const symbol = type.getSymbol();
+	return (
+		symbol?.name === name
+		&& symbol.declarations?.some((declaration) => reading.program.isSourceFileDefaultLibrary(declaration.getSourceFile())) === true
+	);
+}
+
+export function declaredClass(reading: TypeReading, symbol: ts.Symbol): DeclaredClass | undefined {
+	const declaration = symbol.declarations?.find(ts.isClassDeclaration);
+	if (declaration === undefined) {
+		return undefined;
+	}
+	const file = declaration.getSourceFile();
+	const module = reading.checker.getSymbolAtLocation(file);
+	const exported =
+		module === undefined
+			? undefined
+			: reading.checker
+					.getExportsOfModule(module)
+					.find((candidate) => (candidate.flags & ts.SymbolFlags.Alias ? reading.checker.getAliasedSymbol(candidate) : candidate) === symbol);
+	return { className: symbol.name, exportName: exported?.name, file: file.fileName };
+}
+
+export function isSchemaClass(reading: TypeReading, symbol: ts.Symbol): boolean {
+	const declaration = symbol.declarations?.find(ts.isClassDeclaration);
+	if (declaration === undefined) {
+		return false;
+	}
+	const staticSide = reading.checker.getTypeOfSymbolAtLocation(symbol, declaration);
+	return staticSide.getProperty("ast") !== undefined && staticSide.getProperty("fields") !== undefined;
+}
+
+// Array, tuple and generic interface instances, such as Effect<A, E, R>, are references that carry their type arguments.
+export function isReference(type: ts.Type): type is ts.TypeReference {
+	return "target" in type;
+}
+
+export function typeArguments(checker: ts.TypeChecker, type: ts.Type): readonly ts.Type[] {
+	return isReference(type) ? checker.getTypeArguments(type) : [];
+}
+
+export function literalOf(checker: ts.TypeChecker, type: ts.Type): Literal | undefined {
+	if (type.flags & ts.TypeFlags.BooleanLiteral) {
+		return checker.typeToString(type) === "true";
+	}
+	return type.isStringLiteral() || type.isNumberLiteral() ? type.value : undefined;
+}

package/src/adapters/typeScript.ts

@@ -0,0 +1,101 @@
+import { createHash } from "node:crypto";
+import { dirname } from "node:path";
+import { Effect } from "effect";
+import ts from "typescript";
+import { moduleCalls } from "#adapters/moduleCalls.ts";
+import { moduleFacts } from "#adapters/moduleFacts.ts";
+import { BuildFailure } from "#BuildFailure.ts";
+
+export interface ProjectConfig {
+	// The tsconfig and every file it extends, which decide how the project's types read.
+	readonly chain: readonly string[];
+	readonly declarations: readonly string[];
+	readonly files: readonly string[];
+	readonly options: ts.CompilerOptions;
+	readonly typeScriptVersion: string;
+}
+
+function diagnosticText(diagnostics: readonly ts.Diagnostic[]): string {
+	return ts.formatDiagnostics(diagnostics, {
+		getCanonicalFileName: (name) => name,
+		getCurrentDirectory: ts.sys.getCurrentDirectory,
+		getNewLine: () => "\n",
+	});
+}
+
+export const readConfig = Effect.fn("Build.readConfig")(function* (tsconfig: string) {
+	const parsed = yield* Effect.sync(() => {
+		const source = ts.readJsonConfigFile(tsconfig, ts.sys.readFile);
+		const config = ts.parseJsonSourceFileConfigFileContent(source, ts.sys, dirname(tsconfig), undefined, tsconfig);
+		return { config, problems: config.errors, source };
+	});
+	if (parsed.problems.length > 0) {
+		return yield* new BuildFailure({ message: `${tsconfig} cannot be read:\n${diagnosticText(parsed.problems)}` });
+	}
+	const config: ProjectConfig = {
+		chain: [tsconfig, ...(parsed.source.extendedSourceFiles ?? [])],
+		declarations: parsed.config.fileNames.filter((file) => file.endsWith(".d.ts")),
+		files: parsed.config.fileNames,
+		options: parsed.config.options,
+		typeScriptVersion: ts.version,
+	};
+	return config;
+});
+
+export function definesModule(file: string, text: string): boolean {
+	return text.includes("defineModule") && moduleCalls(ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true)).length > 0;
+}
+
+export const resolvedImports = Effect.fn("Build.resolvedImports")(function* (config: ProjectConfig, file: string, text: string) {
+	return yield* Effect.sync(() =>
+		ts.preProcessFile(text, true, true).importedFiles.flatMap(({ fileName }) => {
+			const resolved = ts.resolveModuleName(fileName, file, config.options, ts.sys).resolvedModule;
+			return resolved === undefined ? [] : [resolved.resolvedFileName];
+		}),
+	);
+});
+
+// Building the program is the expensive part of a run, and parsing the installed packages' declarations is most of it. They rarely
+// change between the runs of one process, such as a dev server's, so the registry hands a later program each file it parsed with the same text and settings.
+const parsedFiles = ts.createDocumentRegistry(ts.sys.useCaseSensitiveFileNames);
+
+function programHost(options: ts.CompilerOptions, rootNames: readonly string[]): ts.LanguageServiceHost {
+	const texts = new Map<string, string | undefined>();
+	function textOf(file: string) {
+		if (!texts.has(file)) {
+			texts.set(file, ts.sys.readFile(file));
+		}
+		return texts.get(file);
+	}
+	return {
+		directoryExists: ts.sys.directoryExists,
+		fileExists: ts.sys.fileExists,
+		getCompilationSettings: () => options,
+		getCurrentDirectory: ts.sys.getCurrentDirectory,
+		getDefaultLibFileName: ts.getDefaultLibFilePath,
+		getDirectories: ts.sys.getDirectories,
+		getScriptFileNames: () => [...rootNames],
+		getScriptSnapshot: (file) => {
+			const text = textOf(file);
+			return text === undefined ? undefined : ts.ScriptSnapshot.fromString(text);
+		},
+		getScriptVersion: (file) =>
+			createHash("sha256")
+				.update(textOf(file) ?? "")
+				.digest("hex"),
+		readDirectory: ts.sys.readDirectory,
+		readFile: textOf,
+		...(ts.sys.realpath === undefined ? {} : { realpath: ts.sys.realpath }),
+		useCaseSensitiveFileNames: () => ts.sys.useCaseSensitiveFileNames,
+	};
+}
+
+export const deriveModules = Effect.fn("Build.deriveModules")(function* (config: ProjectConfig, modules: readonly string[]) {
+	const program = yield* Effect.sync(() =>
+		ts.createLanguageService(programHost({ ...config.options, noEmit: true }, [...modules, ...config.declarations]), parsedFiles).getProgram(),
+	);
+	if (program === undefined) {
+		return yield* new BuildFailure({ message: "TypeScript's language service built no program" });
+	}
+	return yield* Effect.sync(() => modules.map((module) => moduleFacts(program, module)));
+});

package/src/adapters/unionForm.ts

@@ -0,0 +1,88 @@
+import ts from "typescript";
+import { declaredIn, literalOf, type TypeReading } from "#adapters/typeReading.ts";
+import { byText } from "#byText.ts";
+import type { Literal, WireForm } from "#facts.ts";
+
+type Read = (type: ts.Type, path: string) => WireForm | undefined;
+
+function discriminant(reading: TypeReading, members: readonly ts.Type[]): string | undefined {
+	const [first] = members;
+	const candidates = first === undefined ? [] : reading.checker.getPropertiesOfType(first).map((property) => property.name);
+	return candidates.sort().find((name) => {
+		const values = members.map((member) => {
+			const property = member.getProperty(name);
+			return property === undefined || property.flags & ts.SymbolFlags.Optional
+				? undefined
+				: literalOf(reading.checker, reading.checker.getTypeOfSymbol(property));
+		});
+		return values.every((value) => value !== undefined) && new Set(values).size === values.length;
+	});
+}
+
+function byValue(left: Literal, right: Literal): number {
+	return byText(String(left), String(right));
+}
+
+function discriminated(reading: TypeReading, members: readonly ts.Type[], tag: string, path: string, read: Read): WireForm | undefined {
+	function tagOf(member: ts.Type) {
+		const property = member.getProperty(tag);
+		return (property === undefined ? undefined : literalOf(reading.checker, reading.checker.getTypeOfSymbol(property))) ?? "";
+	}
+	const forms = [...members]
+		.sort((left, right) => byValue(tagOf(left), tagOf(right)))
+		.map((member) => read(member, `${path}<${tag}: ${tagOf(member)}>`));
+	return forms.every((form) => form !== undefined) ? { form: "union", members: forms } : undefined;
+}
+
+function optionValue(reading: TypeReading, members: readonly ts.Type[]): ts.Type | undefined {
+	const some = members.find((member) => member.getSymbol()?.name === "Some" && declaredIn(member, "Option"));
+	const none = members.find((member) => member.getSymbol()?.name === "None" && declaredIn(member, "Option"));
+	const value = some?.getProperty("value");
+	return none === undefined || value === undefined ? undefined : reading.checker.getTypeOfSymbol(value);
+}
+
+function withoutNull(reading: TypeReading, type: ts.Type, all: readonly ts.Type[], path: string, read: Read): WireForm | undefined {
+	const members = all.filter((member) => !(member.flags & ts.TypeFlags.Null));
+	const [only] = members;
+	if (members.length === 1 && only !== undefined && only.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) {
+		return reading.refuse(type, path, "return either null or undefined, since the wire carries both as one");
+	}
+	const booleans = members.filter((member) => member.flags & ts.TypeFlags.BooleanLiteral);
+	const optionInner = optionValue(reading, members);
+	if (optionInner !== undefined && members.length === 2) {
+		const inner = read(optionInner, `${path}<Some>`);
+		return inner === undefined ? undefined : { form: "option", inner };
+	}
+	if (booleans.length === 2 && members.length === 2) {
+		return { form: "primitive", primitive: "Boolean" };
+	}
+	if (members.length === 1 && only !== undefined) {
+		return read(only, path);
+	}
+	if (members.some((member) => member.flags & ts.TypeFlags.Undefined)) {
+		return reading.refuse(type, path, "return null instead of undefined, or make the property optional");
+	}
+	const values = members.map((member) => literalOf(reading.checker, member));
+	if (values.every((value) => value !== undefined)) {
+		return { form: "literals", values: values.sort(byValue) };
+	}
+	const objects = members.every(
+		(member) => member.flags & ts.TypeFlags.Object && !reading.checker.isArrayType(member) && !reading.checker.isTupleType(member),
+	);
+	const tag = objects ? discriminant(reading, members) : undefined;
+	if (tag !== undefined) {
+		return discriminated(reading, members, tag, path, read);
+	}
+	return reading.refuse(type, path, "return string, number or boolean literals, or objects told apart by one literal field such as _tag");
+}
+
+// The members are the union's own, or an optional property's without the undefined its optionality adds.
+export function unionForm(reading: TypeReading, type: ts.Type, members: readonly ts.Type[], path: string, read: Read): WireForm | undefined {
+	if (type.aliasSymbol?.name === "Option" && declaredIn(type, "Option") && type.aliasTypeArguments?.[0] !== undefined) {
+		const inner = read(type.aliasTypeArguments[0], `${path}<Some>`);
+		return inner === undefined ? undefined : { form: "option", inner };
+	}
+	const inner = withoutNull(reading, type, members, path, read);
+	const nullable = members.some((member) => member.flags & ts.TypeFlags.Null);
+	return inner === undefined || !nullable ? inner : { form: "nullOr", inner };
+}

package/src/adapters/vitePlugin.ts

@@ -0,0 +1,103 @@
+import { Option } from "effect";
+import type { EnvironmentModuleNode, HookHandler, Plugin, ResolvedConfig, Rollup, ViteDevServer } from "vite";
+import { bundleCheck } from "#adapters/bundleCheck.ts";
+import { runNode } from "#adapters/runNode.ts";
+import { type GenerateRound, type WatchedGeneration, watchedGeneration } from "#generateRound.ts";
+
+export interface BuildPluginOptions {
+	readonly bundleCheck?: boolean;
+	readonly serverOnly?: readonly string[];
+}
+
+type HotUpdateContext = ThisParameterType<HookHandler<NonNullable<Plugin["hotUpdate"]>>>;
+
+interface SharedRound {
+	readonly round: Promise<Option.Option<GenerateRound>>;
+	seenBy: number;
+}
+
+function tellTheBrowser(environment: HotUpdateContext["environment"], devServer: ViteDevServer, refusal: Option.Option<string>, file: string) {
+	if (Option.isSome(refusal)) {
+		devServer.config.logger.error(refusal.value, { timestamp: true });
+		environment.hot.send({ err: { message: refusal.value, plugin: "shivaedev:build", stack: "" }, type: "error" });
+		return;
+	}
+	environment.hot.send({ path: "*", triggeredBy: file, type: "full-reload" });
+}
+
+function generateFiles(): Plugin {
+	let config: ResolvedConfig | undefined;
+	let server: ViteDevServer | undefined;
+	let generation: Promise<WatchedGeneration> | undefined;
+	let started: Promise<GenerateRound> | undefined;
+	let outputs = new Set<string>();
+	// One change reaches hotUpdate once per environment; they share one run.
+	const shared = new Map<string, SharedRound>();
+	function remember(round: GenerateRound) {
+		outputs = new Set([...outputs, ...round.outputs]);
+		if (server !== undefined) {
+			const root = server.config.root;
+			server.watcher.add(round.inputs.filter((file) => !file.startsWith(root)));
+		}
+		return round;
+	}
+	function sharedRound(changed: WatchedGeneration["changed"], file: string, timestamp: number, environments: number) {
+		const key = `${timestamp}\u0000${file}`;
+		const entry = shared.get(key) ?? { round: runNode(changed(file)), seenBy: 0 };
+		entry.seenBy += 1;
+		shared.set(key, entry);
+		if (entry.seenBy === environments) {
+			shared.delete(key);
+		}
+		return entry.round;
+	}
+	return {
+		async buildStart(this: Rollup.PluginContext) {
+			generation ??= runNode(watchedGeneration(config?.root ?? "."));
+			const { run } = await generation;
+			started ??= runNode(run);
+			const round = remember(await started);
+			if (Option.isSome(round.refusal)) {
+				this.error(round.refusal.value);
+			}
+		},
+		configResolved(resolved) {
+			config = resolved;
+		},
+		configureServer(devServer) {
+			server = devServer;
+		},
+		enforce: "pre",
+		async hotUpdate(this: HotUpdateContext, { file, modules, server: devServer, timestamp }) {
+			// A run hands Vite the modules of each file it rewrites and reloads the page when it creates one, since a page may have failed
+			// to resolve it, so the watcher's own event for that write would reload twice.
+			if (outputs.has(file)) {
+				return [];
+			}
+			if (generation === undefined) {
+				return;
+			}
+			const known = outputs;
+			const { changed } = await generation;
+			const round = Option.map(await sharedRound(changed, file, timestamp, Object.keys(devServer.environments).length), remember);
+			if (Option.isNone(round)) {
+				return;
+			}
+			if (Option.isSome(round.value.refusal) || round.value.changed.some((output) => !known.has(output))) {
+				if (this.environment.config.consumer === "client") {
+					tellTheBrowser(this.environment, devServer, round.value.refusal, file);
+				}
+				return [];
+			}
+			const regenerated = round.value.changed.flatMap((output): EnvironmentModuleNode[] => [
+				...(this.environment.moduleGraph.getModulesByFile(output) ?? []),
+			]);
+			return [...modules, ...regenerated];
+		},
+		name: "shivaedev:build-generate",
+	};
+}
+
+export function buildPlugin({ bundleCheck: checked = true, serverOnly = [] }: BuildPluginOptions = {}): Plugin[] {
+	return checked ? [generateFiles(), bundleCheck(serverOnly)] : [generateFiles()];
+}

package/src/adapters/vitePort.ts

@@ -0,0 +1,5 @@
+import { Config, ConfigProvider, Effect } from "effect";
+
+export function vitePort(name: string, fallback: number): number {
+	return Effect.runSync(Config.Int(name).pipe(Config.withDefault(fallback)).parse(ConfigProvider.fromEnv()));
+}

package/src/adapters/vitest/setup.ts

@@ -0,0 +1,12 @@
+import { Option } from "effect";
+import type { TestProject } from "vitest/node";
+import { runNode } from "#adapters/runNode.ts";
+import { generateRound } from "#generateRound.ts";
+
+// A Vitest global setup: every module's files are written before the first test file loads, and a refusal stops the run.
+export async function setup(project: TestProject): Promise<void> {
+	const round = await runNode(generateRound(project.config.root));
+	if (Option.isSome(round.refusal)) {
+		throw new Error(round.refusal.value);
+	}
+}

package/src/adapters/wireForm.ts

@@ -0,0 +1,98 @@
+import ts from "typescript";
+import { classForm, objectForm } from "#adapters/objectForm.ts";
+import { declaredIn, isLibraryType, isReference, literalOf, type TypeReading, typeArguments } from "#adapters/typeReading.ts";
+import { unionForm } from "#adapters/unionForm.ts";
+import type { Primitive, WireForm } from "#facts.ts";
+
+const PRIMITIVES: readonly (readonly [ts.TypeFlags, Primitive])[] = [
+	[ts.TypeFlags.String, "String"],
+	[ts.TypeFlags.Number, "Number"],
+	[ts.TypeFlags.Boolean, "Boolean"],
+	[ts.TypeFlags.BigInt, "BigInt"],
+	[ts.TypeFlags.Null, "Null"],
+	[ts.TypeFlags.Void, "Void"],
+	[ts.TypeFlags.Undefined, "Undefined"],
+];
+
+const UNMAPPED: readonly (readonly [ts.TypeFlags, string])[] = [
+	[ts.TypeFlags.Any, "decode the value with a schema, or give it a type"],
+	[ts.TypeFlags.Unknown, "decode the value with a schema, or give it a type"],
+	[ts.TypeFlags.Never, "return a value, or nothing"],
+	[ts.TypeFlags.EnumLike, "return string or number literals instead of an enum"],
+	[ts.TypeFlags.TemplateLiteral | ts.TypeFlags.StringMapping, "return string"],
+	[ts.TypeFlags.ESSymbolLike, "return a string instead of a symbol"],
+	[ts.TypeFlags.TypeParameter | ts.TypeFlags.Index | ts.TypeFlags.IndexedAccess | ts.TypeFlags.Conditional, "give run's return a concrete type"],
+	[ts.TypeFlags.NonPrimitive, "return a type with known properties"],
+];
+
+function arrayForm(reading: TypeReading, type: ts.Type, path: string, seen: ReadonlySet<ts.Type>): WireForm | undefined {
+	const [element] = typeArguments(reading.checker, type);
+	const item = element === undefined ? undefined : wireForm(reading, element, `${path}[number]`, seen);
+	return item === undefined ? undefined : { form: "array", item, mutable: type.getSymbol()?.name === "Array" };
+}
+
+function isTuple(target: ts.GenericType): target is ts.TupleType {
+	return "elementFlags" in target;
+}
+
+function tupleForm(reading: TypeReading, type: ts.TypeReference, path: string, seen: ReadonlySet<ts.Type>): WireForm | undefined {
+	const target = type.target;
+	if (!isTuple(target) || target.elementFlags.some((flags) => flags !== ts.ElementFlags.Required)) {
+		return reading.refuse(type, path, "use an array, or a tuple of required elements");
+	}
+	const elements = reading.checker
+		.getTypeArguments(type)
+		.slice(0, target.elementFlags.length)
+		.map((element, index) => wireForm(reading, element, `${path}[${index}]`, seen));
+	return elements.every((element) => element !== undefined) ? { elements, form: "tuple", mutable: !target.readonly } : undefined;
+}
+
+function objectTypeForm(reading: TypeReading, type: ts.Type, path: string, seen: ReadonlySet<ts.Type>): WireForm | undefined {
+	if (isLibraryType(reading, type, "Date")) {
+		return { form: "primitive", primitive: "Date" };
+	}
+	if (declaredIn(type, "DateTime") && type.getSymbol()?.name === "Utc") {
+		return { form: "primitive", primitive: "DateTimeUtc" };
+	}
+	if (reading.checker.isTupleType(type) && isReference(type)) {
+		return tupleForm(reading, type, path, seen);
+	}
+	if (reading.checker.isArrayType(type)) {
+		return arrayForm(reading, type, path, seen);
+	}
+	const symbol = type.getSymbol();
+	if (symbol !== undefined && symbol.flags & ts.SymbolFlags.Class) {
+		return classForm(reading, type, symbol, path);
+	}
+	return objectForm(reading, type, path, (property, propertyPath) => wireForm(reading, property, propertyPath, seen));
+}
+
+// The schema whose Type is exactly this type, or undefined after refusing it: the wire never carries a looser form.
+export function wireForm(reading: TypeReading, type: ts.Type, path: string, seen: ReadonlySet<ts.Type> = new Set()): WireForm | undefined {
+	if (seen.has(type)) {
+		return reading.refuse(type, path, "return a type that does not contain itself");
+	}
+	const within = new Set([...seen, type]);
+	const primitive = PRIMITIVES.find(([flags]) => type.flags & flags);
+	if (primitive !== undefined) {
+		return { form: "primitive", primitive: primitive[1] };
+	}
+	const unmapped = UNMAPPED.find(([flags]) => type.flags & flags);
+	if (unmapped !== undefined) {
+		return reading.refuse(type, path, unmapped[1]);
+	}
+	const literal = literalOf(reading.checker, type);
+	if (literal !== undefined) {
+		return { form: "literals", values: [literal] };
+	}
+	if (type.isUnion()) {
+		return unionForm(reading, type, type.types, path, (member, memberPath) => wireForm(reading, member, memberPath, within));
+	}
+	if (type.isIntersection() && type.types.some((member) => !(member.flags & ts.TypeFlags.Object))) {
+		return reading.refuse(type, path, "return the unbranded type, or wrap the value in an exported Schema class");
+	}
+	if (type.flags & ts.TypeFlags.Object || type.isIntersection()) {
+		return objectTypeForm(reading, type, path, within);
+	}
+	return reading.refuse(type, path, "return plain data");
+}

package/src/byText.ts

@@ -0,0 +1,7 @@
+// Code-unit order, so output is the same on every machine, unlike localeCompare.
+export function byText(left: string, right: string): number {
+	if (left < right) {
+		return -1;
+	}
+	return left > right ? 1 : 0;
+}