mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
feat(skills): add composition-structure block + soft-warn feedback lint
Extend the CLI feedback reproduction packet (#2498) with a fifth mandated field, `COMPOSITION_STRUCTURE:`, and enforce presence of `REPRO COMMAND:` / `COMPOSITION_STRUCTURE:` at feedback-submit time. - Skill + reference now specify `COMPOSITION_STRUCTURE:` — a privacy-preserving structural anatomy (element census + attribute presence + timeline shape + delta + defect location) — required for any rating <=7 that describes a visual defect. - `buildCompositionCensus()` + `renderCompositionCensusBlock()` auto-fill the block from composition HTML so agents don't ask the human user to hand-count `<video>` / `<img>` / sub-comp mounts. Counts + presence flags only — no file paths, no src URLs, no user text. - `hyperframes feedback` soft-warns (never blocks) when a non-10 `--comment` is missing `REPRO COMMAND:`, and when a rating-<=7 visual-defect comment is missing `COMPOSITION_STRUCTURE:`. The warning points at the auto-census helper so agents remediate themselves. - `coreSkillContent.test.ts` locks the new literal in both the skill and the reference file, following #2498's pattern. Extends #2498. Follow-up: no change to `doctorSummary` generation, no change to the feedback-submission API endpoint, no refactor of #2498's doc-content Jest test. Signed-off-by: Via
This commit is contained in:
Via
@@ -35,6 +35,20 @@ describe("hyperframes-core contract docs", () => {
|
||||
expect(renderReference).toContain("OUTCOME:");
|
||||
expect(renderReference).toContain("WORKAROUND:");
|
||||
});
|
||||
|
||||
it("mandates a composition-structure block for visual-defect feedback", () => {
|
||||
const skill = read("skills", "hyperframes-cli", "SKILL.md");
|
||||
const renderReference = read("skills", "hyperframes-cli", "references", "preview-render.md");
|
||||
|
||||
// Skill teaches the mandate at a high level.
|
||||
expect(skill).toContain("COMPOSITION_STRUCTURE:");
|
||||
// Reference carries the fillable block + agent-helper pointer.
|
||||
expect(renderReference).toContain("COMPOSITION_STRUCTURE:");
|
||||
expect(renderReference).toContain("elements: video=");
|
||||
expect(renderReference).toContain("attributes:");
|
||||
expect(renderReference).toContain("timeline:");
|
||||
expect(renderReference).toContain("buildCompositionCensus");
|
||||
});
|
||||
});
|
||||
|
||||
describe("media-use TTS documentation", () => {
|
||||
|
||||
@@ -12,6 +12,7 @@ import { buildIssueUrl, HYPERFRAMES_REPO_URL } from "../utils/feedbackIssue.js";
|
||||
import { VERSION } from "../version.js";
|
||||
import { c } from "../ui/colors.js";
|
||||
import { parseFeedbackRating } from "../utils/feedbackRating.js";
|
||||
import { lintFeedbackComment } from "../utils/feedbackLint.js";
|
||||
|
||||
export const examples: Example[] = [
|
||||
["Submit render feedback", 'hyperframes feedback --rating 8 --comment "fast but font missing"'],
|
||||
@@ -156,6 +157,13 @@ export default defineCommand({
|
||||
const comment = normalizeComment(args.comment);
|
||||
const doctorSummary = await getDoctorSummary();
|
||||
|
||||
// Soft-warn (never blocks) when the comment for a non-clean report is
|
||||
// missing the mandated reproduction-packet markers. Prints before the
|
||||
// submission ack so the reporter sees the nudge while their run is fresh.
|
||||
for (const warning of lintFeedbackComment({ rating, comment })) {
|
||||
console.log(c.warn(`⚠ ${warning.message}`));
|
||||
}
|
||||
|
||||
// The standalone command runs separately from `render`, so it has no real
|
||||
// elapsed time to report. Omit it rather than recording a fake duration.
|
||||
trackRenderFeedback({ rating, comment, doctorSummary });
|
||||
|
||||
@@ -0,0 +1,135 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { buildCompositionCensus, renderCompositionCensusBlock } from "./compositionCensus.js";
|
||||
|
||||
const MINIMAL_HTML = `<!doctype html>
|
||||
<html>
|
||||
<body>
|
||||
<div data-composition-id="main" data-start="0" data-duration="5"></div>
|
||||
</body>
|
||||
</html>`;
|
||||
|
||||
const RICH_HTML = `<!doctype html>
|
||||
<html>
|
||||
<head>
|
||||
<style>
|
||||
.card { filter: blur(4px); mix-blend-mode: multiply; }
|
||||
.fixed-bar { position: fixed; overflow: hidden; }
|
||||
</style>
|
||||
<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<div data-composition-id="main" data-start="0" data-duration="10">
|
||||
<video data-has-audio="true"></video>
|
||||
<video></video>
|
||||
<audio></audio>
|
||||
<img />
|
||||
<img />
|
||||
<img />
|
||||
<svg></svg>
|
||||
<canvas></canvas>
|
||||
<div data-composition-src="scenes/intro.html" data-start="0"></div>
|
||||
<div data-composition-src="scenes/outro.html" data-start="5"></div>
|
||||
<div style="clip-path: circle(50%); transform: translateX(10px); z-index: 3"></div>
|
||||
<div style="background-image: url('bg.png')"></div>
|
||||
<div style="mask-image: url('mask.svg')"></div>
|
||||
</div>
|
||||
<script>
|
||||
gsap.timeline().to(".card", { x: 100 });
|
||||
</script>
|
||||
</body>
|
||||
</html>`;
|
||||
|
||||
describe("buildCompositionCensus", () => {
|
||||
it("counts zero media on a minimal composition", () => {
|
||||
const c = buildCompositionCensus(MINIMAL_HTML);
|
||||
expect(c.elementCensus).toEqual({
|
||||
video: 0,
|
||||
audio: 0,
|
||||
img: 0,
|
||||
svg: 0,
|
||||
canvas: 0,
|
||||
subCompositionMounts: 0,
|
||||
});
|
||||
expect(c.timelineShape.nested).toBe(false);
|
||||
expect(c.timelineShape.subCompositionCount).toBe(0);
|
||||
expect(c.timelineShape.usesGsap).toBe(false);
|
||||
expect(c.timelineShape.usesDataTimeline).toBe(true);
|
||||
});
|
||||
|
||||
it("counts each element category on a rich composition", () => {
|
||||
const c = buildCompositionCensus(RICH_HTML);
|
||||
expect(c.elementCensus).toEqual({
|
||||
video: 2,
|
||||
audio: 1,
|
||||
img: 3,
|
||||
svg: 1,
|
||||
canvas: 1,
|
||||
subCompositionMounts: 2,
|
||||
});
|
||||
});
|
||||
|
||||
it("detects structural attributes from both inline style and <style> rules", () => {
|
||||
const c = buildCompositionCensus(RICH_HTML);
|
||||
// Inline-style probes
|
||||
expect(c.structuralAttributes.clipPath).toBe(true);
|
||||
expect(c.structuralAttributes.transform).toBe(true);
|
||||
expect(c.structuralAttributes.zIndex).toBe(true);
|
||||
expect(c.structuralAttributes.backgroundImage).toBe(true);
|
||||
expect(c.structuralAttributes.maskImage).toBe(true);
|
||||
// <style> tag probes
|
||||
expect(c.structuralAttributes.filter).toBe(true);
|
||||
expect(c.structuralAttributes.mixBlendMode).toBe(true);
|
||||
expect(c.structuralAttributes.positionFixed).toBe(true);
|
||||
expect(c.structuralAttributes.overflowHidden).toBe(true);
|
||||
// data-* attribute probes
|
||||
expect(c.structuralAttributes.dataHasAudio).toBe(true);
|
||||
expect(c.structuralAttributes.dataDuration).toBe(true);
|
||||
expect(c.structuralAttributes.dataStart).toBe(true);
|
||||
expect(c.structuralAttributes.dataCompositionSrc).toBe(true);
|
||||
});
|
||||
|
||||
it("reports absent attributes as false on minimal HTML", () => {
|
||||
const c = buildCompositionCensus(MINIMAL_HTML);
|
||||
expect(c.structuralAttributes.clipPath).toBe(false);
|
||||
expect(c.structuralAttributes.filter).toBe(false);
|
||||
expect(c.structuralAttributes.mixBlendMode).toBe(false);
|
||||
expect(c.structuralAttributes.dataHasAudio).toBe(false);
|
||||
expect(c.structuralAttributes.backgroundImage).toBe(false);
|
||||
expect(c.structuralAttributes.maskImage).toBe(false);
|
||||
});
|
||||
|
||||
it("detects gsap from both script src and inline gsap.* calls", () => {
|
||||
expect(buildCompositionCensus(RICH_HTML).timelineShape.usesGsap).toBe(true);
|
||||
const inlineOnly = `<html><body><div data-composition-id="m"></div><script>gsap.to('.x', {})</script></body></html>`;
|
||||
expect(buildCompositionCensus(inlineOnly).timelineShape.usesGsap).toBe(true);
|
||||
const noGsap = `<html><body><div data-composition-id="m"></div><script>console.log('hi')</script></body></html>`;
|
||||
expect(buildCompositionCensus(noGsap).timelineShape.usesGsap).toBe(false);
|
||||
});
|
||||
|
||||
it("marks timelines as nested when sub-comp mounts exist", () => {
|
||||
const c = buildCompositionCensus(RICH_HTML);
|
||||
expect(c.timelineShape.nested).toBe(true);
|
||||
expect(c.timelineShape.subCompositionCount).toBe(2);
|
||||
});
|
||||
});
|
||||
|
||||
describe("renderCompositionCensusBlock", () => {
|
||||
it("emits a REPRO-packet-compatible block starting with the mandated header", () => {
|
||||
const block = renderCompositionCensusBlock(buildCompositionCensus(RICH_HTML));
|
||||
expect(block.startsWith("COMPOSITION_STRUCTURE:")).toBe(true);
|
||||
expect(block).toContain("elements: video=2 audio=1 img=3 svg=1 canvas=1 subComps=2");
|
||||
expect(block).toContain("attributes:");
|
||||
expect(block).toContain("timeline: nested (2 sub-comps); driver=gsap+data-timeline");
|
||||
// Placeholder slots the parser can't infer.
|
||||
expect(block).toContain("delta:");
|
||||
expect(block).toContain("defect:");
|
||||
});
|
||||
|
||||
it("emits '(none present)' on the attributes line when no structural attrs are found", () => {
|
||||
const empty = `<html><body><div data-composition-id="m"></div></body></html>`;
|
||||
const block = renderCompositionCensusBlock(buildCompositionCensus(empty));
|
||||
expect(block).toContain("attributes: (none present)");
|
||||
expect(block).toContain("timeline: flat; driver=none");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,234 @@
|
||||
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 (script tags referencing gsap or data-gsap-*). */
|
||||
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. 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"]);
|
||||
|
||||
function hasNonEmptyInlineStyle(el: Element, property: string): boolean {
|
||||
const raw = el.getAttribute("style");
|
||||
if (!raw) return false;
|
||||
// Case-insensitive property match. We intentionally do NOT parse CSS
|
||||
// shorthand-style semantics — a `background: url(...)` in the shorthand
|
||||
// still surfaces via a substring probe of the property token, which is
|
||||
// sufficient for structural presence signaling.
|
||||
const target = property.toLowerCase();
|
||||
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 (prop === target && !EMPTY_VALUES.has(value.toLowerCase())) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
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 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.
|
||||
*/
|
||||
export function buildCompositionCensus(html: string): CompositionCensus {
|
||||
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);
|
||||
|
||||
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:
|
||||
anyElementHasInlineStyle(doc, "position") ||
|
||||
hasStyleTagReferencing(doc, /position\s*:\s*fixed/i),
|
||||
overflowHidden: hasStyleTagReferencing(doc, /overflow\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,
|
||||
backgroundImage: anyStyle("background-image", /background(-image)?\s*:[^;]*url\(/i),
|
||||
maskImage: anyStyle("mask-image", /mask(-image)?\s*:[^;]*url\(/i),
|
||||
},
|
||||
timelineShape: {
|
||||
nested: subCompositionCount > 0,
|
||||
subCompositionCount,
|
||||
usesGsap: detectGsap(doc),
|
||||
usesDataTimeline: count(DATA_START_SELECTOR) + count(DATA_DURATION_SELECTOR) > 0,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 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");
|
||||
}
|
||||
@@ -0,0 +1,105 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
COMPOSITION_STRUCTURE_RATING_CEILING,
|
||||
VISUAL_DEFECT_KEYWORDS,
|
||||
lintFeedbackComment,
|
||||
mentionsVisualDefect,
|
||||
} from "./feedbackLint.js";
|
||||
|
||||
describe("lintFeedbackComment", () => {
|
||||
it("returns no warnings for a perfect rating regardless of comment", () => {
|
||||
expect(lintFeedbackComment({ rating: 10, comment: "black frame at 0.5s, no REPRO" })).toEqual(
|
||||
[],
|
||||
);
|
||||
});
|
||||
|
||||
it("returns no warnings when the comment is missing or blank", () => {
|
||||
expect(lintFeedbackComment({ rating: 6, comment: undefined })).toEqual([]);
|
||||
expect(lintFeedbackComment({ rating: 6, comment: "" })).toEqual([]);
|
||||
expect(lintFeedbackComment({ rating: 6, comment: " \n " })).toEqual([]);
|
||||
});
|
||||
|
||||
it("warns on non-10 comments missing REPRO COMMAND:", () => {
|
||||
const warnings = lintFeedbackComment({
|
||||
rating: 6,
|
||||
comment: "fast but crashed after a bit",
|
||||
});
|
||||
expect(warnings).toHaveLength(1);
|
||||
expect(warnings[0]?.code).toBe("missing-repro-command");
|
||||
expect(warnings[0]?.message).toContain("REPRO COMMAND:");
|
||||
});
|
||||
|
||||
it("stays silent when the reporter already included a REPRO COMMAND: block", () => {
|
||||
const warnings = lintFeedbackComment({
|
||||
rating: 4,
|
||||
comment: [
|
||||
"cloudrun submission kept timing out.",
|
||||
"REPRO COMMAND: cd project && npx hyperframes cloudrun submit",
|
||||
"EXPECTED / ACTUAL: uploads / hangs at seek",
|
||||
].join("\n"),
|
||||
});
|
||||
expect(warnings).toEqual([]);
|
||||
});
|
||||
|
||||
it("warns on rating<=7 visual-defect comments missing COMPOSITION_STRUCTURE:", () => {
|
||||
const warnings = lintFeedbackComment({
|
||||
rating: 5,
|
||||
comment: [
|
||||
"REPRO COMMAND: cd proj && npx hyperframes render",
|
||||
"EXPECTED / ACTUAL: output correct / black frame at 0.5s",
|
||||
].join("\n"),
|
||||
});
|
||||
expect(warnings).toHaveLength(1);
|
||||
expect(warnings[0]?.code).toBe("missing-composition-structure");
|
||||
expect(warnings[0]?.message).toContain("COMPOSITION_STRUCTURE:");
|
||||
expect(warnings[0]?.message).toContain("buildCompositionCensus");
|
||||
});
|
||||
|
||||
it("skips the composition-structure warning above the rating ceiling", () => {
|
||||
const warnings = lintFeedbackComment({
|
||||
rating: COMPOSITION_STRUCTURE_RATING_CEILING + 1,
|
||||
comment: [
|
||||
"REPRO COMMAND: cd proj && npx hyperframes render",
|
||||
"minor black bar on the right edge; workaround with --resolution landscape",
|
||||
].join("\n"),
|
||||
});
|
||||
// Missing structure warning is suppressed at rating 8+.
|
||||
expect(warnings.filter((w) => w.code === "missing-composition-structure")).toEqual([]);
|
||||
});
|
||||
|
||||
it("skips the composition-structure warning when no visual-defect keyword is present", () => {
|
||||
const warnings = lintFeedbackComment({
|
||||
rating: 4,
|
||||
comment: [
|
||||
"docker mode always fails on Alpine",
|
||||
"REPRO COMMAND: docker run ... && npx hyperframes doctor --docker",
|
||||
].join("\n"),
|
||||
});
|
||||
expect(warnings.filter((w) => w.code === "missing-composition-structure")).toEqual([]);
|
||||
});
|
||||
|
||||
it("emits both warnings when a low-rating visual comment lacks both markers", () => {
|
||||
const warnings = lintFeedbackComment({
|
||||
rating: 3,
|
||||
comment: "flickers at every scene boundary",
|
||||
});
|
||||
expect(new Set(warnings.map((w) => w.code))).toEqual(
|
||||
new Set(["missing-repro-command", "missing-composition-structure"]),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("mentionsVisualDefect", () => {
|
||||
it.each(VISUAL_DEFECT_KEYWORDS.map((kw) => kw as string))(
|
||||
"matches keyword %j case-insensitively",
|
||||
(kw) => {
|
||||
expect(mentionsVisualDefect(`Reports a ${kw.toUpperCase()} issue`)).toBe(true);
|
||||
},
|
||||
);
|
||||
|
||||
it("returns false for comments about non-visual friction", () => {
|
||||
expect(mentionsVisualDefect("cli hangs on init prompt in non-TTY shells")).toBe(false);
|
||||
expect(mentionsVisualDefect("cloudrun deploy expired auth token")).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,111 @@
|
||||
import { FEEDBACK_RATING_SCALE } from "./feedbackRating.js";
|
||||
|
||||
/**
|
||||
* Keywords that suggest the reporter is describing a visual defect (as opposed
|
||||
* to a build failure, missing feature, or plain workflow friction). When these
|
||||
* appear in a non-10 feedback comment, the reporter should include a
|
||||
* `COMPOSITION_STRUCTURE:` block so maintainers can pattern-match against
|
||||
* known bug families without receiving the composition ZIP. Matched
|
||||
* case-insensitively against the raw comment.
|
||||
*
|
||||
* Keep the list short and unambiguous — false positives are cheap (a soft
|
||||
* warn), false negatives just mean the reporter skips the structure block on
|
||||
* a non-visual bug, which is fine.
|
||||
*/
|
||||
export const VISUAL_DEFECT_KEYWORDS: readonly string[] = [
|
||||
"black",
|
||||
"flicker",
|
||||
"corrupt",
|
||||
"wrong frame",
|
||||
"blank",
|
||||
"visual",
|
||||
"render",
|
||||
] as const;
|
||||
|
||||
/**
|
||||
* Ratings that should mandate `COMPOSITION_STRUCTURE:` when the comment
|
||||
* contains a visual-defect keyword. 7 and below covers "clearly broken" —
|
||||
* 8-9 are usually "worked, but noticed a nit" which doesn't need the full
|
||||
* structural anatomy.
|
||||
*/
|
||||
export const COMPOSITION_STRUCTURE_RATING_CEILING = 7;
|
||||
|
||||
const REPRO_MARKER = "REPRO COMMAND:";
|
||||
const STRUCTURE_MARKER = "COMPOSITION_STRUCTURE:";
|
||||
|
||||
export interface FeedbackLintInput {
|
||||
rating: number;
|
||||
comment: string | undefined;
|
||||
}
|
||||
|
||||
export interface FeedbackLintWarning {
|
||||
code: "missing-repro-command" | "missing-composition-structure";
|
||||
message: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Soft-warn lint on the `hyperframes feedback` comment body. Never blocks
|
||||
* submission — some legitimate reports (a one-line "cloudrun quota bumped
|
||||
* yesterday, fine now") won't fit the mold. The warning is just a nudge and
|
||||
* a pointer to the auto-census helper.
|
||||
*
|
||||
* Rules:
|
||||
* 1. `rating === 10` — no check. A perfect run doesn't need a repro packet.
|
||||
* 2. Comment missing / empty — no check. `feedback --rating 6` with no
|
||||
* comment is a valid quick vote; the maintainer sees rating drift without
|
||||
* the reporter having to synthesize a fake repro.
|
||||
* 3. Comment present + rating < 10 + no `REPRO COMMAND:` — warn.
|
||||
* 4. Comment present + rating ≤ 7 + visual-defect keyword + no
|
||||
* `COMPOSITION_STRUCTURE:` — warn (in addition to any #3 warning).
|
||||
*/
|
||||
export function lintFeedbackComment(input: FeedbackLintInput): FeedbackLintWarning[] {
|
||||
const { rating, comment } = input;
|
||||
if (rating === FEEDBACK_RATING_SCALE) return [];
|
||||
const trimmed = comment?.trim();
|
||||
if (!trimmed) return [];
|
||||
|
||||
const warnings: FeedbackLintWarning[] = [];
|
||||
|
||||
if (!trimmed.includes(REPRO_MARKER)) {
|
||||
warnings.push({
|
||||
code: "missing-repro-command",
|
||||
message: [
|
||||
`Comment on a ${rating}/${FEEDBACK_RATING_SCALE} report is missing a "${REPRO_MARKER}" block —`,
|
||||
"maintainers can't rerun the failure from a symptom summary alone.",
|
||||
"See `references/preview-render.md` → feedback for the required packet shape.",
|
||||
].join(" "),
|
||||
});
|
||||
}
|
||||
|
||||
if (
|
||||
rating <= COMPOSITION_STRUCTURE_RATING_CEILING &&
|
||||
mentionsVisualDefect(trimmed) &&
|
||||
!trimmed.includes(STRUCTURE_MARKER)
|
||||
) {
|
||||
warnings.push({
|
||||
code: "missing-composition-structure",
|
||||
message: [
|
||||
`Comment describes a visual defect at ${rating}/${FEEDBACK_RATING_SCALE} but omits a`,
|
||||
`"${STRUCTURE_MARKER}" block. Agents can auto-fill this via the composition-census helper`,
|
||||
"(`buildCompositionCensus`/`renderCompositionCensusBlock` in `packages/cli/src/utils/compositionCensus.ts`)",
|
||||
"so maintainers can pattern-match against known bug families without the composition ZIP.",
|
||||
].join(" "),
|
||||
});
|
||||
}
|
||||
|
||||
return warnings;
|
||||
}
|
||||
|
||||
/**
|
||||
* Case-insensitive substring probe against `VISUAL_DEFECT_KEYWORDS`. Exposed
|
||||
* for tests and reuse; keywords are matched anywhere in the comment (no word
|
||||
* boundaries) since real reports mix them into free prose. False positives
|
||||
* cost one soft warn, which is acceptable.
|
||||
*/
|
||||
export function mentionsVisualDefect(comment: string): boolean {
|
||||
const lower = comment.toLowerCase();
|
||||
for (const kw of VISUAL_DEFECT_KEYWORDS) {
|
||||
if (lower.includes(kw)) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
@@ -26,7 +26,7 @@
|
||||
"files": 102
|
||||
},
|
||||
"hyperframes-cli": {
|
||||
"hash": "79ab5a7856a42d68",
|
||||
"hash": "8bee5964bf77cc24",
|
||||
"files": 11
|
||||
},
|
||||
"hyperframes-core": {
|
||||
|
||||
@@ -104,7 +104,7 @@ After verifying a successful render, send one feedback report unless telemetry i
|
||||
npx hyperframes feedback --rating <0-10> --comment "<specific result or friction>"
|
||||
```
|
||||
|
||||
Keep clean-run feedback concise. For any bug or friction, capture a **reproduction packet** before submitting; do not send only a symptom summary. Include the rerunnable command and working directory, expected versus actual behavior, exact error, whether output completed/fell back/failed, workaround, and repro-project status. If the issue did not reproduce again, say so and still include the last failing command and logs. Use `--file-issue` only with consent: it publishes a minimal reproduction to a public URL. The required packet format and privacy warning live in `references/preview-render.md`.
|
||||
Keep clean-run feedback concise. For any bug or friction, capture a **reproduction packet** before submitting; do not send only a symptom summary. Include the rerunnable command and working directory, expected versus actual behavior, exact error, whether output completed/fell back/failed, workaround, and repro-project status. For a rating ≤ 7 that describes a visual defect (black frame, flicker, corrupt output, wrong frame, blank output, other visual anomaly), also include a `COMPOSITION_STRUCTURE:` block — a privacy-preserving structural anatomy (element census + attribute presence + timeline shape) so maintainers can pattern-match against known bug families without the composition ZIP. Agents auto-fill this via the composition-census helper; the human user does not fill it by hand. If the issue did not reproduce again, say so and still include the last failing command and logs. Use `--file-issue` only with consent: it publishes a minimal reproduction to a public URL. The required packet format and privacy warning live in `references/preview-render.md`.
|
||||
|
||||
## Read the matching reference before running a command
|
||||
|
||||
|
||||
@@ -161,10 +161,20 @@ EXPECTED / ACTUAL: <expected behavior> / <observed behavior and isolated trigger
|
||||
EXACT ERROR: <verbatim error or warning; include frame/timestamp for visual defects>
|
||||
OUTCOME: <output correct | output corrupt | fallback succeeded | hard exit | command hung>
|
||||
WORKAROUND: <exact workaround, or none>
|
||||
COMPOSITION_STRUCTURE:
|
||||
elements: video=<n> audio=<n> img=<n> svg=<n> canvas=<n> subComps=<n>
|
||||
attributes: <comma-joined subset of clip-path, filter, mix-blend-mode, transform, mask, position:fixed, overflow:hidden, z-index, data-has-audio, data-duration, data-start, data-composition-src, background-image:url, mask-image:url — or "(none present)">
|
||||
timeline: <flat | nested (<n> sub-comps)>; driver=<gsap | data-timeline | gsap+data-timeline | none>
|
||||
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>
|
||||
```
|
||||
|
||||
`COMPOSITION_STRUCTURE:` is a privacy-preserving structural anatomy: counts + presence flags only, no file paths, no src URLs, no user text. It lets maintainers pattern-match the report against known bug families (e.g. "sub-comp mount + clip-path", "GSAP timeline + z-index") without receiving the composition ZIP. Required for any rating ≤ 7 that describes a visual defect (black frame, flicker, corrupt output, wrong frame, blank output, other visual anomaly); optional but appreciated on higher ratings. Agents on this skill can auto-fill the block by calling `buildCompositionCensus(html)` and `renderCompositionCensusBlock(census)` from `packages/cli/src/utils/compositionCensus.ts` against the composition HTML they already have access to — the human user does not fill this out by hand.
|
||||
|
||||
Preserve paths containing spaces, flags, and relevant `HF_*` / `PRODUCER_*` variables; redact secrets and credentials. If the failure no longer reproduces, include the last failing command and log excerpt. Share a project link only when one is already available and safe to share.
|
||||
|
||||
The `hyperframes feedback` command soft-warns when a non-10 `--comment` is missing `REPRO COMMAND:`, and when a rating-≤-7 visual-defect comment is missing `COMPOSITION_STRUCTURE:`. The warnings print above the submission ack and do not block — some legitimate reports (a one-line "cloudrun quota bumped yesterday, fine now") won't fit the mold. Fix the packet and rerun to silence them.
|
||||
|
||||
Hit a reproducible bug? Add `--file-issue` (optionally `--dir <project>` and `--yes` for non-interactive shells) to also publish a minimal repro to a public URL and open a pre-filled GitHub `bug` issue draft for a maintainer to file. This publishes the project publicly, so it is opt-in and consent-gated; the issue is never auto-submitted.
|
||||
|
||||
## publish
|
||||
|
||||
Reference in New Issue
Block a user