Files
hyperframes/packages/lint/src/utils.ts
T
Miguel Ángel 50e7e8df69 fix(lint): check no longer fails projects that inline the GSAP library (#6018)
* fix(lint): check no longer fails projects that inline the GSAP library

non_deterministic_code skips a script that is GSAP itself (producer inlining comment
or GSAP banner), using the detector missing_gsap_script already had, now one shared
helper. The author's own Math.random/Date.now calls are still flagged.

* fix(lint): only GSAP's own code is exempt from the determinism check

Exempt the parsed GSAP UMD statement that carries its banner, not every script that
mentions GreenSock. Strings, comments, spoofed banners and author code before or after
the library in the same script are checked again.

* refactor(lint): name the GSAP blanking step instead of commenting it

* fix(lint): exempt only GSAP's verified wrapper call from the determinism check

Recognise GSAP's UMD wrapper by structure (factory IIFE called with this and a function,
with a real define.amd member) anywhere in the tree, and blank only that call. Author code
joined by a comma or wrapped in an outer IIFE is checked; define.amd text is not enough.

* fix(lint): a bundle wrapping GSAP no longer inherits its determinism exemption

The define.amd check reads only the wrapper's own body, and each GSAP banner belongs to the
wrapper right after it, else the innermost one containing it. An outer wrapper or UMD bundle
around pasted GSAP keeps its author code checked.

* fix(lint): a banner inside a bundle no longer exempts the bundle around GSAP

A banner introduces the wrapper after it across whitespace, ! ; ( and comments, so producer
comments and statement separators bind to GSAP itself. The fallback owner for a banner
inside a wrapper must wrap no other wrapper, so a bundle around GSAP never inherits it.

* fix(lint): author code bundled with GSAP keeps its randomness checked

A GSAP banner now exempts only the UMD wrapper call that starts right after
it (skipping whitespace, comments, `!`, `;` and `(`). The fallback that gave
a banner to the innermost enclosing wrapper is gone: Rollup's UMD output for
an ESM import of GSAP keeps the banner inside the one factory it shares with
author code, so that fallback exempted the whole bundle, author
Math.random() and Date.now() included.

Tradeoff: unminified dist/gsap.js pasted inline has its banner inside its
own factory, so it is flagged again, as on main. The minified gsap.min.js
and producer-inlined copies stay exempt.

* test(lint): the Rollup bundle case reuses the GSAP banner constant

* fix(lint): a script name that mentions gsap no longer exempts the bundle it heads

The producer's inlined-source comment now marks library code only when its
URL path is an npm gsap dist file (gsap or gsap@<version>, then /dist/<file>.js,
query and hash ignored). A Rollup/Terser bundle of GSAP plus author code
inlined from gsap-composition.js, scene.js?vendor=gsap or another domain's
gsap-demo/scene.js keeps its own Math.random() and Date.now() checked.
2026-10-21 17:21:44 +00:00

973 lines
32 KiB
TypeScript

// Shared types, regex constants, and utility functions used across lint rule modules.
// Nothing in this file should emit findings — it only parses and extracts.
import { Parser } from "htmlparser2";
import { parse, type CallExpression, type Comment, type Program } from "acorn";
import { base, recursive, simple } from "acorn-walk";
export type OpenTag = {
raw: string;
name: string;
attrs: string;
index: number;
closeIndex?: number;
endIndex?: number;
};
export type ExtractedBlock = {
contentStart?: number;
file?: string;
rootRelativePath?: string;
attrs: string;
content: string;
raw: string;
index: number;
};
const COMPOSITION_ID_IN_CSS_PATTERN = /\[data-composition-id=["']([^"']+)["']\]/g;
export const TIMELINE_REGISTRY_INIT_PATTERN =
/window\.__timelines\s*=\s*window\.__timelines\s*\|\|\s*\{\}|window\.__timelines\s*=\s*\{\}|window\.__timelines\s*\?\?=\s*\{\}/i;
// Object-literal registration that assigns at least one `key: value` entry inline,
// e.g. `window.__timelines = { main: tl }` or `window.__timelines = { "comp-1": tl }`.
// Distinct from the empty-init form (`= {}`) — requires a key followed by `:`.
export const TIMELINE_REGISTRY_OBJECT_LITERAL_PATTERN =
/window\.__timelines\s*=\s*\{\s*(?:["'][^"']+["']|[A-Za-z_$][\w$]*)\s*:/i;
export const TIMELINE_REGISTRY_ASSIGN_PATTERN =
/window\.__timelines(?:\[[^\]]+\]|\.[A-Za-z_$][\w$]*)\s*=/i;
// The bracket branch accepts either a quoted string key (`["root"]`) or a
// computed key (`[spec.id]`, `[id]`) — a bare-identifier-only bracket branch
// missed `window.__timelines[spec.id] = tl`, a pattern the shipped
// code-particle-assemble/code-3d-extrude registry blocks actually use,
// making gsap_timeline_not_registered false-fire on correctly registered
// timelines. The computed-key alternative is non-capturing; remaining
// callers only `.test()` this pattern.
export const WINDOW_TIMELINE_ASSIGN_PATTERN =
/window\.__timelines(?:\[\s*(?:["']([^"']+)["']|[A-Za-z_$][\w$.]*)\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*=\s*([A-Za-z_$][\w$]*)/i;
export const INVALID_SCRIPT_CLOSE_PATTERN = /<script[^>]*>[\s\S]*?<\s*\/\s*script(?!>)/i;
const TIMELINE_REGISTRY_KEY_PATTERN =
/window\.__timelines(?:\[\s*["']([^"']+)["']\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*(?:\?\?|\|\||&&)?=/g;
// The `window.__timelines = { ... }` object-literal body (group 1), captured so its
// `key: value` entries can be scanned for registered keys.
// Locates the START of a `window.__timelines = { ... }` literal. Deliberately does
// not try to match the closing brace: see readTimelineRegistryObjectBody, which walks
// braces instead. A regex cannot tell the registry's own `}` from the `}` of an
// inlined options object.
const TIMELINE_REGISTRY_OBJECT_OPEN_PATTERN = /window\.__timelines\s*=\s*\{/i;
// A single object-literal entry whose value is an identifier (real timeline registration),
// e.g. `main: tl` or `"comp-1": tl`. Captures the key in group 1 (quoted) or 2 (bare).
const TIMELINE_REGISTRY_OBJECT_ENTRY_PATTERN =
/(?:["']([^"']+)["']|([A-Za-z_$][\w$]*))\s*:\s*[A-Za-z_$][\w$]*/g;
export function parseHtmlStructure(source: string): {
tags: OpenTag[];
scripts: ExtractedBlock[];
styles: ExtractedBlock[];
} {
const tags: OpenTag[] = [];
const blocks = { script: [] as ExtractedBlock[], style: [] as ExtractedBlock[] };
const openTagsByName = new Map<string, OpenTag[]>();
const openBlocks: Array<{
name: "script" | "style";
attrs: string;
contentStart: number;
index: number;
}> = [];
let explicitOpenTag: { index: number; nameEnd: number } | null = null;
const parser: Parser = new Parser(
{
onopentagname(name) {
// startIndex can still point into the preceding close. Bound this scan by
// HTML name delimiters, not '<' (which can occur in a malformed name).
// Keep the raw name end too: Unicode lowercasing can change UTF-16 length.
let tokenStart = parser.endIndex - 1;
while (
tokenStart >= parser.startIndex &&
!/[\t\n\f\r />]/.test(source.charAt(tokenStart))
) {
tokenStart -= 1;
}
const index = source.indexOf("<", tokenStart + 1);
explicitOpenTag =
index >= 0 &&
index < parser.endIndex &&
source.slice(index + 1, parser.endIndex).toLowerCase() === name
? { index, nameEnd: parser.endIndex }
: null;
},
onopentag(name, _attrs, isImplied) {
const origin = !isImplied ? explicitOpenTag : null;
const index = origin?.index ?? parser.startIndex;
explicitOpenTag = null;
const raw = source.slice(index, parser.endIndex + 1);
const rawAttrs = origin
? source.slice(origin.nameEnd, parser.endIndex)
: raw.slice(name.length + 1, -1);
const attrs = rawAttrs.replace(/\s*\/$/, "");
const tag = { raw, name, attrs, index };
tags.push(tag);
const sameNameStack = openTagsByName.get(name) ?? [];
sameNameStack.push(tag);
openTagsByName.set(name, sameNameStack);
if (name === "script" || name === "style") {
openBlocks.push({ name, attrs, contentStart: parser.endIndex + 1, index });
}
},
onclosetag(name) {
const tag = openTagsByName.get(name)?.pop();
if (tag) {
tag.closeIndex = parser.startIndex;
tag.endIndex = parser.endIndex + 1;
}
if (name !== "script" && name !== "style") return;
const block = openBlocks.pop();
if (!block || block.name !== name) return;
blocks[name].push({
attrs: block.attrs,
content: source.slice(block.contentStart, parser.startIndex),
contentStart: block.contentStart,
raw: source.slice(block.index, parser.endIndex + 1),
index: block.index,
});
},
},
{ decodeEntities: false, lowerCaseAttributeNames: false, lowerCaseTags: true },
);
parser.end(source);
return { tags, scripts: blocks.script, styles: blocks.style };
}
/**
* Find the `<html>` open tag in the source. Distinct from `findRootTag`,
* which returns the first element inside `<body>` — the latter is "the
* composition's visible root", whereas `<html>` is where document-level
* metadata like `data-composition-variables` lives.
*/
export function findHtmlTag(tags: readonly OpenTag[]): OpenTag | null {
return tags.find((tag) => tag.name === "html") ?? null;
}
const hasCompositionMarker = (tag: OpenTag): boolean =>
Boolean(
readDecodedAttr(tag.raw, "data-composition-id") ||
readAttr(tag.raw, "data-width") ||
readAttr(tag.raw, "data-height"),
);
// fallow-ignore-next-line complexity
export function findRootTag(source: string, parsedTags?: readonly OpenTag[]): OpenTag | null {
const tags = parsedTags ?? parseHtmlStructure(source).tags;
const bodyTag = tags.find((tag) => tag.name === "body");
if (bodyTag && hasCompositionMarker(bodyTag)) return bodyTag;
const bodyStart = bodyTag ? bodyTag.index + bodyTag.raw.length : 0;
const bodyEnd = bodyTag?.closeIndex ?? source.length;
const bodyTags = tags.filter((tag) => tag.index >= bodyStart && tag.index < bodyEnd);
// Set when a leading <svg> defs block is skipped (see below) — extractOpenTags
// is a flat, nesting-unaware scan, so without this the very next tag it
// returns is the svg's own nested child (<defs>, <filter>, ...), not the
// sibling that follows the closed </svg>.
let skipBefore = -1;
for (const tag of bodyTags) {
if (tag.index < skipBefore) continue;
if (["script", "style", "meta", "link", "title"].includes(tag.name)) continue;
if ((tag.name === "html" || tag.name === "head") && !hasCompositionMarker(tag)) continue;
// A leading <svg> block (icon/gradient/filter <defs>, referenced by url(#id)
// from elsewhere in the document) is shared visual plumbing, not the
// composition root — two independent reports of this being mistaken for
// the root, manufacturing root_missing_composition_id/root_missing_dimensions
// on an otherwise-correct composition. Only skip it when it carries none of
// the composition markers itself, so an intentionally SVG-rooted composition
// (data-composition-id/data-width/data-height directly on the <svg>) is
// still eligible as the root.
if (tag.name === "svg" && !hasCompositionMarker(tag)) {
// No closing tag found (malformed HTML) — skip everything rather than
// risk returning one of the svg's own children as the root.
skipBefore = tag.endIndex ?? Infinity;
continue;
}
return tag;
}
return null;
}
/**
* Whether a tag's attribute text contains a `<` outside any quoted value.
*
* A legitimate attribute value may itself contain a raw `<` (e.g.
* `data-expr="x < y"`) — that's fine, htmlparser2 (and browsers) parse it as
* ordinary attribute text. But a `<` OUTSIDE any quotes means a following
* start tag never got its own `<`: the HTML tokenizer swallowed it as bogus
* attribute-name text on the tag currently open, and the intended element
* never becomes a real node. `<img src="a.png" <div class="hl">` is exactly
* this: `attrs` comes back as ` src="a.png" <div class="hl"` and the `.hl`
* div silently never renders.
*/
export function hasUnquotedLessThan(attrs: string): boolean {
let quote: '"' | "'" | null = null;
for (const ch of attrs) {
if (quote) {
if (ch === quote) quote = null;
continue;
}
if (ch === '"' || ch === "'") {
quote = ch;
} else if (ch === "<") {
return true;
}
}
return false;
}
export function readAttr(tagSource: string, attr: string): string | null {
return readAttributeValue(tagSource, attr, false) || null;
}
export function hasAttrName(tagSource: string, attr: string): boolean {
return readDecodedAttr(tagSource, attr) !== null;
}
// An explicit data-has-audio is authoritative for the compiler; only the exact value "true" means audible.
export function isAudibleVideo(attr: (name: string) => string | null): boolean {
if (attr("muted") !== null) return false;
const declared = attr("data-has-audio");
return declared === null || declared === "true";
}
export function isAudibleVideoTag(tagSource: string): boolean {
return isAudibleVideo((name) => readDecodedAttr(tagSource, name));
}
export function mediaTimeWindow(tagSource: string): { start: number; end: number } | null {
const start = Number(readAttr(tagSource, "data-start"));
const duration = Number(readAttr(tagSource, "data-duration"));
if (!readAttr(tagSource, "data-start") || !readAttr(tagSource, "data-duration")) return null;
if (!Number.isFinite(start) || !Number.isFinite(duration)) return null;
return { start, end: start + duration };
}
export function mediaWindowsOverlap(
a: { start: number; end: number } | null,
b: { start: number; end: number } | null,
): boolean {
if (!a || !b) return true;
return a.start < b.end && b.start < a.end;
}
/** Read an HTML attribute using browser-equivalent character-reference decoding. */
export function readDecodedAttr(tagSource: string, attr: string): string | null {
return readAttributeValue(tagSource, attr, true);
}
function readAttributeValue(
tagSource: string,
attr: string,
decodeEntities: boolean,
): string | null {
if (!tagSource) return null;
let value: string | null = null;
const parser = new Parser(
{
onattribute(name, attributeValue) {
if (value === null && name.toLowerCase() === attr.toLowerCase()) value = attributeValue;
},
},
{ decodeEntities, lowerCaseAttributeNames: false, lowerCaseTags: true },
);
parser.end(tagSource);
return value;
}
/**
* Read a JSON-bearing attribute with browser-equivalent character-reference
* decoding. Imported or formatter-serialized HTML commonly stores JSON quotes
* as `&quot;`; lint must inspect the same decoded value that `getAttribute()`
* exposes at runtime.
*/
export function readJsonAttr(tagSource: string, attr: string): string | null {
return readDecodedAttr(tagSource, attr);
}
export function collectCompositionIds(tags: OpenTag[]): Set<string> {
const ids = new Set<string>();
for (const tag of tags) {
const compId = readDecodedAttr(tag.raw, "data-composition-id");
if (compId) ids.add(compId);
}
return ids;
}
export function extractCompositionIdsFromCss(css: string): string[] {
const ids = new Set<string>();
let match: RegExpExecArray | null;
const pattern = new RegExp(
COMPOSITION_ID_IN_CSS_PATTERN.source,
COMPOSITION_ID_IN_CSS_PATTERN.flags,
);
while ((match = pattern.exec(css)) !== null) {
if (match[1]) ids.add(match[1]);
}
return [...ids];
}
export function extractTimelineRegistryKeys(source: string): string[] {
const keys = new Set<string>();
let match: RegExpExecArray | null;
const pattern = new RegExp(
TIMELINE_REGISTRY_KEY_PATTERN.source,
TIMELINE_REGISTRY_KEY_PATTERN.flags,
);
while ((match = pattern.exec(source)) !== null) {
const key = match[1] ?? match[2];
if (key) keys.add(key);
}
for (const entry of readTimelineRegistryTopLevelKeys(source)) keys.add(entry);
return [...keys];
}
/**
* Top-level keys of a `window.__timelines = { ... }` literal.
*
* Walks brace depth rather than regex-matching the body. The previous non-greedy
* body match stopped at the first `}` it saw, which for the legal one-liner
*
* window.__timelines = { main: gsap.timeline({ paused: true }) };
*
* was the brace of the INLINED OPTIONS OBJECT. The entry scanner then harvested
* `paused` as a composition id and timeline_id_mismatch reported a timeline
* "registered as paused" — a registration that does not exist, so its fixHint
* could never be applied. Hoisting the timeline to a variable was the only escape,
* and nothing said so.
*/
/** Index of the brace that closes the group opened just before `bodyStart`. */
function findMatchingBrace(source: string, bodyStart: number): number {
let depth = 1;
for (let i = bodyStart; i < source.length; i += 1) {
if (source[i] === "{") depth += 1;
else if (source[i] === "}" && (depth -= 1) === 0) return i;
}
return source.length;
}
/** Replace every nested brace group with spaces so only depth-0 text remains. */
function blankNestedBraceGroups(body: string): string {
let out = "";
let depth = 0;
for (const ch of body) {
if (ch === "{") depth += 1;
else if (ch === "}") depth = Math.max(0, depth - 1);
else if (depth === 0) {
out += ch;
continue;
}
out += " ";
}
return out;
}
function readTimelineRegistryTopLevelKeys(source: string): string[] {
const open = TIMELINE_REGISTRY_OBJECT_OPEN_PATTERN.exec(source);
if (!open) return [];
const bodyStart = open.index + open[0].length;
const body = source.slice(bodyStart, findMatchingBrace(source, bodyStart));
const flattened = blankNestedBraceGroups(body);
const keys: string[] = [];
const entryPattern = new RegExp(
TIMELINE_REGISTRY_OBJECT_ENTRY_PATTERN.source,
TIMELINE_REGISTRY_OBJECT_ENTRY_PATTERN.flags,
);
let entry: RegExpExecArray | null;
while ((entry = entryPattern.exec(flattened)) !== null) {
const key = entry[1] ?? entry[2];
if (key) keys.push(key);
}
return keys;
}
export function getInlineScriptSyntaxError(
source: string,
): { message: string; offset?: number } | null {
if (!source.trim()) return null;
try {
// Match the former Function-body grammar (including top-level return), without eval.
parse(source, {
ecmaVersion: "latest",
sourceType: "script",
allowReturnOutsideFunction: true,
});
return null;
} catch (error) {
return {
message: error instanceof Error ? error.message : String(error),
offset:
error instanceof SyntaxError && "pos" in error && typeof error.pos === "number"
? error.pos
: undefined,
};
}
}
// fallow-ignore-next-line complexity
/**
* Blank the contents of every `'...'` and `"..."` literal, keeping the quotes so
* the source stays the same shape.
*
* Needed because a composition that *displays* source code carries things like
* `Math.random()` inside a string it never executes. Scanning raw script text for
* non-determinism reported those compositions as non-deterministic, and no edit
* could clear it while keeping the displayed snippet intact.
*
* Template literals are deliberately left alone: `${Math.random()}` inside one IS
* executed, and blanking it would hide real non-determinism. A snippet stored in a
* backtick string therefore still reports — a narrower gap than the one this closes.
*/
export function stripStringLiterals(source: string): string {
return source.replace(
/(['"])(?:\\.|(?!\1)[^\\\n])*\1?/g,
(literal) => literal[0] + " ".repeat(Math.max(0, literal.length - 1)),
);
}
// fallow-ignore-next-line complexity
function scanJsComments(source: string): { out: string; balanced: boolean } {
let out = "";
let i = 0;
let quote: "'" | '"' | "`" | null = null;
let escaped = false;
let inRegex = false;
let inRegexClass = false;
let regexMisread = false;
const ctx = new CodeContext();
const emitCode = (ch: string) => {
out += ch;
ctx.push(ch);
};
const emitOpaque = (ch: string) => {
out += ch;
ctx.push(" ");
};
while (i < source.length) {
const ch = source[i] ?? "";
const next = source[i + 1] ?? "";
if (inRegex) {
out += ch;
if (escaped) {
escaped = false;
if (ch === "\n" || ch === "\r") {
inRegex = false;
inRegexClass = false;
regexMisread = true;
}
} else if (ch === "\\") {
escaped = true;
} else if (ch === "[") {
inRegexClass = true;
} else if (ch === "]") {
inRegexClass = false;
} else if (ch === "/" && !inRegexClass) {
inRegex = false;
ctx.push(ch);
} else if (ch === "\n" || ch === "\r") {
inRegex = false;
inRegexClass = false;
regexMisread = true;
}
i += 1;
continue;
}
if (quote) {
if (escaped) {
escaped = false;
emitOpaque(ch);
} else if (ch === "\\") {
escaped = true;
emitOpaque(ch);
} else if (ch === quote) {
quote = null;
emitCode(ch);
} else {
emitOpaque(ch);
}
i += 1;
continue;
}
if (ch === "'" || ch === '"' || ch === "`") {
quote = ch;
emitCode(ch);
i += 1;
continue;
}
if (ch === "/" && next === "/") {
out += " ";
ctx.push(" ");
ctx.push(" ");
i += 2;
while (i < source.length && source[i] !== "\n" && source[i] !== "\r") {
out += " ";
ctx.push(" ");
i += 1;
}
continue;
}
if (ch === "/" && next === "*") {
out += " ";
ctx.push(" ");
ctx.push(" ");
i += 2;
while (i < source.length) {
const blockCh = source[i] ?? "";
const blockNext = source[i + 1] ?? "";
if (blockCh === "*" && blockNext === "/") {
out += " ";
ctx.push(" ");
ctx.push(" ");
i += 2;
break;
}
const kept = blockCh === "\n" || blockCh === "\r" ? blockCh : " ";
out += kept;
ctx.push(kept);
i += 1;
}
continue;
}
if (ch === "/" && ctx.startsRegexLiteral()) {
inRegex = true;
emitCode(ch);
i += 1;
continue;
}
emitCode(ch);
i += 1;
}
return { out, balanced: quote === null && !inRegex && !regexMisread };
}
export function stripJsComments(source: string): string {
return scanJsComments(source).out;
}
// A GreenSock banner, or the producer's inlined-source comment when its URL path is an npm gsap dist file.
function isGsapLibraryComment(comment: Comment): boolean {
if (comment.type !== "Block") return false;
const { value } = comment;
const src = /^\s*inlined:\s*(\S+)\s*$/.exec(value)?.[1]?.split(/[?#]/)[0];
return (
(value.startsWith("!") && /\bGreenSock\b/.test(value)) ||
(src !== undefined && /(?:^|\/)gsap(?:@[^/]+)?\/dist\/[^/]+\.js$/.test(src))
);
}
/** GSAP's UMD wrapper `function (g, f) { ...define.amd... }(this, function (e) {...})`, AMD in its own body. */
function isUmdWrapperCall(call: CallExpression): boolean {
const [scope, factory] = call.arguments;
if (
call.callee.type !== "FunctionExpression" ||
call.arguments.length !== 2 ||
scope?.type !== "ThisExpression" ||
factory?.type !== "FunctionExpression"
)
return false;
let checksAmd = false;
recursive(call.callee.body, null, {
Function() {},
MemberExpression(member, state, visit) {
if (
!member.computed &&
member.object.type === "Identifier" &&
member.object.name === "define" &&
member.property.type === "Identifier" &&
member.property.name === "amd"
)
checksAmd = true;
base.MemberExpression?.(member, state, visit);
},
});
return checksAmd;
}
/**
* A GSAP banner belongs only to the wrapper right after it. A banner inside a factory exempts nothing:
* a bundler (Rollup ESM to UMD) puts it in the same factory as author code.
*/
function bannerOwner(
banner: Comment,
source: string,
commentAt: Map<number, Comment>,
wrappers: CallExpression[],
): CallExpression | undefined {
let next = banner.end;
for (;;) {
while (/[\s!;(]/.test(source[next] ?? "")) next++;
const comment = commentAt.get(next);
if (!comment) break;
next = comment.end;
}
return wrappers.find((call) => call.start === next);
}
/** Offsets of inlined GSAP library code: the UMD wrapper call each GSAP banner belongs to. */
function findInlinedGsapLibrarySpans(source: string): Array<[number, number]> {
if (!/GreenSock|inlined:/.test(source)) return [];
const comments: Comment[] = [];
let program: Program;
try {
program = parse(source, {
ecmaVersion: "latest",
sourceType: "script",
allowReturnOutsideFunction: true,
onComment: comments,
});
} catch {
return [];
}
const banners = comments.filter(isGsapLibraryComment);
const wrappers: CallExpression[] = [];
simple(program, {
CallExpression(call) {
if (isUmdWrapperCall(call)) wrappers.push(call);
},
});
const commentAt = new Map(comments.map((comment) => [comment.start, comment]));
const owners = new Set<CallExpression>();
for (const banner of banners) {
const owner = bannerOwner(banner, source, commentAt, wrappers);
if (owner) owners.add(owner);
}
return [...owners].map((call): [number, number] => [call.start, call.end]);
}
export function blankInlinedGsapLibrary(source: string): string {
let out = source;
for (const [start, end] of findInlinedGsapLibrarySpans(source)) {
out = out.slice(0, start) + " ".repeat(end - start) + out.slice(end);
}
return out;
}
export function stripJsCode(source: string): string {
const { out, balanced } = scanJsComments(source);
return balanced ? stripJsStringLiterals(out) : source;
}
const REGEX_ALLOWED_BEFORE = new Set("=(,:[!&|?{};+-*%^~<>");
const REGEX_ALLOWED_KEYWORDS = new Set([
"return",
"typeof",
"instanceof",
"in",
"of",
"new",
"delete",
"void",
"case",
"do",
"else",
"yield",
"await",
]);
const WORD_CHAR = /[A-Za-z0-9_$]/;
/**
* Tracks just enough emitted context to tell a regex literal from a division: the last
* two significant characters and the trailing identifier. Carried incrementally because
* re-scanning the accumulated output per candidate slash is quadratic — a composition
* with one inlined vendor bundle took 58x longer to lint.
*/
class CodeContext {
private last = "";
private prev = "";
private word = "";
private wordEnded = false;
private wordAfterDot = false;
push(ch: string): void {
if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
this.wordEnded = true;
return;
}
if (WORD_CHAR.test(ch)) {
if (this.wordEnded || this.word === "") this.wordAfterDot = this.last === ".";
this.word = this.wordEnded ? ch : this.word + ch;
} else {
this.word = "";
this.wordAfterDot = false;
}
this.wordEnded = false;
this.prev = this.last;
this.last = ch;
}
startsRegexLiteral(): boolean {
if (this.last === "") return true;
if (WORD_CHAR.test(this.last))
return !this.wordAfterDot && REGEX_ALLOWED_KEYWORDS.has(this.word);
if ((this.last === "+" || this.last === "-") && this.prev === this.last) return false;
return REGEX_ALLOWED_BEFORE.has(this.last);
}
}
/**
* Blanks string, template-literal and regex-literal *contents* (delimiters, length
* and newline positions kept) so a rule scanning for an API call does not match one
* a composition merely renders as on-screen text. Template `${…}` expressions stay —
* they are code. Returns the source untouched if the scan ends mid-literal, so a
* parse this scanner cannot model degrades to the caller's pre-existing behaviour
* rather than silently blanking real code on an `error`-severity gate.
*/
// fallow-ignore-next-line complexity
export function stripJsStringLiterals(source: string): string {
let out = "";
let i = 0;
const templateBraces: number[] = [];
const ctx = new CodeContext();
let quote: "'" | '"' | "`" | null = null;
let escaped = false;
let inRegex = false;
let inRegexClass = false;
let regexMisread = false;
const blank = (ch: string) => (ch === "\n" || ch === "\r" ? ch : " ");
const emit = (text: string) => {
out += text;
for (const ch of text) ctx.push(ch);
};
while (i < source.length) {
const ch = source[i] ?? "";
const next = source[i + 1] ?? "";
if (inRegex) {
if (escaped) {
escaped = false;
if (ch === "\n" || ch === "\r") {
inRegex = false;
inRegexClass = false;
regexMisread = true;
}
emit(blank(ch));
} else if (ch === "\\") {
escaped = true;
emit(" ");
} else if (ch === "[") {
inRegexClass = true;
emit(" ");
} else if (ch === "]") {
inRegexClass = false;
emit(" ");
} else if (ch === "/" && !inRegexClass) {
inRegex = false;
emit(ch);
} else if (ch === "\n" || ch === "\r") {
inRegex = false;
inRegexClass = false;
escaped = false;
regexMisread = true;
emit(ch);
} else {
emit(" ");
}
i += 1;
continue;
}
if (quote) {
if (escaped) {
escaped = false;
emit(blank(ch));
} else if (ch === "\\") {
escaped = true;
emit(" ");
} else if (ch === quote) {
quote = null;
emit(ch);
} else if (ch === "`" || quote !== "`" || ch !== "$" || next !== "{") {
emit(blank(ch));
} else {
templateBraces.push(0);
quote = null;
emit("${");
i += 2;
continue;
}
i += 1;
continue;
}
if (ch === "'" || ch === '"' || ch === "`") {
quote = ch;
emit(ch);
i += 1;
continue;
}
if (ch === "/" && next !== "/" && next !== "*" && ctx.startsRegexLiteral()) {
inRegex = true;
emit(ch);
i += 1;
continue;
}
if (templateBraces.length > 0) {
const depth = templateBraces[templateBraces.length - 1] ?? 0;
if (ch === "{") templateBraces[templateBraces.length - 1] = depth + 1;
else if (ch === "}") {
if (depth === 0) {
templateBraces.pop();
quote = "`";
emit(ch);
i += 1;
continue;
}
templateBraces[templateBraces.length - 1] = depth - 1;
}
}
emit(ch);
i += 1;
}
if (quote !== null || templateBraces.length > 0 || inRegex || regexMisread) return source;
return out;
}
/**
* Drops CSS comments without following a `/*` that only appears inside a string —
* a slide printing comment markers as content otherwise pairs two of them and
* deletes the real rules in between.
*/
// fallow-ignore-next-line complexity
export function stripCssComments(source: string): string {
let out = "";
let i = 0;
let quote: "'" | '"' | null = null;
while (i < source.length) {
const ch = source[i] ?? "";
if (quote) {
out += ch;
if (ch === "\\") {
out += source[i + 1] ?? "";
i += 2;
continue;
}
if (ch === quote) quote = null;
i += 1;
continue;
}
if (ch === '"' || ch === "'") {
quote = ch;
out += ch;
i += 1;
continue;
}
if (ch === "/" && source[i + 1] === "*") {
const end = source.indexOf("*/", i + 2);
const stop = end === -1 ? source.length : end + 2;
for (let j = i; j < stop; j += 1) {
const c = source[j] ?? "";
out += c === "\n" || c === "\r" ? c : " ";
}
i = stop;
continue;
}
out += ch;
i += 1;
}
return out;
}
// One linear pass that drops every `<!-- … -->` region. Uses indexOf, not a
// `/<!--[\s\S]*?-->/` regex: that pattern backtracks O(n²) on inputs with many
// unterminated "<!--" (CodeQL js/polynomial-redos). An unterminated "<!--" with
// no closing "-->" is kept verbatim, matching the prior regex's no-match behavior.
function stripHtmlCommentsOnce(
source: string,
removed?: (start: number, end: number) => void,
): string {
let out = "";
let i = 0;
for (;;) {
const start = source.indexOf("<!--", i);
if (start < 0) return out + source.slice(i);
const end = source.indexOf("-->", start + 4);
if (end < 0) return out + source.slice(i);
out += source.slice(i, start);
removed?.(start, end + 3);
i = end + 3;
}
}
// Strip HTML comments to a fixpoint. A single pass is not enough: deleting one
// comment can splice adjacent markers into a fresh, complete <!-- … --> (e.g.
// "<<!-- -->!-- … -->" → "<!-- … -->"), which would otherwise survive and let a
// commented-out <template>/tag hijack the linter's tag scan.
export function stripHtmlComments(
source: string,
pass?: (ranges: Array<[number, number]>) => void,
): string {
let out = source;
for (let prev = ""; prev !== out; ) {
prev = out;
const ranges: Array<[number, number]> = [];
out = stripHtmlCommentsOnce(out, pass ? (start, end) => ranges.push([start, end]) : undefined);
if (ranges.length) pass?.(ranges);
}
return out;
}
export function extractScriptTextsAndSrcs(scripts: ExtractedBlock[]): {
texts: string[];
srcs: string[];
} {
const texts = scripts.filter((s) => !/\bsrc\s*=/.test(s.attrs)).map((s) => s.content);
const srcs = scripts.map((s) => readAttr(`<script ${s.attrs}>`, "src") || "").filter(Boolean);
return { texts, srcs };
}
export function isMediaTag(tagName: string): boolean {
return tagName === "video" || tagName === "audio" || tagName === "img";
}
// Whether any <style> block in the composition defines caption group/word
// classes (`.caption-group`, `.caption_word`, etc.) — the signal several
// caption-specific rules use to skip non-caption compositions entirely.
export function hasCaptionStyles(styles: ExtractedBlock[]): boolean {
return styles.some((s) => /\.caption[-_]?(?:group|word)/i.test(s.content));
}
export function truncateSnippet(value: string, maxLength = 220): string | undefined {
const normalized = value.replace(/\s+/g, " ").trim();
if (!normalized) return undefined;
if (normalized.length <= maxLength) return normalized;
return `${normalized.slice(0, maxLength - 3)}...`;
}
/**
* Matches a media tag carrying a real `src` attribute, capturing the tag name in
* group 1 and the quoted src in group 2; {@link mediaSrcOf} reads its value.
* `src` must follow whitespace so the tail of `data-var-src="bg"` is not read as one.
*/
export function mediaSrcTagRe(tagAlternation: string): RegExp {
return new RegExp(`<(${tagAlternation})\\b[^>]*\\ssrc\\s*=\\s*("[^"]*"|'[^']*')[^>]*>`, "gi");
}
export function mediaSrcOf(match: RegExpExecArray): string {
return readDecodedAttr(match[0], "src") ?? "";
}