fix(catalog): detect drift in generated registry and documentation

This commit is contained in:
Miguel Angel Simon Sierra
2026-09-23 02:09:48 -04:00
parent ae5023096b
commit 10ce4b06ca
10 changed files with 314 additions and 51 deletions
+65 -8
View File
@@ -1,10 +1,19 @@
// Fails when the committed docs/public/catalog, which the docs build serves as-is, differs from generator output.
import { spawnSync } from "node:child_process";
import { mkdirSync, readdirSync, readFileSync, mkdtempSync, rmSync } from "node:fs";
import { execFileSync, spawnSync } from "node:child_process";
import {
cpSync,
existsSync,
mkdirSync,
readdirSync,
readFileSync,
mkdtempSync,
rmSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join, relative, resolve, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { runAsCommand } from "./entrypoint.ts";
import { generateCatalog, GENERATED_CATALOG_PATHS } from "./generate-catalog.ts";
const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
const MAX_LISTED = 40;
@@ -44,24 +53,72 @@ function generateInto(outRoot: string): number {
}
/** The catalog as `git` holds it, so a file the working tree has but a .gitignore rule keeps out cannot hide drift. */
function extractCommittedCatalog(into: string): string {
const archive = spawnSync("git", ["archive", "HEAD", "docs/public/catalog"], {
cwd: repoRoot,
function extractCommittedTree(into: string, paths: readonly string[], root = repoRoot): void {
mkdirSync(into, { recursive: true });
const tracked = execFileSync("git", ["ls-tree", "--name-only", "HEAD", "--", ...paths], {
cwd: root,
encoding: "utf8",
})
.trim()
.split("\n")
.filter(Boolean);
if (tracked.length === 0) return;
const archive = spawnSync("git", ["archive", "HEAD", ...tracked], {
cwd: root,
maxBuffer: 2 ** 31 - 1,
});
if (archive.status !== 0) throw new Error("git archive of docs/public/catalog failed.");
if (archive.status !== 0) throw new Error(`git archive failed for ${paths.join(", ")}.`);
mkdirSync(into, { recursive: true });
const untar = spawnSync("tar", ["-x", "-C", into], { input: archive.stdout });
if (untar.status !== 0) throw new Error("could not unpack the committed catalog.");
return join(into, "docs/public/catalog");
}
function copyPaths(from: string, into: string, paths: readonly string[]): void {
mkdirSync(into, { recursive: true });
for (const path of paths) {
if (!existsSync(join(from, path))) continue;
mkdirSync(dirname(join(into, path)), { recursive: true });
cpSync(join(from, path), join(into, path), { recursive: true });
}
}
export function generatedCatalogDifferences(root = repoRoot): string[] {
const base = mkdtempSync(join(tmpdir(), "generated-catalog-drift-"));
try {
const generated = join(base, "generated");
copyPaths(root, generated, [
"registry",
"docs/docs.json",
"docs/catalog/blocks",
"docs/catalog/components",
"docs/public/catalog",
]);
mkdirSync(join(generated, "docs/snippets"), { recursive: true });
generateCatalog(generated);
const actual = join(base, "actual");
extractCommittedTree(actual, GENERATED_CATALOG_PATHS, root);
const expected = join(base, "expected");
copyPaths(generated, expected, GENERATED_CATALOG_PATHS);
return treeDifferences(expected, actual);
} finally {
rmSync(base, { recursive: true, force: true });
}
}
async function main(): Promise<void> {
const catalogDrift = generatedCatalogDifferences();
if (catalogDrift.length > 0) {
throw new Error(
`Generated catalog differs in ${catalogDrift.length} file(s):\n${catalogDrift.slice(0, MAX_LISTED).join("\n")}\nRun \`bun run generate:catalog\` and commit the result.`,
);
}
const base = mkdtempSync(join(tmpdir(), "catalog-drift-"));
const outRoot = join(base, "generated");
try {
if (generateInto(outRoot) !== 0) throw new Error("The catalog payload generator failed.");
const committedRoot = extractCommittedCatalog(join(base, "committed"));
const committed = join(base, "committed");
extractCommittedTree(committed, ["docs/public/catalog"]);
const committedRoot = join(committed, "docs/public/catalog");
const differences = treeDifferences(outRoot, committedRoot);
if (differences.length === 0) return console.log("docs/public/catalog matches the generator.");
const listed = differences.slice(0, MAX_LISTED).map((line) => ` ${line}`);
+6 -4
View File
@@ -16,9 +16,8 @@ export function registryItemNamesFromPaths(paths) {
return names;
}
// A name only counts as an intentional removal or addition when its own
// registry-item.json file was deleted or added in the same diff — a bare
// registry.json edit with no matching file change is never expected.
// Removals require a deleted source. Additions may also restore an index
// entry omitted earlier, but must be backed by a tracked registry-item.json.
export function computeRegistrySetDelta({ baseNames, headNames, removed, added }) {
const expected = new Set([...baseNames].filter((name) => !removed.has(name)));
for (const name of added) expected.add(name);
@@ -39,8 +38,11 @@ export function runRegistrySetDeltaCheck(base, { run, readRegistryJson }) {
const baseManifest = JSON.parse(run(["show", base + ":registry/registry.json"]));
const headManifest = JSON.parse(readRegistryJson());
const removed = registryItemNamesFromPaths(diffPaths(run, base, "D"));
const added = registryItemNamesFromPaths(diffPaths(run, base, "A"));
const baseNames = new Set(baseManifest.items.map(({ name }) => name));
const tracked = registryItemNamesFromPaths(
run(["ls-tree", "-r", "--name-only", "HEAD", "--", "registry"]).split("\n"),
);
const added = new Set([...tracked].filter((name) => !baseNames.has(name)));
const headNames = new Set(headManifest.items.map(({ name }) => name));
const { missing, unexpected } = computeRegistrySetDelta({ baseNames, headNames, removed, added });
return { missing, unexpected, removedCount: removed.size, addedCount: added.size };
+41 -3
View File
@@ -1,4 +1,8 @@
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { describe, it } from "node:test";
import {
computeRegistrySetDelta,
@@ -82,9 +86,7 @@ describe("runRegistrySetDeltaCheck", () => {
if (args[0] === "show") {
return JSON.stringify({ items: [{ name: "existing" }] });
}
// diff --name-only --diff-filter=A|D base...HEAD
const filter = args[2];
if (filter === "--diff-filter=A") {
if (args[0] === "ls-tree") {
return "registry/components/text-match-cut/registry-item.json\n";
}
return "";
@@ -136,3 +138,39 @@ describe("formatRegistrySetDeltaResult", () => {
);
});
});
it("permits a tracked-source repair while refusing invented entries and unbacked deletion", (t) => {
const root = mkdtempSync(join(tmpdir(), "registry-repair-"));
t.after(() => rmSync(root, { recursive: true, force: true }));
const run = (args) => execFileSync("git", args, { cwd: root, encoding: "utf8" }).trim();
run(["init", "--quiet"]);
for (const name of ["existing", "omitted"]) {
const dir = join(root, "registry", "blocks", name);
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, "registry-item.json"), JSON.stringify({ name }));
}
const index = join(root, "registry/registry.json");
const putIndex = (names) =>
writeFileSync(index, JSON.stringify({ items: names.map((name) => ({ name })) }));
putIndex(["existing"]);
run(["add", "."]);
run([
"-c",
"user.name=Test",
"-c",
"user.email=test@example.invalid",
"commit",
"--quiet",
"-m",
"fixture",
]);
const base = run(["rev-parse", "HEAD"]);
const check = () =>
runRegistrySetDeltaCheck(base, { run, readRegistryJson: () => readFileSync(index, "utf8") });
putIndex(["existing", "omitted"]);
assert.deepEqual(check(), { missing: [], unexpected: [], removedCount: 0, addedCount: 1 });
putIndex(["existing", "omitted", "invented"]);
assert.deepEqual(check().unexpected, ["invented"]);
putIndex(["omitted"]);
assert.deepEqual(check().missing, ["existing"]);
});
+3 -1
View File
@@ -3,7 +3,9 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
export function resolveDocsRoot(argv2) {
const root = fileURLToPath(new URL("..", import.meta.url));
const root = path.resolve(
process.env.CATALOG_REPO_ROOT ?? fileURLToPath(new URL("..", import.meta.url)),
);
return { root, docs: path.resolve(argv2 || path.join(root, "docs")) };
}
+4 -6
View File
@@ -14,8 +14,8 @@
*/
import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
import { join, resolve, dirname } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { join, resolve } from "node:path";
import { pathToFileURL } from "node:url";
// Import from source — bun workspace linking doesn't resolve for scripts outside packages/.
import {
type FileTarget,
@@ -25,12 +25,10 @@ import {
} from "../packages/core/src/registry/types.js";
import { withHostedDefaults } from "./registry-hosted-assets.ts";
import { declaredVariables } from "./catalog/component-variables.ts";
import { usesWebgpu } from "./docs-catalog-shared.mjs";
import { resolveDocsRoot, usesWebgpu } from "./docs-catalog-shared.mjs";
const scriptDir = dirname(fileURLToPath(import.meta.url));
const repoRoot = resolve(scriptDir, "..");
const { root: repoRoot, docs: docsDir } = resolveDocsRoot();
const registryDir = resolve(repoRoot, "registry");
const docsDir = resolve(repoRoot, "docs");
const rawSourceBase = "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry";
const catalogImageBase = "https://static.heygen.ai/hyperframes-oss/docs/images/catalog";
const payloadRoot = resolve(repoRoot, "docs/public/catalog");
+38
View File
@@ -0,0 +1,38 @@
import { execFileSync } from "node:child_process";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { runAsCommand } from "./entrypoint.ts";
import { writeRegistryManifest } from "./generate-registry-items.ts";
const scriptsDir = dirname(fileURLToPath(import.meta.url));
const repoRoot = resolve(scriptsDir, "..");
export const GENERATED_CATALOG_PATHS = [
"registry/registry.json",
"docs/catalog/blocks",
"docs/catalog/components",
"docs/public/catalog-index.json",
"docs/snippets/catalog-gallery-data.mdx",
"docs/docs.json",
] as const;
export function generateCatalog(root = repoRoot): void {
writeRegistryManifest(root);
execFileSync(
process.execPath,
["--import", "tsx", join(scriptsDir, "generate-catalog-pages.ts")],
{
cwd: repoRoot,
env: { ...process.env, CATALOG_REPO_ROOT: root },
stdio: ["ignore", "ignore", "inherit"],
},
);
execFileSync(process.execPath, [join(scriptsDir, "sync-docs-catalog.mjs"), join(root, "docs")], {
cwd: repoRoot,
env: { ...process.env, CATALOG_REPO_ROOT: root },
stdio: ["ignore", "ignore", "inherit"],
});
console.log("Registry index, catalog pages, gallery data and navigation regenerated.");
}
runAsCommand(import.meta.url, async () => generateCatalog());
+19 -28
View File
@@ -18,6 +18,7 @@
import { readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
import { join, relative, resolve, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { isEntrypoint } from "./entrypoint.ts";
import {
ITEM_TYPE_DIRS,
type FileTarget,
@@ -27,12 +28,11 @@ import {
// Import from source, like every other script here: bun workspace linking
// does not resolve for scripts outside packages/, so the package name
// typechecks on a machine with a warm node_modules and fails in CI.
} from "../packages/core/src/index.js";
} from "../packages/core/src/registry/types.js";
const scriptDir = dirname(fileURLToPath(import.meta.url));
const repoRoot = resolve(scriptDir, "..");
const examplesDir = resolve(repoRoot, "registry", ITEM_TYPE_DIRS["hyperframes:example"]);
const registryManifestPath = resolve(repoRoot, "registry/registry.json");
const legacyManifestPath = resolve(examplesDir, "templates.json");
const DEFAULT_DURATION_SECONDS = 10;
@@ -158,24 +158,18 @@ function writeItem(item: RegistryItem): void {
* files; scanning the tree keeps them from being dropped on regeneration
* (previously this rewrote 300+ entries down to the 8 examples).
*/
function writeRegistryManifest(): void {
export function writeRegistryManifest(root = repoRoot): void {
const registryManifestPath = resolve(root, "registry/registry.json");
const items: Array<{ name: string; type: RegistryItem["type"] }> = [];
for (const [type, dir] of Object.entries(ITEM_TYPE_DIRS) as Array<
[RegistryItem["type"], string]
>) {
const typeDir = resolve(repoRoot, "registry", dir);
let entries: string[];
try {
entries = readdirSync(typeDir);
} catch {
continue;
}
for (const name of entries.sort()) {
try {
statSync(join(typeDir, name, "registry-item.json"));
} catch {
continue;
}
const typeDir = resolve(root, "registry", dir);
if (statSync(typeDir, { throwIfNoEntry: false }) === undefined) continue;
for (const name of readdirSync(typeDir).sort()) {
if (!statSync(join(typeDir, name)).isDirectory()) continue;
const manifestPath = join(typeDir, name, "registry-item.json");
if (statSync(manifestPath, { throwIfNoEntry: false }) === undefined) continue;
items.push({ name, type });
}
}
@@ -185,24 +179,21 @@ function writeRegistryManifest(): void {
// else, so it carries that field through rather than rewriting the file
// without it: dropping it makes the gate fail and the staleness check answer
// "missing" until someone rebuilds the index.
const existing = ((): { catalogArtifact?: unknown } => {
try {
return JSON.parse(readFileSync(registryManifestPath, "utf-8")) as {
catalogArtifact?: unknown;
};
} catch {
return {};
}
})();
let existing: { catalogArtifact?: unknown } = {};
if (statSync(registryManifestPath, { throwIfNoEntry: false }) !== undefined) {
existing = JSON.parse(readFileSync(registryManifestPath, "utf-8"));
}
const manifest: RegistryManifest = {
$schema: "https://hyperframes.heygen.com/schema/registry.json",
name: "hyperframes",
homepage: "https://hyperframes.heygen.com",
items,
...(existing.catalogArtifact ? { catalogArtifact: existing.catalogArtifact } : {}),
...(existing.catalogArtifact !== undefined
? { catalogArtifact: existing.catalogArtifact }
: {}),
} as RegistryManifest;
writeFileSync(registryManifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
console.log(`wrote ${relative(repoRoot, registryManifestPath)} (${items.length} items)`);
console.log(`wrote ${relative(root, registryManifestPath)} (${items.length} items)`);
}
function main(): void {
@@ -242,4 +233,4 @@ function main(): void {
}
}
main();
if (isEntrypoint(import.meta.url)) main();
+132
View File
@@ -0,0 +1,132 @@
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { test } from "node:test";
import { generatedCatalogDifferences } from "./catalog-drift.ts";
import { generateCatalog } from "./generate-catalog.ts";
function write(root: string, path: string, value: string): void {
mkdirSync(dirname(join(root, path)), { recursive: true });
writeFileSync(join(root, path), value);
}
function git(root: string, ...args: string[]): void {
execFileSync("git", ["-c", "user.name=Test", "-c", "user.email=test@example.invalid", ...args], {
cwd: root,
stdio: "pipe",
env: { ...process.env, LEFTHOOK: "0" },
});
}
function commit(root: string): void {
git(root, "add", ".");
git(root, "commit", "--quiet", "-m", "fixture");
}
function fixture(): string {
const root = mkdtempSync(join(tmpdir(), "catalog-pipeline-test-"));
write(
root,
"docs/docs.json",
JSON.stringify({ navigation: { tabs: [{ tab: "Catalog", groups: [] }] } }),
);
mkdirSync(join(root, "docs/snippets"), { recursive: true });
write(
root,
"registry/registry.json",
JSON.stringify({ items: [], catalogArtifact: { revision: "keep" } }),
);
write(
root,
"registry/examples/authored/registry-item.json",
'{"name":"authored","description":"Keep this prose"}\n',
);
write(
root,
"registry/blocks/chart/registry-item.json",
JSON.stringify({
name: "chart",
type: "hyperframes:block",
title: "Chart",
description: "A chart.",
tags: ["data"],
dimensions: { width: 1920, height: 1080 },
duration: 5,
files: [{ path: "chart.html", target: "chart.html", type: "hyperframes:composition" }],
}),
);
write(root, "registry/blocks/chart/chart.html", '<div data-composition-id="chart">Chart</div>\n');
write(root, "docs/catalog/blocks/chart.mdx", "## Features\n\nKeep the authored section.\n");
git(root, "init", "--quiet");
return root;
}
const outputs = [
"registry/registry.json",
"docs/catalog/blocks/chart.mdx",
"docs/public/catalog-index.json",
"docs/snippets/catalog-gallery-data.mdx",
"docs/docs.json",
];
function snapshot(root: string): Map<string, string> {
return new Map(outputs.map((path) => [path, readFileSync(join(root, path), "utf8")]));
}
test("the complete pipeline is idempotent and preserves authored inputs", (t) => {
const root = fixture();
t.after(() => rmSync(root, { recursive: true, force: true }));
const example = readFileSync(join(root, "registry/examples/authored/registry-item.json"), "utf8");
generateCatalog(root);
const first = snapshot(root);
const index = JSON.parse(first.get("registry/registry.json")!);
assert.deepEqual(index.items, [
{ name: "authored", type: "hyperframes:example" },
{ name: "chart", type: "hyperframes:block" },
]);
assert.deepEqual(index.catalogArtifact, { revision: "keep" });
assert.equal(
readFileSync(join(root, "registry/examples/authored/registry-item.json"), "utf8"),
example,
);
assert.match(first.get("docs/catalog/blocks/chart.mdx")!, /Keep the authored section\./);
generateCatalog(root);
assert.deepEqual(snapshot(root), first);
commit(root);
assert.deepEqual(generatedCatalogDifferences(root), []);
assert.deepEqual(snapshot(root), first);
});
test("committed drift is reported even when the working tree has already been regenerated", (t) => {
const root = fixture();
t.after(() => rmSync(root, { recursive: true, force: true }));
generateCatalog(root);
const clean = snapshot(root);
for (const path of outputs) write(root, path, "stale committed output\n");
commit(root);
for (const [path, text] of clean) write(root, path, text);
assert.deepEqual(
generatedCatalogDifferences(root),
outputs.map((path) => `stale: ${path}`).sort(),
);
assert.deepEqual(snapshot(root), clean);
});
test("an unreadable registry index is not overwritten by regeneration", (t) => {
const root = fixture();
t.after(() => rmSync(root, { recursive: true, force: true }));
write(root, "registry/registry.json", "{invalid json");
assert.throws(() => generateCatalog(root), SyntaxError);
assert.equal(readFileSync(join(root, "registry/registry.json"), "utf8"), "{invalid json");
});
test("a registry scan failure leaves the index unchanged", (t) => {
const root = fixture();
t.after(() => rmSync(root, { recursive: true, force: true }));
const before = readFileSync(join(root, "registry/registry.json"), "utf8");
write(root, "registry/components", "not a directory");
assert.throws(() => generateCatalog(root), { code: "ENOTDIR" });
assert.equal(readFileSync(join(root, "registry/registry.json"), "utf8"), before);
});