@augeo/smelt 1.2.2

package/lib/build/build.ts

@@ -0,0 +1,314 @@
+// Compiles a merged source tree into Shopify-flat output directories. See
+// docs/build-spec.md for the full spec.
+
+import {
+	mkdir,
+	readdir,
+	readFile,
+	rm,
+	stat,
+	writeFile,
+} from "node:fs/promises";
+import { join, relative } from "node:path";
+import { type BuildOptions, build as esbuild } from "esbuild";
+import {
+	type ComponentSource,
+	type ComponentType,
+	type Layer,
+	type ResolvedComponent,
+	resolveLayers,
+} from "../resolver.ts";
+
+export interface BuildContext {
+	/** Ordered source layers — first wins on per-file shadowing. */
+	layers: Layer[];
+}
+
+const BUILT_PREFIX = "built--";
+// Matches anything the build emits: regular `built--*.liquid` and private
+// `_built--*.liquid` theme blocks (see docs/build-spec.md "Private blocks").
+const BUILT_FILE_PATTERN = /^_?built--/;
+
+const TYPE_TO_OUTPUT_DIRECTORY = {
+	sections: "sections",
+	blocks: "blocks",
+	components: "snippets",
+} as const satisfies Record<ComponentType, string>;
+
+export async function build(context: BuildContext): Promise<number> {
+	const outputRoot = context.layers[0]?.path;
+	if (!outputRoot) {
+		throw new Error("build() requires at least one layer.");
+	}
+	const components = await resolveLayers(context.layers);
+	await cleanBuiltOutputs(outputRoot);
+
+	const lookup = new Map(
+		components.map((component) => [component.segments.join("/"), component]),
+	);
+	await Promise.all(
+		components.map((component) =>
+			buildComponent(component, lookup, outputRoot),
+		),
+	);
+
+	return components.length;
+}
+
+async function cleanBuiltOutputs(outputRoot: string): Promise<void> {
+	await Promise.all(
+		Object.values(TYPE_TO_OUTPUT_DIRECTORY).map(async (directory) => {
+			const directoryPath = join(outputRoot, directory);
+			if (!(await exists(directoryPath))) return;
+			const entries = await readdir(directoryPath);
+			await Promise.all(
+				entries
+					.filter((entry) => BUILT_FILE_PATTERN.test(entry))
+					.map((entry) => rm(join(directoryPath, entry))),
+			);
+		}),
+	);
+}
+
+async function buildComponent(
+	component: ResolvedComponent,
+	lookup: Map<string, ResolvedComponent>,
+	outputRoot: string,
+): Promise<void> {
+	const source = await readFile(component.liquid.path, "utf-8");
+	assertNoInlineSchema(source, component);
+	const body = rewriteRenders(source, component, lookup);
+
+	const sections = [banner(component), body.trimEnd()];
+
+	if (component.schema) {
+		const schema = await loadSchema(component.schema);
+		const merged = mergePrivateBlocks(schema, component, lookup);
+		sections.push(renderSchemaBlock(merged));
+	}
+	if (component.css) {
+		const css = await readFile(component.css.path, "utf-8");
+		sections.push(wrapEmbedded("stylesheet", css));
+	}
+	if (component.ts) {
+		sections.push(wrapEmbedded("javascript", await bundleJs(component.ts)));
+	}
+
+	const liquid = `${sections.join("\n\n")}\n`;
+
+	const outputDirectory = join(
+		outputRoot,
+		TYPE_TO_OUTPUT_DIRECTORY[component.type],
+	);
+	const outputName = `${builtNameOf(component)}.liquid`;
+	const outputPath = join(outputDirectory, outputName);
+
+	await mkdir(outputDirectory, { recursive: true });
+	await writeFile(outputPath, liquid);
+}
+
+function assertNoInlineSchema(
+	source: string,
+	component: ResolvedComponent,
+): void {
+	if (!/\{%-?\s*schema\s*-?%\}/.test(source)) return;
+	const last = component.segments[component.segments.length - 1];
+	throw new Error(
+		`Inline {% schema %} block in ${sourcePathForComponent(component)}. ` +
+			`Schemas must live in a sibling ${last}.schema.ts file — import ` +
+			`{ defineSchemaSection } (or defineSchemaBlock) from "@augeo/smelt/schema".`,
+	);
+}
+
+async function loadSchema(schemaSource: ComponentSource): Promise<unknown> {
+	// esbuild auto-discovers tsconfig.json by walking up from the entry file,
+	// so `paths` (including the `@/*` alias) come from whichever tsconfig the
+	// schema's own layer puts closest. This matches what `tsc` sees.
+	const code = await bundle(schemaSource.path, {
+		format: "esm",
+		platform: "node",
+		target: "node24",
+	});
+	const loaded = await import(
+		`data:text/javascript,${encodeURIComponent(code)}`
+	);
+	if (loaded.schema === undefined) {
+		const available = Object.keys(loaded).join(", ") || "no exports";
+		throw new Error(
+			`${schemaSource.path} must export a named 'schema' (found: ${available}).`,
+		);
+	}
+	return loaded.schema;
+}
+
+function renderSchemaBlock(schema: unknown): string {
+	return `{% schema %}\n${JSON.stringify(schema, null, 2)}\n{% endschema %}`;
+}
+
+/**
+ * A block is "private" when its segments were reached through a nested
+ * `blocks/` type marker — i.e. there is a `blocks` segment at any position
+ * after the root. That covers both a section/component owning private blocks
+ * (`sections/hero/blocks/headline`) and a public block owning its own private
+ * blocks (`blocks/promo/blocks/item`). Shopify treats files prefixed `_` in
+ * `blocks/` as hidden from the merchant picker; we map our nested authoring
+ * convention onto that filename convention.
+ */
+function isPrivateBlock(component: ResolvedComponent): boolean {
+	if (component.type !== "blocks") return false;
+	return component.segments.slice(1).includes("blocks");
+}
+
+/** Filename minus `.liquid` — also the Shopify-facing `type` for blocks. */
+function builtNameOf(component: ResolvedComponent): string {
+	const prefix = isPrivateBlock(component) ? "_" : "";
+	return `${prefix}${BUILT_PREFIX}${component.segments.join("--")}`;
+}
+
+/**
+ * Auto-merge immediate private children (blocks under `<parent>/blocks/`) into
+ * the parent's `blocks: [...]` schema array. Discovered children are sorted
+ * by directory name and prepended; any explicitly-listed entries the author
+ * wrote are appended after.
+ */
+function mergePrivateBlocks(
+	schema: unknown,
+	component: ResolvedComponent,
+	lookup: Map<string, ResolvedComponent>,
+): unknown {
+	if (!isPlainObject(schema)) return schema;
+	const children = findPrivateChildren(component, lookup);
+	if (children.length === 0) return schema;
+	const discovered = children.map((child) => ({ type: builtNameOf(child) }));
+	const explicit = Array.isArray(schema.blocks) ? schema.blocks : [];
+	return { ...schema, blocks: [...discovered, ...explicit] };
+}
+
+function findPrivateChildren(
+	component: ResolvedComponent,
+	lookup: Map<string, ResolvedComponent>,
+): ResolvedComponent[] {
+	const parent = component.segments;
+	const candidates = Array.from(lookup.values()).filter((other) => {
+		if (other.type !== "blocks") return false;
+		// Immediate child only: segments == [...parent, "blocks", <name>]
+		if (other.segments.length !== parent.length + 2) return false;
+		if (other.segments[parent.length] !== "blocks") return false;
+		return parent.every((segment, index) => other.segments[index] === segment);
+	});
+	return candidates.sort((a, b) =>
+		(a.segments[a.segments.length - 1] ?? "").localeCompare(
+			b.segments[b.segments.length - 1] ?? "",
+		),
+	);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function banner(component: ResolvedComponent): string {
+	return `{%- comment -%}
+	GENERATED FROM ${sourcePathForComponent(component)} — do not edit this file directly.
+	Edit the source and run \`npm run build\`.
+{%- endcomment -%}`;
+}
+
+function sourcePathForComponent(component: ResolvedComponent): string {
+	const relativePath = relative(
+		component.liquid.layer.path,
+		component.liquid.path,
+	);
+	return `${component.liquid.layer.name}/${relativePath}`;
+}
+
+function wrapEmbedded(tag: "stylesheet" | "javascript", body: string): string {
+	return `{% ${tag} %}\n${indent(body.trimEnd())}\n{% end${tag} %}`;
+}
+
+/** Prepends a tab to each non-empty line. */
+function indent(text: string): string {
+	return text.replace(/^(?=.)/gm, "\t");
+}
+
+function rewriteRenders(
+	source: string,
+	component: ResolvedComponent,
+	lookup: Map<string, ResolvedComponent>,
+): string {
+	return source.replace(
+		/(\{%-?\s*(?:render|include)\s+['"])((?:@|\.)\/[^'"]+)(['"])/g,
+		(_match, prefix, importPath, suffix) => {
+			const targetSegments = resolveImport(importPath, component);
+			const lookupKey = targetSegments.join("/");
+			const target = lookup.get(lookupKey);
+			if (!target) {
+				throw new Error(
+					`Cannot resolve render '${importPath}' (looked up '${lookupKey}') from ${component.liquid.path}`,
+				);
+			}
+			return `${prefix}${builtNameOf(target)}${suffix}`;
+		},
+	);
+}
+
+function resolveImport(
+	importPath: string,
+	component: ResolvedComponent,
+): string[] {
+	if (importPath.startsWith("@/")) {
+		return importPath.slice(2).split("/").filter(Boolean);
+	}
+	if (importPath.startsWith("./")) {
+		// `../` is intentionally not supported — see docs/build-spec.md.
+		if (importPath.includes("../")) {
+			throw new Error(
+				`'../' is not supported in render path: '${importPath}' (in ${component.liquid.path})`,
+			);
+		}
+		const remaining = importPath.slice(2).split("/").filter(Boolean);
+		return [...component.segments, ...remaining];
+	}
+	throw new Error(`Unexpected import path: '${importPath}'`);
+}
+
+async function bundleJs(tsSource: ComponentSource): Promise<string> {
+	// `absWorkingDir` pins esbuild's source-path annotation (`// src/...`) to
+	// the file's own layer, so baseline files don't get a leading `../` just
+	// because the CLI happens to be invoked from the consumer's cwd.
+	const code = await bundle(tsSource.path, {
+		format: "iife",
+		platform: "browser",
+		target: "es2022",
+		absWorkingDir: tsSource.layer.path,
+	});
+	// esbuild always emits 2-space indents; project style is tabs.
+	return code.replace(/^( {2})+/gm, (match) => "\t".repeat(match.length / 2));
+}
+
+async function bundle(
+	entryPoint: string,
+	options: Partial<BuildOptions>,
+): Promise<string> {
+	const result = await esbuild({
+		entryPoints: [entryPoint],
+		bundle: true,
+		write: false,
+		logLevel: "warning",
+		...options,
+	});
+	const [first] = result.outputFiles ?? [];
+	if (!first) {
+		throw new Error(`esbuild produced no output for ${entryPoint}`);
+	}
+	return first.text;
+}
+
+async function exists(path: string): Promise<boolean> {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/lib/build/command.ts

@@ -0,0 +1,27 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineCommand } from "citty";
+import { build as runBuild } from "./build.ts";
+
+// After tsdown bundles to `dist/cli.mjs`, `import.meta.url` points at that
+// bundle. Walk up two levels to the package root, where the baseline `src/`
+// lives. For the consumer (the running process's cwd), the consumer's `src/`
+// lives directly under it.
+const cliPath = fileURLToPath(import.meta.url);
+const smeltRoot = dirname(dirname(cliPath));
+
+export const build = defineCommand({
+	meta: {
+		name: "build",
+		description: "Compile src/ into Shopify-flat output directories.",
+	},
+	async run() {
+		const count = await runBuild({
+			layers: [
+				{ name: "consumer", path: process.cwd() },
+				{ name: "@augeo/smelt", path: smeltRoot },
+			],
+		});
+		console.log(`Built ${count} component(s).`);
+	},
+});

package/lib/build/index.ts

@@ -0,0 +1 @@
+export { build } from "./command.ts";

package/lib/cli.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { defineCommand, runMain } from "citty";
+import { build } from "./build/index.ts";
+import { dev } from "./dev/index.ts";
+
+const main = defineCommand({
+	meta: {
+		name: "smelt",
+		description: "Smelt build CLI.",
+	},
+	subCommands: {
+		build,
+		dev,
+	},
+});
+
+runMain(main);

package/lib/dev/command.ts

@@ -0,0 +1,25 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineCommand } from "citty";
+import { runWatch } from "./watch.ts";
+
+// Same self-locating dance as `lib/build/command.ts` — after tsdown bundles to
+// `dist/cli.mjs`, `import.meta.url` points at the bundle, so walk up two
+// levels to reach the package root that hosts the baseline `src/` layer.
+const cliPath = fileURLToPath(import.meta.url);
+const smeltRoot = dirname(dirname(cliPath));
+
+export const dev = defineCommand({
+	meta: {
+		name: "dev",
+		description: "Watch src/ and rebuild on change.",
+	},
+	async run() {
+		await runWatch({
+			layers: [
+				{ name: "consumer", path: process.cwd() },
+				{ name: "@augeo/smelt", path: smeltRoot },
+			],
+		});
+	},
+});

package/lib/dev/index.ts

@@ -0,0 +1 @@
+export { dev } from "./command.ts";

package/lib/dev/watch.ts

@@ -0,0 +1,52 @@
+import { join } from "node:path";
+import { watch } from "chokidar";
+import { type BuildContext, build } from "../build/build.ts";
+
+// Editors often write files in bursts (saves of multiple files, atomic
+// rename-into-place writes, etc.). Coalesce those into one rebuild.
+const DEBOUNCE_MS = 100;
+
+export async function runWatch(context: BuildContext): Promise<void> {
+	await safeBuild(context);
+
+	const sources = context.layers.map((layer) => join(layer.path, "src"));
+	const watcher = watch(sources, {
+		ignoreInitial: true,
+		ignored: /node_modules/,
+	});
+
+	let pending: NodeJS.Timeout | undefined;
+	function scheduleRebuild(): void {
+		if (pending) clearTimeout(pending);
+		pending = setTimeout(() => {
+			pending = undefined;
+			void safeBuild(context);
+		}, DEBOUNCE_MS);
+	}
+
+	watcher.on("add", scheduleRebuild);
+	watcher.on("change", scheduleRebuild);
+	watcher.on("unlink", scheduleRebuild);
+
+	process.on("SIGINT", async () => {
+		await watcher.close();
+		process.exit(0);
+	});
+
+	console.log(
+		`smelt dev — watching ${sources.length} layer(s). Ctrl-C to stop.`,
+	);
+	// Watcher holds the event loop open; this promise never resolves.
+	return new Promise(() => {});
+}
+
+async function safeBuild(context: BuildContext): Promise<void> {
+	const start = Date.now();
+	try {
+		const count = await build(context);
+		console.log(`✓ Built ${count} component(s) in ${Date.now() - start}ms`);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(`✗ Build failed: ${message}`);
+	}
+}