@homepages/template-kit 0.2.0 → 0.3.0

package/dist/cli/check/loader.js

@@ -0,0 +1,142 @@
+import { loadEsbuild } from "./resolve-tool.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],
+		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/stages/deps.js

@@ -0,0 +1,337 @@
+import { CHECK_CONFIG } from "../config.js";
+import { z } from "zod";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { execFile } from "node:child_process";
+
+//#region src/cli/check/stages/deps.ts
+const execFileAsync = promisify(execFile);
+/** Real `execFile`-backed runner. Never throws on a non-zero exit — `npm audit`
+* and `npm ls` both use exit codes to report *findings*, not tool failure, so
+* the caller must always get the payload to parse. */
+const defaultRun = async (cmd, args, cwd) => {
+	try {
+		const { stdout } = await execFileAsync(cmd, args, {
+			cwd,
+			maxBuffer: 64 * 1024 * 1024
+		});
+		return {
+			stdout,
+			code: 0
+		};
+	} catch (err) {
+		const e = err;
+		return {
+			stdout: typeof e.stdout === "string" ? e.stdout : "",
+			code: typeof e.code === "number" ? e.code : 1
+		};
+	}
+};
+async function isFile(p) {
+	try {
+		return (await stat(p)).isFile();
+	} catch {
+		return false;
+	}
+}
+async function isDir(p) {
+	try {
+		return (await stat(p)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/** `fs.realpath`, or `undefined` if the path is missing or unresolvable
+* (e.g. a broken symlink or a genuine symlink loop, which trips `ELOOP`). */
+async function realPathOrUndefined(p) {
+	try {
+		return await realpath(p);
+	} catch {
+		return;
+	}
+}
+async function readJsonIfPresent(path) {
+	if (!await isFile(path)) return void 0;
+	const text = await readFile(path, "utf8");
+	return JSON.parse(text);
+}
+const LOCKFILE_MISSING_FIX = "Run npm install and commit the package-lock.json it writes. A submission without one cannot be reproduced.";
+function lockfileMissingGate(hasLockfile) {
+	if (hasLockfile) return [];
+	return [{
+		ruleId: "template-kit/lockfile-missing",
+		template: "",
+		message: "no package-lock.json at the workspace root.",
+		fix: LOCKFILE_MISSING_FIX
+	}];
+}
+const LOCKFILE_STALE_FIX = "The lockfile does not match package.json. Run npm install and commit the updated lockfile.";
+const npmLsNodeSchema = z.lazy(() => z.object({
+	invalid: z.boolean().optional(),
+	dependencies: z.record(z.string(), npmLsNodeSchema).optional()
+}).passthrough());
+const npmLsPayloadSchema = z.object({
+	problems: z.array(z.unknown()).optional(),
+	dependencies: z.record(z.string(), npmLsNodeSchema).optional()
+}).passthrough();
+function anyInvalid(nodes) {
+	if (!nodes) return false;
+	for (const node of Object.values(nodes)) {
+		if (node.invalid === true) return true;
+		if (anyInvalid(node.dependencies)) return true;
+	}
+	return false;
+}
+async function lockfileStaleGate(run, workspaceRoot) {
+	const { stdout, code } = await run("npm", [
+		"ls",
+		"--json",
+		"--package-lock-only"
+	], workspaceRoot);
+	const parsed = npmLsPayloadSchema.safeParse(safeJsonParse(stdout));
+	if (!(code !== 0 || !parsed.success || (parsed.data.problems?.length ?? 0) > 0 || anyInvalid(parsed.data.dependencies))) return [];
+	return [{
+		ruleId: "template-kit/lockfile-stale",
+		template: "",
+		message: "the lockfile does not satisfy package.json — npm ci would fail.",
+		fix: LOCKFILE_STALE_FIX
+	}];
+}
+function safeJsonParse(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+const SINGLE_REACT_FIX = "Two copies of React break hydration. React is a peer of everything here — deduplicate with npm dedupe, or align the dependency that pins its own copy.";
+const packageManifestSchema = z.object({ version: z.string().optional() }).passthrough();
+async function readVersion(pkgDir) {
+	try {
+		const raw = await readJsonIfPresent(join(pkgDir, "package.json"));
+		const parsed = packageManifestSchema.safeParse(raw);
+		return parsed.success && parsed.data.version !== void 0 ? parsed.data.version : "unknown version";
+	} catch {
+		return "unknown version";
+	}
+}
+/** True when `entry` is worth descending into: a real directory, or a
+* symlink whose target is one. `Dirent.isDirectory()` reports the dirent's
+* OWN type, not what it resolves to — a symlink to a directory (exactly how
+* `npm link` and npm/yarn workspaces lay out linked packages) reports
+* `false`, so trusting it blindly makes the walk blind to every linked
+* package's own `node_modules`. `isDir` re-`stat`s, which follows the link. */
+async function isTraversableDir(dir, entry) {
+	if (entry.isDirectory()) return true;
+	if (!entry.isSymbolicLink()) return false;
+	return isDir(join(dir, entry.name));
+}
+/**
+* Walks `node_modules` for a nested `react` or `react-dom` — one whose own
+* `node_modules` (not the workspace's top-level one) holds a copy. `owner` is
+* the name of the package whose private `node_modules` directory holds the
+* offending copy, so the message can point straight at what to dedupe.
+*
+* `topLevelReal` maps "react"/"react-dom" to the REAL (symlink-resolved)
+* path of the workspace's own top-level copy, if any — see
+* `visitReactCandidate` for why identity is checked against it rather than
+* against walk depth. `visited` is the set of real directory paths already
+* walked: a defense against a symlink cycle (a linked package whose own
+* `node_modules` loops back to an ancestor already on the path) turning this
+* into infinite recursion.
+*/
+async function walkForNestedReact(dir, atTopLevel, owner, out, topLevelReal, visited) {
+	const real = await realPathOrUndefined(dir);
+	if (real === void 0 || visited.has(real)) return;
+	visited.add(real);
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (!await isTraversableDir(dir, entry)) continue;
+		if (entry.name.startsWith("@")) {
+			const scopeDir = join(dir, entry.name);
+			let scoped;
+			try {
+				scoped = await readdir(scopeDir, { withFileTypes: true });
+			} catch {
+				continue;
+			}
+			for (const inner of scoped) {
+				if (!await isTraversableDir(scopeDir, inner)) continue;
+				await visitReactCandidate(join(scopeDir, inner.name), `${entry.name}/${inner.name}`, atTopLevel, owner, out, topLevelReal, visited);
+			}
+			continue;
+		}
+		await visitReactCandidate(join(dir, entry.name), entry.name, atTopLevel, owner, out, topLevelReal, visited);
+	}
+}
+async function visitReactCandidate(pkgDir, name, atTopLevel, owner, out, topLevelReal, visited) {
+	if (!atTopLevel && (name === "react" || name === "react-dom")) {
+		if ((await realPathOrUndefined(pkgDir) ?? pkgDir) !== topLevelReal.get(name)) out.push({
+			name,
+			version: await readVersion(pkgDir),
+			owner
+		});
+	}
+	const nested = join(pkgDir, "node_modules");
+	if (await isDir(nested)) await walkForNestedReact(nested, false, name, out, topLevelReal, visited);
+}
+async function singleReactGate(workspaceRoot) {
+	const nodeModules = join(workspaceRoot, "node_modules");
+	const offenders = [];
+	const topLevelReal = /* @__PURE__ */ new Map();
+	for (const name of ["react", "react-dom"]) {
+		const real = await realPathOrUndefined(join(nodeModules, name));
+		if (real !== void 0) topLevelReal.set(name, real);
+	}
+	await walkForNestedReact(nodeModules, true, "", offenders, topLevelReal, /* @__PURE__ */ new Set());
+	return offenders.map((offender) => ({
+		ruleId: "template-kit/single-react",
+		template: "",
+		message: `a nested copy of ${offender.name}@${offender.version} is bundled inside ${offender.owner}'s own node_modules.`,
+		fix: SINGLE_REACT_FIX
+	}));
+}
+const AUDIT_SEVERITY_FIX = "Run npm audit fix, or upgrade the package the advisory names.";
+const npmAuditPayloadSchema = z.object({ metadata: z.object({ vulnerabilities: z.record(z.string(), z.number()).optional() }).passthrough().optional() }).passthrough();
+async function auditSeverityGate(run, workspaceRoot) {
+	const { stdout } = await run("npm", ["audit", "--json"], workspaceRoot);
+	const parsed = npmAuditPayloadSchema.safeParse(safeJsonParse(stdout));
+	const vulnerabilities = parsed.success ? parsed.data.metadata?.vulnerabilities : void 0;
+	if (vulnerabilities === void 0) return [{
+		ruleId: "template-kit/audit-severity",
+		template: "",
+		message: "npm audit did not return a parseable report — the audit could not run.",
+		fix: "Run npm audit --json in the workspace and fix whatever is preventing it (usually missing network access), then re-run check."
+	}];
+	const offendingSeverities = CHECK_CONFIG.audit.failOn.filter((severity) => (vulnerabilities[severity] ?? 0) > 0);
+	if (offendingSeverities.length === 0) return [];
+	return [{
+		ruleId: "template-kit/audit-severity",
+		template: "",
+		message: `npm audit found ${offendingSeverities.map((severity) => `${String(vulnerabilities[severity] ?? 0)} ${severity}`).join(", ")} severity advisories.`,
+		fix: AUDIT_SEVERITY_FIX
+	}];
+}
+const LICENSE_DENIED_FIX = "Only permissively licensed packages can ship in a template. Replace this one, or ask us to review it.";
+const lockPackageEntrySchema = z.object({
+	version: z.string().optional(),
+	license: z.string().optional(),
+	dependencies: z.record(z.string(), z.string()).optional(),
+	peerDependencies: z.record(z.string(), z.string()).optional(),
+	peerDependenciesMeta: z.record(z.string(), z.object({ optional: z.boolean().optional() }).passthrough()).optional()
+}).passthrough();
+const lockFileSchema = z.object({ packages: z.record(z.string(), lockPackageEntrySchema) }).passthrough();
+/** `"node_modules/@scope/name/node_modules/other"` -> `["@scope/name", "other"]`; `""` -> `[]`. */
+function parseChain(key) {
+	if (key === "") return [];
+	return key.split("/node_modules/").map((segment, i) => i === 0 ? segment.replace(/^node_modules\//, "") : segment);
+}
+function buildKey(chain) {
+	return chain.length === 0 ? "" : `node_modules/${chain.join("/node_modules/")}`;
+}
+/** Node's own nearest-ancestor `node_modules` resolution, applied to lockfile keys instead of disk. */
+function resolveDependencyKey(packages, fromKey, name) {
+	const chain = parseChain(fromKey);
+	for (let i = chain.length; i >= 0; i--) {
+		const candidate = buildKey([...chain.slice(0, i), name]);
+		if (Object.hasOwn(packages, candidate)) return candidate;
+	}
+}
+/**
+* The set of lockfile package keys in the production install tree (what an
+* `npm ci --omit=dev` leaves on disk): the root's `dependencies` (never its
+* `devDependencies`), walked transitively through each package's own
+* `dependencies` and its `peerDependencies`. A `devDependencies` edge is a
+* dead end. An optional peer is walked only when it resolves to an installed
+* entry — one the workspace has anyway is kept by `npm ci --omit=dev`; one it
+* lacks never installs and resolves to nothing.
+*/
+function shippedPackageKeys(packages) {
+	const root = packages[""];
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [];
+	const seed = (fromKey, deps) => {
+		if (!deps) return;
+		for (const name of Object.keys(deps)) {
+			const key = resolveDependencyKey(packages, fromKey, name);
+			if (key !== void 0) queue.push(key);
+		}
+	};
+	seed("", root?.dependencies);
+	for (let key = queue.pop(); key !== void 0; key = queue.pop()) {
+		if (visited.has(key)) continue;
+		visited.add(key);
+		const entry = packages[key];
+		if (!entry) continue;
+		seed(key, entry.dependencies);
+		if (entry.peerDependencies) for (const name of Object.keys(entry.peerDependencies)) {
+			const peerKey = resolveDependencyKey(packages, key, name);
+			if (peerKey !== void 0) queue.push(peerKey);
+		}
+	}
+	return visited;
+}
+function packageNameFromKey(key) {
+	const chain = parseChain(key);
+	return chain[chain.length - 1] ?? key;
+}
+async function licenseOf(entry, workspaceRoot, key) {
+	if (entry.license !== void 0 && entry.license !== "") return entry.license;
+	const raw = await readJsonIfPresent(join(workspaceRoot, key, "package.json")).catch(() => void 0);
+	const parsed = packageManifestLicenseSchema.safeParse(raw);
+	return parsed.success ? parsed.data.license : void 0;
+}
+const packageManifestLicenseSchema = z.object({ license: z.string().optional() }).passthrough();
+async function licenseDeniedGate(lockfileText, workspaceRoot) {
+	const parsed = lockFileSchema.safeParse(safeJsonParse(lockfileText));
+	if (!parsed.success) return [];
+	const packages = parsed.data.packages;
+	const shipped = shippedPackageKeys(packages);
+	const out = [];
+	for (const key of shipped) {
+		const name = packageNameFromKey(key);
+		if (CHECK_CONFIG.licenseExemptions.includes(name)) continue;
+		const entry = packages[key];
+		if (!entry) continue;
+		const license = await licenseOf(entry, workspaceRoot, key);
+		const version = entry.version ?? "unknown version";
+		if (license === void 0) {
+			out.push({
+				ruleId: "template-kit/license-denied",
+				template: "",
+				message: `${name}@${version} has no license field.`,
+				fix: LICENSE_DENIED_FIX
+			});
+			continue;
+		}
+		if (!CHECK_CONFIG.licenseAllowlist.includes(license)) out.push({
+			ruleId: "template-kit/license-denied",
+			template: "",
+			message: `${name}@${version} is licensed ${license}, which is not on the allowlist.`,
+			fix: LICENSE_DENIED_FIX
+		});
+	}
+	return out;
+}
+async function depsStage(workspaceRoot, run = defaultRun) {
+	const lockfilePath = join(workspaceRoot, "package-lock.json");
+	const hasLockfile = await isFile(lockfilePath);
+	const diagnostics = [...lockfileMissingGate(hasLockfile)];
+	if (hasLockfile) {
+		diagnostics.push(...await lockfileStaleGate(run, workspaceRoot));
+		const lockfileText = await readFile(lockfilePath, "utf8");
+		diagnostics.push(...await licenseDeniedGate(lockfileText, workspaceRoot));
+	}
+	diagnostics.push(...await singleReactGate(workspaceRoot));
+	diagnostics.push(...await auditSeverityGate(run, workspaceRoot));
+	return diagnostics;
+}
+
+//#endregion
+export { defaultRun, depsStage };

package/dist/cli/check/stages/lint.js

@@ -0,0 +1,46 @@
+import { resolveFromWorkspace } from "../resolve-tool.js";
+import { sectionOf } from "../paths.js";
+import { relativizePaths } from "../relativize.js";
+import { join, relative } from "node:path";
+
+//#region src/cli/check/stages/lint.ts
+const PARSE_ERROR_RULE_ID = "template-kit/parse-error";
+const FIX_HINTS = {
+	"template-kit/no-nondeterminism": "Remove the clock or randomness read from server-rendered code, or move this logic into an island (a file marked use client).",
+	"template-kit/no-client-runtime-in-server": "Move this into an island (mark the file use client) or drop the browser-only API — a Renderer must be a pure function of its props.",
+	"template-kit/serializable-island-props": "Pass only JSON-serializable values to an island: no functions, Date/Map/Set instances, bigints, NaN, or Infinity.",
+	"template-kit/no-inline-style": "Replace the style prop with a Tailwind class or a design-system token. Inline style bypasses the cascade and responsive prefixes.",
+	"template-kit/no-raw-element": "Use the contract-bearing primitive instead of the raw element: Section for section, Image for img.",
+	"template-kit/image-bare-needs-reason": "Add a bare: comment above the Image explaining why the frame is skipped, or remove the bare prop.",
+	"template-kit/slot-marker-literal": "Give the marker's id a string literal, not an expression, so the slot-marker completeness check can read it statically.",
+	"template-kit/no-hex": "Use a design-system color token instead of a hex literal or CSS color function.",
+	"template-kit/no-css-import-from-render-path": "Delete the relative CSS import. The file's own CSS is already collected by path; use a bare package specifier for a third-party stylesheet.",
+	"template-kit/props-from-schema": "Derive Props from SectionProps<typeof schema> instead of hand-writing the type.",
+	"template-kit/no-client-directive-in-contract": "Remove the use client directive from this contract file. schema.ts, fill-spec.ts, fixtures.ts and Renderer.tsx are read outside the browser."
+};
+async function lintStage(workspaceRoot, template) {
+	const { ESLint } = await resolveFromWorkspace(workspaceRoot, "eslint");
+	const results = await new ESLint({
+		cwd: workspaceRoot,
+		errorOnUnmatchedPattern: false
+	}).lintFiles([join(template.dir, "**/*.{ts,tsx}")]);
+	const out = [];
+	for (const result of results) for (const message of result.messages) {
+		if (message.severity !== 2) continue;
+		const ruleId = message.ruleId ?? PARSE_ERROR_RULE_ID;
+		const text = relativizePaths(message.message, workspaceRoot);
+		out.push({
+			ruleId,
+			template: template.key,
+			section: sectionOf(template, result.filePath),
+			file: relative(workspaceRoot, result.filePath),
+			line: message.line,
+			message: text,
+			fix: FIX_HINTS[ruleId] ?? text
+		});
+	}
+	return out;
+}
+
+//#endregion
+export { lintStage };