Files
hyperframes/packages/cli/src/utils/catalogUsage.ts
T
Michael WangandClaude Opus 5.5 5a88c9938e fix(parsers,lint,producer,cli): confine composition path lookups to the project (#7534)
* fix(parsers,lint,producer,cli): confine composition path lookups to the project

- The local asset resolver offers only files inside the project: a path
  that is still absolute after its leading `../` is clamped (an encoded
  `//`, a drive letter, a leading backslash) yields no candidate.
- Lint, the catalog-usage walk and `keyframes` read a
  data-composition-src only inside the project. Lint and the catalog
  walk resolve it with the render's own resolver, now shared from
  `@hyperframes/parsers/asset-resolution`, and lint reports one outside
  the project as the render pre-flight does.
- The render compile step does not look at a media, gsap script or image
  path on another UNC or device root, and the GIF and HEIC preparation
  treats a `//host/...` image src as a URL rather than a share.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(parsers,lint): keep Windows absolute asset paths that render copies in

The shared asset resolver now offers only files inside the project. On
Windows a drive-letter src such as C:\media\clip.mp4 used to reach the
real file through the old fallback, and render still copies that file in.
Lint now accepts such a file for media and for CSS written in the page,
so it raises no new missing_local_asset or texture_mask_asset_not_found
error. The media-treatment and normalize-audio commands find it again.

The check never looks at another computer's share, and on macOS and
Linux a src that starts with / is still a project URL, so nothing
changes there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(parsers): expect a drive-letter sub-composition src to be refused on Windows

On Windows an absolute src outside the project is a drive-letter path,
which resolveCompositionSrc refuses, as the render pre-flight already
does. On POSIX the same src is a project URL and resolves inside the
project. The test now expects each platform's result.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(lint): do not report a missing timeline registry a script outside the project may hold

Lint no longer reads a script outside the project. When a root
composition loads such a script, lint cannot know whether the script
registers the timeline, so it no longer reports missing_timeline_registry
for that composition. Render still loads the script. A composition whose
scripts are all in the project is checked as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 04:14:45 +00:00

158 lines
6.1 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,
resolveCompositionSrc,
} 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)) {
const file = resolveCompositionSrc(projectDir, src);
if (file) queue.push(file);
}
}
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 };
}