/** * 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 * `