mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-17 15:24:19 +00:00
feat(lint): warn when a script builds an element's text with no static fallback
Studio's manual-edit save patches text fields back into the static HTML source by locating existing content. When an element's visible text is built entirely at runtime (getElementById/querySelector + appendChild/ innerHTML/textContent), there's nothing in the source to patch, and a manual edit in Studio silently fails with "Couldn't find this element in the source file." Hit this exact failure authoring a Studio QA fixture whose caption-word spans were only ever created by a load-time script. Adds manual_edit_unsupported_runtime_text (warning) to catch it, exempting caption-cue elements since transcript-driven word spans are an intentional instance of the same shape.
This commit is contained in:
@@ -1688,4 +1688,111 @@ describe("composition rules", () => {
|
||||
expect(find(result.findings)).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe("manual_edit_unsupported_runtime_text", () => {
|
||||
const CODE = "manual_edit_unsupported_runtime_text";
|
||||
const find = (findings: { code: string }[]) => findings.find((f) => f.code === CODE);
|
||||
|
||||
it("warns when a script builds an empty element's content via getElementById + appendChild", async () => {
|
||||
const html = `<html><body>
|
||||
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
|
||||
<div id="qa-caption-host"></div>
|
||||
</div>
|
||||
<script>
|
||||
const host = document.getElementById("qa-caption-host");
|
||||
for (const word of ["Generated", "caption", "words", "here"]) {
|
||||
const span = document.createElement("span");
|
||||
span.textContent = word;
|
||||
host.appendChild(span);
|
||||
}
|
||||
</script>
|
||||
</body></html>`;
|
||||
const result = await lintHyperframeHtml(html);
|
||||
const finding = find(result.findings);
|
||||
expect(finding).toBeDefined();
|
||||
expect(finding?.severity).toBe("warning");
|
||||
expect(finding?.elementId).toBe("qa-caption-host");
|
||||
});
|
||||
|
||||
it("warns for a direct getElementById(...).innerHTML assignment with no static content", async () => {
|
||||
const html = `<html><body>
|
||||
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
|
||||
<div id="stat-value"></div>
|
||||
</div>
|
||||
<script>
|
||||
document.getElementById("stat-value").innerHTML = "<b>42</b>";
|
||||
</script>
|
||||
</body></html>`;
|
||||
const result = await lintHyperframeHtml(html);
|
||||
const finding = find(result.findings);
|
||||
expect(finding).toBeDefined();
|
||||
expect(finding?.elementId).toBe("stat-value");
|
||||
});
|
||||
|
||||
it("warns when the element is targeted via a bare #id querySelector", async () => {
|
||||
const html = `<html><body>
|
||||
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
|
||||
<div id="qa-list"></div>
|
||||
</div>
|
||||
<script>
|
||||
const host = document.querySelector("#qa-list");
|
||||
host.textContent = "built at runtime";
|
||||
</script>
|
||||
</body></html>`;
|
||||
const result = await lintHyperframeHtml(html);
|
||||
expect(find(result.findings)).toBeDefined();
|
||||
});
|
||||
|
||||
it("does not warn when the element already has static fallback content", async () => {
|
||||
const html = `<html><body>
|
||||
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
|
||||
<div id="qa-caption-host"><span>Generated</span></div>
|
||||
</div>
|
||||
<script>
|
||||
const host = document.getElementById("qa-caption-host");
|
||||
host.appendChild(document.createElement("span"));
|
||||
</script>
|
||||
</body></html>`;
|
||||
const result = await lintHyperframeHtml(html);
|
||||
expect(find(result.findings)).toBeUndefined();
|
||||
});
|
||||
|
||||
it("does not warn for a caption-cue id even with no static content", async () => {
|
||||
const html = `<html><body>
|
||||
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
|
||||
<div id="caption-word"></div>
|
||||
</div>
|
||||
<script>
|
||||
const host = document.getElementById("caption-word");
|
||||
host.appendChild(document.createElement("span"));
|
||||
</script>
|
||||
</body></html>`;
|
||||
const result = await lintHyperframeHtml(html);
|
||||
expect(find(result.findings)).toBeUndefined();
|
||||
});
|
||||
|
||||
it("does not warn when the script only reads the element, never injects content", async () => {
|
||||
const html = `<html><body>
|
||||
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
|
||||
<div id="qa-readonly"></div>
|
||||
</div>
|
||||
<script>
|
||||
const el = document.getElementById("qa-readonly");
|
||||
console.log(el.getBoundingClientRect());
|
||||
</script>
|
||||
</body></html>`;
|
||||
const result = await lintHyperframeHtml(html);
|
||||
expect(find(result.findings)).toBeUndefined();
|
||||
});
|
||||
|
||||
it("does not warn when there are no scripts at all", async () => {
|
||||
const html = `<html><body>
|
||||
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
|
||||
<div id="qa-empty"></div>
|
||||
</div>
|
||||
</body></html>`;
|
||||
const result = await lintHyperframeHtml(html);
|
||||
expect(find(result.findings)).toBeUndefined();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -10,6 +10,10 @@ import {
|
||||
} from "../utils";
|
||||
import { COMPOSITION_VARIABLE_TYPES } from "@hyperframes/parsers/composition";
|
||||
|
||||
function escapeRegExp(value: string): string {
|
||||
return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
||||
}
|
||||
|
||||
// Agent guidance thresholds: warning-only nudges for files/tracks that become hard
|
||||
// to inspect and revise reliably in a single composition.
|
||||
const MAX_COMPOSITION_LINES = 300;
|
||||
@@ -178,6 +182,98 @@ function isInsideInertTemplate(tag: OpenTag, tags: readonly OpenTag[]): boolean
|
||||
);
|
||||
}
|
||||
|
||||
// A DOM call that injects content into an element: appendChild/append/
|
||||
// insertAdjacentHTML/insertAdjacentElement, or an innerHTML/textContent/
|
||||
// innerText assignment (the negative lookahead keeps `===` from matching).
|
||||
const RUNTIME_INJECTION_CALL_PATTERN =
|
||||
"(?:\\.(?:appendChild|append|insertAdjacentHTML|insertAdjacentElement)\\s*\\(|\\.(?:innerHTML|textContent|innerText)\\s*=(?!=))";
|
||||
|
||||
// Element ids referenced via `document.getElementById("x")` or a bare `#x`
|
||||
// querySelector, immediately chained into an injection call — e.g.
|
||||
// `document.getElementById("x").appendChild(...)`. A multi-part selector
|
||||
// isn't resolved to a single id, so it's left alone rather than guessed at.
|
||||
function findDirectlyInjectedIds(scriptContent: string): Set<string> {
|
||||
const ids = new Set<string>();
|
||||
const patterns = [
|
||||
new RegExp(
|
||||
`(?:document|window\\.document)\\.getElementById\\(\\s*["']([^"']+)["']\\s*\\)\\s*${RUNTIME_INJECTION_CALL_PATTERN}`,
|
||||
"g",
|
||||
),
|
||||
new RegExp(
|
||||
`(?:document|window\\.document)\\.querySelector\\(\\s*["']#([\\w-]+)["']\\s*\\)\\s*${RUNTIME_INJECTION_CALL_PATTERN}`,
|
||||
"g",
|
||||
),
|
||||
];
|
||||
for (const pattern of patterns) {
|
||||
let match: RegExpExecArray | null;
|
||||
while ((match = pattern.exec(scriptContent)) !== null) {
|
||||
if (match[1]) ids.add(match[1]);
|
||||
}
|
||||
}
|
||||
return ids;
|
||||
}
|
||||
|
||||
// Element ids captured into a variable (`const host = document.getElementById(...)`
|
||||
// or the `#x` querySelector form) that the variable is later used to inject
|
||||
// content into, anywhere else in the same script.
|
||||
function findIndirectlyInjectedIds(scriptContent: string): Set<string> {
|
||||
const idsByVariable = new Map<string, string>();
|
||||
const assignmentPatterns = [
|
||||
/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)/g,
|
||||
/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:document|window\.document)\.querySelector\(\s*["']#([\w-]+)["']\s*\)/g,
|
||||
];
|
||||
for (const pattern of assignmentPatterns) {
|
||||
let match: RegExpExecArray | null;
|
||||
while ((match = pattern.exec(scriptContent)) !== null) {
|
||||
const [, variableName, targetId] = match;
|
||||
if (variableName && targetId) idsByVariable.set(variableName, targetId);
|
||||
}
|
||||
}
|
||||
|
||||
const ids = new Set<string>();
|
||||
for (const [variableName, targetId] of idsByVariable) {
|
||||
const usagePattern = new RegExp(
|
||||
`\\b${escapeRegExp(variableName)}\\s*${RUNTIME_INJECTION_CALL_PATTERN}`,
|
||||
);
|
||||
if (usagePattern.test(scriptContent)) ids.add(targetId);
|
||||
}
|
||||
return ids;
|
||||
}
|
||||
|
||||
// Whether `targetId` is a legitimate finding: it resolves to a real element
|
||||
// with no static text/markup already in source, and isn't a caption-cue
|
||||
// element (transcript-driven word spans are an intentional instance of this
|
||||
// same shape, not a bug — see isCaptionCue).
|
||||
function buildRuntimeTextFinding(
|
||||
targetId: string,
|
||||
tags: readonly OpenTag[],
|
||||
source: string,
|
||||
): HyperframeLintFinding | null {
|
||||
const targetTag = tags.find((tag) => readAttr(tag.raw, "id") === targetId);
|
||||
if (!targetTag || targetTag.closeIndex == null) return null;
|
||||
if (isCaptionCue(targetTag)) return null;
|
||||
|
||||
const innerContent = source.slice(targetTag.index + targetTag.raw.length, targetTag.closeIndex);
|
||||
if (innerContent.trim().length > 0) return null; // already has static fallback content
|
||||
|
||||
return {
|
||||
code: "manual_edit_unsupported_runtime_text",
|
||||
severity: "warning",
|
||||
elementId: targetId,
|
||||
message:
|
||||
`#${targetId} has no static text/markup in source — its visible content is built entirely ` +
|
||||
"at runtime by a script. HyperFrames Studio's manual-edit save locates text fields by " +
|
||||
"matching existing source content, so a manual edit to this element in Studio will fail to " +
|
||||
'save with "Couldn\'t find this element in the source file".',
|
||||
fixHint:
|
||||
"Author the element's expected content as static markup (even placeholder text) so Studio's " +
|
||||
"manual-edit save has something to patch, and have the script update/replace it rather than " +
|
||||
"build it from nothing. If this element is intentionally not meant to be manually edited " +
|
||||
"(e.g. transcript-driven captions), this warning can be ignored.",
|
||||
snippet: truncateSnippet(targetTag.raw),
|
||||
};
|
||||
}
|
||||
|
||||
export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
|
||||
// duplicate_composition_id catches meta-tag/root collisions that create duplicate composition entries.
|
||||
({ tags }) => {
|
||||
@@ -1079,4 +1175,46 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
|
||||
// in runtime/init.ts). Not an error; data-duration is optional here.
|
||||
return [];
|
||||
},
|
||||
|
||||
// manual_edit_unsupported_runtime_text
|
||||
//
|
||||
// Studio's manual-edit save path patches text fields back into the static
|
||||
// HTML source by locating the element's existing text content. When an
|
||||
// element's visible text is built entirely at runtime — a script grabbing
|
||||
// it via getElementById/querySelector and then appendChild/innerHTML/
|
||||
// textContent — there is no static counterpart in the source for the save
|
||||
// path to locate, and a manual text edit made to that element in Studio
|
||||
// silently fails to save ("Couldn't find this element in the source
|
||||
// file"). This is a real failure mode hit while authoring a Studio QA
|
||||
// fixture: a <div> whose word-spans were only ever created by a load-time
|
||||
// script had nothing for the save path to patch.
|
||||
//
|
||||
// Caption/subtitle word-by-word spans generated from a transcript are a
|
||||
// deliberate, expected instance of this same shape — per-word manual
|
||||
// editing isn't the intended workflow there — so elements matching the
|
||||
// existing caption-cue id/class convention (see isCaptionCue above) are
|
||||
// exempted. This is advisory (warning): the pattern is often intentional;
|
||||
// the point is to surface the save-time limitation, not to forbid it.
|
||||
({ tags, scripts, source }) => {
|
||||
const findings: HyperframeLintFinding[] = [];
|
||||
const flaggedIds = new Set<string>();
|
||||
|
||||
for (const script of scripts) {
|
||||
const content = stripJsComments(script.content);
|
||||
const candidateIds = new Set([
|
||||
...findDirectlyInjectedIds(content),
|
||||
...findIndirectlyInjectedIds(content),
|
||||
]);
|
||||
|
||||
for (const targetId of candidateIds) {
|
||||
if (flaggedIds.has(targetId)) continue;
|
||||
const finding = buildRuntimeTextFinding(targetId, tags, source);
|
||||
if (!finding) continue;
|
||||
flaggedIds.add(targetId);
|
||||
findings.push(finding);
|
||||
}
|
||||
}
|
||||
|
||||
return findings;
|
||||
},
|
||||
];
|
||||
|
||||
Reference in New Issue
Block a user