Files
hyperframes/packages/cli/src/utils/catalogUsage.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

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 };
}