diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e3f829bc75..e37ae30eff 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -88,6 +88,10 @@ jobs: - "docs/**" - "registry/**" - "scripts/*catalog*" + - "scripts/generate-registry-items.ts" + - "scripts/build-docs-gallery-nav.mjs" + - "scripts/registry-hosted-assets.ts" + - "scripts/catalog/**" - "scripts/catalog-fetch-mirror/**" - "scripts/docs-catalog-shared.mjs" - "packages/core/**" diff --git a/package.json b/package.json index 8743467b56..887d93ad6a 100644 --- a/package.json +++ b/package.json @@ -34,6 +34,7 @@ "check:tracked-artifacts": "node scripts/check-tracked-artifacts.mjs", "check:docs-snippet-motion": "node scripts/check-docs-snippet-motion.mjs", "check:docs-catalog": "node scripts/check-docs-catalog.mjs", + "generate:catalog": "tsx scripts/generate-catalog.ts", "check:catalog-drift": "node scripts/check-registry-set-delta.mjs origin/main && tsx scripts/catalog-drift.ts", "verify:catalog-payloads": "tsx scripts/verify-catalog-payloads.ts", "check:workspace-contracts": "node scripts/check-workspace-contracts.mjs", @@ -51,7 +52,7 @@ "player:perf": "bun run --filter @hyperframes/player perf", "format:check": "oxfmt --check .", "knip": "knip", - "test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-registry-set-delta.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-pr-captures.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-media-use-copy-parity.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-large-files.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/publish-workflow.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/host-registry-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/catalog-hosted-files.test.ts scripts/player-cdn-pin.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/lint-skills.test.mjs scripts/creator-editing-recipes.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts scripts/catalog-drift.test.ts scripts/catalog-fetch-mirror.test.ts scripts/catalog-script-inlining.test.ts scripts/catalog-detail.test.ts scripts/generate-catalog-pages.test.ts scripts/verify-catalog-payloads.test.ts scripts/registry-skill-files.test.ts scripts/creator-editing-capabilities.test.mjs scripts/generate-catalog-previews.test.ts scripts/registry-primitive-payloads.test.ts registry/components/pan-stations/pan-stations.test.mjs && vitest run scripts/catalog/ scripts/contrastRatchet.test.ts scripts/generate-catalog-payloads.test.ts", + "test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-registry-set-delta.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-pr-captures.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-media-use-copy-parity.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-large-files.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/publish-workflow.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/host-registry-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/catalog-hosted-files.test.ts scripts/player-cdn-pin.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/lint-skills.test.mjs scripts/creator-editing-recipes.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts scripts/catalog-drift.test.ts scripts/generated-catalog-drift.test.ts scripts/catalog-fetch-mirror.test.ts scripts/catalog-script-inlining.test.ts scripts/catalog-detail.test.ts scripts/generate-catalog-pages.test.ts scripts/verify-catalog-payloads.test.ts scripts/registry-skill-files.test.ts scripts/creator-editing-capabilities.test.mjs scripts/generate-catalog-previews.test.ts scripts/registry-primitive-payloads.test.ts registry/components/pan-stations/pan-stations.test.mjs && vitest run scripts/catalog/ scripts/contrastRatchet.test.ts scripts/generate-catalog-payloads.test.ts", "typecheck:scripts": "tsc --noEmit -p scripts/tsconfig.json", "test:skills": "node --test 'skills/**/*.test.mjs' 'packages/cli/src/media-use/**/*.test.mjs'", "generate:previews": "tsx scripts/generate-template-previews.ts", diff --git a/scripts/catalog-drift.ts b/scripts/catalog-drift.ts index 4eec1eab3c..e53721e902 100644 --- a/scripts/catalog-drift.ts +++ b/scripts/catalog-drift.ts @@ -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 { + 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}`); diff --git a/scripts/check-registry-set-delta.mjs b/scripts/check-registry-set-delta.mjs index 3977f4eb4c..e048a1c6c5 100644 --- a/scripts/check-registry-set-delta.mjs +++ b/scripts/check-registry-set-delta.mjs @@ -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 }; diff --git a/scripts/check-registry-set-delta.test.mjs b/scripts/check-registry-set-delta.test.mjs index e38243668c..954351febd 100644 --- a/scripts/check-registry-set-delta.test.mjs +++ b/scripts/check-registry-set-delta.test.mjs @@ -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"]); +}); diff --git a/scripts/docs-catalog-shared.mjs b/scripts/docs-catalog-shared.mjs index 2e6c3bebf1..8f6d458811 100644 --- a/scripts/docs-catalog-shared.mjs +++ b/scripts/docs-catalog-shared.mjs @@ -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")) }; } diff --git a/scripts/generate-catalog-pages.ts b/scripts/generate-catalog-pages.ts index bf435eb0af..a27b84626b 100644 --- a/scripts/generate-catalog-pages.ts +++ b/scripts/generate-catalog-pages.ts @@ -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"); diff --git a/scripts/generate-catalog.ts b/scripts/generate-catalog.ts new file mode 100644 index 0000000000..31d936a2cc --- /dev/null +++ b/scripts/generate-catalog.ts @@ -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()); diff --git a/scripts/generate-registry-items.ts b/scripts/generate-registry-items.ts index b32aa22a5b..916feb02a8 100644 --- a/scripts/generate-registry-items.ts +++ b/scripts/generate-registry-items.ts @@ -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(); diff --git a/scripts/generated-catalog-drift.test.ts b/scripts/generated-catalog-drift.test.ts new file mode 100644 index 0000000000..03a557898b --- /dev/null +++ b/scripts/generated-catalog-drift.test.ts @@ -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", '
Chart
\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 { + 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); +});