Files
hyperframes/packages/cli/src/utils/compositionCensus.ts
T
Via 490642b78a fix(feedback-lint): tighten census value scoping and defect-keyword matching
Addresses C1-C7 from Rames's adversarial review + N2/N3 nits:

- C1 (positionFixed): inline probe now value-scopes to 'fixed' — previously
  fired on any position value (absolute, relative, sticky), producing a
  false-positive anatomy that would mislead maintainers pattern-matching
  the 'sub-comp + position:fixed capture' bug family.

- C2 (overflowHidden): symmetric fix — inline path now catches
  style='overflow: hidden' via the value-scoped probe, matching the
  <style>-tag branch. Also handles overflow-x/overflow-y variants.

- C3 (VISUAL_DEFECT_KEYWORDS): drop 'render' — CLI's primary command is
  'hyperframes render', so build/perf/hang reports were triggering an
  inappropriate COMPOSITION_STRUCTURE: nudge on the most common failure
  mode. Rely on the more specific tokens (black, blank, flicker, corrupt,
  wrong frame) to identify actual visual defects.

- C4 (mentionsVisualDefect): compile keywords into a word-bounded regex.
  'blackboard', 'blanket', 'visualize', 'corruptible' no longer false-
  positive. Accepted tradeoff: plural forms ('flickers') don't match.

- C5 (marker case-normalization): REPRO COMMAND: / COMPOSITION_STRUCTURE:
  checks now case-insensitive, matching mentionsVisualDefect's
  normalization. Reporters using 'Repro command:' or lowercase
  'composition_structure:' get credit for compliance.

- C6 (background/mask shorthand): inline branch previously required the
  longhand 'background-image:' / 'mask-image:' — style='background:
  url(bg.png)' silently returned false. Now checks both longhand AND
  shorthand-with-url() inline forms.

- C7 (usesGsap docstring): trim promise of data-gsap-* attribute scanning
  that detectGsap never implemented — attribute scan lives outside the
  <script>-only detection path.

- N2 (EMPTY_VALUES): include 'inherit', 'revert', 'revert-layer' — a
  style='position: inherit' is authored intent to defer, not authored
  intent to place.

- N3 (input size cap): early-exit to a zero census on HTML > 20 MB
  rather than feeding linkedom a hostile input. Not expected in normal
  usage; guard for future callers that might pass raw user uploads.

Extends the test locks: 6 new census tests (value-scoping, size cap) and
5 new lint tests (word-boundary rejections, render-noise rejections,
lowercase-marker acceptance). All existing tests unchanged in intent —
only the 'flickers' plural in one test updated to 'flicker' to reflect
the new word-boundary rule.

No behavior change to the wire path: lint is still soft-warn, census is
still never called from feedback.ts, no new dependencies.
2026-07-17 06:22:00 +00:00

323 lines
12 KiB
TypeScript

import { parseHTML } from "linkedom";
/**
* A privacy-preserving structural anatomy of a HyperFrames composition. The
* agent fills this before submitting a non-clean `hyperframes feedback` so
* maintainers can pattern-match the report against known bug families without
* receiving the composition ZIP.
*
* Counts and presence flags only — no file paths, no src URLs, no user text.
*/
export interface CompositionCensus {
/** Counts of media/graphic elements at the failing HTML pass. */
elementCensus: {
video: number;
audio: number;
img: number;
svg: number;
canvas: number;
/** Sub-composition mount points (elements with `data-composition-src`). */
subCompositionMounts: number;
};
/**
* Union set of structural attributes present anywhere in the composition.
* Each key is HF's capture-routing signal set (see references/preview-render.md).
*/
structuralAttributes: {
clipPath: boolean;
filter: boolean;
mixBlendMode: boolean;
transform: boolean;
mask: boolean;
positionFixed: boolean;
overflowHidden: boolean;
zIndex: boolean;
dataHasAudio: boolean;
dataDuration: boolean;
dataStart: boolean;
dataCompositionSrc: boolean;
backgroundImage: boolean;
maskImage: boolean;
};
/**
* Timeline shape summary. Distinguishes flat single-composition renders
* from nested sub-composition trees, and GSAP-driven vs data-attribute-driven.
*/
timelineShape: {
/** True if any `data-composition-src` mount exists. */
nested: boolean;
/** Count of sub-composition mounts (`data-composition-src` count). */
subCompositionCount: number;
/**
* Any GSAP timeline usage detected via `<script>` src or inline
* `gsap.<method>(...)` invocation. Does not scan for `data-gsap-*`
* attributes on non-script elements — HTML-authored GSAP hooks that live
* outside script tags won't surface here.
*/
usesGsap: boolean;
/** Any element carrying `data-start` or `data-duration`. */
usesDataTimeline: boolean;
};
}
const SUB_COMPOSITION_SELECTOR = "[data-composition-src]";
const DATA_HAS_AUDIO_SELECTOR = "[data-has-audio]";
const DATA_DURATION_SELECTOR = "[data-duration]";
const DATA_START_SELECTOR = "[data-start]";
// Values that should NOT count as a "filter"/"mask"/"transform" attribute — the
// browser default or an explicit inherit/revert to the ancestor's value.
// Explicit "none" is authored intent to disable, still counts as noteworthy for
// the census (author touched the property).
const EMPTY_VALUES = new Set(["", "initial", "unset", "inherit", "revert", "revert-layer"]);
// Hard cap on input HTML size. Above this, we early-exit rather than feed
// linkedom a hostile input. The census is a heuristic for maintainer
// pattern-matching; a truncated result is preferable to an OOM on a bad file.
const MAX_HTML_BYTES = 20 * 1024 * 1024;
function iterInlineDeclarations(
el: Element,
visit: (property: string, value: string) => boolean,
): boolean {
const raw = el.getAttribute("style");
if (!raw) return false;
const declarations = raw.split(";");
for (const decl of declarations) {
const colon = decl.indexOf(":");
if (colon <= 0) continue;
const prop = decl.slice(0, colon).trim().toLowerCase();
const value = decl.slice(colon + 1).trim();
if (visit(prop, value)) return true;
}
return false;
}
function hasNonEmptyInlineStyle(el: Element, property: string): boolean {
const target = property.toLowerCase();
return iterInlineDeclarations(el, (prop, value) => {
if (prop !== target) return false;
return !EMPTY_VALUES.has(value.toLowerCase());
});
}
function hasInlineStyleValueMatching(el: Element, property: string, valueRe: RegExp): boolean {
const target = property.toLowerCase();
return iterInlineDeclarations(el, (prop, value) => {
if (prop !== target) return false;
return valueRe.test(value);
});
}
function anyElementHasInlineStyle(doc: Document, property: string): boolean {
const all = doc.querySelectorAll("[style]");
for (const el of Array.from(all)) {
if (hasNonEmptyInlineStyle(el as unknown as Element, property)) return true;
}
return false;
}
function anyElementHasInlineStyleValue(doc: Document, property: string, valueRe: RegExp): boolean {
const all = doc.querySelectorAll("[style]");
for (const el of Array.from(all)) {
if (hasInlineStyleValueMatching(el as unknown as Element, property, valueRe)) return true;
}
return false;
}
function hasStyleTagReferencing(doc: Document, needle: RegExp): boolean {
const styles = doc.querySelectorAll("style");
for (const styleEl of Array.from(styles)) {
const text = (styleEl as unknown as Element).textContent ?? "";
if (needle.test(text)) return true;
}
return false;
}
function detectGsap(doc: Document): boolean {
const scripts = doc.querySelectorAll("script");
for (const script of Array.from(scripts)) {
const el = script as unknown as Element;
const src = el.getAttribute("src") ?? "";
if (/gsap/i.test(src)) return true;
const text = el.textContent ?? "";
if (/\bgsap\.(timeline|to|from|fromTo|set)\b/.test(text)) return true;
}
return false;
}
/**
* Build a structural census of a composition HTML document. Counts elements
* and probes for structural attributes without reading any user-supplied
* strings (paths, src URLs, text content) beyond what's needed to detect
* presence.
*
* Safe to call on partial/malformed HTML — linkedom's parser tolerates the
* usual authoring accidents and the census reports zeros for missing sections.
* Inputs larger than {@link MAX_HTML_BYTES} short-circuit to a zero census
* rather than risk OOMing linkedom on a hostile file.
*/
export function buildCompositionCensus(html: string): CompositionCensus {
if (html.length > MAX_HTML_BYTES) return emptyCensus();
const doc = parseHTML(html).document as unknown as Document;
const count = (selector: string): number => doc.querySelectorAll(selector).length;
const subCompositionCount = count(SUB_COMPOSITION_SELECTOR);
// Inline-style presence probes. Class-based rules would require full CSS
// parsing — out of scope here. But we also check <style> tag contents as a
// best-effort catch for authored stylesheets in the same file.
const anyStyle = (property: string, styleRegex: RegExp): boolean =>
anyElementHasInlineStyle(doc, property) || hasStyleTagReferencing(doc, styleRegex);
// Value-scoped probe — inline branch matches on property value (not just
// property presence), so `position:fixed` doesn't false-positive on
// `position:absolute` and `overflow:hidden` catches inline `overflow:hidden`.
const anyStyleValue = (property: string, inlineValueRe: RegExp, styleRegex: RegExp): boolean =>
anyElementHasInlineStyleValue(doc, property, inlineValueRe) ||
hasStyleTagReferencing(doc, styleRegex);
return {
elementCensus: {
video: count("video"),
audio: count("audio"),
img: count("img"),
svg: count("svg"),
canvas: count("canvas"),
subCompositionMounts: subCompositionCount,
},
structuralAttributes: {
clipPath: anyStyle("clip-path", /clip-path\s*:/i),
filter: anyStyle("filter", /(^|\s|\{)filter\s*:/i),
mixBlendMode: anyStyle("mix-blend-mode", /mix-blend-mode\s*:/i),
transform: anyStyle("transform", /(^|\s|\{)transform\s*:/i),
mask: anyStyle("mask", /(^|\s|\{)mask\s*:/i),
positionFixed: anyStyleValue("position", /^fixed$/i, /position\s*:\s*fixed/i),
overflowHidden: anyStyleValue(
"overflow",
/(^|\b)hidden(\b|$)/i,
/overflow(-[xy])?\s*:\s*hidden/i,
),
zIndex: anyStyle("z-index", /z-index\s*:/i),
dataHasAudio: count(DATA_HAS_AUDIO_SELECTOR) > 0,
dataDuration: count(DATA_DURATION_SELECTOR) > 0,
dataStart: count(DATA_START_SELECTOR) > 0,
dataCompositionSrc: subCompositionCount > 0,
// Match longhand (`background-image:`) OR shorthand (`background:`)
// pointing at a `url(...)`. Same for `mask` / `mask-image`.
backgroundImage:
anyElementHasInlineStyle(doc, "background-image") ||
anyElementHasInlineStyleValue(doc, "background", /url\(/i) ||
hasStyleTagReferencing(doc, /background(-image)?\s*:[^;]*url\(/i),
maskImage:
anyElementHasInlineStyle(doc, "mask-image") ||
anyElementHasInlineStyleValue(doc, "mask", /url\(/i) ||
hasStyleTagReferencing(doc, /mask(-image)?\s*:[^;]*url\(/i),
},
timelineShape: {
nested: subCompositionCount > 0,
subCompositionCount,
usesGsap: detectGsap(doc),
usesDataTimeline: count(DATA_START_SELECTOR) + count(DATA_DURATION_SELECTOR) > 0,
},
};
}
function emptyCensus(): CompositionCensus {
return {
elementCensus: {
video: 0,
audio: 0,
img: 0,
svg: 0,
canvas: 0,
subCompositionMounts: 0,
},
structuralAttributes: {
clipPath: false,
filter: false,
mixBlendMode: false,
transform: false,
mask: false,
positionFixed: false,
overflowHidden: false,
zIndex: false,
dataHasAudio: false,
dataDuration: false,
dataStart: false,
dataCompositionSrc: false,
backgroundImage: false,
maskImage: false,
},
timelineShape: {
nested: false,
subCompositionCount: 0,
usesGsap: false,
usesDataTimeline: false,
},
};
}
/**
* Render the census as the exact `COMPOSITION_STRUCTURE:` block the skill
* mandates for non-10 visual-defect feedback. Reporter-friendly plain text:
* element counts, present attributes as a comma-joined list, and a compact
* timeline summary. Placeholder markers (`<...>`) are left for the reporter
* to fill in for delta/defect location — those slots the parser can't infer
* from HTML alone.
*/
export function renderCompositionCensusBlock(census: CompositionCensus): string {
const { elementCensus, structuralAttributes, timelineShape } = census;
const elementLine = [
`video=${elementCensus.video}`,
`audio=${elementCensus.audio}`,
`img=${elementCensus.img}`,
`svg=${elementCensus.svg}`,
`canvas=${elementCensus.canvas}`,
`subComps=${elementCensus.subCompositionMounts}`,
].join(" ");
const attrPresent: string[] = [];
const push = (key: keyof CompositionCensus["structuralAttributes"], label: string): void => {
if (structuralAttributes[key]) attrPresent.push(label);
};
push("clipPath", "clip-path");
push("filter", "filter");
push("mixBlendMode", "mix-blend-mode");
push("transform", "transform");
push("mask", "mask");
push("positionFixed", "position:fixed");
push("overflowHidden", "overflow:hidden");
push("zIndex", "z-index");
push("dataHasAudio", "data-has-audio");
push("dataDuration", "data-duration");
push("dataStart", "data-start");
push("dataCompositionSrc", "data-composition-src");
push("backgroundImage", "background-image:url");
push("maskImage", "mask-image:url");
const attrLine = attrPresent.length > 0 ? attrPresent.join(", ") : "(none present)";
const shape = timelineShape.nested
? `nested (${timelineShape.subCompositionCount} sub-comps)`
: "flat";
const driver =
[
timelineShape.usesGsap ? "gsap" : null,
timelineShape.usesDataTimeline ? "data-timeline" : null,
]
.filter(Boolean)
.join("+") || "none";
return [
"COMPOSITION_STRUCTURE:",
` elements: ${elementLine}`,
` attributes: ${attrLine}`,
` timeline: ${shape}; driver=${driver}`,
" delta: <what differs between the working workaround-render and the broken default render>",
" defect: <spatial location + frame index range, e.g. top-left / frames 0-30 — omit for non-visual defects>",
].join("\n");
}