@shivaedev/build 0.0.0 → 0.1.0

package/src/packageScope.ts

@@ -0,0 +1,35 @@
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
+
+const Manifest = Schema.Struct({
+	exports: Schema.optionalKey(Schema.Unknown),
+	imports: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown)),
+	name: Schema.optionalKey(Schema.String),
+});
+
+export interface PackageScope {
+	readonly directory: string;
+	readonly manifest: typeof Manifest.Type;
+}
+
+const decodeManifest = Schema.decodeUnknownEffect(Schema.fromJsonString(Manifest));
+
+// The nearest named package.json above a file decides how the file is imported; a nameless one only sets a folder's module type.
+export const packageScopeOf = Effect.fn("Build.packageScopeOf")(function* (file: string) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	let directory = path.dirname(file);
+	for (;;) {
+		const manifestPath = path.join(directory, "package.json");
+		if (yield* fs.exists(manifestPath)) {
+			const manifest = yield* decodeManifest(yield* fs.readFileString(manifestPath));
+			if (manifest.name !== undefined) {
+				return Option.some<PackageScope>({ directory, manifest });
+			}
+		}
+		const parent = path.dirname(directory);
+		if (parent === directory) {
+			return Option.none<PackageScope>();
+		}
+		directory = parent;
+	}
+});

package/src/plan.ts

@@ -0,0 +1,138 @@
+import { Effect, Option, Path } from "effect";
+import { byText } from "#byText.ts";
+import { code, type ImportRef } from "#code.ts";
+import type { PlannedModule, PlannedOperation } from "#emit.ts";
+import type { CodePart, DeclaredClass, ModuleFacts, OperationFacts, WireForm } from "#facts.ts";
+import { formCode } from "#formCode.ts";
+import { packageScopeOf } from "#packageScope.ts";
+import { rejectionsOf } from "#rejections.ts";
+import { specifierFor } from "#specifiers.ts";
+
+export interface Placement {
+	readonly output: string;
+	readonly root: string;
+}
+
+function classesIn(form: WireForm | undefined): readonly DeclaredClass[] {
+	if (form === undefined) {
+		return [];
+	}
+	switch (form.form) {
+		case "class":
+			return [form.declared];
+		case "array":
+			return classesIn(form.item);
+		case "tuple":
+			return form.elements.flatMap(classesIn);
+		case "struct":
+			return form.fields.flatMap((field) => classesIn(field.form));
+		case "record":
+			return classesIn(form.value);
+		case "union":
+			return form.members.flatMap(classesIn);
+		case "nullOr":
+		case "option":
+			return classesIn(form.inner);
+		default:
+			return [];
+	}
+}
+
+const classRef = Effect.fn("Build.classRef")(function* (placement: Placement, declared: DeclaredClass) {
+	const specifier = yield* specifierFor(placement.root, placement.output, declared.file);
+	const name = declared.exportName ?? declared.className;
+	return specifier === undefined ? undefined : { name, preferred: name, specifier, typeOnly: false };
+});
+
+const codeOf = Effect.fn("Build.codeOf")(function* (placement: Placement, parts: readonly CodePart[]) {
+	const path = yield* Path.Path;
+	return yield* Effect.forEach(parts, (part) =>
+		Effect.gen(function* () {
+			if (typeof part === "string") {
+				return part;
+			}
+			const own = !path.relative(placement.root, part.writtenIn).startsWith("..");
+			const specifier =
+				own || !part.specifier.startsWith("#") || part.target === undefined
+					? part.specifier
+					: yield* specifierFor(placement.root, placement.output, part.target);
+			return { name: part.name, preferred: part.local, specifier: specifier ?? part.specifier, typeOnly: part.typeOnly } satisfies ImportRef;
+		}),
+	);
+});
+
+function copiedOf(placement: Placement, parts: readonly CodePart[] | undefined) {
+	return parts === undefined ? Effect.succeed(undefined) : codeOf(placement, parts);
+}
+
+const operationPlan = Effect.fn("Build.operationPlan")(function* (
+	placement: Placement,
+	label: string,
+	operation: OperationFacts,
+	refuse: (message: string) => void,
+) {
+	const packages = new Map<string, string | undefined>();
+	for (const failure of operation.failures) {
+		if (failure.kind === "class" && !packages.has(failure.declared.file)) {
+			const scope = yield* packageScopeOf(failure.declared.file);
+			packages.set(failure.declared.file, Option.getOrUndefined(Option.map(scope, ({ manifest }) => manifest.name)));
+		}
+	}
+	const { refusals, rejections } = rejectionsOf(label, operation.failures, (file) => packages.get(file));
+	refusals.forEach(refuse);
+	const refs = new Map<string, ImportRef>();
+	for (const declared of [...classesIn(operation.success), ...rejections.map((rejection) => rejection.declared)]) {
+		const ref = yield* classRef(placement, declared);
+		if (ref === undefined) {
+			refuse(
+				`${label}: ${declared.className} in ${declared.file} cannot be imported by the generated file; export it from a module its package exports`,
+			);
+		} else {
+			refs.set(`${declared.file}\u0000${declared.className}`, ref);
+		}
+	}
+	function refOf(declared: DeclaredClass): ImportRef {
+		return (
+			refs.get(`${declared.file}\u0000${declared.className}`) ?? {
+				name: declared.className,
+				preferred: declared.className,
+				specifier: declared.file,
+				typeOnly: false,
+			}
+		);
+	}
+	const members = yield* Effect.forEach([operation.reads, operation.readsCollections, operation.invalidates], (parts) => copiedOf(placement, parts));
+	// A browser contract's query always carries reads, so a query that declares no keys gets none, as query() gives it.
+	const reads = operation.kind === "query" && operation.reads === undefined ? [code("reads: () => []")] : [];
+	const planned: PlannedOperation = {
+		kind: operation.kind,
+		members: [...reads, ...members.filter((member) => member !== undefined)],
+		name: operation.name,
+		payload: yield* copiedOf(placement, operation.payload),
+		rejections: rejections.map(({ declared, tag }) => [tag, refOf(declared)] as const),
+		success: operation.success === undefined ? code() : formCode(operation.success, (form) => refOf(form.declared)),
+	};
+	return planned;
+});
+
+export const plan = Effect.fn("Build.plan")(function* (placement: Placement, facts: ModuleFacts) {
+	const path = yield* Path.Path;
+	const refusals: string[] = [...facts.refusals];
+	function refuse(message: string) {
+		refusals.push(message);
+	}
+	const sorted = [...facts.operations].sort((left, right) => byText(left.name, right.name));
+	const operations = yield* Effect.forEach(sorted, (operation) => operationPlan(placement, `${facts.name}.${operation.name}`, operation, refuse));
+	const moduleSpecifier = (yield* specifierFor(placement.root, placement.output, facts.file)) ?? facts.file;
+	const planned: PlannedModule = {
+		exportName: facts.exportName,
+		keyScope: yield* copiedOf(placement, facts.keyScope),
+		middleware: yield* copiedOf(placement, facts.middleware),
+		module: { name: facts.exportName, preferred: facts.exportName, specifier: moduleSpecifier, typeOnly: true },
+		name: facts.name,
+		operations,
+		source: path.relative(placement.root, facts.file),
+		subject: yield* copiedOf(placement, facts.subject),
+	};
+	return { planned, refusals: [...new Set(refusals)] };
+});

package/src/project.ts

@@ -0,0 +1,30 @@
+import { Effect, FileSystem, Path } from "effect";
+import { definesModule, readConfig } from "#adapters/typeScript.ts";
+import { generatorFingerprint, type Project } from "#inputs.ts";
+
+export interface ModuleFile {
+	readonly module: string;
+	readonly output: string;
+}
+
+export const openProject = Effect.fn("Build.openProject")(function* (directory: string) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const root = yield* fs.realPath(directory);
+	const config = yield* readConfig(path.join(root, "tsconfig.json"));
+	const project: Project = { config, generated: `${path.join(root, "src", "generated")}${path.sep}`, generator: yield* generatorFingerprint(), root };
+	return project;
+});
+
+// Every file of the tsconfig that calls defineModule, so no list of modules needs keeping; each writes src/generated/<its path under src>.
+export const moduleFiles = Effect.fn("Build.moduleFiles")(function* (project: Project) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const sources = project.config.files.filter((file) => !(file.startsWith(project.generated) || file.endsWith(".d.ts"))).sort();
+	const modules = yield* Effect.filter(sources, (file) => Effect.map(fs.readFileString(file), (text) => definesModule(file, text)));
+	const source = path.join(project.root, "src");
+	return modules.map((module): ModuleFile & { readonly underSource: boolean } => {
+		const underSource = path.relative(source, module);
+		return { module, output: path.join(project.generated, underSource), underSource: !underSource.startsWith("..") };
+	});
+});

package/src/rejections.ts

@@ -0,0 +1,57 @@
+import { byText } from "#byText.ts";
+import type { DeclaredClass, Failure } from "#facts.ts";
+
+// Never rejections: the wire adds the automatic two to every operation, and the others are infrastructure or policy outcomes.
+const NOT_REJECTIONS: ReadonlySet<string> = new Set([
+	"@shivaedev/contract QueryReadDenied",
+	"@shivaedev/errors InternalServerError",
+	"@shivaedev/errors ServiceUnavailable",
+	"effect SchemaError",
+]);
+
+export interface Rejection {
+	readonly declared: DeclaredClass;
+	readonly tag: string;
+}
+
+export function isRejection(packageName: string | undefined, declared: DeclaredClass): boolean {
+	return !NOT_REJECTIONS.has(`${packageName ?? ""} ${declared.className}`);
+}
+
+function refusalOf(label: string, failure: Failure): string | undefined {
+	switch (failure.kind) {
+		case "untagged":
+			return `${label}: run fails with ${failure.text}, which has no _tag; fail with an exported tagged error class instead`;
+		case "unexported":
+			return `${label}: run fails with ${failure.text} (${failure.tag}), which is not an exported class; export its class so the browser can decode it`;
+		case "class":
+			return failure.schema
+				? undefined
+				: `${label}: run fails with ${failure.declared.className} (${failure.tag}), which is not a Schema class, so the browser cannot decode it; declare it as a Schema tagged error, such as class ${failure.declared.className} extends Schema.TaggedError<${failure.declared.className}>()("${failure.tag}", { ... })`;
+		case "retryable":
+			return undefined;
+	}
+}
+
+export function rejectionsOf(label: string, failures: readonly Failure[], packageOf: (file: string) => string | undefined) {
+	const refusals: string[] = [];
+	const byTag = new Map<string, Rejection>();
+	for (const failure of failures) {
+		const rejection = failure.kind !== "class" || isRejection(packageOf(failure.declared.file), failure.declared);
+		const refusal = rejection ? refusalOf(label, failure) : undefined;
+		if (refusal !== undefined) {
+			refusals.push(refusal);
+		}
+		if (failure.kind === "class" && rejection) {
+			const known = byTag.get(failure.tag);
+			if (known !== undefined && (known.declared.file !== failure.declared.file || known.declared.className !== failure.declared.className)) {
+				refusals.push(
+					`${label}: run fails with two classes tagged ${failure.tag}, from ${known.declared.file} and ${failure.declared.file}; raise one of them`,
+				);
+			}
+			byTag.set(failure.tag, failure);
+		}
+	}
+	const rejections = [...byTag.values()].sort((left, right) => byText(left.tag, right.tag));
+	return { refusals, rejections };
+}

package/src/report.ts

@@ -0,0 +1,39 @@
+import { Data } from "effect";
+
+// current: rebuilt and equal to the file; unchanged: inputs as last time, so no program was built; removed and, under
+// --check, orphaned: a generated file whose module is gone.
+export type ModuleStatus = "current" | "missing" | "orphaned" | "refused" | "removed" | "stale" | "unchanged" | "written";
+
+export interface ModuleOutcome {
+	readonly module: string;
+	readonly output: string;
+	readonly status: ModuleStatus;
+}
+
+export interface GenerateReport {
+	readonly inputs: readonly string[];
+	readonly modules: readonly ModuleOutcome[];
+	readonly programBuilt: boolean;
+}
+
+export function problemOf({ module, output, status }: ModuleOutcome): string | undefined {
+	switch (status) {
+		case "missing":
+		case "stale":
+			return `${output} is ${status}; run \`pnpm generate\``;
+		case "orphaned":
+			return `${output} is left from ${module}, which defines no module any more; run \`pnpm generate\``;
+		case "current":
+		case "refused":
+		case "removed":
+		case "unchanged":
+		case "written":
+			return undefined;
+	}
+}
+
+// A refused module, or under --check a missing, stale or orphaned file: the command prints each problem and exits 1.
+export class GenerateFailed extends Data.TaggedError("GenerateFailed")<{
+	readonly problems: readonly string[];
+	readonly report: GenerateReport;
+}> {}

package/src/serverCode.ts

@@ -0,0 +1,139 @@
+import { Effect, Option, Path } from "effect";
+import { type Owner, ownerOf } from "#ownerOf.ts";
+
+export interface BundleModule {
+	readonly builtin: boolean;
+	readonly imports: readonly string[];
+}
+
+export interface BundleGraph {
+	readonly entries: readonly string[];
+	readonly modules: ReadonlyMap<string, BundleModule>;
+}
+
+export interface ServerMarkers {
+	readonly defineModule: Option.Option<string>;
+	readonly operation: Option.Option<string>;
+	readonly sql: Option.Option<string>;
+}
+
+export interface ServerCodeOptions {
+	readonly root: string;
+	readonly serverOnly: readonly string[];
+}
+
+const displayed = Effect.fn("Build.displayed")(function* (id: string, options: ServerCodeOptions, owners: Map<string, Option.Option<Owner>>) {
+	const path = yield* Path.Path;
+	const relative = path.relative(options.root, id);
+	if (path.isAbsolute(id) && !relative.startsWith("..") && !relative.split(path.sep).includes("node_modules")) {
+		return relative;
+	}
+	const owner = yield* ownerOf(id, owners);
+	return Option.match(owner, {
+		onNone: () => id.replace(/^__vite-browser-external:/u, ""),
+		onSome: ({ directory, name }) => `${name}/${path.relative(directory, id)}`,
+	});
+});
+
+const reasonOf = Effect.fn("Build.reasonOf")(function* (
+	id: string,
+	module: BundleModule,
+	markers: ServerMarkers,
+	options: ServerCodeOptions,
+	owners: Map<string, Option.Option<Owner>>,
+) {
+	const path = yield* Path.Path;
+	if (module.builtin) {
+		return Option.some("a Node builtin");
+	}
+	if (Option.exists(markers.defineModule, (marker) => module.imports.includes(marker))) {
+		return Option.some("a module file: it calls defineModule");
+	}
+	if (Option.exists(markers.operation, (marker) => module.imports.includes(marker))) {
+		return Option.some("an operation file: it defines a query or a command");
+	}
+	const owner = yield* ownerOf(id, owners);
+	if (Option.isSome(owner) && options.serverOnly.includes(owner.value.name)) {
+		return Option.some(`part of ${owner.value.name}, which is listed as server-only`);
+	}
+	const folders = Option.match(owner, { onNone: () => "", onSome: ({ directory }) => path.dirname(path.relative(directory, id)) });
+	if (folders.split(path.sep).includes("server")) {
+		return Option.some("under a server/ folder");
+	}
+	return Option.none<string>();
+});
+
+// Effect's own index re-exports modules that import effect/sql, which tree shaking drops, so the import edge decides: every
+// importer of effect/sql outside Effect counts, however many paths inside Effect reach the same module sooner.
+const importsSqlFromOutside = Effect.fn("Build.importsSqlFromOutside")(function* (
+	importer: string,
+	imported: string,
+	markers: ServerMarkers,
+	owners: Map<string, Option.Option<Owner>>,
+) {
+	const path = yield* Path.Path;
+	if (!Option.exists(markers.sql, (directory) => imported.startsWith(`${directory}${path.sep}`))) {
+		return false;
+	}
+	const sqlOwner = yield* ownerOf(imported, owners);
+	const importerOwner = yield* ownerOf(importer, owners);
+	return !Option.exists(importerOwner, (each) => Option.exists(sqlOwner, ({ directory }) => each.directory === directory));
+});
+
+const failure = Effect.fn("Build.failure")(function* (
+	chain: readonly string[],
+	reason: string,
+	options: ServerCodeOptions,
+	owners: Map<string, Option.Option<Owner>>,
+) {
+	const shown = yield* Effect.forEach(chain, (each) => displayed(each, options, owners));
+	return [
+		`Server code reached the browser bundle: ${shown.at(-1)} is ${reason}. The import chain from the client entry:`,
+		...shown.map((each, index) => (index === 0 ? `  ${each}` : `  → ${each}`)),
+		"The browser reaches a defined module through its generated client in src/generated and imports no server code.",
+	].join("\n");
+});
+
+function chainTo(id: string, parents: ReadonlyMap<string, string | undefined>): readonly string[] {
+	const chain: string[] = [];
+	for (let each: string | undefined = id; each !== undefined; each = parents.get(each)) {
+		chain.unshift(each);
+	}
+	return chain;
+}
+
+interface Walk {
+	readonly owners: Map<string, Option.Option<Owner>>;
+	readonly parents: Map<string, string | undefined>;
+	readonly pending: string[];
+}
+
+const visit = Effect.fn("Build.visit")(function* (id: string, module: BundleModule, walk: Walk, markers: ServerMarkers, options: ServerCodeOptions) {
+	const reason = yield* reasonOf(id, module, markers, options, walk.owners);
+	if (Option.isSome(reason)) {
+		return Option.some(yield* failure(chainTo(id, walk.parents), reason.value, options, walk.owners));
+	}
+	for (const imported of module.imports) {
+		if (yield* importsSqlFromOutside(id, imported, markers, walk.owners)) {
+			return Option.some(yield* failure([...chainTo(id, walk.parents), imported], "Effect's SQL client, effect/sql", options, walk.owners));
+		}
+		if (!walk.parents.has(imported)) {
+			walk.parents.set(imported, id);
+			walk.pending.push(imported);
+		}
+	}
+	return Option.none<string>();
+});
+
+// Breadth first from the entries, so the chain printed is a shortest one to the nearest server module.
+export const serverCodeIn = Effect.fn("Build.serverCodeIn")(function* (graph: BundleGraph, markers: ServerMarkers, options: ServerCodeOptions) {
+	const walk: Walk = { owners: new Map(), parents: new Map(graph.entries.map((entry) => [entry, undefined])), pending: [...graph.entries] };
+	for (let id = walk.pending.shift(); id !== undefined; id = walk.pending.shift()) {
+		const module = graph.modules.get(id);
+		const found = module === undefined ? Option.none<string>() : yield* visit(id, module, walk, markers, options);
+		if (Option.isSome(found)) {
+			return found;
+		}
+	}
+	return Option.none<string>();
+});

package/src/settleOrphans.ts

@@ -0,0 +1,58 @@
+import { Effect, FileSystem, Option, Path } from "effect";
+import { definesModule } from "#adapters/typeScript.ts";
+import { generatedFrom } from "#emit.ts";
+import { readIfPresent } from "#files.ts";
+import type { Project } from "#inputs.ts";
+import type { ModuleOutcome } from "#report.ts";
+
+interface Orphan {
+	readonly file: string;
+	readonly source: string;
+}
+
+const definesModuleStill = Effect.fn("Build.definesModuleStill")(function* (project: Project, source: string) {
+	const path = yield* Path.Path;
+	const module = path.join(project.root, source);
+	return Option.exists(yield* readIfPresent(module), (text) => definesModule(module, text));
+});
+
+// Decided by the module the header names, never by comparing paths: on a case-insensitive file system a folder renamed by
+// case alone lists the module's own file under its old spelling.
+const orphansOf = Effect.fn("Build.orphansOf")(function* (project: Project) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	if (!(yield* fs.exists(project.generated))) {
+		return [];
+	}
+	const entries = (yield* fs.readDirectory(project.generated, { recursive: true })).map((entry) => path.join(project.generated, entry)).sort();
+	const orphans = yield* Effect.forEach(
+		entries.filter((file) => file.endsWith(".ts")),
+		(file) =>
+			Effect.gen(function* () {
+				if ((yield* fs.stat(file)).type !== "File") {
+					return [];
+				}
+				const source = Option.flatMap(yield* readIfPresent(file), (text) => Option.fromUndefinedOr(generatedFrom(text)));
+				return Option.isSome(source) && !(yield* definesModuleStill(project, source.value)) ? [{ file, source: source.value } satisfies Orphan] : [];
+			}),
+	);
+	return orphans.flat();
+});
+
+export const settleOrphans = Effect.fn("Build.settleOrphans")(function* (project: Project, check: boolean) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	return yield* Effect.forEach(yield* orphansOf(project), (orphan) =>
+		Effect.gen(function* () {
+			if (!check) {
+				yield* fs.remove(orphan.file);
+			}
+			const outcome: ModuleOutcome = {
+				module: orphan.source,
+				output: path.relative(project.root, orphan.file),
+				status: check ? "orphaned" : "removed",
+			};
+			return outcome;
+		}),
+	);
+});

package/src/specifiers.ts

@@ -0,0 +1,55 @@
+import { Effect, Option, Path } from "effect";
+import { packageScopeOf } from "#packageScope.ts";
+
+function targetsOf(value: unknown): readonly string[] {
+	if (typeof value === "string") {
+		return [value];
+	}
+	if (Array.isArray(value)) {
+		return value.flatMap(targetsOf);
+	}
+	return typeof value === "object" && value !== null ? Object.values(value).flatMap(targetsOf) : [];
+}
+
+function exportEntries(exports: unknown): readonly (readonly [string, unknown])[] {
+	if (typeof exports !== "object" || exports === null || Array.isArray(exports)) {
+		return exports === undefined ? [] : [[".", exports]];
+	}
+	const entries = Object.entries(exports);
+	return entries.every(([key]) => key.startsWith(".")) ? entries : [[".", exports]];
+}
+
+// The key of the first entry whose target names the file, with its wildcard filled in.
+export function matchingKey(entries: readonly (readonly [string, unknown])[], relativeFile: string): string | undefined {
+	for (const [key, value] of entries) {
+		for (const target of targetsOf(value)) {
+			const [prefix = "", suffix, ...rest] = target.split("*");
+			if (suffix === undefined && target === relativeFile) {
+				return key;
+			}
+			const fits = suffix !== undefined && rest.length === 0 && relativeFile.length >= prefix.length + suffix.length;
+			if (fits && relativeFile.startsWith(prefix) && relativeFile.endsWith(suffix)) {
+				return key.replace("*", relativeFile.slice(prefix.length, relativeFile.length - suffix.length));
+			}
+		}
+	}
+	return undefined;
+}
+
+// How the generated file at `from` imports `file`: the project's own imports, another package's exports, else a relative path.
+export const specifierFor = Effect.fn("Build.specifierFor")(function* (root: string, from: string, file: string) {
+	const path = yield* Path.Path;
+	const scope = yield* packageScopeOf(file);
+	if (Option.isNone(scope)) {
+		return undefined;
+	}
+	const { directory, manifest } = scope.value;
+	const relativeFile = `./${path.relative(directory, file)}`;
+	if (directory === root) {
+		const own = matchingKey(Object.entries(manifest.imports ?? {}), relativeFile);
+		const relative = path.relative(path.dirname(from), file);
+		return own ?? (relative.startsWith(".") ? relative : `./${relative}`);
+	}
+	const exported = matchingKey(exportEntries(manifest.exports), relativeFile);
+	return exported === undefined || manifest.name === undefined ? undefined : `${manifest.name}${exported.slice(1)}`;
+});