@augeo/smelt 1.2.2

package/lib/resolver.test.ts

@@ -0,0 +1,275 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+	type Layer,
+	type ResolvedComponent,
+	resolveLayers,
+} from "./resolver.ts";
+
+interface Fixture {
+	path: string;
+	layer: Layer;
+}
+
+describe("resolveLayers()", () => {
+	let tempRoot: string;
+	beforeEach(async () => {
+		tempRoot = await mkdtemp(join(tmpdir(), "smelt-resolver-"));
+	});
+
+	let baseline: Fixture;
+	beforeEach(async () => {
+		baseline = await makeFixture(tempRoot, "baseline");
+	});
+
+	let consumer: Fixture;
+	beforeEach(async () => {
+		consumer = await makeFixture(tempRoot, "consumer");
+	});
+
+	afterEach(async () => {
+		await rm(tempRoot, { recursive: true, force: true });
+	});
+
+	describe("with a baseline layer only", () => {
+		beforeEach(async () => {
+			await writeComponent(baseline, "components/button", {
+				liquid: "<button></button>",
+				ts: "console.log('hi')",
+				css: ".btn {}",
+			});
+		});
+
+		let resolved: ResolvedComponent[];
+		beforeEach(async () => {
+			resolved = await resolveLayers([baseline.layer]);
+		});
+
+		it("returns the component", () => {
+			expect(resolved).toHaveLength(1);
+		});
+
+		it("anchors the liquid slot against the baseline", () => {
+			expect(resolved[0].liquid.layer).toBe(baseline.layer);
+		});
+
+		it("provides the ts slot from the baseline", () => {
+			expect(resolved[0].ts?.layer).toBe(baseline.layer);
+		});
+
+		it("provides the css slot from the baseline", () => {
+			expect(resolved[0].css?.layer).toBe(baseline.layer);
+		});
+
+		it("leaves the test slot empty when no test file exists", () => {
+			expect(resolved[0].test).toBeUndefined();
+		});
+
+		it("leaves the schema slot empty when no schema file exists", () => {
+			expect(resolved[0].schema).toBeUndefined();
+		});
+	});
+
+	describe("with a component that has a sibling .schema.ts file", () => {
+		beforeEach(async () => {
+			await writeComponent(baseline, "sections/hero", {
+				liquid: "<section></section>",
+				schema: "export const schema = { name: 'Hero' };",
+			});
+		});
+
+		let hero: ResolvedComponent;
+		beforeEach(async () => {
+			const resolved = await resolveLayers([baseline.layer]);
+			hero = resolved[0];
+		});
+
+		it("picks up the schema slot", () => {
+			expect(hero.schema?.layer).toBe(baseline.layer);
+		});
+
+		it("does not put the schema file on the ts slot", () => {
+			// hero.ts and hero.schema.ts are distinct filenames; only the former
+			// would land in the ts slot.
+			expect(hero.ts).toBeUndefined();
+		});
+	});
+
+	describe("with a consumer layer ahead of the baseline", () => {
+		describe("when the consumer shadows only the css slot", () => {
+			beforeEach(async () => {
+				await writeComponent(baseline, "components/button", {
+					liquid: "<button></button>",
+					ts: "console.log('hi')",
+					css: ".btn { color: black; }",
+				});
+			});
+			beforeEach(async () => {
+				await writeComponent(consumer, "components/button", {
+					css: ".btn { color: yellow; }",
+				});
+			});
+
+			let button: ResolvedComponent;
+			beforeEach(async () => {
+				const resolved = await resolveLayers([consumer.layer, baseline.layer]);
+				button = resolved[0];
+			});
+
+			it("takes the liquid slot from the baseline", () => {
+				expect(button.liquid.layer).toBe(baseline.layer);
+			});
+
+			it("takes the ts slot from the baseline", () => {
+				expect(button.ts?.layer).toBe(baseline.layer);
+			});
+
+			it("takes the css slot from the consumer", () => {
+				expect(button.css?.layer).toBe(consumer.layer);
+			});
+		});
+
+		describe("when the consumer fully shadows the baseline", () => {
+			beforeEach(async () => {
+				await writeComponent(baseline, "components/button", {
+					liquid: "<button>baseline</button>",
+					css: ".btn {}",
+				});
+			});
+			beforeEach(async () => {
+				await writeComponent(consumer, "components/button", {
+					liquid: "<button>consumer</button>",
+					ts: "console.log('consumer')",
+					css: ".btn {}",
+				});
+			});
+
+			let button: ResolvedComponent;
+			beforeEach(async () => {
+				const resolved = await resolveLayers([consumer.layer, baseline.layer]);
+				button = resolved[0];
+			});
+
+			it("takes the liquid slot from the consumer", () => {
+				expect(button.liquid.layer).toBe(consumer.layer);
+			});
+
+			it("takes the ts slot from the consumer", () => {
+				expect(button.ts?.layer).toBe(consumer.layer);
+			});
+
+			it("takes the css slot from the consumer", () => {
+				expect(button.css?.layer).toBe(consumer.layer);
+			});
+		});
+
+		describe("when the consumer adds a slot the baseline lacks", () => {
+			beforeEach(async () => {
+				await writeComponent(baseline, "components/button", {
+					liquid: "<button></button>",
+					ts: "console.log('baseline ts')",
+				});
+			});
+			beforeEach(async () => {
+				await writeComponent(consumer, "components/button", {
+					ts: "console.log('consumer ts')",
+				});
+			});
+
+			let button: ResolvedComponent;
+			beforeEach(async () => {
+				const resolved = await resolveLayers([consumer.layer, baseline.layer]);
+				button = resolved[0];
+			});
+
+			it("uses the consumer's ts slot", () => {
+				expect(button.ts?.layer).toBe(consumer.layer);
+			});
+
+			it("still anchors the liquid slot against the baseline", () => {
+				expect(button.liquid.layer).toBe(baseline.layer);
+			});
+		});
+
+		describe("with disjoint components in each layer", () => {
+			beforeEach(async () => {
+				await writeComponent(baseline, "components/button", {
+					liquid: "<button></button>",
+				});
+			});
+			beforeEach(async () => {
+				await writeComponent(consumer, "components/icon", {
+					liquid: "<svg></svg>",
+				});
+			});
+
+			let segmentKeys: string[];
+			beforeEach(async () => {
+				const resolved = await resolveLayers([consumer.layer, baseline.layer]);
+				segmentKeys = resolved
+					.map((component) => component.segments.join("/"))
+					.sort();
+			});
+
+			it("includes both components in the merged result", () => {
+				expect(segmentKeys).toEqual(["components/button", "components/icon"]);
+			});
+		});
+
+		describe("when a slot has no liquid anchor in any layer", () => {
+			beforeEach(async () => {
+				// Consumer has button.css but neither layer has button.liquid.
+				await writeComponent(consumer, "components/button", {
+					css: ".btn {}",
+				});
+			});
+
+			let resolved: ResolvedComponent[];
+			beforeEach(async () => {
+				resolved = await resolveLayers([consumer.layer, baseline.layer]);
+			});
+
+			it("treats the orphan slot as dead code", () => {
+				expect(resolved).toHaveLength(0);
+			});
+		});
+	});
+});
+
+async function makeFixture(tempRoot: string, name: string): Promise<Fixture> {
+	const path = join(tempRoot, name);
+	await mkdir(join(path, "src"), { recursive: true });
+	return { path, layer: { path, name } };
+}
+
+async function writeComponent(
+	fixture: Fixture,
+	segments: string,
+	slots: {
+		liquid?: string;
+		ts?: string;
+		css?: string;
+		test?: string;
+		schema?: string;
+	},
+): Promise<void> {
+	const parts = segments.split("/");
+	const last = parts[parts.length - 1];
+	const directory = join(fixture.path, "src", ...parts);
+	await mkdir(directory, { recursive: true });
+	await Promise.all(
+		Object.entries({
+			[`${last}.liquid`]: slots.liquid,
+			[`${last}.ts`]: slots.ts,
+			[`${last}.css`]: slots.css,
+			[`${last}.test.ts`]: slots.test,
+			[`${last}.schema.ts`]: slots.schema,
+		})
+			.filter(([, content]) => content !== undefined)
+			.map(([filename, content]) =>
+				writeFile(join(directory, filename), content ?? ""),
+			),
+	);
+}

package/lib/resolver.ts

@@ -0,0 +1,156 @@
+// Walks N source layers and produces an ordered list of resolved components:
+// per-file shadowing, first layer wins. See docs/build-spec.md for the layer
+// model.
+
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+export interface Layer {
+	/** Absolute path to the layer's root — the dir that contains `src/`. */
+	path: string;
+	/** Display label for diagnostics (e.g. "consumer", "@augeo/smelt"). */
+	name: string;
+}
+
+export interface ComponentSource {
+	/** Absolute path to the file. */
+	path: string;
+	/** Which layer this slot resolved against. */
+	layer: Layer;
+}
+
+export interface ResolvedComponent {
+	/** Component kind — determines the output directory. */
+	type: ComponentType;
+	/** Path segments under `src/`, e.g. `["components", "button"]`. */
+	segments: string[];
+	/** The anchor — every component has a liquid file. */
+	liquid: ComponentSource;
+	/** Optional sibling slots; each may come from a different layer. */
+	ts?: ComponentSource;
+	css?: ComponentSource;
+	test?: ComponentSource;
+	/** Section schema authored in TS; executed at build time. */
+	schema?: ComponentSource;
+}
+
+const TYPE_NAMES = ["sections", "blocks", "components"] as const;
+export type ComponentType = (typeof TYPE_NAMES)[number];
+
+export async function resolveLayers(
+	layers: Layer[],
+): Promise<ResolvedComponent[]> {
+	const perLayerComponents = await Promise.all(layers.map(walkLayer));
+	const allKeys = new Map<
+		string,
+		{ type: ComponentType; segments: string[] }
+	>();
+	perLayerComponents.flat().forEach(({ type, segments }) => {
+		const key = `${type}:${segments.join("/")}`;
+		if (!allKeys.has(key)) {
+			allKeys.set(key, { type, segments });
+		}
+	});
+
+	const resolved = await Promise.all(
+		Array.from(allKeys.values()).map(
+			async ({ type, segments }): Promise<ResolvedComponent | undefined> => {
+				const [liquid, ts, css, test, schema] = await Promise.all([
+					firstExisting(layers, segments, ".liquid"),
+					firstExisting(layers, segments, ".ts"),
+					firstExisting(layers, segments, ".css"),
+					firstExisting(layers, segments, ".test.ts"),
+					firstExisting(layers, segments, ".schema.ts"),
+				]);
+				if (!liquid) return undefined;
+				const component: ResolvedComponent = { type, segments, liquid };
+				if (ts) component.ts = ts;
+				if (css) component.css = css;
+				if (test) component.test = test;
+				if (schema) component.schema = schema;
+				return component;
+			},
+		),
+	);
+
+	return resolved.filter(
+		(component): component is ResolvedComponent => component !== undefined,
+	);
+}
+
+async function walkLayer(
+	layer: Layer,
+): Promise<Array<{ type: ComponentType; segments: string[] }>> {
+	const sourceRoot = join(layer.path, "src");
+	if (!(await exists(sourceRoot))) return [];
+	const perType = await Promise.all(
+		TYPE_NAMES.map(async (type) => {
+			const typeDir = join(sourceRoot, type);
+			if (!(await exists(typeDir))) return [];
+			return walkType(typeDir, type, [type]);
+		}),
+	);
+	return perType.flat();
+}
+
+async function walkType(
+	directory: string,
+	type: ComponentType,
+	segments: string[],
+): Promise<Array<{ type: ComponentType; segments: string[] }>> {
+	const entries = await readdir(directory, { withFileTypes: true });
+	const directories = entries.filter((entry) => entry.isDirectory());
+
+	const nested = await Promise.all(
+		directories.map(async (entry) => {
+			const subdirectory = join(directory, entry.name);
+
+			// Nested type marker (e.g. `components/` under a section) shifts type
+			// and namespace.
+			if ((TYPE_NAMES as readonly string[]).includes(entry.name)) {
+				return walkType(subdirectory, entry.name as ComponentType, [
+					...segments,
+					entry.name,
+				]);
+			}
+
+			const componentSegments = [...segments, entry.name];
+			const liquidPath = join(subdirectory, `${entry.name}.liquid`);
+			const here = (await exists(liquidPath))
+				? [{ type, segments: componentSegments }]
+				: [];
+
+			const deeper = await walkType(subdirectory, type, componentSegments);
+			return [...here, ...deeper];
+		}),
+	);
+
+	return nested.flat();
+}
+
+async function firstExisting(
+	layers: Layer[],
+	segments: string[],
+	extension: string,
+): Promise<ComponentSource | undefined> {
+	const last = segments[segments.length - 1];
+	const relativePath = join("src", ...segments, `${last}${extension}`);
+	const candidates = await Promise.all(
+		layers.map(async (layer) => ({
+			layer,
+			path: join(layer.path, relativePath),
+			exists: await exists(join(layer.path, relativePath)),
+		})),
+	);
+	const winner = candidates.find((candidate) => candidate.exists);
+	return winner ? { path: winner.path, layer: winner.layer } : undefined;
+}
+
+async function exists(path: string): Promise<boolean> {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/lib/schema.ts

@@ -0,0 +1,37 @@
+// Public surface for authoring Shopify schemas in TypeScript. Consumers import
+// the matching `defineSchema*` helper for the component kind they're authoring
+// and place the result in a sibling `<name>.schema.ts` file. The build engine
+// executes the file and injects the result as a `{% schema %}` block.
+//
+// Types are codegen'd from Shopify's authoritative JSON Schemas — see
+// scripts/codegen-schema.ts.
+
+export type { ThemeBlockSchema } from "./schema-block.generated.ts";
+export type { SectionSchema } from "./schema-section.generated.ts";
+
+import type { ThemeBlockSchema } from "./schema-block.generated.ts";
+import type { SectionSchema } from "./schema-section.generated.ts";
+
+/**
+ * Identity helper for authoring a Shopify section schema. The `const T`
+ * parameter preserves literal types so the schema author gets autocomplete
+ * for setting `type` values, `id`s, etc.
+ *
+ * Use in `<name>.schema.ts` files under `src/sections/`.
+ */
+export function defineSchemaSection<const T extends SectionSchema>(
+	schema: T,
+): T {
+	return schema;
+}
+
+/**
+ * Identity helper for authoring a Shopify theme-block schema.
+ *
+ * Use in `<name>.schema.ts` files under `src/blocks/`.
+ */
+export function defineSchemaBlock<const T extends ThemeBlockSchema>(
+	schema: T,
+): T {
+	return schema;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+	"name": "@augeo/smelt",
+	"version": "1.2.2",
+	"description": "Library + CLI for building Shopify themes from a colocated component tree",
+	"license": "MIT",
+	"type": "module",
+	"bin": {
+		"smelt": "./dist/cli.mjs"
+	},
+	"exports": {
+		"./schema": {
+			"types": "./dist/schema.d.mts",
+			"import": "./dist/schema.mjs"
+		}
+	},
+	"engines": {
+		"node": "24.11.0",
+		"npm": "11.6.2"
+	},
+	"volta": {
+		"node": "24.11.0",
+		"npm": "11.6.2"
+	},
+	"scripts": {
+		"schema:codegen": "tsx scripts/codegen-schema.ts",
+		"docs:update": "git submodule update --remote vendor/theme-liquid-docs",
+		"prebuild": "npm run schema:codegen",
+		"build": "tsdown",
+		"build:watch": "tsdown --watch",
+		"lint": "biome check && prettier --check --cache .",
+		"lint:fix": "biome check --write && prettier --write --cache .",
+		"typecheck": "npm run schema:codegen && tsc --noEmit && tsc --noEmit -p src",
+		"verify": "npm run lint:fix && npm run typecheck",
+		"pretest": "npm run build",
+		"test": "vitest run",
+		"test:all": "npm test && npm test --prefix example",
+		"prepare": "npm run build",
+		"prepublishOnly": "npm run build"
+	},
+	"devDependencies": {
+		"@augeo/assay": "^1.3.0",
+		"@biomejs/biome": "^2.4.16",
+		"@shopify/cli": "^3",
+		"@shopify/prettier-plugin-liquid": "^1",
+		"@types/node": "^25.9.1",
+		"@vitest/browser-playwright": "^4.1.7",
+		"json-schema-to-typescript": "^15.0.4",
+		"prettier": "^3",
+		"tsdown": "^0.22.1",
+		"tsx": "^4.22.3",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.7"
+	},
+	"dependencies": {
+		"chokidar": "^5.0.0",
+		"citty": "^0.2.2",
+		"esbuild": "^0.28.0"
+	}
+}

package/scripts/codegen-schema.ts

@@ -0,0 +1,66 @@
+// Generates lib/schema-*.generated.ts from Shopify's authoritative JSON Schemas
+// vendored at vendor/theme-liquid-docs/schemas/theme/. One file per schema kind
+// — each is self-contained (shared supporting types like `Setting` are
+// re-emitted per file rather than deduped). Run via `npm run schema:codegen`
+// (also fires from the `prebuild` hook).
+
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compile } from "json-schema-to-typescript";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "..");
+const vendorRoot = join(repoRoot, "vendor/theme-liquid-docs/schemas/theme");
+const outputDir = join(repoRoot, "lib");
+
+const entries = [
+	{
+		source: "section.json",
+		output: "schema-section.generated.ts",
+		typeName: "SectionSchema",
+	},
+	{
+		source: "theme_block.json",
+		output: "schema-block.generated.ts",
+		typeName: "ThemeBlockSchema",
+	},
+] as const;
+
+main().catch((error) => {
+	console.error(error);
+	process.exit(1);
+});
+
+async function main(): Promise<void> {
+	await Promise.all(entries.map(generateOne));
+	console.log(`Wrote ${entries.length} generated file(s) to ${outputDir}.`);
+}
+
+async function generateOne(entry: (typeof entries)[number]): Promise<void> {
+	const schemaJson = JSON.parse(
+		await readFile(join(vendorRoot, entry.source), "utf-8"),
+	);
+	// json-schema-to-typescript prefers `title` over the passed name. Drop it
+	// so our `typeName` wins (e.g. `SectionSchema` rather than
+	// `ShopifyLiquidThemeSectionSchema`).
+	delete schemaJson.title;
+
+	const compiled = await compile(schemaJson, entry.typeName, {
+		cwd: vendorRoot,
+		bannerComment: "",
+		additionalProperties: false,
+		declareExternallyReferenced: true,
+		strictIndexSignatures: true,
+	});
+
+	const header = [
+		"// Generated by scripts/codegen-schema.ts — DO NOT EDIT.",
+		`// Source: vendor/theme-liquid-docs/schemas/theme/${entry.source}`,
+		"// Update by running `npm run docs:update && npm run schema:codegen`.",
+		"",
+		"",
+	].join("\n");
+
+	await writeFile(join(outputDir, entry.output), header + compiled);
+}

package/src/components/button/button.css

@@ -0,0 +1,13 @@
+.tr-button {
+	padding: 0.5rem 1rem;
+	font: inherit;
+	color: #fff;
+	cursor: pointer;
+	background: #111;
+	border: 0;
+	border-radius: 4px;
+}
+
+.tr-button:hover {
+	background: #333;
+}

package/src/components/button/button.liquid

@@ -0,0 +1,5 @@
+{%- liquid
+	assign label = label | default: 'Click me'
+-%}
+
+<button class="tr-button" type="button">{{ label }}</button>

package/src/components/button/button.ts

@@ -0,0 +1,5 @@
+document.querySelectorAll<HTMLButtonElement>(".tr-button").forEach((button) => {
+	button.addEventListener("click", () => {
+		console.log("tr-button clicked");
+	});
+});

package/src/tsconfig.json

@@ -0,0 +1,10 @@
+{
+	"extends": "../tsconfig.json",
+	"compilerOptions": {
+		"lib": ["dom", "dom.iterable", "esnext"],
+		"paths": {
+			"@/*": ["./*"]
+		}
+	},
+	"include": ["**/*.ts"]
+}