@homepages/template-kit 0.2.0 → 0.4.0

package/dist/cli/check/css.js

@@ -0,0 +1,131 @@
+import { loadEsbuild } from "./resolve-tool.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readdir } from "node:fs/promises";
+
+//#region src/cli/check/css.ts
+/**
+* Every `.css` file anywhere in a section folder (the folder is free-form —
+* an author may nest CSS under components/, enhancers/, wherever), in
+* published order: `styles.css` first (the conventional root-level home),
+* then every other file sorted by path. `snapshots/` and `node_modules/` are
+* skipped — generated or not authored, never hand-CSS.
+*/
+async function sectionCssFiles(dir) {
+	if (!existsSync(dir)) return [];
+	const found = [];
+	const walk = async (d) => {
+		for (const entry of await readdir(d, { withFileTypes: true })) {
+			const full = join(d, entry.name);
+			if (entry.isDirectory()) {
+				if (entry.name === "snapshots" || entry.name === "node_modules") continue;
+				await walk(full);
+			} else if (entry.isFile() && entry.name.endsWith(".css")) found.push(full);
+		}
+	};
+	await walk(dir);
+	const own = join(dir, "styles.css");
+	const rest = found.filter((f) => f !== own).sort();
+	return (existsSync(own) ? [own] : []).concat(rest);
+}
+const ASSET_LOADERS = {
+	".svg": "file",
+	".png": "file",
+	".jpg": "file",
+	".jpeg": "file",
+	".gif": "file",
+	".webp": "file",
+	".avif": "file",
+	".ico": "file",
+	".woff": "file",
+	".woff2": "file",
+	".ttf": "file",
+	".otf": "file",
+	".eot": "file",
+	".mp4": "file",
+	".webm": "file",
+	".mov": "file",
+	".mp3": "file",
+	".wav": "file",
+	".pdf": "file",
+	".zip": "file"
+};
+const ASSET_PUBLIC_PATH = "/section-assets";
+const ASSET_NAMES = "[name]-[hash]";
+/**
+* A section's third-party package CSS — discovered by the bundler, not
+* declared. An author writes `import "swiper/css"` in Renderer.tsx exactly
+* as in React; this runs a CSS-only esbuild pass rooted at Renderer.tsx and
+* returns the emitted stylesheet (empty string if there is none).
+*
+* A relative CSS import in the render path is a lint error
+* (`no-css-import-from-render-path`, already enforced by ESLint) — this pass
+* does not re-implement that rejection, it only has to not crash on one.
+*
+* `platform: "neutral"` defaults `mainFields` to `[]`, which cannot resolve a
+* package that ships only a CJS `main` (no `exports` map) — `mainFields`
+* is set explicitly so such a package still resolves to its ESM `module`
+* build where one exists.
+*/
+async function compileSectionPackageCss(workspaceRoot, sectionDir) {
+	const renderer = join(sectionDir, "Renderer.tsx");
+	if (!existsSync(renderer)) return "";
+	const { build } = await loadEsbuild(workspaceRoot);
+	const css = (await build({
+		entryPoints: [renderer],
+		bundle: true,
+		write: false,
+		minify: true,
+		outdir: join(workspaceRoot, "node_modules", ".template-kit", "check-css"),
+		format: "esm",
+		target: "es2022",
+		platform: "neutral",
+		mainFields: ["module", "main"],
+		jsx: "automatic",
+		external: [
+			"react",
+			"react-dom",
+			"react/jsx-runtime"
+		],
+		loader: { ...ASSET_LOADERS },
+		publicPath: ASSET_PUBLIC_PATH,
+		assetNames: ASSET_NAMES,
+		absWorkingDir: workspaceRoot,
+		logLevel: "silent"
+	})).outputFiles?.find((f) => f.path.endsWith(".css"));
+	return css ? css.text : "";
+}
+/**
+* The 1-based line of the first top-level `@import`, or `undefined` if there
+* is none. Comment-aware: an `@import` mentioned inside a CSS block comment
+* is prose (e.g. a header warning authors not to write one), not a rule — a
+* naive line-regex would false-fire on it.
+*/
+function findImportLine(css) {
+	const lines = css.split("\n");
+	let inComment = false;
+	for (let i = 0; i < lines.length; i++) {
+		let line = lines[i];
+		if (inComment) {
+			const close = line.indexOf("*/");
+			if (close === -1) continue;
+			line = line.slice(close + 2);
+			inComment = false;
+		}
+		for (;;) {
+			const open = line.indexOf("/*");
+			if (open === -1) break;
+			const close = line.indexOf("*/", open + 2);
+			if (close === -1) {
+				line = line.slice(0, open);
+				inComment = true;
+				break;
+			}
+			line = line.slice(0, open) + line.slice(close + 2);
+		}
+		if (/^\s*@import\b/.test(line)) return i + 1;
+	}
+}
+
+//#endregion
+export { ASSET_LOADERS, ASSET_NAMES, ASSET_PUBLIC_PATH, compileSectionPackageCss, findImportLine, sectionCssFiles };

package/dist/cli/check/diagnostics.js

@@ -0,0 +1,32 @@
+//#region src/cli/check/diagnostics.ts
+function location(d) {
+	if (!d.file) return "";
+	return d.line === void 0 ? d.file : `${d.file}:${d.line}`;
+}
+function formatOne(d) {
+	const where = location(d);
+	return `${where ? `  ${where}\n` : ""}    [${d.ruleId}] ${d.message}\n    fix: ${d.fix}\n`;
+}
+function formatHuman(report) {
+	const parts = [];
+	for (const [key, t] of Object.entries(report.templates)) {
+		if (t.ok) {
+			parts.push(`✓ ${key}\n`);
+			continue;
+		}
+		parts.push(`✗ ${key} — ${String(t.diagnostics.length)} problem(s)\n`);
+		for (const d of t.diagnostics) parts.push(formatOne(d));
+	}
+	if (!report.workspace.ok) {
+		parts.push(`✗ workspace — ${String(report.workspace.diagnostics.length)} problem(s)\n`);
+		for (const d of report.workspace.diagnostics) parts.push(formatOne(d));
+	}
+	if (report.ok) parts.push("check passed\n");
+	return parts.join("");
+}
+function toJson(report) {
+	return JSON.stringify(report, null, 2);
+}
+
+//#endregion
+export { formatHuman, toJson };

package/dist/cli/check/index.js

@@ -0,0 +1,87 @@
+import { KIT_VERSION } from "../../index.js";
+import { formatHuman, toJson } from "./diagnostics.js";
+import { loadEsbuild } from "./resolve-tool.js";
+import { resetLoadCache } from "./loader.js";
+import { depsStage } from "./stages/deps.js";
+import { lintStage } from "./stages/lint.js";
+import { renderStage } from "./stages/render.js";
+import { sizeStage } from "./stages/size.js";
+import { treeStage } from "./stages/tree.js";
+import { typecheckStage } from "./stages/typecheck.js";
+import { validateStage } from "./stages/validate/index.js";
+import { findWorkspaceRoot, selectTemplates, templateFromCwd } from "./workspace.js";
+import { parseArgs } from "node:util";
+
+//#region src/cli/check/index.ts
+const STAGES = [
+	typecheckStage,
+	lintStage,
+	validateStage,
+	treeStage,
+	renderStage,
+	sizeStage
+];
+/**
+* A run that gated nothing must never report success. `every()` over an empty set
+* is vacuously true, so a selection of zero templates printed "check passed" and
+* exited 0 having run not one gate — the worst failure this command has, since
+* ingest re-runs it and would accept the submission on that same silence.
+*/
+function emptySelectionDiagnostics(selected, all) {
+	if (selected.length > 0) return [];
+	return [{
+		ruleId: "template-kit/no-templates",
+		template: "",
+		file: "templates",
+		message: all ? "check --all found no template to check: templates/ holds no template folder." : "This workspace has no template to check: templates/ holds no template folder.",
+		fix: "Add a template: templates/<key>/ with a manifest.json declaring its section composition and a sections/ folder holding the sections it composes."
+	}];
+}
+async function checkTemplate(root, template) {
+	const diagnostics = [];
+	for (const stage of STAGES) diagnostics.push(...await stage(root, template));
+	return {
+		ok: diagnostics.length === 0,
+		diagnostics
+	};
+}
+async function runCheck(argv, cwd) {
+	resetLoadCache();
+	const { values, positionals } = parseArgs({
+		args: argv,
+		options: {
+			all: {
+				type: "boolean",
+				default: false
+			},
+			json: {
+				type: "boolean",
+				default: false
+			}
+		},
+		allowPositionals: true
+	});
+	const root = await findWorkspaceRoot(cwd);
+	const selected = await selectTemplates(root, positionals[0] ?? (values.all ? void 0 : templateFromCwd(root, cwd)), values.all, "check");
+	if (selected.length > 0) await loadEsbuild(root);
+	const templates = {};
+	for (const template of selected) templates[template.key] = await checkTemplate(root, template);
+	const workspaceDiagnostics = [...await depsStage(root), ...emptySelectionDiagnostics(selected, values.all)];
+	const workspace = {
+		ok: workspaceDiagnostics.length === 0,
+		diagnostics: workspaceDiagnostics
+	};
+	const report = {
+		ok: workspace.ok && Object.values(templates).every((t) => t.ok),
+		kitVersion: KIT_VERSION,
+		templates,
+		workspace
+	};
+	return {
+		code: report.ok ? 0 : 1,
+		output: values.json ? toJson(report) : formatHuman(report)
+	};
+}
+
+//#endregion
+export { runCheck };

package/dist/cli/check/loader.js

@@ -0,0 +1,146 @@
+import { loadEsbuild } from "./resolve-tool.js";
+import { ASSET_LOADERS, ASSET_NAMES, ASSET_PUBLIC_PATH } from "./css.js";
+import { join, relative } from "node:path";
+import { createHash } from "node:crypto";
+import { mkdir, rm, stat } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+
+//#region src/cli/check/loader.ts
+const CONTRACT_FILES = [
+	"Renderer.tsx",
+	"schema.ts",
+	"fill-spec.ts",
+	"fixtures.ts"
+];
+const EXPECTED_EXPORT = {
+	"Renderer.tsx": "default",
+	"schema.ts": "schema",
+	"fill-spec.ts": "fillSpec",
+	"fixtures.ts": "default"
+};
+/**
+* A section is missing one or more of the four contract files. Typed (not a bare
+* Error) because exactly one stage owns this failure: the tree stage's
+* `bundle-incomplete`, which names the missing file and where it belongs. Every
+* other stage swallows this cause rather than re-reporting the same root problem
+* under a second rule id.
+*/
+var MissingContractFile = class extends Error {
+	files;
+	constructor(files) {
+		super(`Section is missing its contract file(s): ${files.join(", ")}.`);
+		this.files = files;
+		this.name = "MissingContractFile";
+	}
+};
+/** A contract file built, but does not export the binding the contract requires. `file` is workspace-relative. */
+var MissingSectionExport = class extends Error {
+	file;
+	binding;
+	constructor(file, binding) {
+		super(binding === "default" ? `${file} has no default export. It must export the section's ${file.endsWith("Renderer.tsx") ? "renderer component" : "fixture module"} as its default export.` : `${file} does not export "${binding}". It must export a "${binding}" binding.`);
+		this.file = file;
+		this.binding = binding;
+		this.name = "MissingSectionExport";
+	}
+};
+const RESOLVING = Symbol("css-stub:resolving");
+const cssStub = {
+	name: "css-stub",
+	setup(b) {
+		b.onResolve({ filter: /.*/ }, async (args) => {
+			if (args.pluginData === RESOLVING) return null;
+			const resolved = await b.resolve(args.path, {
+				importer: args.importer,
+				namespace: args.namespace,
+				resolveDir: args.resolveDir,
+				kind: args.kind,
+				pluginData: RESOLVING
+			});
+			if (resolved.errors.length === 0 && resolved.path !== "" && resolved.path.endsWith(".css")) return {
+				path: resolved.path,
+				namespace: "css-stub"
+			};
+			if (!args.path.startsWith(".") && !args.path.startsWith("/")) return {
+				path: args.path,
+				external: true
+			};
+			return null;
+		});
+		b.onLoad({
+			filter: /.*/,
+			namespace: "css-stub"
+		}, () => ({
+			contents: "",
+			loader: "js"
+		}));
+	}
+};
+const loadCache = /* @__PURE__ */ new Map();
+/** Drops every memoized section load. Called once per `runCheck`; see the note above. */
+function resetLoadCache() {
+	loadCache.clear();
+}
+/**
+* Transpile + evaluate a section's four contract modules. Throws `MissingContractFile`
+* when one of the four is absent, `MissingSectionExport` when one built but does not
+* export its required binding, and a plain `Error` (esbuild's, path-relativized by the
+* caller) when one fails to build.
+*/
+function loadSection(workspaceRoot, section) {
+	const outdir = join(workspaceRoot, "node_modules", ".template-kit", "check", createHash("sha256").update(section.dir).digest("hex").slice(0, 12));
+	const cached = loadCache.get(outdir);
+	if (cached) return cached;
+	const promise = buildAndLoad(section, outdir, workspaceRoot);
+	loadCache.set(outdir, promise);
+	return promise;
+}
+const isFile = async (p) => {
+	try {
+		return (await stat(p)).isFile();
+	} catch {
+		return false;
+	}
+};
+async function buildAndLoad(section, outdir, workspaceRoot) {
+	const missing = [];
+	for (const file of CONTRACT_FILES) if (!await isFile(join(section.dir, file))) missing.push(file);
+	if (missing.length > 0) throw new MissingContractFile(missing);
+	await rm(outdir, {
+		recursive: true,
+		force: true
+	});
+	await mkdir(outdir, { recursive: true });
+	const { build } = await loadEsbuild(workspaceRoot);
+	await build({
+		entryPoints: CONTRACT_FILES.map((f) => join(section.dir, f)),
+		outdir,
+		bundle: true,
+		splitting: true,
+		format: "esm",
+		platform: "neutral",
+		jsx: "automatic",
+		logLevel: "silent",
+		plugins: [cssStub],
+		loader: { ...ASSET_LOADERS },
+		publicPath: ASSET_PUBLIC_PATH,
+		assetNames: ASSET_NAMES,
+		absWorkingDir: workspaceRoot
+	});
+	const load = async (source, emitted) => {
+		const mod = await import(pathToFileURL(join(outdir, emitted)).href);
+		const binding = EXPECTED_EXPORT[source];
+		const value = mod[binding];
+		if (value === void 0) throw new MissingSectionExport(relative(workspaceRoot, join(section.dir, source)), binding);
+		return value;
+	};
+	return {
+		Renderer: await load("Renderer.tsx", "Renderer.js"),
+		schema: await load("schema.ts", "schema.js"),
+		fillSpec: await load("fill-spec.ts", "fill-spec.js"),
+		fixtures: await load("fixtures.ts", "fixtures.js")
+	};
+}
+
+//#endregion
+export { CONTRACT_FILES, MissingContractFile, MissingSectionExport, cssStub, loadSection, resetLoadCache };

package/dist/cli/check/paths.js

@@ -0,0 +1,15 @@
+import { relative, sep } from "node:path";
+
+//#region src/cli/check/paths.ts
+/** `file` is `dir` itself or nested under it. */
+function isUnder(dir, file) {
+	const rel = relative(dir, file);
+	return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`);
+}
+/** The section `file` sits inside, or `undefined` when it isn't under any of the template's sections. */
+function sectionOf(template, file) {
+	return template.sections.find((section) => isUnder(section.dir, file))?.name;
+}
+
+//#endregion
+export { isUnder, sectionOf };

package/dist/cli/check/relativize.js

@@ -0,0 +1,18 @@
+import { resolve, sep } from "node:path";
+
+//#region src/cli/check/relativize.ts
+function escapeRegExp(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Rewrites every occurrence of `workspaceRoot` in a tool-sourced message to the
+* path an author would type: workspace-relative, or "." for the root itself.
+* Idempotent, and a no-op on a message that names no path.
+*/
+function relativizePaths(message, workspaceRoot) {
+	const root = resolve(workspaceRoot);
+	return message.replace(new RegExp(`${escapeRegExp(root)}${escapeRegExp(sep)}`, "g"), "").replace(new RegExp(escapeRegExp(root), "g"), ".");
+}
+
+//#endregion
+export { relativizePaths };

package/dist/cli/check/render-invariants.js

@@ -0,0 +1,24 @@
+//#region src/cli/check/render-invariants.ts
+function checkRenderInvariants(html) {
+	const violations = [];
+	if (html.includes("[object Object]")) violations.push({
+		rule: "sentinel-text",
+		detail: "rendered text contains \"[object Object]\""
+	});
+	for (const m of html.matchAll(/>\s*(null|undefined|NaN)\s*</g)) violations.push({
+		rule: "sentinel-text",
+		detail: `rendered leaf is the bare sentinel "${m[1]}"`
+	});
+	for (const m of html.matchAll(/<img\b[^>]*>/g)) {
+		const attr = /\ssrc\s*=\s*(?:"([^"]*)"|'([^']*)')/.exec(m[0]);
+		const src = attr ? attr[1] ?? attr[2] : void 0;
+		if (src === void 0 || src.trim() === "" || src === "undefined" || src === "null") violations.push({
+			rule: "broken-image",
+			detail: `<img> with ${src === void 0 ? "no src" : `src="${src}"`}`
+		});
+	}
+	return violations;
+}
+
+//#endregion
+export { checkRenderInvariants };

package/dist/cli/check/resolve-tool.js

@@ -0,0 +1,38 @@
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+
+//#region src/cli/check/resolve-tool.ts
+/**
+* Loads `specifier` exactly as code running in the workspace at `root` would:
+* resolved from that workspace's own `package.json`, never from this
+* package's dependency tree. A missing install is a clean, actionable
+* `Error` — never a bare `MODULE_NOT_FOUND` stack trace.
+*/
+async function resolveFromWorkspace(root, specifier) {
+	const require = createRequire(pathToFileURL(join(root, "package.json")));
+	let resolved;
+	try {
+		resolved = require.resolve(specifier);
+	} catch {
+		throw new Error(`${specifier} is not installed in this workspace. Install it: npm i -D ${specifier}`);
+	}
+	return await import(pathToFileURL(resolved).href);
+}
+/**
+* The workspace's esbuild — `check` transpiles a section's contract modules
+* (loader.ts), bundles its package CSS (css.ts) and measures its published bytes
+* (stages/size.ts) with it.
+*
+* `typeof import("esbuild")` is a TYPE-only import: it is erased at build time, so
+* this module never carries a static `esbuild` import into the shipped `dist/`, and
+* a consumer that only renders sections never installs it. Every call site must
+* `await` this rather than importing `build` at module scope — a static import would
+* put esbuild back on the critical path of `import "@homepages/template-kit"`.
+*/
+function loadEsbuild(root) {
+	return resolveFromWorkspace(root, "esbuild");
+}
+
+//#endregion
+export { loadEsbuild, resolveFromWorkspace };

package/dist/cli/check/section-assets.js

@@ -0,0 +1,58 @@
+import { loadEsbuild } from "./resolve-tool.js";
+import { ASSET_LOADERS, ASSET_NAMES, ASSET_PUBLIC_PATH, sectionCssFiles } from "./css.js";
+import { isUnder } from "./paths.js";
+import { extname, join, resolve } from "node:path";
+
+//#region src/cli/check/section-assets.ts
+const ASSET_EXTS = new Set(Object.keys(ASSET_LOADERS));
+async function referencedSectionAssets(workspaceRoot, section) {
+	const { build } = await loadEsbuild(workspaceRoot);
+	const referenced = /* @__PURE__ */ new Set();
+	const collect = (inputs) => {
+		for (const key of Object.keys(inputs ?? {})) {
+			const abs = resolve(workspaceRoot, key);
+			if (ASSET_EXTS.has(extname(abs).toLowerCase()) && isUnder(section.dir, abs)) referenced.add(abs);
+		}
+	};
+	collect((await build({
+		entryPoints: [join(section.dir, "Renderer.tsx")],
+		bundle: true,
+		write: false,
+		metafile: true,
+		format: "esm",
+		platform: "browser",
+		jsx: "automatic",
+		outdir: "dist",
+		external: [
+			"react",
+			"react-dom",
+			"react-dom/server",
+			"react/jsx-runtime",
+			"react/jsx-dev-runtime"
+		],
+		loader: { ...ASSET_LOADERS },
+		publicPath: ASSET_PUBLIC_PATH,
+		assetNames: ASSET_NAMES,
+		absWorkingDir: workspaceRoot,
+		logLevel: "silent"
+	})).metafile?.inputs);
+	for (const cssFile of await sectionCssFiles(section.dir)) collect((await build({
+		entryPoints: [cssFile],
+		bundle: true,
+		write: false,
+		metafile: true,
+		outdir: "dist",
+		loader: {
+			".css": "css",
+			...ASSET_LOADERS
+		},
+		publicPath: ASSET_PUBLIC_PATH,
+		assetNames: ASSET_NAMES,
+		absWorkingDir: workspaceRoot,
+		logLevel: "silent"
+	})).metafile?.inputs);
+	return referenced;
+}
+
+//#endregion
+export { referencedSectionAssets };