mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
`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.
154 lines
6.0 KiB
TypeScript
154 lines
6.0 KiB
TypeScript
/**
|
|
* Which catalog (registry) items a project installed, and which of them the
|
|
* composition being rendered actually reaches.
|
|
*
|
|
* `hyperframes add` is the only place that knows a file came from the registry
|
|
* — installed files are plain composition HTML and carry no provenance marker —
|
|
* so it records each item in `hyperframes.json`. Render reads that manifest
|
|
* back and walks the composition's `data-composition-src` tree, letting the
|
|
* render event report both halves: what the project pulled in, and what
|
|
* survived into the video.
|
|
*
|
|
* The delta is the part no add-time event can produce. `registry_item_added`
|
|
* says a block was installed; only this says it was then thrown away.
|
|
*/
|
|
|
|
import { readFileSync } from "node:fs";
|
|
import { isAbsolute, relative, resolve } from "node:path";
|
|
import { collectSubCompositionSrcs } from "@hyperframes/parsers/asset-resolution";
|
|
import { type RegistryItemRecord, readProjectConfigWithStatus } from "./projectConfig.js";
|
|
|
|
/** Installed catalog items, and the subset the rendered composition reaches. */
|
|
export interface CatalogUsage {
|
|
/**
|
|
* Every item name recorded by `hyperframes add`, sorted, deduped, slug-gated.
|
|
* Not truncated: the reporting cap belongs to whoever builds the event
|
|
* string, so a count taken from this array is the real number.
|
|
*/
|
|
installed: string[];
|
|
/**
|
|
* Installed `hyperframes:block` items whose file is reachable from the render
|
|
* entry. Always a subset of {@link installed}. Components are excluded: they
|
|
* are pasted inline into the user's own markup rather than mounted by src, so
|
|
* a component leaves no trace to match.
|
|
*/
|
|
usedBlocks: string[];
|
|
/**
|
|
* True when `hyperframes.json` exists but could not be read or parsed.
|
|
*
|
|
* A degraded read must not look like a project that never touched the
|
|
* catalog: the no-catalog cohort is the control this whole feature is
|
|
* measured against, and quietly enrolling failures into it biases the
|
|
* comparison toward "the catalog makes no difference".
|
|
*/
|
|
manifestUnreadable: boolean;
|
|
}
|
|
|
|
const EMPTY: CatalogUsage = Object.freeze({
|
|
installed: [],
|
|
usedBlocks: [],
|
|
manifestUnreadable: false,
|
|
});
|
|
|
|
const UNREADABLE: CatalogUsage = Object.freeze({
|
|
installed: [],
|
|
usedBlocks: [],
|
|
manifestUnreadable: true,
|
|
});
|
|
|
|
/**
|
|
* Cap on files visited while walking the sub-composition tree. A composition
|
|
* nests a handful of blocks; anything past this is a pathological or cyclic
|
|
* project, and telemetry must not turn into an unbounded filesystem crawl.
|
|
*/
|
|
const MAX_VISITED_FILES = 250;
|
|
|
|
/** Cap on a single file fed to the scanner, mirroring the composition census. */
|
|
const MAX_HTML_BYTES = 20 * 1024 * 1024;
|
|
|
|
/**
|
|
* Item names are slug-gated before they reach the anonymous event stream, the
|
|
* same guard `normalizeSkillSlug` applies to authoring skills: a custom or
|
|
* hand-edited registry must not be able to push paths, PII, or unbounded
|
|
* cardinality into telemetry. The two rules share a shape but not an owner —
|
|
* a registry name and a skill slug are free to diverge.
|
|
*/
|
|
const REGISTRY_ITEM_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
|
|
|
|
/**
|
|
* Absolute paths of every composition file reachable from `entryPath` through
|
|
* `data-composition-src`, entry included.
|
|
*
|
|
* Two invariants are borrowed rather than re-derived, because getting either
|
|
* wrong silently reports a block that renders in every video as abandoned:
|
|
* references are collected by text scan (`collectSubCompositionSrcs`, so
|
|
* `<template>`-wrapped sub-compositions are visible), and each one resolves
|
|
* against the PROJECT ROOT at every nesting level, never the referencing
|
|
* file's directory. Both mirror the renderer's `parseSubCompositions`.
|
|
*
|
|
* Unreadable files are skipped rather than thrown: this feeds a telemetry
|
|
* property, and a render that produced a video must never fail on the way to
|
|
* reporting it.
|
|
*/
|
|
function reachableCompositions(projectDir: string, entryPath: string): Set<string> {
|
|
const seen = new Set<string>();
|
|
const queue = [resolve(entryPath)];
|
|
while (queue.length > 0 && seen.size < MAX_VISITED_FILES) {
|
|
const current = queue.shift()!;
|
|
if (seen.has(current)) continue;
|
|
seen.add(current);
|
|
let html: string;
|
|
try {
|
|
html = readFileSync(current, "utf-8");
|
|
} catch {
|
|
continue;
|
|
}
|
|
if (html.length > MAX_HTML_BYTES) continue;
|
|
for (const src of collectSubCompositionSrcs(html)) {
|
|
queue.push(resolve(projectDir, src));
|
|
}
|
|
}
|
|
return seen;
|
|
}
|
|
|
|
/** True when `target` (project-relative, per the manifest) is in `reachable`. */
|
|
function isReached(projectDir: string, target: string, reachable: Set<string>): boolean {
|
|
// A manifest target is written project-relative. Guard against an absolute
|
|
// or escaping one rather than resolving it against the wrong root.
|
|
if (isAbsolute(target)) return false;
|
|
const abs = resolve(projectDir, target);
|
|
if (relative(projectDir, abs).startsWith("..")) return false;
|
|
return reachable.has(abs);
|
|
}
|
|
|
|
function reportableNames(names: string[]): string[] {
|
|
return [...new Set(names.filter((name) => REGISTRY_ITEM_NAME.test(name)))].sort();
|
|
}
|
|
|
|
/**
|
|
* Read the project's catalog manifest and resolve it against the composition
|
|
* being rendered. Returns empty sets for a project that never ran
|
|
* `hyperframes add`, which is the honest answer: no catalog items, not unknown.
|
|
*/
|
|
export function summarizeCatalogUsage(projectDir: string, entryPath: string): CatalogUsage {
|
|
const { status, config } = readProjectConfigWithStatus(projectDir);
|
|
if (status === "unreadable") return UNREADABLE;
|
|
|
|
const items: RegistryItemRecord[] = config?.registryItems ?? [];
|
|
if (items.length === 0) return EMPTY;
|
|
|
|
const installed = reportableNames(items.map((item) => item.name));
|
|
if (installed.length === 0) return EMPTY;
|
|
|
|
const reachable = reachableCompositions(projectDir, entryPath);
|
|
const usedBlocks = reportableNames(
|
|
items
|
|
.filter(
|
|
(item) =>
|
|
item.type === "hyperframes:block" && isReached(projectDir, item.target, reachable),
|
|
)
|
|
.map((item) => item.name),
|
|
);
|
|
return { installed, usedBlocks, manifestUnreadable: false };
|
|
}
|