mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-17 07:05:28 +00:00
## Summary
- Breaks `hyperframeLinter.ts` from 1,314 lines (one massive function) into a plugin system of focused rule modules
- Introduces `LintContext` — HTML is parsed once and shared across all rules
- Adds `LintRule<TContext>` type as the formal contract for rules
- Public API unchanged: `lintHyperframeHtml`, `lintMediaUrls`, `lintScriptUrls` signatures identical
## New file structure
```
src/lint/
utils.ts — shared types (OpenTag, ExtractedBlock), regex constants, helpers
context.ts — LintContext type + buildLintContext() factory
rules/
core.ts — structural rules (root attrs, timeline registry, script syntax)
media.ts — media element rules (duplicate ids, video pitfalls, placeholder URLs, etc.)
gsap.ts — GSAP rules + GSAP-specific parsing utils
captions.ts — caption rules
composition.ts — timed element, deprecated attrs, template literal selector, external scripts
adapters.ts — Lottie + Three.js missing-script rules (from PR #149)
hyperframeLinter.ts — orchestrator only (~200 lines, down from 1,314)
```
## Adding a new adapter rule going forward
1. Create `src/lint/rules/my-adapter.ts` exporting `myAdapterRules: LintRule[]`
2. Import and spread into `ALL_RULES` in `hyperframeLinter.ts`
## Test plan
- [x] All 402 core tests pass unchanged
- [x] Full workspace build clean (`pnpm build`)
- [x] TypeScript strict mode clean (`pnpm tsc --noEmit`)
229 lines
6.9 KiB
TypeScript
229 lines
6.9 KiB
TypeScript
import type { HyperframeLintFinding, HyperframeLintResult, HyperframeLinterOptions } from "./types";
|
|
import { buildLintContext } from "./context";
|
|
import { readAttr, truncateSnippet } from "./utils";
|
|
import { coreRules } from "./rules/core";
|
|
import { mediaRules } from "./rules/media";
|
|
import { gsapRules } from "./rules/gsap";
|
|
import { captionRules } from "./rules/captions";
|
|
import { compositionRules } from "./rules/composition";
|
|
import { adapterRules } from "./rules/adapters";
|
|
|
|
const ALL_RULES = [
|
|
...coreRules,
|
|
...mediaRules,
|
|
...gsapRules,
|
|
...captionRules,
|
|
...compositionRules,
|
|
...adapterRules,
|
|
];
|
|
|
|
export function lintHyperframeHtml(
|
|
html: string,
|
|
options: HyperframeLinterOptions = {},
|
|
): HyperframeLintResult {
|
|
const ctx = buildLintContext(html, options);
|
|
const findings: HyperframeLintFinding[] = [];
|
|
const seen = new Set<string>();
|
|
|
|
for (const rule of ALL_RULES) {
|
|
for (const finding of rule(ctx)) {
|
|
const dedupeKey = [
|
|
finding.code,
|
|
finding.severity,
|
|
finding.selector || "",
|
|
finding.elementId || "",
|
|
finding.message,
|
|
].join("|");
|
|
if (seen.has(dedupeKey)) continue;
|
|
seen.add(dedupeKey);
|
|
findings.push(options.filePath ? { ...finding, file: options.filePath } : finding);
|
|
}
|
|
}
|
|
|
|
const errorCount = findings.filter((f) => f.severity === "error").length;
|
|
const warningCount = findings.filter((f) => f.severity === "warning").length;
|
|
const infoCount = findings.filter((f) => f.severity === "info").length;
|
|
|
|
return {
|
|
ok: errorCount === 0,
|
|
errorCount,
|
|
warningCount,
|
|
infoCount,
|
|
findings,
|
|
};
|
|
}
|
|
|
|
// ── Async media URL accessibility checker ─────────────────────────────────
|
|
|
|
function extractMediaUrls(html: string): Array<{
|
|
url: string;
|
|
tagName: string;
|
|
elementId?: string;
|
|
snippet: string;
|
|
}> {
|
|
const results: Array<{
|
|
url: string;
|
|
tagName: string;
|
|
elementId?: string;
|
|
snippet: string;
|
|
}> = [];
|
|
const tagRe = /<(video|audio|img|source)\b[^>]*>/gi;
|
|
let match: RegExpExecArray | null;
|
|
while ((match = tagRe.exec(html)) !== null) {
|
|
const tagName = (match[1] ?? "").toLowerCase();
|
|
const raw = match[0];
|
|
const src = readAttr(raw, "src");
|
|
if (!src) continue;
|
|
if (/^https?:\/\//i.test(src)) {
|
|
results.push({
|
|
url: src,
|
|
tagName,
|
|
elementId: readAttr(raw, "id") || undefined,
|
|
snippet: truncateSnippet(raw) ?? "",
|
|
});
|
|
}
|
|
}
|
|
return results;
|
|
}
|
|
|
|
/**
|
|
* Async lint pass: HEAD-checks every remote media URL in the HTML.
|
|
* Returns findings for URLs that are unreachable (non-2xx status or network error).
|
|
*
|
|
* Call this after `lintHyperframeHtml()` and merge the findings.
|
|
*
|
|
* @param timeoutMs - per-request timeout (default 8000ms)
|
|
*/
|
|
export async function lintMediaUrls(
|
|
html: string,
|
|
options: { timeoutMs?: number } = {},
|
|
): Promise<HyperframeLintFinding[]> {
|
|
const urls = extractMediaUrls(html);
|
|
if (urls.length === 0) return [];
|
|
|
|
const timeout = options.timeoutMs ?? 8000;
|
|
const findings: HyperframeLintFinding[] = [];
|
|
|
|
const seen = new Set<string>();
|
|
const unique = urls.filter((u) => {
|
|
if (seen.has(u.url)) return false;
|
|
seen.add(u.url);
|
|
return true;
|
|
});
|
|
|
|
const checks = unique.map(async ({ url, tagName, elementId, snippet }) => {
|
|
try {
|
|
const controller = new AbortController();
|
|
const timer = setTimeout(() => controller.abort(), timeout);
|
|
const resp = await fetch(url, {
|
|
method: "HEAD",
|
|
signal: controller.signal,
|
|
redirect: "follow",
|
|
});
|
|
clearTimeout(timer);
|
|
if (!resp.ok) {
|
|
findings.push({
|
|
code: "inaccessible_media_url",
|
|
severity: "error",
|
|
message: `<${tagName}${elementId ? ` id="${elementId}"` : ""}> references a URL that returned HTTP ${resp.status}: ${url.slice(0, 100)}`,
|
|
elementId,
|
|
fixHint: "This URL is not accessible. Replace with a valid, reachable media URL.",
|
|
snippet,
|
|
});
|
|
}
|
|
} catch (err) {
|
|
const reason = err instanceof Error ? err.name : "unknown";
|
|
findings.push({
|
|
code: "inaccessible_media_url",
|
|
severity: "error",
|
|
message: `<${tagName}${elementId ? ` id="${elementId}"` : ""}> references an unreachable URL (${reason}): ${url.slice(0, 100)}`,
|
|
elementId,
|
|
fixHint: "This URL is not accessible. Replace with a valid, reachable media URL.",
|
|
snippet,
|
|
});
|
|
}
|
|
});
|
|
|
|
await Promise.all(checks);
|
|
return findings;
|
|
}
|
|
|
|
function extractScriptUrls(html: string): Array<{ url: string; snippet: string }> {
|
|
const results: Array<{ url: string; snippet: string }> = [];
|
|
const scriptRe = /<script\b[^>]*>/gi;
|
|
let match: RegExpExecArray | null;
|
|
while ((match = scriptRe.exec(html)) !== null) {
|
|
const raw = match[0];
|
|
const src = readAttr(raw, "src");
|
|
if (!src) continue;
|
|
if (/^https?:\/\//i.test(src)) {
|
|
results.push({
|
|
url: src,
|
|
snippet: truncateSnippet(raw) ?? "",
|
|
});
|
|
}
|
|
}
|
|
return results;
|
|
}
|
|
|
|
/**
|
|
* Async lint pass: HEAD-checks every external script URL in the HTML.
|
|
* Returns findings for URLs that are unreachable (non-2xx status or network error).
|
|
*
|
|
* Call this after `lintHyperframeHtml()` and merge the findings.
|
|
*
|
|
* @param timeoutMs - per-request timeout (default 8000ms)
|
|
*/
|
|
export async function lintScriptUrls(
|
|
html: string,
|
|
options: { timeoutMs?: number } = {},
|
|
): Promise<HyperframeLintFinding[]> {
|
|
const urls = extractScriptUrls(html);
|
|
if (urls.length === 0) return [];
|
|
|
|
const timeout = options.timeoutMs ?? 8000;
|
|
const findings: HyperframeLintFinding[] = [];
|
|
|
|
const seen = new Set<string>();
|
|
const unique = urls.filter((u) => {
|
|
if (seen.has(u.url)) return false;
|
|
seen.add(u.url);
|
|
return true;
|
|
});
|
|
|
|
const checks = unique.map(async ({ url, snippet }) => {
|
|
try {
|
|
const controller = new AbortController();
|
|
const timer = setTimeout(() => controller.abort(), timeout);
|
|
const resp = await fetch(url, {
|
|
method: "HEAD",
|
|
signal: controller.signal,
|
|
redirect: "follow",
|
|
});
|
|
clearTimeout(timer);
|
|
if (!resp.ok) {
|
|
findings.push({
|
|
code: "inaccessible_script_url",
|
|
severity: "error",
|
|
message: `<script> references a URL that returned HTTP ${resp.status}: ${url.slice(0, 120)}`,
|
|
fixHint:
|
|
"This script URL is not accessible. Remove it or replace with a valid URL. The HyperFrames runtime is injected automatically — do not load it manually.",
|
|
snippet,
|
|
});
|
|
}
|
|
} catch (err) {
|
|
const reason = err instanceof Error ? err.name : "unknown";
|
|
findings.push({
|
|
code: "inaccessible_script_url",
|
|
severity: "error",
|
|
message: `<script> references an unreachable URL (${reason}): ${url.slice(0, 120)}`,
|
|
fixHint: "This script URL is not accessible. Remove it or replace with a valid URL.",
|
|
snippet,
|
|
});
|
|
}
|
|
});
|
|
|
|
await Promise.all(checks);
|
|
return findings;
|
|
}
|