@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/dist/src/rules/lib/html-safety.js

@@ -0,0 +1,755 @@
+/**
+ * IS THIS EXPRESSION SAFE TO HAND TO AN HTML PARSER?
+ * ==================================================
+ *
+ * WHY THIS FILE EXISTS
+ *
+ * The XSS rule used to fire on the SHAPE of the line alone:
+ *
+ *     element.innerHTML = <anything not a fixed string>
+ *
+ * and then print "No escaping or sanitiser call is visible at this line."
+ *
+ * Pointing the scanner at this project's own browser UI produced seven of
+ * these. Every one was wrong, and one of them was wrong in a way that matters:
+ *
+ *     $('progressLabel').innerHTML = `<span class="err">${escapeHtml(msg)}</span>`
+ *
+ * The escaper is RIGHT THERE, in the same expression, four characters from the
+ * value it protects. The finding said we could not see it. That is not a
+ * conservative guess, it is a false statement about code we had already parsed,
+ * and a tool whose entire pitch is "we never overclaim" cannot afford to make
+ * it.
+ *
+ * WHAT THIS DOES
+ *
+ * It answers one question about one expression: can every value spliced into
+ * this string be PROVEN incapable of carrying markup? A value qualifies when
+ * it is
+ *
+ *   - a fixed literal (nobody injects into a constant),
+ *   - a number, or an expression that can only produce one (`x.length`,
+ *     `a - b`, `n.toFixed(2)`) - digits cannot open a tag,
+ *   - the result of a known escaping function (`escapeHtml`, `encodeURIComponent`,
+ *     `DOMPurify.sanitize`),
+ *   - a local variable or local function whose every possible value is,
+ *     recursively, one of the above.
+ *
+ * The last case is what makes it useful rather than cosmetic. Real UI code is
+ * built out of small render helpers - `list.map(renderRow).join('')` - and a
+ * check that stops at the first function call proves nothing about any of them.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO
+ *
+ * It PROVES SAFE or it says NOTHING. There is no "probably fine". Anything it
+ * does not recognise - a bare property access, an imported function, a value
+ * from another file - comes back unproven, and the finding still fires. That
+ * asymmetry is the whole design: a wrong "safe" hides a real cross-site
+ * scripting bug, while a wrong "unproven" only costs the reader a second look.
+ *
+ * It also does not decide whether the value is attacker-controlled. That is the
+ * tracer's job, one pass later. This is the narrower question of whether the
+ * value could carry markup at all, and it is worth asking first because a value
+ * that provably cannot needs no trace.
+ *
+ * SCOPE: JavaScript and TypeScript only. Those are the languages whose HTML
+ * sinks take an expression built in the same file. The Python, Java and Go
+ * branches of the XSS rule are untouched and still report on shape alone -
+ * that gap is stated in the rule's `support` notes rather than papered over.
+ */
+/* ---------------------------------------------------------------------------
+ * The escaper list.
+ *
+ * A name gets in here only if its ONE job is to make text safe for HTML. That
+ * excludes `escape()` (deprecated URL escaping - leaves `<` alone), `String()`
+ * (converts, does not clean) and `JSON.stringify` (its output can contain a
+ * literal `</script>`, which closes the surrounding tag and ends the game).
+ * ------------------------------------------------------------------------ */
+const ESCAPER_NAMES = new Set([
+    'escapeHtml',
+    'escapeHTML',
+    'escapehtml',
+    'htmlEscape',
+    'html_escape',
+    'escapeHtmlAttribute',
+    'escapeAttribute',
+    'encodeURIComponent',
+    'encodeURI',
+    'sanitize',
+    'sanitizeHtml',
+    'sanitizeHTML',
+    'purify',
+]);
+/** Member-call escapers, matched on the property name of `X.sanitize(...)`. */
+const ESCAPER_METHODS = new Set(['sanitize', 'escape', 'clean']);
+/** Objects whose `.escape`/`.sanitize` we trust. Prevents `router.escape()` counting. */
+const ESCAPER_OBJECTS = new Set([
+    'DOMPurify',
+    'dompurify',
+    'sanitizeHtml',
+    'xss',
+    'he',
+    'validator',
+    'escapeHtml',
+]);
+/** Properties that can only ever hold a number. Digits cannot open a tag. */
+const NUMERIC_PROPERTIES = new Set(['length', 'size', 'byteLength']);
+/** Methods whose return value is a number or a boolean, whatever the receiver. */
+const NUMERIC_METHODS = new Set([
+    'toFixed',
+    'indexOf',
+    'lastIndexOf',
+    'charCodeAt',
+    'codePointAt',
+    'includes',
+    'startsWith',
+    'endsWith',
+    'has',
+    'valueOf',
+]);
+/** Operators whose result is a number or a boolean regardless of the operands. */
+const NUMERIC_OPERATORS = new Set([
+    '-',
+    '*',
+    '/',
+    '%',
+    '**',
+    '<',
+    '>',
+    '<=',
+    '>=',
+    '==',
+    '!=',
+    '===',
+    '!==',
+    'instanceof',
+    'in',
+    '&',
+    '|',
+    '^',
+    '<<',
+    '>>',
+    '>>>',
+]);
+/** Array methods that pass their safety straight through from the receiver. */
+const PASSTHROUGH_METHODS = new Set([
+    'filter',
+    'slice',
+    'sort',
+    'reverse',
+    'flat',
+    'concat',
+    'toSorted',
+    'toReversed',
+]);
+/** Node types that open a new function scope. We never resolve names across one. */
+const FUNCTION_SCOPES = new Set([
+    'function_declaration',
+    'function_expression',
+    'function',
+    'arrow_function',
+    'method_definition',
+    'generator_function',
+    'generator_function_declaration',
+]);
+/** How far the recursion may go before giving up and reporting unproven. */
+const MAX_DEPTH = 30;
+/** How many nested calls we will follow with their arguments bound. */
+const MAX_FRAMES = 6;
+const NOT_APPLICABLE = { proven: false, unproven: [], escapers: [] };
+/**
+ * A binding is normally the expression a caller passed. `NUMERIC` is the one
+ * exception: a name the LANGUAGE guarantees holds a number, with no expression
+ * anywhere to point at. See `judgeIteratorCallback`.
+ */
+const NUMERIC = Symbol('numeric-by-language');
+export function supportsHtmlSafety(language) {
+    return language === 'javascript' || language === 'typescript';
+}
+/**
+ * Judge one expression. `root` is the file's root node, used to look up
+ * function declarations; pass `ctx.file.root`.
+ */
+export function analyzeHtmlSafety(node, root, language) {
+    if (!supportsHtmlSafety(language))
+        return NOT_APPLICABLE;
+    const unproven = [];
+    const escapers = new Set();
+    const seen = new Set();
+    /* ---------------------------------------------------------------------
+     * ARGUMENT BINDING
+     *
+     * A render helper judged on its own is almost never provably safe:
+     *
+     *     function tile(count, label, note, className) {
+     *       return `<div class="${className}"><b>${count}</b>${label}</div>`;
+     *     }
+     *
+     * `className` is a parameter, so on its own it could be anything, and the
+     * helper reads as unsafe at every call site. But the call sites say:
+     *
+     *     tile(flow, 'flow-verified', '...', 'tile-verified')
+     *
+     * - all four arguments are literals or numbers. The helper is safe HERE,
+     * which is the only question being asked.
+     *
+     * So each call pushes a frame binding parameter names to the argument
+     * EXPRESSIONS, and a parameter resolves to whatever the caller passed. This
+     * is the same interprocedural move the taint tracer makes one pass later,
+     * for the same reason: a function boundary is not an analysis boundary.
+     *
+     * The frame is popped while the argument itself is judged, so an argument
+     * that happens to reuse a parameter's name resolves in the CALLER's scope,
+     * where it belongs.
+     * ------------------------------------------------------------------- */
+    const frames = [];
+    const collapse = (n) => (n.text ?? '').replace(/\s+/g, ' ').trim().slice(0, 60);
+    /**
+     * Returns true when `n` is proven safe. Records the reason for every
+     * failure so the finding can point at the actual risky sub-expression
+     * instead of the whole statement.
+     */
+    const judge = (n, depth) => {
+        if (!n)
+            return false;
+        // Every `false` this function returns MUST leave a reason behind. A verdict
+        // of "not proven" with nothing to point at produces a finding that says
+        // "something here is unsafe" and names nothing - which is the vague,
+        // unfalsifiable output this whole project exists to avoid.
+        if (depth > MAX_DEPTH) {
+            unproven.push(`${collapse(n)} (nested deeper than this analysis follows)`);
+            return false;
+        }
+        // A name that refers to itself (a recursive render helper) must not spin.
+        // The back-edge stops rather than re-judging: every sub-expression of the
+        // function body is judged exactly once on the way in, so the second visit
+        // could not discover anything the first did not. The key includes the frame
+        // depth, because the same expression judged with different arguments bound
+        // is a different question.
+        const key = `${n.id}#${frames.length}`;
+        if (seen.has(key))
+            return true;
+        seen.add(key);
+        switch (n.type) {
+            /* ---- Fixed values ---- */
+            case 'string':
+            case 'number':
+            case 'true':
+            case 'false':
+            case 'null':
+            case 'undefined':
+            case 'regex':
+                return true;
+            /* ---- A comment produces no value, so it cannot carry markup ---- */
+            case 'comment':
+                return true;
+            /* ---- `a ${b} c` ---- */
+            case 'template_string': {
+                let ok = true;
+                for (const child of n.namedChildren) {
+                    if (!child)
+                        continue;
+                    if (child.type !== 'template_substitution')
+                        continue;
+                    /*
+                     * A `${ }` hole can contain a comment BEFORE the expression, and this
+                     * used to take the substitution's first named child - which in that
+                     * case is the comment, not the code:
+                     *
+                     *     ${
+                     *       // A traced path is only as strong as its weakest hop.
+                     *       verified && finding.unmodelledHops?.length ? ... : ''
+                     *     }
+                     *
+                     * Scanning this project's own UI found it: the checker reported the
+                     * COMMENT as the thing it could not prove safe, and never looked at
+                     * the ternary underneath. Both directions of that bug are bad - here
+                     * it invented a false alarm, but a hole whose comment came first and
+                     * whose expression was genuinely dangerous would have been waved
+                     * through the moment `comment` counted as safe.
+                     *
+                     * So: drop comments, then judge EVERY remaining part rather than the
+                     * first one. A hole holds one expression, but "judge all of them" is
+                     * the reading that cannot silently skip anything.
+                     */
+                    const parts = child.namedChildren.filter((c) => c !== null && c.type !== 'comment');
+                    for (const part of parts)
+                        if (!judge(part, depth + 1))
+                            ok = false;
+                }
+                return ok;
+            }
+            /* ---- a + b, a - b, a || b ---- */
+            case 'binary_expression': {
+                const operator = n.childForFieldName('operator')?.text ?? '';
+                // `a - b` is a number whatever a and b are; no need to look inside.
+                if (NUMERIC_OPERATORS.has(operator))
+                    return true;
+                const left = judge(n.childForFieldName('left'), depth + 1);
+                const right = judge(n.childForFieldName('right'), depth + 1);
+                return left && right;
+            }
+            case 'unary_expression':
+                return true; // !x, -x, ~x, +x - all number or boolean
+            case 'parenthesized_expression':
+                return judge(n.namedChildren.find((c) => c !== null) ?? null, depth + 1);
+            /* ---- cond ? a : b - the condition never reaches the page ---- */
+            case 'ternary_expression': {
+                const consequence = judge(n.childForFieldName('consequence'), depth + 1);
+                const alternative = judge(n.childForFieldName('alternative'), depth + 1);
+                return consequence && alternative;
+            }
+            case 'array': {
+                let ok = true;
+                for (const element of n.namedChildren) {
+                    if (!element)
+                        continue;
+                    if (!judge(element, depth + 1))
+                        ok = false;
+                }
+                return ok;
+            }
+            case 'arrow_function':
+            case 'function_expression':
+            case 'function':
+            case 'function_declaration': {
+                // Reached as a VALUE (`rows.map(renderRow)`), so nobody told us what
+                // the arguments will be. Push an empty frame so an enclosing call's
+                // bindings cannot leak in and answer for a parameter they never saw.
+                frames.push(new Map());
+                const verdict = judgeFunctionResult(n, depth + 1);
+                frames.pop();
+                return verdict;
+            }
+            case 'member_expression': {
+                const property = n.childForFieldName('property')?.text ?? '';
+                if (NUMERIC_PROPERTIES.has(property))
+                    return true;
+                unproven.push(collapse(n));
+                return false;
+            }
+            case 'call_expression':
+                return judgeCall(n, depth);
+            case 'identifier':
+            case 'shorthand_property_identifier': {
+                // A bound parameter resolves to what the caller actually passed.
+                const frame = frames[frames.length - 1];
+                const bound = frame?.get(n.text ?? '');
+                if (bound === NUMERIC)
+                    return true;
+                if (bound) {
+                    // Judge the argument in the CALLER's scope, not this one.
+                    const saved = frames.pop();
+                    const verdict = judge(bound, depth + 1);
+                    frames.push(saved);
+                    return verdict;
+                }
+                const bindings = resolveBinding(n);
+                if (bindings.length > 0) {
+                    let ok = true;
+                    for (const binding of bindings)
+                        if (!judge(binding, depth + 1))
+                            ok = false;
+                    return ok;
+                }
+                /*
+                 * An escaper passed BY REFERENCE:
+                 *
+                 *     finding.unmodelledHops.map(escapeHtml).join(', ')
+                 *
+                 * This is the same promise as calling it, and it is one of the most
+                 * common safe idioms in real UI code. Without this branch the name
+                 * resolves to the function DECLARATION and we judge its body, which
+                 * ends at `String(x).replace(...)` - a `.replace()` call we cannot
+                 * prove anything about. The checker then reported the innards of its
+                 * own escaper as the unsafe part, which is a confusing way to be wrong.
+                 *
+                 * The `bindings.length === 0` test above is what keeps this honest, and
+                 * makes it STRICTER than the call form: a local `const sanitize = x =>
+                 * x` shadows the trusted name, resolves first, and gets judged on its
+                 * actual body instead of being waved through on its name.
+                 */
+                if (ESCAPER_NAMES.has(n.text ?? '')) {
+                    escapers.add(`${n.text}()`);
+                    return true;
+                }
+                // A bare name can also be a function passed by reference -
+                // `rows.map(renderRow)`. Without this the commonest shape in real UI
+                // code resolves to nothing and every render helper reads as unproven.
+                const fn = findFunctionNamed(n.text ?? '', root);
+                if (fn)
+                    return judgeFunctionResult(fn, depth + 1);
+                unproven.push(collapse(n));
+                return false;
+            }
+            default:
+                unproven.push(collapse(n));
+                return false;
+        }
+    };
+    /* ---- Calls ------------------------------------------------------------ */
+    const judgeCall = (n, depth) => {
+        const callee = n.childForFieldName('function');
+        const args = n.childForFieldName('arguments');
+        const argList = args ? args.namedChildren.filter((c) => c !== null) : [];
+        if (callee && callee.type === 'identifier') {
+            const name = callee.text ?? '';
+            if (ESCAPER_NAMES.has(name)) {
+                /*
+                 * Trusting a name is a CONVENTION, not a proof, and a file is free to
+                 * break it. `sanitize` is on the trusted list; a codebase that writes
+                 *
+                 *     const sanitize = (x) => x;
+                 *
+                 * has a function with the right name that cleans nothing, and taking
+                 * the name at face value silences the rule for the whole file.
+                 *
+                 * We do not try to decide whether an arbitrary local escaper is any
+                 * good - that is a research problem. We check the one case that needs
+                 * no judgement: a function that hands back its own argument untouched
+                 * escapes nothing, whatever it is called. Anything more involved keeps
+                 * the benefit of the doubt, which is what `limitations` already says.
+                 */
+                const local = findFunctionNamed(name, root);
+                if (local && isIdentityFunction(local)) {
+                    unproven.push(`${collapse(n)} (\`${name}\` is defined in this file and returns its argument unchanged)`);
+                    return false;
+                }
+                escapers.add(`${name}()`);
+                return true;
+            }
+            // Number(x) is a number. String(x) is NOT safe - it converts, it does
+            // not clean - and neither is JSON.stringify, whose output can carry a
+            // literal `</script>` that closes the tag it sits inside.
+            if (name === 'Number' || name === 'parseInt' || name === 'parseFloat' || name === 'BigInt') {
+                return true;
+            }
+            const fn = findFunctionNamed(name, root);
+            if (fn)
+                return judgeCallWithArguments(fn, argList, n, depth + 1);
+            unproven.push(collapse(n));
+            return false;
+        }
+        if (callee && callee.type === 'member_expression') {
+            const object = callee.childForFieldName('object');
+            const property = callee.childForFieldName('property')?.text ?? '';
+            const objectName = object?.type === 'identifier' ? (object.text ?? '') : '';
+            // DOMPurify.sanitize(x) and friends.
+            if (ESCAPER_METHODS.has(property) && ESCAPER_OBJECTS.has(objectName)) {
+                escapers.add(`${objectName}.${property}()`);
+                return true;
+            }
+            if (ESCAPER_NAMES.has(property)) {
+                escapers.add(`.${property}()`);
+                return true;
+            }
+            if (NUMERIC_METHODS.has(property))
+                return true;
+            if (objectName === 'Math')
+                return true;
+            // `parts.join('')` - safe when the thing being joined is safe.
+            if (property === 'join')
+                return judge(object, depth + 1);
+            // `rows.map(renderRow)` - the array's safety is the CALLBACK's safety,
+            // never the receiver's. This is the case that makes the whole analysis
+            // worth having: UI code is render helpers all the way down.
+            if (property === 'map' || property === 'flatMap') {
+                const callback = argList[0];
+                if (!callback) {
+                    unproven.push(collapse(n));
+                    return false;
+                }
+                return judgeIteratorCallback(callback, depth);
+            }
+            if (PASSTHROUGH_METHODS.has(property))
+                return judge(object, depth + 1);
+            // `"x".repeat(n)`, `s.padStart(...)` on a literal receiver stay safe.
+            if ((property === 'repeat' || property === 'padStart' || property === 'padEnd') &&
+                object &&
+                object.type === 'string') {
+                return true;
+            }
+            unproven.push(collapse(n));
+            return false;
+        }
+        unproven.push(collapse(n));
+        return false;
+    };
+    /**
+     * Does this function return one of its own parameters, unchanged?
+     *
+     * `(x) => x` and `function f(x) { return x; }` both qualify. A single
+     * transformation anywhere - a `.replace()`, a template, a call - and the
+     * answer is no, because then we genuinely cannot tell what it does and the
+     * name is the only evidence available.
+     */
+    const isIdentityFunction = (fn) => {
+        const params = new Set(parameterNames(fn)
+            .map((p) => p.name)
+            .filter((name) => name.length > 0));
+        if (params.size === 0)
+            return false;
+        const body = fn.childForFieldName('body');
+        if (!body)
+            return false;
+        // Concise arrow body: `(x) => x`
+        if (body.type !== 'statement_block') {
+            return body.type === 'identifier' && params.has(body.text ?? '');
+        }
+        // Block body: every return must hand back a parameter, and there must be
+        // at least one - a function that returns nothing is not an identity.
+        let returns = 0;
+        let allBareParameters = true;
+        const collect = (n, isRoot) => {
+            if (!isRoot && FUNCTION_SCOPES.has(n.type))
+                return;
+            if (n.type === 'return_statement') {
+                const value = n.namedChildren.find((c) => c !== null && c.type !== 'comment') ?? null;
+                if (value) {
+                    returns++;
+                    if (value.type !== 'identifier' || !params.has(value.text ?? '')) {
+                        allBareParameters = false;
+                    }
+                }
+            }
+            for (const child of n.namedChildren)
+                if (child)
+                    collect(child, false);
+        };
+        collect(body, true);
+        return returns > 0 && allBareParameters;
+    };
+    /**
+     * Judge the callback of `rows.map((row, i) => ...)`.
+     *
+     * The first parameter is an element, and nobody here knows what is in the
+     * array, so it stays unbound and reads as unproven. The SECOND parameter is
+     * the index, and that one is not a guess: `Array.prototype.map` is specified
+     * to pass an integer, and no caller can make it anything else. Digits cannot
+     * open a tag, so the index is provably safe.
+     *
+     * This earns its place because loop counters are spliced into rendered markup
+     * constantly - `<span class="ln">${i + 1}</span>` is in this project's own
+     * code viewer - and without it every such line reads as unproven forever, for
+     * a value that is arithmetic by construction.
+     *
+     * Only `map`/`flatMap` get this: they are the iterators whose RESULT becomes
+     * markup. `forEach` returns undefined and never reaches the page.
+     */
+    const judgeIteratorCallback = (callback, depth) => {
+        if (!FUNCTION_SCOPES.has(callback.type))
+            return judge(callback, depth + 1);
+        const names = parameterNames(callback);
+        const frame = new Map();
+        // names[1] is the index. names[0] (the element) and names[2] (the whole
+        // array) are deliberately left unbound - we know nothing about either.
+        const indexName = names[1]?.name;
+        if (indexName)
+            frame.set(indexName, NUMERIC);
+        frames.push(frame);
+        const verdict = judgeFunctionResult(callback, depth + 1);
+        frames.pop();
+        return verdict;
+    };
+    /** Judge `fn(...args)` with each parameter bound to the argument passed. */
+    const judgeCallWithArguments = (fn, argList, callSite, depth) => {
+        if (frames.length >= MAX_FRAMES) {
+            unproven.push(`${collapse(callSite)} (call chain longer than this analysis follows)`);
+            return false;
+        }
+        const names = parameterNames(fn);
+        const frame = new Map();
+        names.forEach((param, index) => {
+            if (!param.name)
+                return;
+            // The caller's argument wins; a missing argument falls back to the
+            // parameter's own default (`className = ''`), which is just as knowable.
+            const arg = argList[index] ?? param.fallback;
+            if (arg)
+                frame.set(param.name, arg);
+        });
+        frames.push(frame);
+        const verdict = judgeFunctionResult(fn, depth);
+        frames.pop();
+        return verdict;
+    };
+    /**
+     * Parameter names, in order. Destructuring and rest parameters are skipped
+     * deliberately: we cannot bind them positionally, so the name stays
+     * unresolved and the value reads as unproven, which is the safe direction.
+     */
+    const parameterNames = (fn) => {
+        const params = fn.childForFieldName('parameters') ?? fn.childForFieldName('parameter');
+        if (!params)
+            return [];
+        if (params.type === 'identifier')
+            return [{ name: params.text ?? '', fallback: null }];
+        const names = [];
+        for (const child of params.namedChildren) {
+            if (!child)
+                continue;
+            if (child.type === 'identifier') {
+                names.push({ name: child.text ?? '', fallback: null });
+            }
+            else if (child.type === 'assignment_pattern') {
+                // `className = ''` - a name AND a known value when the caller omits it.
+                const left = child.childForFieldName('left');
+                names.push({
+                    name: left?.type === 'identifier' ? (left.text ?? '') : '',
+                    fallback: child.childForFieldName('right'),
+                });
+            }
+            else if (child.type === 'required_parameter' || child.type === 'optional_parameter') {
+                // TypeScript wraps the name in a parameter node, sometimes with a default.
+                const pattern = child.childForFieldName('pattern');
+                names.push({
+                    name: pattern?.type === 'identifier' ? (pattern.text ?? '') : '',
+                    fallback: child.childForFieldName('value'),
+                });
+            }
+            else {
+                // Destructuring or a rest parameter: we cannot bind it positionally,
+                // so the name stays unresolved and its uses read as unproven. Holding
+                // the position matters - dropping it would shift every later argument.
+                names.push({ name: '', fallback: null });
+            }
+        }
+        return names;
+    };
+    /* ---- What can this function return? ----------------------------------- */
+    const judgeFunctionResult = (fn, depth) => {
+        if (depth > MAX_DEPTH) {
+            unproven.push(`${collapse(fn)} (nested deeper than this analysis follows)`);
+            return false;
+        }
+        const body = fn.childForFieldName('body');
+        if (!body) {
+            unproven.push(`${collapse(fn)} (no body to read)`);
+            return false;
+        }
+        // Concise arrow body: `x => \`<b>${escapeHtml(x)}</b>\``
+        if (body.type !== 'statement_block')
+            return judge(body, depth + 1);
+        const returns = [];
+        const collect = (n, isRoot) => {
+            if (!isRoot && FUNCTION_SCOPES.has(n.type))
+                return; // a nested helper is its own problem
+            if (n.type === 'return_statement') {
+                const value = n.namedChildren.find((c) => c !== null) ?? null;
+                if (value)
+                    returns.push(value);
+                else
+                    return; // `return;` yields undefined - harmless
+            }
+            for (const child of n.namedChildren)
+                if (child)
+                    collect(child, false);
+        };
+        collect(body, true);
+        // A function with no return statement yields undefined, which prints as
+        // "undefined" - ugly, but not markup.
+        if (returns.length === 0)
+            return true;
+        let ok = true;
+        for (const value of returns)
+            if (!judge(value, depth + 1))
+                ok = false;
+        return ok;
+    };
+    /* ---- Name resolution --------------------------------------------------
+     * Two hard rules, both learned the expensive way on this project:
+     *
+     *   1. Never descend into a nested function scope when searching. An earlier
+     *      helper did, walked into sibling functions, and matched a same-named
+     *      variable that had nothing to do with the one being asked about.
+     *   2. A name we cannot find is UNPROVEN, never safe. Function parameters,
+     *      imports and globals all land here, which is correct - we have no idea
+     *      what a caller passes in.
+     * -------------------------------------------------------------------- */
+    const resolveBinding = (identifier) => {
+        const name = identifier.text ?? '';
+        if (!name)
+            return [];
+        // Walk outward through enclosing scopes, nearest first.
+        let scope = identifier.parent;
+        while (scope) {
+            if (FUNCTION_SCOPES.has(scope.type) || scope.type === 'program') {
+                const found = bindingsIn(scope, name);
+                if (found.length > 0)
+                    return found;
+            }
+            scope = scope.parent;
+        }
+        return [];
+    };
+    const bindingsIn = (scope, name) => {
+        const values = [];
+        const visit = (n) => {
+            // Rule 1: stop at the boundary of any scope that is not the one we were
+            // asked about. Sibling functions are a different world.
+            if (n !== scope && FUNCTION_SCOPES.has(n.type))
+                return;
+            if (n.type === 'variable_declarator') {
+                const target = n.childForFieldName('name');
+                if (target && target.type === 'identifier' && target.text === name) {
+                    const value = n.childForFieldName('value');
+                    // `let x;` with no initialiser tells us nothing.
+                    if (value)
+                        values.push(value);
+                    else
+                        values.push(n); // deliberately unresolvable -> judged unproven
+                }
+            }
+            if (n.type === 'assignment_expression') {
+                const target = n.childForFieldName('left');
+                if (target && target.type === 'identifier' && target.text === name) {
+                    const value = n.childForFieldName('right');
+                    if (value)
+                        values.push(value);
+                }
+            }
+            for (const child of n.namedChildren)
+                if (child)
+                    visit(child);
+        };
+        visit(scope);
+        return values;
+    };
+    const findFunctionNamed = (name, from) => {
+        let found = null;
+        const visit = (n) => {
+            if (found)
+                return;
+            if (n.type === 'function_declaration') {
+                if (n.childForFieldName('name')?.text === name) {
+                    found = n;
+                    return;
+                }
+            }
+            if (n.type === 'variable_declarator') {
+                const target = n.childForFieldName('name');
+                const value = n.childForFieldName('value');
+                if (target?.text === name &&
+                    value &&
+                    (value.type === 'arrow_function' ||
+                        value.type === 'function_expression' ||
+                        value.type === 'function')) {
+                    found = value;
+                    return;
+                }
+            }
+            for (const child of n.namedChildren)
+                if (child)
+                    visit(child);
+        };
+        visit(from);
+        return found;
+    };
+    const proven = judge(node, 0);
+    return {
+        proven: proven && unproven.length === 0,
+        unproven: [...new Set(unproven)],
+        escapers: [...escapers],
+    };
+}
+//# sourceMappingURL=html-safety.js.map