@homepages/template-kit 0.9.0-dev-20260719224319 → 0.9.0

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

@@ -1,337 +0,0 @@
-import { CHECK_CONFIG } from "../config.js";
-import { z } from "zod";
-import { promisify } from "node:util";
-import { readFile, readdir, realpath, stat } from "node:fs/promises";
-import { join } from "node:path";
-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

@@ -1,46 +0,0 @@
-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 };

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

@@ -1,98 +0,0 @@
-import { FixtureModuleShape, buildInvariantFixtures } from "../../../schema/fixture-schema.js";
-import { loadSection } from "../loader.js";
-import { resolveFixtureSetMedia } from "../../../media/resolve-fixture-media.js";
-import { flattenLayout } from "../../../schema/rows.js";
-import { renderSectionHtml } from "../../../ssr.js";
-import { checkRenderInvariants } from "../render-invariants.js";
-
-//#region src/cli/check/stages/render.ts
-const SLOT_ID_RE = /data-slot-id="([^"]*)"/g;
-function renderSlotOrder(html) {
-	const seen = /* @__PURE__ */ new Set();
-	const order = [];
-	for (const match of html.matchAll(SLOT_ID_RE)) {
-		const id = match[1];
-		if (seen.has(id)) continue;
-		seen.add(id);
-		order.push(id);
-	}
-	return order;
-}
-function checkSidebarOrder(sectionKey, schema, html) {
-	const out = [];
-	const groupOf = /* @__PURE__ */ new Map();
-	for (const group of schema.meta?.groups ?? []) for (const member of flattenLayout(group.members)) groupOf.set(member, group.id);
-	const cardOf = (slotId) => groupOf.get(slotId) ?? slotId;
-	const slotOrder = renderSlotOrder(html);
-	const renderCardOrder = [];
-	for (const slotId of slotOrder) {
-		const card = cardOf(slotId);
-		if (!renderCardOrder.includes(card)) renderCardOrder.push(card);
-	}
-	const presentCards = new Set(renderCardOrder);
-	const schemaCardOrder = [];
-	for (const slotId of Object.keys(schema.slots)) {
-		const card = cardOf(slotId);
-		if (!presentCards.has(card)) continue;
-		if (!schemaCardOrder.includes(card)) schemaCardOrder.push(card);
-	}
-	if (JSON.stringify(schemaCardOrder) !== JSON.stringify(renderCardOrder)) out.push({
-		section: sectionKey,
-		rule: "sidebar-order",
-		message: `Sidebar card order (schema slot declaration order) does not match page render order.\n  schema: [${schemaCardOrder.join(", ")}]\n  render: [${renderCardOrder.join(", ")}]`
-	});
-	return out;
-}
-async function renderStage(workspaceRoot, template) {
-	const diagnostics = [];
-	for (const section of template.sections) {
-		const file = `templates/${template.key}/sections/${section.name}/Renderer.tsx`;
-		let loaded;
-		let fixtures;
-		try {
-			loaded = await loadSection(workspaceRoot, section);
-			fixtures = resolveFixtureSetMedia(buildInvariantFixtures({
-				schema: loaded.schema,
-				module: FixtureModuleShape.parse(loaded.fixtures),
-				selfAnchor: section.name
-			}));
-		} catch {
-			continue;
-		}
-		for (const fixture of fixtures) {
-			const props = fixture.props;
-			const first = renderSectionHtml(loaded.Renderer, props);
-			if (first !== renderSectionHtml(loaded.Renderer, props)) {
-				diagnostics.push({
-					ruleId: "template-kit/determinism-drift",
-					template: template.key,
-					section: section.name,
-					file,
-					message: `fixture "${fixture.id}" rendered differently twice from the same props`,
-					fix: "Something in the render path is nondeterministic — a clock, a random, or an unstable iteration order. Server-rendered code must be a pure function of its props."
-				});
-				continue;
-			}
-			for (const violation of checkRenderInvariants(first)) diagnostics.push({
-				ruleId: "template-kit/render-invariant",
-				template: template.key,
-				section: section.name,
-				file,
-				message: `fixture "${fixture.id}": ${violation.detail}`,
-				fix: violation.rule === "broken-image" ? "Render a placeholder, or nothing, when an image slot is empty — never an <img> with no src." : "A value reached the page without a formatter. Format it, or render nothing when it is absent."
-			});
-			if (fixture.id === "typical") for (const violation of checkSidebarOrder(section.name, loaded.schema, first)) diagnostics.push({
-				ruleId: "template-kit/sidebar-order",
-				template: template.key,
-				section: section.name,
-				file: `templates/${template.key}/sections/${section.name}/schema.ts`,
-				message: violation.message,
-				fix: "The editor lists slots in schema declaration order. Reorder the schema, or the markup, so the two agree."
-			});
-		}
-	}
-	return diagnostics;
-}
-
-//#endregion
-export { checkSidebarOrder, renderStage };