@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/dist/src/rules/lib/strings.js

@@ -0,0 +1,1970 @@
+/**
+ * STRING BUILDING ANALYSIS
+ * ========================
+ *
+ * Almost every injection bug in this tool's catalogue has the same skeleton:
+ * a string was ASSEMBLED at runtime and then handed to something that treats
+ * strings as instructions (a database, a shell, a browser).
+ *
+ * So the one question we ask over and over is: "was this expression a fixed
+ * piece of text, or was it stitched together from parts?" This file answers it
+ * for all five languages, and it is the piece of shared machinery that lets one
+ * rule cover JavaScript, Python, Java and Go at once.
+ *
+ * VOCABULARY YOU'LL NEED:
+ *
+ *   Sanitisation - cleaning or neutralising untrusted input before use. For SQL
+ *     the real fix is not cleaning at all but PARAMETERISATION: you hand the
+ *     database the query and the values separately, so the values can never be
+ *     read as commands. For HTML it means escaping < > & " so text is displayed
+ *     rather than executed.
+ *
+ *   Interpolation - languages' built-in "put this value inside this string"
+ *     syntax: `${x}` in JS, f"{x}" in Python, fmt.Sprintf("%s", x) in Go.
+ *     To a database or a shell it is identical to concatenation. Feeling
+ *     modern does not make it safe.
+ *
+ * PHASE 1 HONESTY NOTE: knowing a string was built dynamically does NOT mean
+ * the parts came from an attacker. `"SELECT * FROM " + TABLE_NAME` with a
+ * hard-coded constant is fine. We cannot tell the difference without data-flow
+ * analysis, which is Phase 3. That is exactly why these findings are labelled
+ * signature-based, and why every one of them says so in its `limitations`.
+ */
+import { SWITCH_NODES, createFolder } from '../../taint/fold.js';
+import { declaredImmutable, enclosingMethod, resolveContainerRead } from '../../taint/local-map.js';
+import { boundElsewhere, enclosingClassLikes, hasModifier, isClassLike, supertypesOf, usedOnlyAsQualifier, } from '../../taint/java-scope.js';
+import { declarationVisibility, hidesCodeFromParser } from '../../taint/visibility.js';
+/** Node types that ARE a string literal, per language. */
+const STRING_LITERAL_TYPES = {
+    javascript: ['string', 'template_string'],
+    typescript: ['string', 'template_string'],
+    python: ['string', 'concatenated_string'],
+    java: ['string_literal', 'text_block'],
+    go: ['interpreted_string_literal', 'raw_string_literal'],
+    // C has one string node type and no interpolation at all, which is why every
+    // dangerous C string is BUILT - by sprintf, strcat or std::string's operator+
+    // - rather than interpolated in place. `concatenated_string` is adjacent
+    // literals ("a" "b"), which C joins at compile time.
+    c: ['string_literal', 'concatenated_string', 'char_literal'],
+    cpp: ['string_literal', 'concatenated_string', 'char_literal', 'raw_string_literal'],
+    // PHP's `string` is single-quoted (never interpolates). `encapsed_string` is
+    // double-quoted and CAN interpolate, which is why it appears in both this
+    // list and INTERPOLATION_TYPES - isStringLiteral checks for a spliced-in
+    // value before calling it a literal.
+    php: ['string', 'encapsed_string', 'heredoc'],
+};
+/** Node types that mean "a value was spliced into this string". */
+const INTERPOLATION_TYPES = new Set([
+    'template_substitution', // JS/TS  `... ${x} ...`
+    'interpolation', // Python f"...{x}..."
+    // PHP splices a variable straight into a double-quoted string with no wrapper
+    // node: "id = $id" holds a `variable_name` child directly. The name exists
+    // only in the PHP grammar, so listing it here cannot affect another language.
+    'variable_name', // PHP  "... $x ..." and "... {$x} ..."
+]);
+/** Node types holding the plain-text chunks inside a string literal. */
+const STRING_CONTENT_TYPES = new Set([
+    'string_fragment',
+    'string_content',
+    'interpreted_string_literal_content',
+    'raw_string_literal_content',
+]);
+/** Function names that build a string from a template plus values. */
+const FORMAT_FUNCTIONS = new Set([
+    'format', // Python "..."​.format(), Java String.format
+    'sprintf',
+    'Sprintf', // Go fmt.Sprintf
+    'Sprintln',
+    'Fprintf',
+    'printf',
+    'Printf',
+    'join', // "".join([...]) and String.join
+    'concat',
+    'append', // Java StringBuilder.append chains
+    'valueOf',
+]);
+/**
+ * Node types that can be the TOP of a string-building expression.
+ *
+ * This gate exists because of a false positive found by pointing the scanner at
+ * its own source code. `analyzeStringExpression` walks a whole subtree and
+ * concatenates every string literal it finds. Handed an object literal like
+ *
+ *     export const sqlInjectionRule: Rule = {
+ *       name: 'SQL query assembled from a built string',
+ *       explanation: '... the query and the values ... update ... table ...',
+ *       ...
+ *     };
+ *
+ * it happily merged prose from a dozen unrelated fields into one blob, and
+ * `looksLikeSql()` found "select", "from" and "where" scattered through it.
+ * The scanner reported its own rule definitions as SQL injection.
+ *
+ * The lesson generalises: an analysis is only as good as the SCOPE it runs on.
+ * Before asking "does this text look like SQL?", make sure the thing you are
+ * looking at is a single string expression - not a container full of unrelated
+ * strings that happen to sit next to each other.
+ */
+const STRING_EXPRESSION_TYPES = {
+    javascript: ['string', 'template_string', 'binary_expression', 'call_expression'],
+    typescript: ['string', 'template_string', 'binary_expression', 'call_expression'],
+    python: ['string', 'concatenated_string', 'binary_operator', 'call'],
+    java: ['string_literal', 'text_block', 'binary_expression', 'method_invocation'],
+    go: [
+        'interpreted_string_literal',
+        'raw_string_literal',
+        'binary_expression',
+        'call_expression',
+    ],
+    php: [
+        'string',
+        'encapsed_string',
+        'heredoc',
+        'binary_expression', // PHP concatenates with `.`
+        'function_call_expression',
+        'member_call_expression',
+    ],
+    // In C a "string expression" is nearly always a CALL - sprintf or strcat -
+    // rather than an operator, because char arrays do not concatenate with `+`.
+    c: ['string_literal', 'concatenated_string', 'binary_expression', 'call_expression'],
+    // C++ gets the operator back via std::string, so binary_expression matters
+    // here in a way it does not in C.
+    cpp: [
+        'string_literal',
+        'concatenated_string',
+        'raw_string_literal',
+        'binary_expression',
+        'call_expression',
+    ],
+};
+/**
+ * True when this node could plausibly evaluate to a string that was assembled.
+ * Object literals, arrays, functions and class bodies return false - they are
+ * containers, not strings, even though they contain strings.
+ */
+export function isStringBuildingExpression(node, language) {
+    return STRING_EXPRESSION_TYPES[language].includes(node.type);
+}
+export function isStringLiteral(node, language) {
+    const types = STRING_LITERAL_TYPES[language];
+    if (!types.includes(node.type))
+        return false;
+    // An f-string or template literal WITH a substitution is not a literal.
+    return !containsType(node, INTERPOLATION_TYPES, 6);
+}
+function containsType(node, types, maxDepth) {
+    if (maxDepth <= 0)
+        return false;
+    for (const child of node.namedChildren) {
+        if (!child)
+            continue;
+        if (types.has(child.type))
+            return true;
+        if (containsType(child, types, maxDepth - 1))
+            return true;
+    }
+    return false;
+}
+/** Remove surrounding quotes, backticks and prefixes (f"", b'', @"", `` ). */
+export function unquote(raw) {
+    return raw
+        .replace(/^[a-zA-Z]{0,2}(["'`])((?:.|\n)*)\1$/, '$2')
+        .replace(/^"""|"""$/g, '')
+        .replace(/^'''|'''$/g, '');
+}
+/**
+ * Read an expression and describe how its text was assembled.
+ *
+ * The walk is deliberately shallow (depth-limited) and deliberately simple: it
+ * collects three things - fixed text chunks, evidence of splicing, and the
+ * spliced expressions - and infers the mechanism from what it found. It does
+ * NOT try to evaluate the expression. A scanner that guesses at runtime values
+ * is a scanner that lies.
+ */
+export function analyzeStringExpression(node, language, maxDepth = 10) {
+    const literalChunks = [];
+    const dynamicParts = [];
+    let sawInterpolation = false;
+    let sawConcatenation = false;
+    let sawFormatCall = false;
+    let sawOpaqueRef = false;
+    const visit = (current, depth) => {
+        if (depth > maxDepth)
+            return;
+        // A string literal: harvest its fixed text and stop (unless it interpolates).
+        if (STRING_LITERAL_TYPES[language].includes(current.type)) {
+            const contents = current.namedChildren.filter((c) => c !== null && STRING_CONTENT_TYPES.has(c.type));
+            if (contents.length > 0) {
+                for (const chunk of contents)
+                    literalChunks.push(chunk.text ?? '');
+            }
+            else if (!containsType(current, INTERPOLATION_TYPES, 4)) {
+                literalChunks.push(unquote(current.text ?? ''));
+            }
+            // Still descend, because a template string can hold substitutions.
+            for (const child of current.namedChildren) {
+                if (child && INTERPOLATION_TYPES.has(child.type))
+                    visit(child, depth + 1);
+            }
+            return;
+        }
+        if (INTERPOLATION_TYPES.has(current.type)) {
+            sawInterpolation = true;
+            const inner = (current.text ?? '').replace(/^\$?\{|\}$/g, '').trim();
+            if (inner)
+                dynamicParts.push(inner);
+            return;
+        }
+        // Concatenation. JS/Java/Go call it binary_expression, Python binary_operator.
+        if (current.type === 'binary_expression' || current.type === 'binary_operator') {
+            const operator = current.childForFieldName('operator')?.text ?? '';
+            if (operator === '+' || operator === '%') {
+                sawConcatenation = true;
+                for (const child of current.namedChildren)
+                    if (child)
+                        visit(child, depth + 1);
+                return;
+            }
+        }
+        // A call: is it a formatter, or just an opaque value?
+        if (current.type === 'call' ||
+            current.type === 'call_expression' ||
+            current.type === 'method_invocation' ||
+            /*
+             * PHP'S CALL NODES WERE MISSING, AND THAT COST 2,547 FINDINGS.
+             *
+             * Without these three types the walker fell through to "recurse into
+             * every child" and descended INSIDE the call, so
+             *
+             *     echo esc_html( $user->user_login );
+             *
+             * was described as "interpolation splicing in `$user`". The escaper was
+             * walked straight past and its argument reported as if it had been
+             * concatenated in raw - which is both a wrong description and the reason
+             * every WordPress escaping call looked like an unescaped one.
+             *
+             * A call is opaque: its RESULT is what gets spliced, and the arguments
+             * are not that result. Naming the node types makes PHP behave like the
+             * other five languages, which had them all along.
+             */
+            current.type === 'function_call_expression' ||
+            current.type === 'member_call_expression' ||
+            current.type === 'scoped_call_expression') {
+            const nameNode = current.childForFieldName('name') ??
+                current.childForFieldName('function') ??
+                current.childForFieldName('constructor');
+            const nameText = nameNode?.text ?? '';
+            const lastSegment = nameText.split(/[.:]/).pop() ?? nameText;
+            if (FORMAT_FUNCTIONS.has(lastSegment)) {
+                sawFormatCall = true;
+                /*
+                 * SKIP THE FUNCTION'S OWN NAME.
+                 *
+                 * `fmt.Sprintf` is a selector_expression, so recursing into every child
+                 * walked into the callee and recorded it as a spliced-in value. Every
+                 * format-call finding therefore opened with "It splices in
+                 * `fmt.Sprintf`, ..." - a sentence about the mechanism presented as a
+                 * sentence about the data, and simply untrue.
+                 *
+                 * It also broke a real proof: a Go escape hatch whose arguments were
+                 * ALL escaped still had `fmt.Sprintf` sitting in its parts list, so
+                 * "is every part escaped?" answered no about the function's own name.
+                 */
+                // Compared by POSITION, not identity: web-tree-sitter hands back a new
+                // wrapper object on every access, so `child !== nameNode` is always true.
+                for (const child of current.namedChildren) {
+                    if (!child)
+                        continue;
+                    if (nameNode && child.startIndex === nameNode.startIndex && child.endIndex === nameNode.endIndex) {
+                        continue;
+                    }
+                    visit(child, depth + 1);
+                }
+                /*
+                 * BUT NOT THE THING IT IS CALLED ON. In JavaScript and Python the
+                 * callee is `dir.concat` or `template.format` as one node, so skipping
+                 * "the function's name" skipped `dir` and `template` with it - and they
+                 * are the very strings being built on (tests/probes/s09b, p01). Their
+                 * receiver is visited like any other part. Go's receiver here is a
+                 * package (`fmt`), and Java's call keeps its receiver in a field of its
+                 * own, which the loop above already visited.
+                 */
+                if (nameNode && (nameNode.type === 'member_expression' || nameNode.type === 'attribute')) {
+                    const receiver = nameNode.childForFieldName('object');
+                    if (receiver)
+                        visit(receiver, depth + 1);
+                }
+                return;
+            }
+            sawOpaqueRef = true;
+            dynamicParts.push((current.text ?? '').replace(/\s+/g, ' ').trim().slice(0, 60));
+            return;
+        }
+        /*
+         * VALUES THAT ARE NOT WHAT THEY SPELL. `(yield prompt)` is whatever the
+         * caller sends back in, not `prompt` (tests/probes/s08). And `"ls " + obj`
+         * in Java or JavaScript calls obj's toString(), which can return anything:
+         * `new Arg(name)` is not `name` (j08), and `this` is not nothing (j14).
+         * Each is one opaque part - never descended into.
+         */
+        if (current.type === 'yield_expression' ||
+            current.type === 'yield' ||
+            ((language === 'java' || language === 'javascript' || language === 'typescript') && current.type === 'this') ||
+            (language === 'java' && current.type === 'object_creation_expression') ||
+            ((language === 'javascript' || language === 'typescript') && current.type === 'new_expression')) {
+            sawOpaqueRef = true;
+            dynamicParts.push((current.text ?? '').replace(/\s+/g, ' ').trim().slice(0, 60));
+            return;
+        }
+        if (current.type === 'identifier' ||
+            current.type === 'member_expression' ||
+            current.type === 'attribute' ||
+            current.type === 'selector_expression' ||
+            current.type === 'field_access' ||
+            current.type === 'subscript' ||
+            current.type === 'subscript_expression' ||
+            current.type === 'index_expression') {
+            sawOpaqueRef = true;
+            dynamicParts.push((current.text ?? '').replace(/\s+/g, ' ').trim().slice(0, 60));
+            return;
+        }
+        for (const child of current.namedChildren)
+            if (child)
+                visit(child, depth + 1);
+    };
+    visit(node, 0);
+    const literalText = literalChunks.join('');
+    let mechanism = 'literal';
+    if (sawInterpolation)
+        mechanism = 'interpolation';
+    else if (sawConcatenation && dynamicParts.length > 0)
+        mechanism = 'concatenation';
+    else if (sawFormatCall)
+        mechanism = 'format-call';
+    else if (sawOpaqueRef && literalChunks.length === 0)
+        mechanism = 'opaque';
+    else if (sawOpaqueRef)
+        mechanism = 'concatenation';
+    return {
+        isDynamic: mechanism !== 'literal',
+        mechanism,
+        literalText,
+        dynamicParts,
+    };
+}
+/* ---------------------------------------------------------------------------
+ * "Does this text look like X?" helpers.
+ *
+ * These are intentionally conservative. Their job is to stop the scanner
+ * shouting about `"Hello " + name`, which is not a SQL query and never was.
+ * ------------------------------------------------------------------------ */
+/* ---------------------------------------------------------------------------
+ * DOES THIS TEXT LOOK LIKE SQL?
+ *
+ * The first version of this asked three independent questions of the text:
+ * is there a SQL verb ANYWHERE, a clause keyword ANYWHERE, and a general SQL
+ * keyword ANYWHERE. Three yesses meant "this is a query".
+ *
+ * Pointing the scanner at its own source found the flaw. This paragraph -
+ * the honesty disclaimer printed under every flow-verified finding - is built
+ * from eight string chunks joined with `+`. `analyzeStringExpression` merges
+ * them into one 638-character blob, and the blob contains:
+ *
+ *     verb   "call"  from ... a CALL into a third-party package ...
+ *     clause "into"  from ... a call INTO a third-party package ...
+ *     clause "where" from ... - WHERE imports resolve - ...
+ *
+ * Three matches, drawn from two unrelated sentences, and the scanner reported
+ * its own disclaimer as a SQL injection. Proximity alone would not have saved
+ * it either: `call ... into` are adjacent words.
+ *
+ * The fix is to stop asking "are these words present?" and start asking
+ * "is this the SHAPE of a statement?". Real SQL is not a bag of keywords, it
+ * is a grammar: SELECT is followed by FROM, INSERT is followed by INTO,
+ * UPDATE is followed by SET. English prose containing the same words almost
+ * never puts them in that order, in that span, without a full stop between.
+ *
+ * This is the same lesson as the STRING_EXPRESSION_TYPES gate above, one level
+ * down: there the scope was wrong, here the test was too weak for the scope.
+ * ------------------------------------------------------------------------ */
+/**
+ * The canonical statement shapes. Each one pairs a verb with the clause the
+ * SQL grammar REQUIRES to follow it, within a bounded window - so the two
+ * halves have to belong to the same statement, not the same paragraph.
+ */
+const SQL_STATEMENT_SHAPES = [
+    /\bselect\b[\s\S]{0,300}?\bfrom\b/i,
+    /\binsert\s+(?:ignore\s+|or\s+\w+\s+)?into\b/i,
+    /\bupdate\b[\s\S]{0,200}?\bset\b/i,
+    /\bdelete\s+from\b/i,
+    /\bmerge\s+into\b/i,
+    /\breplace\s+into\b/i,
+    /\bunion(?:\s+all)?\s+select\b/i,
+    /\bwith\b[\s\S]{0,200}?\bas\s*\(/i, // common table expression
+    /\bcall\s+[\w.]+\s*\(/i, // stored procedure
+    /\bexec(?:ute)?\s+(?:sp_|dbo\.|[\w.]+\s*[('@])/i,
+    /\b(?:drop|alter|create|truncate)\s+(?:table|index|view|database|schema)\b/i,
+    // Query FRAGMENTS: a lot of real injection is ` WHERE id = ` + x, appended
+    // to a query built elsewhere. A clause keyword sitting at the very start of
+    // the fragment is the tell, and prose does not open that way.
+    /^\s*(?:where|from|order\s+by|group\s+by|having|limit|offset)\b/i,
+    /*
+     * VALUES AND AND ARE ALSO ENGLISH, so these two need the rest of the clause.
+     *
+     * An f-string's literal parts ARE fragments in the sense above - the text
+     * between two interpolations is exactly a string appended to something else -
+     * which is why the fragment rule reads them. Scanning pandas turned up four
+     * assertion messages that way:
+     *
+     *     f"{obj} values are different ({pct} %)"     -> " values are different ("
+     *     f"{a} and {b} were approximately equal"     -> " and "
+     *
+     * Both open with a clause keyword and neither continues into anything a
+     * database could parse. SQL's VALUES is always followed by a parenthesis, and
+     * a WHERE clause continued by AND or OR always reaches a comparison. Asking
+     * for the second half of the clause keeps ` AND id = ` and ` VALUES (` - the
+     * shapes the rule was written for - and drops the English.
+     */
+    /^\s*values\s*\(/i,
+    /^\s*(?:and|or)\b[\s\S]{0,80}?(?:[=<>]|\b(?:like|ilike|in|is|between)\b)/i,
+];
+/**
+ * A full stop followed by a capital letter, or a comma followed by a
+ * conjunction, means the window crossed a sentence boundary - so the verb and
+ * the clause came from different thoughts, not from one statement.
+ * SQL has no sentences; prose has little else.
+ */
+const SENTENCE_BREAK = /[.!?]\s+[A-Z(]|[,;:]\s+(?:and|or|but|so|which|because|then)\b/;
+/**
+ * SQL needs the SHAPE of a statement, not a scattering of keywords.
+ * Conservative on purpose: a fragment we cannot recognise is reported as
+ * "not SQL", which loses a finding rather than inventing one.
+ */
+export function looksLikeSql(text) {
+    if (text.length < 8)
+        return false;
+    for (const shape of SQL_STATEMENT_SHAPES) {
+        const match = shape.exec(text);
+        if (!match)
+            continue;
+        if (SENTENCE_BREAK.test(match[0]))
+            continue;
+        return true;
+    }
+    return false;
+}
+export function looksLikeHtml(text) {
+    return /<\s*[a-zA-Z][a-zA-Z0-9-]*(\s|>|\/)/.test(text) || /&(lt|gt|amp|quot);/.test(text);
+}
+/**
+ * Shannon entropy: a number for "how random does this look?".
+ * Roughly - English prose scores ~2.5-3.5 bits/char, a base64 API key ~4.5-6.
+ * It is a hint, never a verdict, and we say so in the finding.
+ */
+export function shannonEntropy(text) {
+    if (text.length === 0)
+        return 0;
+    const counts = new Map();
+    for (const char of text)
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const p = count / text.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+/** Strings that are obviously not real credentials. Keeps the noise down. */
+const PLACEHOLDER_PATTERNS = [
+    /^$/,
+    /^(x{3,}|\*{3,}|\.{3,}|-{3,}|_{3,})$/i,
+    /^(none|null|nil|undefined|true|false|test|todo|fixme|example|sample|dummy|placeholder|changeme|change_me|your[-_ ]?\w*|my[-_ ]?\w*|insert[-_ ]?\w*|redacted|secret|password|passwd|pwd|key|token|value|string|foo|bar|baz|abc123?|123456?)$/i,
+    /^\$\{?[\w.]+\}?$/, // ${ENV_VAR} or $VAR - a reference, not a value
+    /^%[\ws]$/, // printf placeholder
+    /^\{\{?[\w.]+\}?\}$/, // {{ template }}
+    /^<[^>]+>$/, // <your-key-here>
+    /^(process\.env|os\.environ|System\.getenv|os\.Getenv)/,
+    // Values that announce themselves as not-real anywhere inside the string.
+    // Added after scanning real repositories, where `'faketoken'`, `'Bearer ...'`
+    // and `'s00pers3cret'`-style fixtures dominated the results.
+    /(fake|dummy|sample|example|placeholder|redacted|changeme|notreal|xxxx|\.\.\.)/i,
+    /*
+     * THE VALUE NAMES THE KIND OF CREDENTIAL IT IS STANDING IN FOR.
+     *
+     *     accessToken:  'exact-token'      'wrong-token'   'notion-token'
+     *     clientSecret: 'notion-client-secret'
+     *     apiKey:       'new-api-key'      connectionToken: 'test-token'
+     *
+     * Ninety-six of the 191 hardcoded-secret findings on a VS Code scan were this
+     * shape, all from test files. A real credential does not contain the word
+     * "secret" - the whole point of one is that it carries no information about
+     * itself. A lowercase hyphenated phrase with `token`, `secret` or `key` as one
+     * of its words is a label a person wrote so a failing assertion would be
+     * readable.
+     *
+     * DELIBERATELY NARROW. An earlier attempt rejected short lowercase words
+     * outright and had to be reverted: it took `password = 'configpass'` and
+     * `SECRET_KEY = 'config'` with it, and those are weak credentials but they
+     * are credentials. Neither has a separator or names itself, so neither
+     * matches this. A passphrase like `correct-horse-battery-staple` does not
+     * match either - it has the separators but names nothing.
+     */
+    /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*[-_](token|secret|key|password|passwd|pwd|auth|credential|creds?|apikey|pat|jwt|salt|nonce|otp)$/i,
+    /^(token|secret|key|password|passwd|pwd|auth|credential|creds?|apikey|pat|jwt|salt|nonce|otp)[-_][a-z0-9]+(?:[-_][a-z0-9]+)*$/i,
+];
+/*
+ * Values that are SETTINGS, not secrets.
+ *
+ * `credentials` matches the credential naming pattern, so this line
+ *
+ *     fetch(url, { credentials: "same-origin" })
+ *
+ * read as a hardcoded credential - twice, inside the vendored tree-sitter
+ * runtime, on a self-scan. It is a fixed enum from the fetch specification and
+ * there is no possible value of it that is a secret.
+ *
+ * The whole set is listed rather than just the three `credentials` values,
+ * because the neighbouring RequestInit fields (`mode`, `cache`, `redirect`)
+ * are one rename away from the same problem. These are exact, whole-string
+ * matches against a closed vocabulary defined by the web platform - not a
+ * guess about what looks secret-ish.
+ */
+const WEB_PLATFORM_ENUMS = new Set([
+    // RequestInit.credentials
+    'same-origin',
+    'include',
+    'omit',
+    // RequestInit.mode
+    'cors',
+    'no-cors',
+    'navigate',
+    // RequestInit.cache
+    'default',
+    'no-store',
+    'reload',
+    'no-cache',
+    'force-cache',
+    'only-if-cached',
+    // RequestInit.redirect
+    'follow',
+    'manual',
+    'error',
+]);
+/**
+ * Is this value STRUCTURALLY incapable of being a credential, whatever the
+ * variable holding it is called?
+ *
+ * The name-based signal ("the variable is called `token`") never asked this,
+ * and VS Code's editor package showed why: 151 of its 163 high-severity secret
+ * findings were Monaco's syntax-highlighting tokens.
+ *
+ *     token: 'delimiter.curly'
+ *     token: 'variable.predefined'
+ *     token: 'comment'
+ *
+ * The variable really is called `token`. The value is a theme scope name. No
+ * amount of suspicion about the NAME should survive looking at the VALUE.
+ *
+ * Two shapes, both decidable:
+ *   - a dotted namespace (`delimiter.curly`, `com.example.thing`) - no key
+ *     format contains dots, except a JWT, which starts `eyJ`;
+ *   - a single lowercase dictionary-shaped word (`comment`, `invalid`) - real
+ *     credentials mix character classes, because they are generated.
+ */
+export function isStructuralIdentifier(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return false;
+    // The trailing dot is not a typo. A dotted name used as a STORAGE PREFIX is
+    // written with the separator still attached, because the caller appends to it:
+    //     SECRET_KEY_PREFIX = 'chat.lm.secret.'
+    //     STORAGE_PREFIX    = 'chat.modelFeedbackSurvey.'
+    // Both were reported as credentials on a VS Code scan, the first at HIGH
+    // because its name contains SECRET and KEY. It is a namespace, and the value
+    // in it is whatever gets appended - which is not in the file.
+    if (/^[\w$-]+(?:\.[\w$-]+)+\.?$/.test(trimmed) && !/^eyJ/.test(trimmed))
+        return true;
+    /*
+     * A value carrying a URI SCHEME is an address or a standard identifier, not
+     * a key. VS Code's OAuth constants are the clean example:
+     *
+     *     TOKEN_TYPE_ACCESS_TOKEN = 'urn:ietf:params:oauth:token-type:access_token'
+     *     token_endpoint = 'http://localhost:8080/token'
+     *
+     * Every one of those variable names screams credential, and every value is
+     * published in an RFC. The name cannot be trusted over the shape.
+     */
+    if (/^(urn|https?|ftp|file|ws{1,2}|mailto|data|vscode[\w-]*):/i.test(trimmed))
+        return true;
+    /*
+     * A COLON-NAMESPACED PERMISSION IS A SCOPE, NOT A CREDENTIAL.
+     *
+     *     AccessTokenScopeReadAdmin AccessTokenScope = "read:admin"
+     *     AccessTokenScopeWriteRepoHook              = "write:repo_hook"
+     *
+     * 106 of gitea's 359 findings were high-severity "hardcoded secret" and this
+     * block is most of them. The constant NAME contains "Token", which is exactly
+     * what the name signal is for - but the value is an OAuth scope printed in
+     * gitea's own public API documentation.
+     *
+     * LETTERS ONLY, deliberately. `admin:password123` keeps its digits and still
+     * reports, and so does anything with mixed case; generated credentials
+     * essentially always carry one or the other. What is left - a lowercase
+     * colon-namespaced phrase - is how every permission system in the world
+     * spells a scope. A bare `user:pass` is lost to this, which is a placeholder
+     * anyway, and a real one inside a URL is caught earlier by the
+     * connection-string format.
+     */
+    if (/^[a-z]+(?:[_-][a-z]+)*(?::[a-z]+(?:[_-][a-z]+)*)+$/.test(trimmed))
+        return true;
+    /*
+     * A Subresource Integrity hash is published in the HTML that loads the
+     * script. It is the opposite of a secret - its whole job is to be public so
+     * a browser can check the file was not tampered with.
+     *
+     *     webWorkerExtensionHostIframeScriptSHA = 'sha256-daEgfo2VIXpx2Np71Kq...'
+     */
+    if (/^sha(256|384|512)-/.test(trimmed))
+        return true;
+    /*
+     * A SCREAMING_SNAKE value is a constant or an environment VARIABLE NAME, not
+     * its value. VS Code names the variable after what it holds and gets caught
+     * by both halves:
+     *
+     *     agentHostBridgeConnectionTokenEnvironmentVariable =
+     *       'VSCODE_AGENT_HOST_BRIDGE_CONNECTION_TOKEN'
+     */
+    if (/^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(trimmed))
+        return true;
+    /*
+     * A single lowercase word is NOT on this list, and the first version of it
+     * was. `token: 'comment'` and `token: 'invalid'` in Monaco are exactly that
+     * shape - but so are
+     *
+     *     password: 'configpass'
+     *     password: 'exfil'
+     *     SECRET_KEY = 'config'
+     *
+     * and rejecting the shape took the library corpus from 48 findings to 32.
+     * Weak human-chosen passwords ARE lowercase words; that is what makes them
+     * weak. Trading sixteen real hardcoded credentials for a dozen theme scope
+     * names is the wrong direction, so the dotted check stands alone and the
+     * remaining Monaco tokens are accepted noise.
+     */
+    return false;
+}
+/**
+ * Does this spliced-in expression produce nothing but SQL PLACEHOLDERS?
+ *
+ * VS Code builds a bulk insert the correct way:
+ *
+ *     `INSERT INTO ItemTable VALUES ${new Array(n).fill('(?,?)').join(',')} ...`
+ *     stmt.run(keysValuesChunk)
+ *
+ * The interpolation expands to `(?,?),(?,?),(?,?)`. Not one byte of data is in
+ * that string - the values go to the driver separately, which is exactly what
+ * parameterisation means. And the rule reported it as SQL injection.
+ *
+ * That is the worst mistake an injection rule can make. Flagging the CORRECT
+ * form teaches people that doing it properly does not help, and this is the
+ * third time today the same failure has turned up in a different rule -
+ * unserialize with allowed_classes, yaml with a SafeLoader, and now this.
+ *
+ * The test is narrow on purpose. Every string literal inside the expression
+ * must be placeholder punctuation, AND at least one must contain an actual
+ * placeholder marker (`?`, `$1`, `%s`). That second half is what stops
+ * `rows.map(r => `'${r}'`).join(',')` - which builds real quoted DATA and is a
+ * genuine injection - from slipping through on its commas.
+ */
+export function expandsOnlyPlaceholders(expressionText) {
+    const literals = [...expressionText.matchAll(/(['"`])((?:\\.|(?!\1)[^\\])*)\1/g)].map((m) => m[2] ?? '');
+    if (literals.length === 0)
+        return false;
+    const hasMarker = literals.some((lit) => /\?|\$\d|%s/.test(lit));
+    if (!hasMarker)
+        return false;
+    return literals.every((lit) => /^[\s?,()$%sd\d]*$/.test(lit));
+}
+export function isLikelyPlaceholder(text) {
+    const trimmed = text.trim();
+    if (WEB_PLATFORM_ENUMS.has(trimmed.toLowerCase()))
+        return true;
+    return PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+/**
+ * "Could this string plausibly BE a credential?" - a structural gate we apply
+ * before the entropy heuristic.
+ *
+ * This function exists because of measurement, not theory. Running the entropy
+ * check alone against five real open-source repositories produced 80 findings,
+ * and the top offenders were things like:
+ *
+ *     'application/x-www-form-urlencoded'   a MIME type
+ *     'abcdefghijklmnopqrstuvwxyz'          a literal alphabet
+ *     'https://images.opencollective.com/…' a URL
+ *
+ * All three score high on randomness and none of them is a secret. Real tokens
+ * share a shape: no spaces, no slashes, and a MIX of character classes. Testing
+ * for that shape first removes the whole category of noise above without
+ * weakening detection of anything that actually looks like a key.
+ */
+export function looksLikeToken(value) {
+    if (/[\s/\\@]/.test(value))
+        return false; // URLs, paths, MIME types, sentences
+    /*
+     * STRUCTURAL PUNCTUATION IS NOT IN ANY CREDENTIAL ALPHABET.
+     *
+     * Every real key format draws from a narrow set of characters: base64 uses
+     * A-Za-z0-9+/=, hex uses 0-9a-f, and vendor keys (AKIA..., ghp_..., sk_live_)
+     * use A-Za-z0-9_-. None of them contains a brace, a bracket, a quote, a
+     * colon or a semicolon.
+     *
+     * Auditing this tool's findings across five real libraries found NINE
+     * entropy-only false positives and every one was killed by this single line:
+     *
+     *     json = "{field1:'abc',field2:'def'}"        a JSON test fixture
+     *     systemProperty = "gson.allowCapturing..."   a property name
+     *     dataURI = "data:;charset=UTF-8,hello"       a data URI
+     *
+     * Entropy alone cannot tell a key from a small structured document - both
+     * score above 4 bits per character. Shape can, and shape is not a guess.
+     */
+    if (/[{}[\]<>(),;:'"`|!?*&^%$#~]/.test(value))
+        return false;
+    if (/^[a-z.\-_]+$/.test(value))
+        return false; // lowercase words / kebab / dotted names
+    if (/^[A-Z.\-_]+$/.test(value))
+        return false; // SCREAMING_CONSTANT names
+    if (/^\d+$/.test(value))
+        return false; // pure numbers, timestamps, ids
+    /*
+     * NAMESPACED IDENTIFIERS ARE NOT KEYS.
+     *
+     *     workbench.action.focusCommentsPanel
+     *     workbench.contrib.viewsExtensionHandler
+     *     editor.action.formatDocument
+     *
+     * Scanning VS Code produced 1,369 hardcoded-secret findings and 1,246 were
+     * entropy-only hits on strings exactly like these - command ids, context
+     * keys, extension ids. They score above 4 bits per character because they mix
+     * case and use many distinct letters, which is precisely what the entropy
+     * heuristic was built to notice, and precisely why entropy alone is not
+     * evidence of anything.
+     *
+     * A dotted name is the single most common long string in a large application,
+     * and no credential format is shaped like one. The exception is a JWT, which
+     * is also dot-separated - so a value that opens with the base64 of `{"` is
+     * kept. That is the standard JWT header prefix and nothing else starts that
+     * way by accident.
+     */
+    if (/^[\w$-]+(?:\.[\w$-]+)+$/.test(value) && !/^eyJ/.test(value))
+        return false;
+    // The alphabet itself, and any run of consecutive letters. `letterBytes =
+    // "abcdefghijklmnopqrstuvwxyzABCDEF..."` in gin scores 4.7 bits/char and is
+    // the least random string it is possible to write.
+    if (/abcdefghij/i.test(value))
+        return false;
+    /*
+     * A CAMELCASE RUN OF PURE LETTERS IS AN IDENTIFIER, NOT A KEY.
+     *
+     *     enablePreviewFromQuickOpen        a settings key
+     *     ChatToolsEligibleForAutoApproval  an experiment name
+     *     didNotEnableEditSessionsWhenPrompted   a telemetry outcome
+     *     historyItemChangeViewModel        a view-model type tag
+     *
+     * The dotted-name rule above catches `workbench.action.focus...`; these are
+     * the same thing with the dots removed, and they were the next 35 findings on
+     * a VS Code scan once the dotted ones were gone. They score above 4 bits per
+     * character for the same reason - many distinct letters, mixed case - which
+     * is again a fact about English identifiers rather than about randomness.
+     *
+     * The discriminator is what is ABSENT. Every generated credential draws on
+     * digits or punctuation somewhere: base64 has digits and +/=, hex is digits
+     * and a-f, vendor keys carry a prefix and an underscore. Twenty-nine letters
+     * and nothing else is a name a person typed.
+     *
+     * This gate is on the ENTROPY path only, which matters: `password =
+     * 'MySecretPassword'` has this exact shape and is a genuine bad credential,
+     * but it is caught by the variable NAME (Signal 2), which never consults this
+     * function. Weak alphabetic passwords therefore still report.
+     */
+    if (value.length >= 12 && /^[A-Za-z]+$/.test(value)) {
+        const humps = value.match(/[a-z][A-Z]/g)?.length ?? 0;
+        if (humps >= 2)
+            return false;
+    }
+    const classes = (/[a-z]/.test(value) ? 1 : 0) + (/[A-Z]/.test(value) ? 1 : 0) + (/[0-9]/.test(value) ? 1 : 0);
+    return classes >= 2;
+}
+/**
+ * Paths that mean "this is a fixture, not production configuration".
+ * A credential in a test file is still a credential in git history, so we do
+ * not drop these findings - we lower their severity and say why.
+ */
+export function isTestPath(filePath) {
+    return TEST_DIRECTORY.test(filePath) || TEST_FILENAME.test(filePath);
+}
+/*
+ * TEST-PATH CONVENTIONS ARE PER-ECOSYSTEM, and this list was built from the
+ * repositories I had happened to be shown.
+ *
+ * Scanning cal.com - 3,941 TypeScript files - produced 196 findings, 138 of
+ * them hardcoded-secret. The ones still ranked HIGH were led by
+ *
+ *     apps/web/playwright/payment-apps.e2e.ts   access_token: "sk_test_randomString"
+ *     packages/testing/src/lib/bookingScenario/bookingScenario.ts
+ *
+ * Both are unambiguously test code, and this function said neither was. The
+ * reasons were boring and specific: `e2e` was recognised only as a whole
+ * DIRECTORY segment, never as the `.e2e.ts` filename suffix that Playwright
+ * actually uses; and `tests?` matches `test` and `tests` but not `testing`.
+ *
+ * That is the third time this exact class has cost real precision. Scanning
+ * elasticsearch proved SOURCES are per-framework rather than per-language;
+ * scanning Jenkins proved ESCAPERS are too. The lesson generalises past both:
+ * ANY list of conventions in this engine is a list of the conventions I have
+ * been shown, and it looks complete right up until a codebase with different
+ * habits arrives.
+ *
+ * WHY THIS IS TWO NARROW PATTERNS AND NOT ONE WIDE ONE. Downranking is a
+ * silencing mechanism, so the failure mode is a real credential in application
+ * source ranked as test noise. `latest.ts`, `contest/`, `testimonials.tsx`,
+ * `protester.js` and `attestation/` all contain the letters "test". Every one
+ * of them is asserted as NOT a test path in the suite, which is what stops a
+ * future widening from quietly eating them.
+ */
+/** A whole path SEGMENT that names a test area. Anchored both sides. */
+const TEST_DIRECTORY = /(^|[/\\])(tests?|testing|spec|specs|__tests__|__mocks__|fixtures?|examples?|e2e|benchmarks?|mocks?|playwright|cypress|testdata)([/\\]|$)/i;
+/**
+ * A FILENAME that names itself a test. Kept separate from the directory rule
+ * because these are suffixes, not segments - `login.e2e.ts` has no `e2e`
+ * segment anywhere in it, which is exactly what cal.com exposed.
+ */
+const TEST_FILENAME = /\.(test|spec|e2e|cy|e2e-spec|int-spec)\.[a-z]+$|[._-]test\.[a-z]+$|Tests?\.(java|cs|kt|scala)$/i;
+/**
+ * Is this value just a restatement of the NAME it is stored under?
+ *
+ *     PRIVATE_KEY_KEY   = "privateKey"          Keycloak, 4,000 Java files
+ *     KEYSTORE_PASSWORD_KEY = "keystorePassword"
+ *     MANAGE_OAUTH      = "manage_oauth"        Mattermost, TypeScript
+ *     TOKEN_CREATING    = "creating"
+ *     SECTION_TOKENS    = "tokens"
+ *
+ * These are the strings a program uses to LOOK UP a secret in a config map, and
+ * they are dense in exactly the codebases that handle credentials for a living
+ * - which is why an identity server produced 152 findings and most were this.
+ *
+ * The test is a subset check on words, which is what makes it safe: a real
+ * credential shares no vocabulary with its own variable name. `password =
+ * "Tr0ub4dor3xK"`, `SECRET_KEY = "config"` and `password = "configpass"` all
+ * survive it, and all three are asserted elsewhere in the suite.
+ *
+ * Requires at least one word on each side, so an empty or punctuation-only
+ * value cannot vacuously qualify.
+ */
+export function echoesItsOwnName(name, value) {
+    const words = (text) => text
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[^A-Za-z0-9]+/)
+        .map((w) => w.toLowerCase())
+        .filter((w) => w.length > 1);
+    const nameWords = new Set(words(name));
+    const valueWords = words(value);
+    if (nameWords.size === 0 || valueWords.length === 0)
+        return false;
+    return valueWords.every((w) => nameWords.has(w));
+}
+/**
+ * Does this value read as an English SENTENCE rather than as a credential?
+ *
+ *     encryption_key_missing: "CALENDSO_ENCRYPTION_KEY is not set"
+ *
+ * From cal.com's OAuthService. The NAME matches the credential pattern - it
+ * contains `key` - and a name-based guess is allowed to be wrong. What it is
+ * not allowed to do is ignore a value that could not possibly be a credential.
+ *
+ * THE TRAP THIS IS SHAPED AROUND: passphrases contain spaces and are real
+ * secrets. `password = "correct horse battery staple"` must still report.
+ *
+ * THE FIRST VERSION OF THIS FUNCTION WAS NOT SAFE, and the corpus caught it -
+ * for the third time in this project's life, after the lowercase-word rejection
+ * that dropped the corpus 48 to 32 and the mathjs.eval regression that showed
+ * up only as dvna's flow count falling 3 to 2.
+ *
+ * Requiring "several words plus an English function word" looked airtight
+ * against a DICEWARE passphrase, whose wordlist is concrete nouns and verbs.
+ * It is not airtight against a HUMAN-CHOSEN one. Express ships
+ *
+ *     secret: 'manny is cool'        examples/cookie-sessions/index.js
+ *
+ * a genuine session secret, silenced by the word `is`. One good suppression
+ * (dvna's `'A2: Broken Authentication'` label) and one real miss.
+ *
+ * So the value's shape is no longer the whole test. The NAME has to say the
+ * slot holds a message - `encryption_key_missing`, `api_key_invalid` - which is
+ * what cal.com's error table actually looks like and what `secret` never does.
+ * Both halves are asserted: the express string is now a fixture that must fire.
+ */
+const PROSE_WORDS = new Set([
+    'is', 'are', 'was', 'were', 'be', 'been', 'not', 'no', 'the', 'a', 'an',
+    'this', 'that', 'these', 'those', 'your', 'you', 'must', 'should',
+    'cannot', 'could', 'would', 'please', 'try', 'again', 'invalid', 'missing',
+    'expired', 'required', 'failed', 'error', 'unable', 'least', 'provided',
+    'for', 'to', 'of', 'in', 'at', 'with', 'and', 'or', 'but', 'if', 'set',
+]);
+export function looksLikeProse(name, value) {
+    // The NAME has to say this slot holds a message. Prose-ness alone is not
+    // enough - see the express regression in the note above.
+    if (!MESSAGE_NAME.test(name))
+        return false;
+    const words = value.trim().split(/\s+/);
+    if (words.length < 3)
+        return false;
+    const lowered = words.map((w) => w.replace(/[^A-Za-z]/g, '').toLowerCase());
+    return lowered.some((w) => PROSE_WORDS.has(w));
+}
+/**
+ * Names that describe a STATE or a MESSAGE rather than a stored credential.
+ * `encryption_key_missing` is not a key; it is what you print when the key is
+ * absent. The word that matters is the suffix.
+ */
+const MESSAGE_NAME = /(_|\b)(missing|invalid|expired|required|failed|error|errors|message|messages|msg|description|hint|warning|notice|reason|too_short|too_long|not_found|unauthorized|denied)$/i;
+export const KNOWN_SECRET_FORMATS = [
+    { label: 'AWS access key id', pattern: /\b(AKIA|ASIA|ABIA|ACCA)[0-9A-Z]{16}\b/ },
+    { label: 'GitHub token', pattern: /\bgh[pousr]_[A-Za-z0-9]{16,}\b/ },
+    { label: 'Slack token', pattern: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/ },
+    { label: 'Stripe secret key', pattern: /\b(sk|rk)_(live|test)_[A-Za-z0-9]{16,}\b/ },
+    { label: 'Google API key', pattern: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+    { label: 'OpenAI API key', pattern: /\bsk-[A-Za-z0-9]{20,}\b/ },
+    /*
+     * OpenAI's CURRENT key format, which the line above cannot match.
+     *
+     * The legacy shape was `sk-` followed by one unbroken run of alphanumerics.
+     * Project and service-account keys put named segments in between -
+     * `sk-proj-...`, `sk-svcacct-...` - and the hyphen ends the `[A-Za-z0-9]{20,}`
+     * run, so a live project key scored only "high-entropy literal, possible
+     * secret" at medium severity instead of being identified outright.
+     *
+     * Found by checking that a placeholder this rule had just started ignoring
+     * (`apiKey: 'sk-secret-internal-key'`) had not taken a real format with it.
+     * It had not - it had exposed one that was already missing. The named segment
+     * is required precisely so that the placeholder stays ignored: "secret" is
+     * not "proj".
+     */
+    { label: 'OpenAI project key', pattern: /\bsk-(proj|svcacct|admin)-[A-Za-z0-9_-]{20,}\b/ },
+    { label: 'JSON Web Token', pattern: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/ },
+    {
+        label: 'private key block',
+        /*
+         * The delimiter has to be followed by KEY MATERIAL. Keycloak defines
+         * `BEGIN_PRIVATE_KEY = "-----BEGIN PRIVATE KEY-----"` as a constant so it
+         * can assemble and parse PEM files; the string IS the delimiter and there
+         * is no key in it. Requiring base64 after the header keeps every real
+         * embedded key and drops the label on its own.
+         */
+        pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?[A-Za-z0-9+/]{40}/,
+    },
+    { label: 'Twilio account SID', pattern: /\bAC[0-9a-fA-F]{32}\b/ },
+    { label: 'SendGrid API key', pattern: /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b/ },
+    { label: 'connection string with password', pattern: /:\/\/[^\s:@/]+:[^\s:@/]{3,}@/ },
+];
+/* ---------------------------------------------------------------------------
+ * VENDOR DOCUMENTATION EXAMPLES
+ *
+ * `AKIAIOSFODNN7EXAMPLE` is not an AWS access key. It is the string AWS
+ * itself prints in its own documentation, chosen so that it matches the key
+ * FORMAT while being guaranteed never to authenticate anything. It appears in
+ * README files, tutorials and UI demos everywhere, and the scanner found one
+ * in this project's own demo panel and called it a hardcoded credential.
+ *
+ * That finding was not merely noisy, it was FALSE: nothing was hardcoded and
+ * nothing needs rotating. So this is not a severity downgrade like the
+ * test-path rule - the claim itself does not hold, and the finding is dropped.
+ *
+ * The allowlist is deliberately narrow. Vendors mark their examples by ending
+ * them in EXAMPLE (AWS's convention, used consistently across its docs) or by
+ * filling the random portion with an obvious run of digits. A real key landing
+ * on one of these by chance is a 1-in-10^12 event; a real key that a developer
+ * has deliberately named EXAMPLE is not a case this tool can help with.
+ *
+ * Anything dropped here is listed in the rule's `limitations` text, so the gap
+ * is documented rather than silent.
+ * ------------------------------------------------------------------------ */
+const VENDOR_DOC_EXAMPLES = [
+    /EXAMPLE(KEY|SECRET)?$/, // AWS: AKIAIOSFODNN7EXAMPLE, ...bPxRfiCYEXAMPLEKEY
+    /\b(AKIA|ASIA|ABIA|ACCA)(?:0{6,}|1234567890|X{6,})/i, // filler-digit stand-ins
+    /^(?:sk|rk|pk)_(?:live|test)_(?:example|1234567890|abcdef|0000)/i,
+    /\bAIza(?:SyExample|0{10,})/i,
+    /\bxox[abprs]-(?:example|0000|1234567890)/i,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----\s*(?:\.\.\.|EXAMPLE|YOUR)/i,
+];
+/**
+ * True when a value matches a vendor key format but is a published,
+ * deliberately non-functional documentation example rather than a credential.
+ *
+ * Pass the MATCHED KEY, not the string it was found in. The first version of
+ * this tested the whole enclosing string, so a demo code sample containing
+ * `AKIAIOSFODNN7EXAMPLE` in the middle of two hundred other characters never
+ * matched the `...EXAMPLE$` anchor and was still reported as a live key. The
+ * question is about the credential, so it has to be asked of the credential.
+ */
+export function isVendorDocExample(matchedKey) {
+    return VENDOR_DOC_EXAMPLES.some((pattern) => pattern.test(matchedKey));
+}
+export function matchKnownSecret(text) {
+    for (const format of KNOWN_SECRET_FORMATS) {
+        const match = format.pattern.exec(text);
+        if (!match)
+            continue;
+        if (isVendorDocExample(match[0]))
+            continue;
+        return format;
+    }
+    return null;
+}
+/* -------------------------------------------------------------------------- *
+ * PROVABLY-CONSTANT INTERPOLATION
+ *
+ * A tester handed the scanner this, expecting silence:
+ *
+ *     def get_admin_table():
+ *         table_name = "admin_users"          # hardcoded, no external input
+ *         query = f"SELECT * FROM {table_name}"
+ *         return conn.execute(query)
+ *
+ * It flagged the f-string. The label was correct - `signature-based`, data flow
+ * NOT traced - but the finding was still noise: the only spliced-in value is a
+ * string literal written on the line above. A scanner that reports that teaches
+ * people to skim past it, and this project's own test suite treats a false
+ * positive as a failure for exactly that reason.
+ *
+ * So: if EVERY spliced-in part is a plain name bound only to literal constants
+ * in the enclosing scope, the string is not dynamic in any sense a reader cares
+ * about, and the rule stays quiet.
+ *
+ * Deliberately conservative in three ways, because losing a real finding is a
+ * worse trade than printing a weak one:
+ *   - a part that is not a bare identifier (a call, an index, an attribute)
+ *     is never treated as constant;
+ *   - a name with NO visible binding - a parameter, an import, a global from
+ *     another file - is never treated as constant;
+ *   - a name bound more than once is constant only if EVERY binding is a
+ *     literal, so `t = "x"` followed later by `t = request.args.get(...)`
+ *     still flags.
+ * -------------------------------------------------------------------------- */
+/** Nodes that introduce a scope worth searching for bindings. */
+const SCOPE_NODES = new Set([
+    'function_declaration', 'function_expression', 'arrow_function', 'method_definition',
+    'generator_function_declaration', 'generator_function', 'class_static_block',
+    'function_definition', 'lambda',
+    'method_declaration', 'constructor_declaration',
+    'func_literal', 'program', 'module', 'source_file', 'compilation_unit',
+]);
+/** Nodes that bind a name to a value, and the fields that hold each side. */
+const BINDING_NODES = {
+    assignment: { name: 'left', value: 'right' }, // Python
+    assignment_expression: { name: 'left', value: 'right' }, // JS/TS/Java
+    variable_declarator: { name: 'name', value: 'value' }, // JS/TS/Java
+    short_var_declaration: { name: 'left', value: 'right' }, // Go
+    assignment_statement: { name: 'left', value: 'right' }, // Go
+};
+/** A literal with no spliced-in parts: a genuinely fixed value. */
+function isPlainLiteral(node, language) {
+    if (!node)
+        return false;
+    if (node.type === 'number' || node.type === 'integer' || node.type === 'float')
+        return true;
+    // Java's `null` is a fixed value too - `String command = null;` before the
+    // branches that set it is how BenchmarkJava's command helper begins.
+    if (language === 'java' && node.type === 'null_literal')
+        return true;
+    if (!STRING_LITERAL_TYPES[language].includes(node.type))
+        return false;
+    return !containsType(node, INTERPOLATION_TYPES, 4);
+}
+function enclosingScopes(node) {
+    const scopes = [];
+    let current = node.parent;
+    while (current) {
+        if (SCOPE_NODES.has(current.type))
+            scopes.push(current);
+        current = current.parent;
+    }
+    return scopes;
+}
+/** Names bound by the parameter list of a function. Never constant. */
+function parameterNames(scope) {
+    const names = new Set();
+    const walk = (n) => {
+        if (!n)
+            return;
+        if (n.type === 'identifier')
+            names.add(n.text ?? '');
+        for (const child of n.namedChildren)
+            walk(child ?? null);
+    };
+    /*
+     * Not only `parameters`: a JavaScript arrow with one bare parameter keeps it
+     * in `parameter` (tests/probes/s07), and a Go method's receiver and named
+     * results are input too (g02).
+     */
+    for (const field of ['parameters', 'parameter', 'receiver', 'result'])
+        walk(scope.childForFieldName(field));
+    return names;
+}
+const TERNARY_NODES = new Set(['ternary_expression', 'conditional_expression']);
+/*
+ * Go binds a NEW variable in two places the write survey does not collect:
+ * `switch t := v.(type)` and `case t := <-ch`. Inside them, `t` is not the
+ * one declared outside (tests/probes/g03, g06).
+ */
+function goBindsOtherwise(root, name) {
+    const word = new RegExp(`(^|[^\\w])${name}(?![\\w])`);
+    for (const n of root.descendantsOfType(['type_switch_statement', 'receive_statement'])) {
+        if (!n)
+            continue;
+        const bound = n.type === 'type_switch_statement' ? n.childForFieldName('alias') : n.childForFieldName('left');
+        if (bound && word.test(bound.text ?? ''))
+            return true;
+    }
+    return false;
+}
+function rootOf(n) {
+    let root = n;
+    while (root.parent)
+        root = root.parent;
+    return root;
+}
+/** Nodes that declare a variable: Java and JavaScript declarators, Go's `var` and `:=`. */
+const DECLARATION_NODES = new Set(['variable_declarator', 'var_spec', 'short_var_declaration']);
+/** Languages whose `+` joins two strings, and the node that holds it. */
+const CONCATENATING = new Set(['java', 'javascript', 'typescript', 'python', 'go']);
+const CONCAT_NODES = new Set(['binary_expression', 'binary_operator']);
+export function constantProof(node, dynamicParts, language, options = {}) {
+    if (dynamicParts.length === 0)
+        return null;
+    // A comment the compiler ends where the parser does not - see
+    // taint/visibility.ts. Such a file is one this proof cannot read.
+    if (hidesCodeFromParser(node, language))
+        return null;
+    /*
+     * A fresh folder per question AND PER FILE: a folder's caches are keyed by
+     * source span, and a span is only meaningful inside one tree. Once a helper
+     * in another file can be read, one folder for both would answer a question
+     * about bytes 400-980 of Utils.java with what it learned about bytes
+     * 400-980 of the caller.
+     */
+    const folders = new Map();
+    const folderOf = (n) => {
+        let folder = folders.get(n.tree);
+        if (!folder) {
+            folder = createFolder(language);
+            folders.set(n.tree, folder);
+        }
+        return folder;
+    };
+    const treeIds = new Map();
+    /** A key for a node that is unique across files, not just within one. */
+    const spanKey = (n) => {
+        let id = treeIds.get(n.tree);
+        if (id === undefined) {
+            id = treeIds.size;
+            treeIds.set(n.tree, id);
+        }
+        return `${id}:${n.startIndex}:${n.endIndex}`;
+    };
+    const lineOf = (n) => n.startPosition.row + 1;
+    const contains = (outer, inner) => inner.startIndex >= outer.startIndex && inner.endIndex <= outer.endIndex;
+    const sameSpan = (a, b) => a.startIndex === b.startIndex && a.endIndex === b.endIndex;
+    /*
+     * The arm of an enclosing `if`, or the case of an enclosing switch, that
+     * cannot run - if `n` sits in one. Returned with the sentence the receipt
+     * uses, so the reader is told which decision made the write irrelevant.
+     */
+    const deadArmHolding = (n, scope, body) => {
+        let current = n.parent;
+        while (current && contains(scope, current)) {
+            if (current.type === 'if_statement') {
+                const dead = folderOf(current).deadBranchOf(current, body);
+                if (dead && contains(dead, n)) {
+                    return { at: current, why: `is in a branch that cannot run (line ${lineOf(current)})` };
+                }
+            }
+            if (SWITCH_NODES.has(current.type)) {
+                const decision = folderOf(current).switchDecision(current, body);
+                if (decision?.dead.some((group) => contains(group, n))) {
+                    return { at: current, why: `is in a case that cannot run: ${decision.note}` };
+                }
+            }
+            if (sameSpan(current, scope))
+                break;
+            current = current.parent;
+        }
+        return null;
+    };
+    /** Every value an expression can take, as nodes - or null if that cannot be bounded. */
+    const liveValues = (value, body, depth) => {
+        let v = value;
+        /*
+         * Go wraps EVERY assigned value in an expression_list, even a single one,
+         * because `a, b := 1, 2` is legal. So `q := "x"` never looked like a literal
+         * to this check - not after the folder arrived, and not before it either:
+         * Go had no constant proof at all until constant-branch.go asked for one.
+         * A one-element list is unwrapped like parentheses; a real multi-value
+         * assignment is left alone, and reads as "not a literal", which is safe.
+         */
+        while ((v.type === 'parenthesized_expression' || v.type === 'expression_list') &&
+            v.namedChildren.length === 1) {
+            v = v.namedChildren[0] ?? v;
+        }
+        if (!TERNARY_NODES.has(v.type) || depth > 4)
+            return { nodes: [v], note: null };
+        const parts = folderOf(v).ternaryParts(v);
+        const truth = folderOf(v).conditionTruth(parts.condition, body);
+        if (truth !== undefined) {
+            const live = truth ? parts.consequence : parts.alternative;
+            if (!live)
+                return null;
+            const inner = liveValues(live, body, depth + 1);
+            return inner && {
+                nodes: inner.nodes,
+                note: `the condition on line ${lineOf(v)} is fixed at compile time, and the side that runs is a literal`,
+            };
+        }
+        if (!parts.consequence || !parts.alternative)
+            return null;
+        const a = liveValues(parts.consequence, body, depth + 1);
+        const b = liveValues(parts.alternative, body, depth + 1);
+        if (!a || !b)
+            return null;
+        return { nodes: [...a.nodes, ...b.nodes], note: `both sides of the condition on line ${lineOf(v)} are literals` };
+    };
+    /*
+     * ONE LEVEL INTO A HELPER. See HelperConstantProof.java and
+     * StaticHelperCommand.java for the fences.
+     *
+     * 46 of BenchmarkJava's surviving SQL false positives had their decoy inside
+     * a helper: `String bar = new Test().doSomething(request, param)`. The tracer
+     * follows that call; this proof stopped at it. It follows three shapes, each
+     * chosen because the method that runs is not in doubt:
+     *
+     *   `new X(...).m(...)`, X declared in this file, X declaring ONE method m;
+     *   `m(...)` in this class, when m is private, static or final;
+     *   `Utils.m(...)` or `a.b.Utils.m(...)` - a static method, which may live
+     *   in ANOTHER file; taint/project.ts, staticMethod(), says when that file
+     *   and that method are the only candidates.
+     *
+     * Every `return` in m must be provable by the same rules as everything else
+     * here, with one addition: a parameter of m is as fixed as the argument this
+     * call passes for it - when that argument is provably fixed itself, the
+     * counts line up with no varargs, and m never writes to the parameter. That
+     * is what makes `getOSCommandString("echo")` fixed: it wraps literals around
+     * `append`, and `append` is "echo".
+     *
+     * Java only. A receiver that is a variable could be any subclass; an
+     * overload depends on argument types this proof does not read; a helper
+     * returning another helper is a second level, and there is no second level.
+     * Other languages' helpers are not followed yet, and the SQL rule's
+     * limitations say so rather than letting "constant" imply they are.
+     */
+    const bindings = new Map();
+    /*
+     * THE `new` A LOCAL CERTAINLY HOLDS, if it holds one.
+     *
+     *     SeparateClassRequest scr = new SeparateClassRequest(request);
+     *     String param = scr.getTheValue("BenchmarkTest00930");
+     *
+     * A variable could hold any subclass - unless it is a local declared once,
+     * in view of the call, with `= new X(...)`, and never written again anywhere
+     * in the method (closures included). Then it holds that X and nothing else.
+     * Not a parameter, not a field, not a name a lambda or a pattern also binds,
+     * and not read from inside a class that could inherit a field of that name
+     * (LocalObjectHelper.java has each).
+     *
+     * And the object must never leave the method's hands: every use of the name
+     * is as the receiver of a call, `h.m(...)`. Passed as an argument, it can be
+     * changed by whatever receives it - reflection rewrites a private field
+     * (tests/probes/r3-b07) - and `h.f = ...` writes a field directly.
+     */
+    const heldCreation = (name, call) => {
+        if (language !== 'java' || !name)
+            return null;
+        const fn = enclosingScopes(call)[0];
+        if (!fn || parameterNames(fn).has(name) || boundElsewhere(rootOf(call), name))
+            return null;
+        const declarators = fn
+            .descendantsOfType('variable_declarator')
+            .filter((d) => !!d && d.childForFieldName('name')?.text === name);
+        const declarator = declarators.length === 1 ? declarators[0] : undefined;
+        const value = declarator?.childForFieldName('value');
+        if (!declarator || value?.type !== 'object_creation_expression')
+            return null;
+        if (declarator.parent?.type !== 'local_variable_declaration')
+            return null;
+        const visible = declarationVisibility(declarator, language);
+        if (!visible || !contains(visible.region, call) || call.startIndex < visible.from)
+            return null;
+        const f = folderOf(fn);
+        if (f.writtenOtherwise(name, fn) || f.plainWriteCount(name, fn) !== 1)
+            return null;
+        if (enclosingClassLikes(call).some((c) => contains(visible.region, c) && supertypesOf(c).length > 0))
+            return null;
+        const nameNode = declarator.childForFieldName('name');
+        const onlyReceiver = fn.descendantsOfType('identifier').every((id) => {
+            if (!id || id.text !== name || (nameNode && sameSpan(id, nameNode)))
+                return true;
+            const p = id.parent;
+            return p?.type === 'method_invocation' && !!p.childForFieldName('object') && sameSpan(p.childForFieldName('object'), id);
+        });
+        if (!onlyReceiver)
+            return null;
+        return value;
+    };
+    const helperReturnsConstant = (call, depth) => {
+        if (depth > 0 || language !== 'java' || call.type !== 'method_invocation')
+            return null;
+        const receiver = call.childForFieldName('object');
+        const methodName = call.childForFieldName('name')?.text ?? '';
+        if (!methodName)
+            return null;
+        const methodsNamed = (klass) => (klass.childForFieldName('body')?.namedChildren ?? []).filter((m) => m !== null && m.type === 'method_declaration' && m.childForFieldName('name')?.text === methodName);
+        let root = call;
+        while (root.parent)
+            root = root.parent;
+        let method = null;
+        let typeName = '';
+        let where = '';
+        /** Could a supertype declared in the scan supply a member we did not look at? */
+        const inherits = (classLike) => supertypesOf(classLike).some((t) => t.split('.').some((part) => (options.javaTypeInScan ? options.javaTypeInScan(part) : true)));
+        /*
+         * `h.m(...)` where `h` is a local that certainly holds a `new X(...)` - see
+         * heldCreation below. The object is exactly an X, so it is read like
+         * `new X(...).m(...)`.
+         */
+        const created = receiver?.type === 'object_creation_expression'
+            ? receiver
+            : receiver?.type === 'identifier'
+                ? heldCreation(receiver.text ?? '', call)
+                : null;
+        if (created) {
+            /*
+             * `new X(...).m(...)`: the type is exact, so X's own m is the one that
+             * runs - when X is the class in scope here. Not with a body attached
+             * (`new X() { ... }` is an anonymous subclass that can override m, p25),
+             * not when X is a class nested somewhere the call cannot see (p26), and
+             * not when X inherits from anything - a superclass or an interface's
+             * default method - since an inherited overload can be the one chosen
+             * (p34, j03). X may live in another file, found the way a static
+             * helper's class is (staticMethod), with an instance method allowed.
+             */
+            if (isClassLike(created))
+                return null;
+            // `o.new X()` creates o's member class X - not the X this name finds
+            // from here (tests/probes/r3-a06, r3-a08, r3-d01).
+            if (created.child(0)?.type !== 'new')
+                return null;
+            typeName = (created.childForFieldName('type')?.text ?? '').replace(/\s+/g, '');
+            if (!/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(typeName))
+                return null; // generic: not read
+            // A class around the call can inherit a member class named X, and then
+            // that is the X created here (tests/probes/j04).
+            if (enclosingClassLikes(call).some(inherits))
+                return null;
+            const declared = [];
+            const findTypes = (n) => {
+                if (n.type !== 'object_creation_expression' && isClassLike(n) && n.childForFieldName('name')?.text === typeName) {
+                    declared.push(n);
+                }
+                for (const child of n.namedChildren)
+                    if (child)
+                        findTypes(child);
+            };
+            if (!typeName.includes('.'))
+                findTypes(root);
+            if (declared.length > 0) {
+                const klass = declared.length === 1 ? declared[0] : undefined;
+                if (!klass || klass.type !== 'class_declaration' || supertypesOf(klass).length > 0)
+                    return null;
+                const owner = klass.parent?.parent ?? null;
+                const inScope = klass.parent?.type === 'program' ||
+                    (klass.parent?.type === 'class_body' && !!owner && contains(owner, call) && isClassLike(owner));
+                if (!inScope)
+                    return null;
+                const candidates = methodsNamed(klass);
+                if (candidates.length !== 1)
+                    return null;
+                method = candidates[0];
+            }
+            else {
+                const first = typeName.split('.')[0] ?? '';
+                if (!options.staticMethod || !first || !usedOnlyAsQualifier(root, first))
+                    return null;
+                const supertypes = enclosingClassLikes(call).flatMap((c) => supertypesOf(c));
+                const found = options.staticMethod(typeName, methodName, supertypes, true);
+                if (!found || hidesCodeFromParser(found.method, 'java'))
+                    return null;
+                method = found.method;
+                where = ` in ${found.path}`;
+            }
+            typeName = typeName.split('.').pop() ?? typeName;
+        }
+        else if (!receiver) {
+            /*
+             * A bare call, `doSomething(request, param)`. It binds to this class's
+             * method only if no subclass can replace it - so only when that method
+             * is private, static or final, read from the modifier tokens (p29).
+             * BenchmarkJava declares its helpers `private static`, and 27 of the
+             * survivors were exactly this shape. The
+             * class is the INNERMOST class-like around the call: inside an anonymous
+             * class or an enum, `m()` means theirs (p27, p28), and those are not
+             * read. A superclass declared in the scan can supply a more specific
+             * overload (p30); one from outside it - BenchmarkJava's HttpServlet - is
+             * not read, and the SQL rule's limitations say so.
+             */
+            const klass = enclosingClassLikes(call)[0];
+            if (!klass || klass.type !== 'class_declaration' || inherits(klass))
+                return null;
+            typeName = klass.childForFieldName('name')?.text ?? '';
+            const candidates = methodsNamed(klass);
+            if (candidates.length !== 1)
+                return null;
+            const candidate = candidates[0];
+            if (!['private', 'static', 'final'].some((k) => hasModifier(candidate, k)))
+                return null;
+            method = candidate;
+        }
+        else if ((receiver.type === 'identifier' || receiver.type === 'field_access') && options.staticMethod) {
+            /*
+             * `Utils.m(...)`. In Java a variable named `Utils` - or `a` for
+             * `a.b.Utils` - hides the class or package of that name, and so does a
+             * type, a pattern variable, an enum constant, a lambda parameter... So
+             * EVERY appearance of that name in this file must be as a qualifier,
+             * like the one here (p10, p11, p12). Names that arrive without appearing
+             * - static imports, inherited members - are checked by the lookup.
+             */
+            const dotted = (receiver.text ?? '').replace(/\s+/g, '');
+            const first = dotted.split('.')[0] ?? '';
+            if (!first || !usedOnlyAsQualifier(root, first))
+                return null;
+            const supertypes = enclosingClassLikes(call).flatMap((c) => supertypesOf(c));
+            const found = options.staticMethod(dotted, methodName, supertypes);
+            if (!found || hidesCodeFromParser(found.method, 'java'))
+                return null;
+            method = found.method;
+            typeName = dotted.split('.').pop() ?? dotted;
+            where = ` in ${found.path}`;
+        }
+        if (!method)
+            return null; // a receiver that is a variable: it could be any subclass
+        /*
+         * A method calling itself. Its parameters are bound to what this call
+         * passes - and the arguments are the CALLER's parameters, the same names in
+         * the same method, which would then read their own binding: `m(b, "x")`
+         * inside m makes the caller's `b` look like "x" (tests/probes/r3-a07,
+         * r3-z-scope-recursive-static). Not read.
+         */
+        if (spanKey(rootOf(method)) === spanKey(rootOf(call)) && contains(method, call))
+            return null;
+        /* ---- the parameters, bound to what this call passes ---- */
+        const formal = (method.childForFieldName('parameters')?.namedChildren ?? []).filter((p) => p !== null && (p.type === 'formal_parameter' || p.type === 'spread_parameter'));
+        const args = (call.childForFieldName('arguments')?.namedChildren ?? []).filter((a) => a !== null && a.type !== 'line_comment' && a.type !== 'block_comment');
+        // The count must match with no varargs, whatever is read: a call that
+        // passes more or fewer arguments than this method takes is calling
+        // another one (p02).
+        if (formal.length !== args.length || formal.some((p) => p.type !== 'formal_parameter'))
+            return null;
+        const callerBody = enclosingScopes(call)[0];
+        const bound = new Map();
+        const used = [];
+        if (callerBody) {
+            formal.forEach((p, i) => {
+                const name = p.childForFieldName('name')?.text ?? '';
+                const arg = args[i];
+                if (!name || !arg)
+                    return;
+                let memo;
+                bound.set(name, () => {
+                    if (memo === undefined) {
+                        const why = valueIsConstant(arg, callerBody, depth);
+                        memo = why && [
+                            ...why,
+                            `\`${name}\` is \`${arg.text.replace(/\s+/g, ' ')}\`, passed on line ${lineOf(arg)}`,
+                        ];
+                        if (memo)
+                            used.push(name);
+                    }
+                    return memo;
+                });
+            });
+        }
+        const returns = [];
+        const findReturns = (n) => {
+            if (n.type === 'return_statement')
+                returns.push(n);
+            // A return inside a nested class or lambda belongs to that, not to m.
+            if (n.type === 'class_body' || n.type === 'lambda_expression')
+                return;
+            for (const child of n.namedChildren)
+                if (child)
+                    findReturns(child);
+        };
+        const methodBody = method.childForFieldName('body');
+        if (!methodBody)
+            return null;
+        findReturns(methodBody);
+        if (returns.length === 0)
+            return null;
+        const key = spanKey(method);
+        bindings.set(key, bound);
+        const notes = [];
+        try {
+            for (const ret of returns) {
+                const expr = ret.namedChildren.find((c) => c !== null) ?? null;
+                if (!expr)
+                    return null;
+                const why = valueIsConstant(expr, method, depth + 1);
+                if (!why)
+                    return null;
+                notes.push(...why);
+            }
+        }
+        finally {
+            bindings.delete(key);
+        }
+        if (used.length === 0) {
+            return [`the helper ${typeName}.${methodName}()${where} on line ${lineOf(method)} returns a fixed literal on every path`];
+        }
+        return [
+            `the helper ${typeName}.${methodName}()${where} on line ${lineOf(method)} returns only literals and ` +
+                `its parameter${used.length === 1 ? '' : 's'} ${used.map((u) => `\`${u}\``).join(', ')}, never written inside it`,
+            ...notes,
+        ];
+    };
+    /** Is this one live value fixed? Returns the notes that justify it, or null. */
+    const valueIsConstant = (v, body, depth) => {
+        const values = liveValues(v, body, 0);
+        if (!values)
+            return null;
+        const notes = values.note ? [values.note] : [];
+        for (const raw of values.nodes) {
+            if (isPlainLiteral(raw, language))
+                continue;
+            /*
+             * `(String) map.get("keyA")` or `list.get(1)` - a read from a local map or
+             * list whose every write is on the page (taint/local-map.ts) is the value
+             * stored there. The cast is looked through first; it changes the type,
+             * not the value.
+             */
+            let each = raw;
+            while (each.type === 'cast_expression' || each.type === 'parenthesized_expression') {
+                each = each.childForFieldName('value') ?? each.namedChildren[each.namedChildren.length - 1] ?? each;
+                if (each === raw)
+                    break;
+            }
+            const read = resolveContainerRead(each, language);
+            if (read) {
+                const where = `\`${each.text.replace(/\s+/g, ' ')}\` on line ${lineOf(each)} returns what was stored at ` +
+                    `${read.selector} on line ${lineOf(read.write)} - the collection is local, handed to nothing, ` +
+                    `and written only by straight-line statements`;
+                if (isPlainLiteral(read.value, language)) {
+                    notes.push(where.replace('returns what was stored', 'returns the literal stored'));
+                    continue;
+                }
+                /*
+                 * A NAME was stored - `map.put("keyB", param)`. Its value is judged
+                 * where it was stored, not where it is read: the map holds what the
+                 * name held then (ContainerHeldValue.java). Only for a type that cannot
+                 * change in place, or an alias could change the stored object later.
+                 */
+                const fn = enclosingMethod(each);
+                const stored = read.value.text ?? '';
+                if (read.value.type !== 'identifier' || !fn || !declaredImmutable(fn, stored))
+                    return null;
+                const inner = nameIsConstant(stored, read.value, depth);
+                if (!inner)
+                    return null;
+                notes.push(...inner, `${where}, and \`${stored}\` was fixed when stored`);
+                continue;
+            }
+            /*
+             * `"cmd.exe /c " + append + " "` - pieces joined with `+` are as fixed as
+             * the pieces. Only `+`, only where it joins strings (C's is pointer
+             * arithmetic, PHP's is `.`), and every piece judged by these same rules.
+             */
+            if (CONCATENATING.has(language) && CONCAT_NODES.has(each.type) && each.childForFieldName('operator')?.text === '+') {
+                const left = each.childForFieldName('left');
+                const right = each.childForFieldName('right');
+                const l = left ? valueIsConstant(left, body, depth) : null;
+                const r = l && right ? valueIsConstant(right, body, depth) : null;
+                if (!l || !r)
+                    return null;
+                notes.push(...l, ...r);
+                continue;
+            }
+            if (/^[A-Za-z_$][\w$]*$/.test((each.text ?? '').trim()) && each.namedChildren.length === 0) {
+                const inner = nameIsConstant((each.text ?? '').trim(), each, depth);
+                if (!inner)
+                    return null;
+                notes.push(...inner);
+                continue;
+            }
+            const helper = helperReturnsConstant(each, depth);
+            if (!helper)
+                return null;
+            notes.push(...helper);
+        }
+        return notes;
+    };
+    /*
+     * THE CYCLE GUARD, BECAUSE THIS PROJECT HAS ALREADY PAID FOR NOT HAVING ONE.
+     *
+     * A value can be another name - `bar = baz` - so resolving a name can land on
+     * a name, and `a = b; b = a` is a loop. The tracer's folder had exactly this
+     * shape with no guard, and DVWA's packed sha256 turned it into an
+     * out-of-memory on a 10KB file. A name already being resolved answers "not
+     * provable", which is the direction that keeps the finding.
+     */
+    const resolving = new Set();
+    /** Is every live write to `part`, as seen from `anchor`, a fixed value? */
+    const nameIsConstant = (part, anchor, depth) => {
+        let scopes = enclosingScopes(anchor);
+        const body = scopes[0];
+        if (!body)
+            return null;
+        /*
+         * A Python name assigned in a function, with no global/nonlocal for it, is
+         * that function's local: no module-level write - and no module-level exec()
+         * - can reach it. Walking the module anyway let an eval() in ANY function
+         * of the file sink every proof (BenchmarkPython's 22 constant-branch evals).
+         */
+        if (language === 'python' && scopes.length > 1 && body.type === 'function_definition' &&
+            folderOf(body).plainWriteCount(part, body) > 0 && !folderOf(body).writtenOtherwise(part, body)) {
+            scopes = [body];
+        }
+        const key = `${spanKey(body)}#${part}`;
+        if (resolving.has(key) || resolving.size > 24)
+            return null;
+        resolving.add(key);
+        try {
+            return resolveName(part, scopes, body, depth, anchor);
+        }
+        finally {
+            resolving.delete(key);
+        }
+    };
+    /** Node types that hold a plain sequence of statements, each run once, in order. */
+    const STATEMENT_LISTS = new Set([
+        'block', 'statement_block', 'compound_statement', 'constructor_body', 'statement_list',
+        'program', 'module', 'source_file',
+    ]);
+    /** Wrappers between a write and the statement that holds it. */
+    const STATEMENT_WRAPPERS = new Set([
+        'expression_statement', 'local_variable_declaration', 'lexical_declaration', 'variable_declaration',
+    ]);
+    /** The write that certainly decides the value at `anchor`, if one does. See resolveName. */
+    const certainLastWrite = (writes, anchor) => {
+        if (language === 'c' || language === 'cpp' || writes.length === 0)
+            return null;
+        const innermost = enclosingScopes(anchor)[0];
+        if (!innermost || writes.some((w) => !sameSpan(w.scope, innermost)))
+            return null;
+        const last = [...writes].sort((a, b) => a.node.startIndex - b.node.startIndex)[writes.length - 1];
+        if (!last || last.node.endIndex > anchor.startIndex)
+            return null;
+        let statement = last.node;
+        while (statement.parent && STATEMENT_WRAPPERS.has(statement.parent.type))
+            statement = statement.parent;
+        const holder = statement.parent;
+        if (!holder || !STATEMENT_LISTS.has(holder.type) || !contains(holder, anchor))
+            return null;
+        return last;
+    };
+    const resolveName = (part, scopes, body, depth, anchor) => {
+        let live = 0;
+        let fixed = true;
+        const notes = [];
+        /* Every plain write, in every scope, before any value is judged. */
+        const writes = [];
+        /* Every declaration of the name the same walk passes - with a value or without. */
+        const declarations = [];
+        for (const scope of scopes) {
+            if (parameterNames(scope).has(part)) {
+                /*
+                 * A parameter is input - unless this is a helper being read for one
+                 * particular call (helperReturnsConstant), and then it is whatever that
+                 * call passes. Only if the helper never writes to it: `a = b;` would
+                 * make the literal passed for `a` irrelevant.
+                 */
+                const bound = bindings.get(spanKey(scope))?.get(part);
+                if (!bound)
+                    return null;
+                const f = folderOf(scope);
+                if (f.writtenOtherwise(part, scope) || f.plainWriteCount(part, scope) > 0)
+                    return null;
+                return bound();
+            }
+            /*
+             * A write this walk does not recognise - `bar, err := f()`, `[bar] = x`,
+             * `bar += param` in Python, `for bar in ...` - would leave only the literal
+             * writes visible, and the proof would call a tainted value constant. The
+             * folder's survey sees every form of write; any irregular one ends this.
+             */
+            if (folderOf(scope).writtenOtherwise(part, scope))
+                return null;
+            const collect = (n) => {
+                if (!n)
+                    return;
+                if (n !== scope && SCOPE_NODES.has(n.type))
+                    return;
+                const fields = BINDING_NODES[n.type];
+                if (fields && (n.childForFieldName(fields.name)?.text ?? '').trim() === part) {
+                    const value = n.childForFieldName(fields.value);
+                    if (value)
+                        writes.push({ node: n, value, scope });
+                }
+                if (DECLARATION_NODES.has(n.type) && (n.childForFieldName(n.type === 'short_var_declaration' ? 'left' : 'name')?.text ?? '').trim() === part) {
+                    declarations.push({ node: n, scope });
+                }
+                for (const child of n.namedChildren)
+                    collect(child ?? null);
+            };
+            collect(scope);
+        }
+        /*
+         * A WRITE INSIDE A CLOSURE is a write this walk does not see - it stops at
+         * nested functions on purpose - and `let bar = "x"; const set = () => {
+         * bar = req.query.q; }; set();` would read as constant. The folder's survey
+         * walks nested functions too; if it counts more writes here than this walk
+         * did, one of them is hidden in a closure, and nothing is proved.
+         */
+        const innermost = scopes[0];
+        if (innermost && folderOf(innermost).plainWriteCount(part, innermost) > writes.filter((w) => w.scope === innermost).length) {
+            return null;
+        }
+        let outerBound = writes.some((w) => innermost && !sameSpan(w.scope, innermost));
+        /*
+         * JAVA SCOPING. The walk above collects every declaration of the name in
+         * the scopes around the read - and Java's scopes are smaller than that.
+         * Each probe in tests/probes/p15-p24 was a constant declaration the read
+         * could not see, standing in for one it could:
+         *
+         *   - a local is visible from its declaration to the end of its block, so
+         *     one in another block (p17), one declared after the read (p18), one
+         *     inside a lambda (p22) and a field of a nested or local class (p19,
+         *     p23, p24) are somebody else's - and any of those ends the proof;
+         *   - a lambda parameter or a pattern variable of the same name can shadow
+         *     the declaration found, and the walk does not collect them (p15, p16);
+         *   - a class between the declaration and the read that inherits from
+         *     anything can inherit a field of the same name, which then wins (p20,
+         *     p21);
+         *   - a field counts only if it is private or final, read from the
+         *     modifier TOKENS - the word in `@SuppressWarnings("private")`, or a
+         *     `final` inside a comment, is not a modifier (p13, p14) - since any
+         *     other class can assign one that is neither;
+         *   - no declaration in view at all - an inherited field, a static import -
+         *     is nothing this proof can read.
+         */
+        if (language === 'java') {
+            if (boundElsewhere(rootOf(anchor), part))
+                return null;
+            if (declarations.length === 0)
+                return null;
+            let local = false;
+            for (const { node: declarator } of declarations) {
+                const visible = declarationVisibility(declarator, language);
+                if (!visible || !contains(visible.region, anchor) || anchor.startIndex < visible.from)
+                    return null;
+                if (enclosingClassLikes(anchor).some((c) => contains(visible.region, c) && supertypesOf(c).length > 0)) {
+                    return null;
+                }
+                const holder = declarator.parent;
+                if (holder?.type === 'local_variable_declaration')
+                    local = true;
+                else if (holder?.type === 'field_declaration' && !hasModifier(holder, 'private') && !hasModifier(holder, 'final')) {
+                    return null;
+                }
+            }
+            /*
+             * A write inside a class nested in this code - a local or anonymous
+             * class, a record's constructor, an initializer block - runs as THAT
+             * class's code, where every name around it may mean something else:
+             * `if (dbg) cmd = ...` inside a record reads the record's own `dbg`
+             * (tests/probes/j09, j10). Its branches cannot be decided from here, so
+             * such a write ends the proof.
+             */
+            if (writes.some((w) => enclosingClassLikes(w.node).some((c) => !contains(c, anchor))))
+                return null;
+            if (!local)
+                outerBound = true;
+        }
+        else if (language === 'javascript' || language === 'typescript' || language === 'go') {
+            /*
+             * The same visibility rule as Java's, by these languages' own scoping:
+             * every declaration found must be one the read can see (a block's
+             * `let`, a `for` header's, a Go block's `:=` - s02, s03, s05, s06, g05),
+             * and there must be one: a name declared nowhere in view is an import,
+             * another script's global or another file's package variable (s04, g04).
+             */
+            if (language === 'go' && goBindsOtherwise(rootOf(anchor), part))
+                return null;
+            if (declarations.length === 0)
+                return null;
+            for (const { node: declarator } of declarations) {
+                const visible = declarationVisibility(declarator, language);
+                if (!visible || !contains(visible.region, anchor) || anchor.startIndex < visible.from)
+                    return null;
+            }
+            // Not declared in the reading function: it belongs to a scope outside,
+            // where any other function can assign it - with or without a write of
+            // its own in view.
+            if (!declarations.some((d) => innermost && sameSpan(d.scope, innermost)))
+                outerBound = true;
+        }
+        /*
+         * A NAME BOUND OUTSIDE THIS FUNCTION CAN BE WRITTEN BY ANY OTHER ONE.
+         *
+         *     static String table = "users";
+         *     void setTable(HttpServletRequest r) { table = r.getParameter("t"); }
+         *     void list(Statement s) { s.execute("SELECT * FROM " + table); }
+         *
+         * The walk above does not enter other functions - on purpose, because a
+         * sibling's OWN local of the same name is irrelevant (const-interp.py). But
+         * `table` here is not anybody's local: it is a field, and setTable writes
+         * it. The walk saw only "users" and called the query constant. So for a
+         * name bound outside the reading function, every function inside the scope
+         * that holds it is searched too, and any write not already judged ends the
+         * proof - a sibling's same-named local included, which costs a little
+         * precision and never a finding. OuterWriteFence.* has each shape.
+         *
+         * Python and PHP are left out on purpose: a plain assignment inside a
+         * function makes a NEW local there, and reaching the outer name takes a
+         * `global` (or `nonlocal`) statement - which the survey above already
+         * treats as an irregular write.
+         */
+        if (outerBound && language !== 'python' && language !== 'php') {
+            const holding = [...declarations.map((d) => d.scope), ...writes.map((w) => w.scope)];
+            const declaring = (holding.length > 0 && innermost && holding.every((h) => sameSpan(h, innermost))
+                ? scopes[scopes.length - 1]
+                : [...scopes].reverse().find((s) => holding.some((h) => sameSpan(h, s)))) ?? scopes[scopes.length - 1];
+            if (!declaring)
+                return null;
+            const folder = folderOf(declaring);
+            if (folder.writtenOtherwise(part, declaring) || folder.plainWriteCount(part, declaring) > writes.length)
+                return null;
+        }
+        /*
+         * THE LAST CERTAIN WRITE.
+         *
+         *     bar = (String) map.get("keyB");   // the request parameter
+         *     bar = (String) map.get("keyA");   // a literal
+         *     sql = "... " + bar;
+         *
+         * Every write to `bar` used to have to be a literal, so the dirty one above
+         * - overwritten one line later - sank the proof. When one write is certain
+         * to run after all the others and before the read, it is the only one that
+         * matters. Certain means: it is a statement directly in a block that holds
+         * the read, it comes before the read, and NO write to the name comes after
+         * it anywhere in the function - so no loop can bring an earlier or later
+         * value round again. Not attempted in C or C++, where a declaration in an
+         * inner block can shadow the name without this walk seeing a write.
+         */
+        // Only for a name local to the reading function: a call between the last
+        // write and the read can change a field, or a variable another function
+        // shares.
+        // A `goto` can jump over the last write (tests/probes/g01).
+        const jumps = !!innermost && innermost.descendantsOfType('goto_statement').length > 0;
+        const last = outerBound || jumps ? null : certainLastWrite(writes, anchor);
+        if (last) {
+            const why = valueIsConstant(last.value, body, depth);
+            if (!why)
+                return null;
+            return [
+                ...why,
+                `the value at line ${lineOf(anchor)} is the one written on line ${lineOf(last.node)}, which ` +
+                    `overwrites every earlier write and is never overwritten itself`,
+            ];
+        }
+        /*
+         * A FIELD OUTLIVES THE CALL. Inside a helper read for one call, a parameter
+         * means what THAT call passes - but a field written from a parameter, `f =
+         * v`, holds what whichever call ran LAST passed: `swap(tainted);
+         * swap("x")` returns the tainted value, and a lazy cache keeps the first
+         * call's (tests/probes/r3-a04, r3-a05, r3-a09, r3-z-scope-static-swap). So
+         * a name bound outside the reading function is judged with no parameter
+         * bound, and a parameter written into it is input.
+         */
+        const suspended = outerBound && bindings.size > 0 ? new Map(bindings) : null;
+        if (suspended)
+            bindings.clear();
+        try {
+            for (const scope of scopes) {
+                const walk = (n) => {
+                    if (!n || !fixed)
+                        return;
+                    // Do NOT descend into a nested scope. Searching the module body walked
+                    // straight into sibling functions, so an unrelated `t = request.args...`
+                    // three functions away made a genuinely constant `t` here look tainted.
+                    if (n !== scope && SCOPE_NODES.has(n.type))
+                        return;
+                    const fields = BINDING_NODES[n.type];
+                    if (fields) {
+                        const target = n.childForFieldName(fields.name);
+                        if ((target?.text ?? '').trim() === part) {
+                            const value = n.childForFieldName(fields.value);
+                            if (value) {
+                                const deadIf = deadArmHolding(n, scope, body);
+                                if (deadIf) {
+                                    notes.push(`the write on line ${lineOf(n)} ${deadIf.why}`);
+                                }
+                                else {
+                                    live++;
+                                    const why = valueIsConstant(value, body, depth);
+                                    if (!why)
+                                        fixed = false;
+                                    else
+                                        notes.push(...why);
+                                }
+                            }
+                        }
+                    }
+                    for (const child of n.namedChildren)
+                        walk(child ?? null);
+                };
+                walk(scope);
+            }
+        }
+        finally {
+            if (suspended)
+                for (const [k, v] of suspended)
+                    bindings.set(k, v);
+        }
+        // No live write means we cannot see where it comes from - so we do not get
+        // to call it constant.
+        if (live === 0 || !fixed)
+            return null;
+        return notes;
+    };
+    let reasoned = false;
+    const reasons = [];
+    for (const raw of dynamicParts) {
+        const part = raw.trim();
+        // Only a bare name can be resolved this cheaply. Anything with a call, an
+        // index or an attribute access is left alone.
+        if (!/^[A-Za-z_$][\w$]*$/.test(part))
+            return null;
+        const notes = nameIsConstant(part, node, 0);
+        if (!notes)
+            return null;
+        if (notes.length > 0) {
+            reasoned = true;
+            reasons.push(`\`${part}\`: ${[...new Set(notes)].join('; ')}`);
+        }
+    }
+    return {
+        reasoned,
+        reason: reasoned
+            ? `Every value that can be spliced in is a fixed literal on every path that runs. ${reasons.join('. ')}.`
+            : 'Every value spliced in is bound only to plain literals.',
+    };
+}
+//# sourceMappingURL=strings.js.map