Files
hyperframes/packages/cli/src/utils/projectConfigSchema.test.ts
T
Miguel Ángel 045b3a4fd7 feat(cli): report which catalog items a render actually used (#3470)
`registry_item_added` fires when a catalog block is installed and
`render_complete` fires when a video is produced, but nothing joined them, so
"did this video use the catalog?" had no answer.

`hyperframes add` now records each installed item in `hyperframes.json`
(installed files are plain composition HTML with no provenance marker, so this
manifest is the only record that a file came from the registry), and
`render_complete` reports both the items the project installed and the blocks
the rendered composition actually reaches. An item installed and then never
mounted was tried and dropped, which no add-time event can express.

The scan answering "which sub-compositions does this file mount" now has one
owner, `collectSubCompositionSrcs` in `@hyperframes/parsers`, shared with
lint's `lintMissingOrEmptySubComposition`. It holds two invariants that were
previously restated per call site and got re-derived wrongly: it is a text scan
rather than a DOM query, because `<template>` content is inert and every
sub-composition except the render entry is wrapped in one; and references
resolve root-relative at every nesting level, matching `parseSubCompositions`.
It walks tag by tag rather than running open-ended spans across the whole file,
so a malformed composition cannot stall the render plan.

Also: `registryItems` is declared in the config schema, which closes with
`additionalProperties: false`, with an ajv-backed test pinning every key the CLI
writes; counts are never truncated by the name cap, and the reported used blocks
stay a subset of the reported installed ones, with `registry_items_truncated`
marking a windowed list; and an unreadable manifest reports itself rather than
posing as a project that never used the catalog.
2026-08-24 19:56:06 -04:00

77 lines
3.2 KiB
TypeScript

/**
* `docs/schema/hyperframes.json` is authored by hand (sync-schemas.ts mirrors
* only the registry schemas and skips this one), sets `additionalProperties:
* false` at both levels, and is the schema every generated `hyperframes.json`
* points at. So a new config key that lands in code but not in the schema turns
* a valid, committed config into one that fails validation in any schema-aware
* editor, with nothing in CI to notice.
*
* This pins the two together by validating a config that exercises every key
* the CLI can write, nested objects included. A key-name check alone is not
* enough: `registryItems` is an array of objects with their own
* `additionalProperties: false`, so a fourth field on `RegistryItemRecord`
* would recreate the same break one level down.
*/
import { describe, expect, it } from "vitest";
import { readFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
import { dirname, resolve } from "node:path";
import { Ajv2020 } from "ajv/dist/2020.js";
import {
DEFAULT_PROJECT_CONFIG,
type ProjectConfig,
type RegistryItemRecord,
} from "./projectConfig.js";
const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../../..");
const SCHEMA_PATH = resolve(REPO_ROOT, "docs/schema/hyperframes.json");
/**
* One record carrying every field the CLI writes. Typed, so a new field on
* `RegistryItemRecord` is a compile error here until it is listed, and then a
* validation failure until it is declared in the schema.
*/
const EVERY_RECORD_FIELD: Required<RegistryItemRecord> = {
name: "data-chart",
type: "hyperframes:block",
target: "compositions/data-chart.html",
};
/** A config exercising every key the CLI can write, at every level. */
const EVERY_WRITTEN_KEY: Required<ProjectConfig> = {
$schema: "https://hyperframes.heygen.com/schema/hyperframes.json",
registry: "https://example.test/registry",
paths: DEFAULT_PROJECT_CONFIG.paths,
media: { autoProxy: true },
authoringSkill: "product-launch-video",
registryItems: [EVERY_RECORD_FIELD],
};
describe("hyperframes.json schema", () => {
const schema = JSON.parse(readFileSync(SCHEMA_PATH, "utf-8")) as Record<string, unknown>;
const validate = new Ajv2020({ strict: false, validateFormats: false }).compile(schema);
it("accepts a config using every key the CLI can write", () => {
// Guard the guard: without a closed schema at both levels the assertion
// below would pass for an undeclared key rather than failing.
expect(schema.additionalProperties).toBe(false);
const items = (schema.properties as Record<string, { items?: Record<string, unknown> }>)
.registryItems?.items;
expect(items?.additionalProperties).toBe(false);
expect(validate(EVERY_WRITTEN_KEY), JSON.stringify(validate.errors)).toBe(true);
});
// Proves the check above can fail, rather than passing because ajv was
// handed something it never rejects.
it("rejects a key the schema does not declare, at either level", () => {
expect(validate({ ...EVERY_WRITTEN_KEY, unknownTopLevelKey: 1 })).toBe(false);
expect(
validate({
...EVERY_WRITTEN_KEY,
registryItems: [{ ...EVERY_RECORD_FIELD, unknownItemKey: 1 }],
}),
).toBe(false);
});
});