ucn 5.5.1 → 5.5.3

package/core/reflection.js

@@ -25,6 +25,7 @@
  */
 
 const { langTraits } = require('../languages');
+const { sameNode } = require('../languages/utils');
 
 const WILD = '\u0000*';
 const MODULE_RECEIVER = Object.freeze({ kind: 'module' });
@@ -501,6 +502,224 @@ function classifyReceiver(node, language) {
     return null;
 }
 
+// ---------------------------------------------------------------------------
+// Names one call away (fix #428)
+// ---------------------------------------------------------------------------
+
+// Callables whose parameters a reflective name can be (grammar node types).
+const PARAMETER_OWNERS = new Set([
+    'function_declaration', 'generator_function_declaration', 'function_expression', 'generator_function',
+    'arrow_function', 'method_definition', 'function_definition', 'method_declaration',
+    'constructor_declaration', 'local_function_statement', 'func_literal',
+]);
+const PARAMETER_LISTS = new Set(['formal_parameters', 'parameters', 'parameter_list']);
+const VARIADIC_PARAMETERS = new Set(['rest_pattern', 'list_splat_pattern', 'dictionary_splat_pattern',
+    'spread_parameter', 'variadic_parameter_declaration', 'variadic_parameter']);
+
+/** The parameter names of a callable in declaration order (null if unknown). */
+function _parameterNames(fn) {
+    const list = fn.childForFieldName('parameters') ||
+        (fn.namedChildren || []).find(child => PARAMETER_LISTS.has(child.type));
+    if (!list) {
+        // `x => ..`: a single bare parameter.
+        const single = fn.childForFieldName('parameter');
+        return single?.type === 'identifier' ? [single.text] : null;
+    }
+    const names = [];
+    for (const param of list.namedChildren) {
+        if (param.type === 'comment') continue;
+        if (param.type === 'identifier') { names.push(param.text); continue; }
+        // A Go declaration may name several parameters of one type.
+        if (param.type === 'parameter_declaration' || param.type === 'variadic_parameter_declaration') {
+            const ids = param.namedChildren.filter(child => child.type === 'identifier');
+            if (ids.length === 0) names.push(null);
+            for (const id of ids) names.push(id.text);
+            continue;
+        }
+        const named = param.childForFieldName('name') || param.childForFieldName('pattern') ||
+            param.childForFieldName('left') ||
+            (param.type === 'typed_parameter' ? param.namedChild(0) : null);
+        names.push(named?.type === 'identifier' ? named.text : null);
+    }
+    return names;
+}
+
+/** The name a callable is called by: its own, or the binding it is assigned to. */
+function _callableName(fn) {
+    const own = fn.childForFieldName('name');
+    if (own) return own.text;
+    const parent = fn.parent;
+    if (parent?.type === 'variable_declarator') return parent.childForFieldName('name')?.text || null;
+    if (parent?.type === 'pair') return parent.childForFieldName('key')?.text?.replace(/^["']|["']$/g, '') || null;
+    if (parent?.type === 'assignment_expression') {
+        const left = parent.childForFieldName('left');
+        if (left?.type === 'identifier') return left.text;
+        if (left?.type === 'member_expression') return left.childForFieldName('property')?.text || null;
+    }
+    return null;
+}
+
+/** Does `body` assign the name anywhere (nested callables included)? */
+function _assignsName(body, name) {
+    const stack = [body];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (_bindingPairs(node).some(([bound]) => bound === name)) return true;
+        for (const child of node.namedChildren || []) stack.push(child);
+    }
+    return false;
+}
+
+/**
+ * A reflective name that is a parameter of an enclosing callable, never
+ * rebound: { name, line, index } (the call-site argument position), else
+ * null. Its value is the argument the callable's callers pass.
+ */
+function _keyParameter(ident, language) {
+    if (ident?.type !== 'identifier') return null;
+    for (let fn = ident.parent; fn; fn = fn.parent) {
+        if (CLASS_NODES.has(fn.type)) return null;
+        if (!PARAMETER_OWNERS.has(fn.type)) continue;
+        const names = _parameterNames(fn);
+        if (!names) return null;
+        let position = names.indexOf(ident.text);
+        if (position < 0) continue; // captured from an outer callable
+        const name = _callableName(fn);
+        if (!name || _assignsName(fn.childForFieldName('body') || fn, ident.text)) return null;
+        // A method's receiver parameter (`self`, `cls`) is not a call
+        // argument of a bound call.
+        const selfNames = langTraits(language)?.selfParam || [];
+        let owner = fn.parent?.type === 'decorated_definition' ? fn.parent.parent : fn.parent;
+        if (fn.type === 'function_definition' && owner?.type === 'block' &&
+            owner.parent?.type === 'class_definition' && selfNames.includes(names[0])) {
+            if (position === 0) return null;
+            position--;
+        }
+        // The class a method belongs to: a call naming another class as its
+        // qualifier is no call of it. A C# extension's `this` parameter is
+        // the receiver of an extension call (`t.M(x)`).
+        const ownerClass = _enclosingClass(fn, false);
+        const ownerName = ownerClass ? _classInfo(ownerClass)?.name || null : null;
+        const params = (fn.childForFieldName('parameters')?.namedChildren || []).filter(child => child.type !== 'comment');
+        const firstParam = params.find(child => child.type === 'parameter');
+        const extension = !!firstParam?.children?.some(child => child.type === 'modifier' && child.text === 'this');
+        // A call passing more arguments than a fixed parameter list takes
+        // is not a call of it.
+        const variadic = params.some(param => VARIADIC_PARAMETERS.has(param.type) ||
+            param.children?.some(child => child.type === 'modifier' && child.text === 'params') ||
+            param.namedChildren?.some(child => VARIADIC_PARAMETERS.has(child.type)));
+        const maxArgs = variadic ? null : names.length - (names.length > 0 && selfNames.includes(names[0]) &&
+            fn.type === 'function_definition' && owner?.type === 'block' && owner.parent?.type === 'class_definition' ? 1 : 0);
+        return { name, line: fn.startPosition.row + 1, index: position,
+            ...(ownerName && { owner: ownerName }), ...(extension && { extension: true }),
+            ...(Number.isInteger(maxArgs) && { maxArgs }) };
+    }
+    return null;
+}
+
+const MAX_KEY_CALLS = 256;
+// Characters after a call's name its arguments are looked for in, when the
+// record keeps only the name's position.
+const KEY_CALL_WINDOW = 4096;
+
+/**
+ * The names a parameter-keyed site receives (fix #428): the string-shaped
+ * arguments at the parameter's position in the calls naming its callable,
+ * read from each call's own AST (one hop). Null when no call passes one.
+ */
+function resolveKeyParameter(index, site, language, onlyFiles = null, onlyName = null) {
+    const key = site.keyParameter;
+    const { getCachedCalls } = require('./callers');
+    const { getParser, safeParse } = require('../languages');
+    const files = [...(onlyFiles || index.getCalleeFiles?.(key.name) || [])].sort();
+    const exact = new Set();
+    let seen = 0;
+    for (const file of files) {
+        const entry = index.files.get(file);
+        if (!entry || _family(entry.language) !== _family(language)) continue;
+        // A call qualified by another class's name never calls the method;
+        // an extension call passes the `this` argument as its receiver.
+        const shift = call => key.extension && call.isMethod && call.receiver && call.receiver !== key.owner ? 1 : 0;
+        const position = call => key.index - shift(call);
+        let calls = (getCachedCalls(index, file) || []).filter(call => call.name === key.name &&
+            !call.isFunctionReference && position(call) >= 0 &&
+            !(Number.isInteger(key.maxArgs) && Number.isInteger(call.argCount) && call.argCount > key.maxArgs - shift(call)) &&
+            !(Number.isInteger(call.argCount) && call.argCount <= position(call)) &&
+            !(key.owner && call.receiverIsTypeQualified && call.receiver && call.receiver !== key.owner));
+        if (calls.length === 0) continue;
+        seen += calls.length;
+        if (seen > MAX_KEY_CALLS) return null;
+        let content;
+        try { content = index._readFile(file); } catch { continue; }
+        // A literal argument lies in the call's text: a call whose text
+        // spells no quoted `onlyName` cannot pass it, and needs no parse.
+        if (onlyName) {
+            const quoted = ['"', "'", '`'].map(quote => `${quote}${onlyName}${quote}`);
+            calls = calls.filter(call => {
+                const start = call.callStart ?? call.callSite?.start;
+                if (!Number.isInteger(start)) return true;
+                const text = content.slice(start, call.callEnd ?? start + KEY_CALL_WINDOW);
+                return quoted.some(spelling => text.includes(spelling));
+            });
+            if (calls.length === 0) continue;
+        }
+        const tree = index._getParsedTree?.(file, content, entry.language) || safeParse(getParser(entry.language), content);
+        if (!tree) continue;
+        const api = langTraits(entry.language)?.reflectionApi || {};
+        const ctx = { formatCalls: api.formatCalls || null, resolve: makeResolver() };
+        for (const call of calls) {
+            const offset = call.callStart ?? call.callSite?.start;
+            if (!Number.isInteger(offset)) continue;
+            let node = tree.rootNode.descendantForIndex(offset);
+            for (let depth = 0; node && depth < 6 && !CALL_NODE_TYPES.includes(node.type); depth++) node = node.parent;
+            const args = node ? _callArgs(node) : null;
+            // Keyword, spread or missing arguments do not bind by position.
+            if (!args || args.slice(0, position(call) + 1).some(arg =>
+                /keyword_argument|spread|splat|named_argument/.test(arg.type) ||
+                (arg.type === 'argument' && arg.childForFieldName('name')))) continue;
+            let arg = args[position(call)];
+            if (arg?.type === 'argument') arg = arg.namedChildren.find(child => child.type !== 'comment') || arg;
+            if (!arg) continue;
+            const cls = classifyNameExpression(arg, ctx);
+            if (cls.name) exact.add(cls.name);
+            for (const pattern of cls.patterns || []) if (!pattern.includes('*')) exact.add(pattern);
+        }
+    }
+    return exact.size > 0 ? [...exact].sort() : null;
+}
+
+const QUOTED_IDENTIFIER = /(["'`])([A-Za-z_$][\w$]*)\1/g;
+
+/**
+ * Could a parameter-keyed site receive `name` (fix #428)? Only when a file
+ * holding a call of its callable spells `name` as a string literal: the
+ * files' quoted identifiers are read once, and the AST resolution runs only
+ * for a name they hold.
+ */
+function _keyParameterPasses(index, pidx, entry, name) {
+    const files = index.getCalleeFiles?.(entry.site.keyParameter.name);
+    if (!files || files.size === 0) return false;
+    const spelled = [];
+    for (const file of files) {
+        let quoted = pidx.quoted.get(file);
+        if (!quoted) {
+            quoted = new Set();
+            try {
+                for (const match of index._readFile(file).matchAll(QUOTED_IDENTIFIER)) quoted.add(match[2]);
+            } catch { /* unreadable: no literal */ }
+            pidx.quoted.set(file, quoted);
+        }
+        if (quoted.has(name)) spelled.push(file);
+    }
+    if (spelled.length === 0) return false;
+    let byName = pidx.keyNames.get(entry);
+    if (!byName) pidx.keyNames.set(entry, byName = new Map());
+    if (!byName.has(name)) {
+        byName.set(name, !!resolveKeyParameter(index, entry.site, entry.language, spelled, name)?.includes(name));
+    }
+    return byName.get(name);
+}
+
 // ---------------------------------------------------------------------------
 // Site extraction
 // ---------------------------------------------------------------------------
@@ -558,7 +777,12 @@ function reflectionSitesInTree(tree, language, code = null) {
     const push = (node, kind, nameNode, receiverNode, receiverFact) => {
         const cls = classifyNameExpression(nameNode, ctx);
         const expression = String(node.text || '');
+        // A name that is the enclosing callable's parameter is decided one
+        // call away, by what its callers pass (fix #428).
+        const keyParameter = cls.dynamic && !cls.patterns && _unwrap(nameNode)?.type === 'identifier'
+            ? _keyParameter(_unwrap(nameNode), language) : null;
         sites.push({
+            ...(keyParameter && { keyParameter }),
             kind,
             line: node.startPosition.row + 1,
             expression: expression.length > EXPRESSION_CAP
@@ -595,6 +819,14 @@ function reflectionSitesInTree(tree, language, code = null) {
             // counts; opaque keys stay the computed-dispatch disclosure.
             const index = node.childForFieldName('index');
             const inner = _unwrap(index);
+            // `registry[type](..)` with `type` a parameter of the enclosing
+            // callable dispatches by the name its callers pass (fix #428).
+            if (inner?.type === 'identifier' && node.parent?.type === 'call_expression' &&
+                sameNode(node.parent.childForFieldName('function'), node) &&
+                _keyParameter(inner, language)) {
+                push(node, 'computed', index, node.childForFieldName('object'));
+                return;
+            }
             if (!inner || !COMPUTED_PATTERN_KEYS.has(inner.type)) return;
             const cls = classifyNameExpression(index, ctx);
             if (cls.patterns && cls.patterns.length > 0) {
@@ -696,6 +928,14 @@ function _longestFragment(pattern) {
     return best;
 }
 
+/** Whether a pattern entry names members by some literal text (fix #433):
+ * a fully dynamic name (`eval(code)`, `globals()[key]` with no literal
+ * part) reaches every top-level name of its module alike and is attributed
+ * to none of them; deadcode still withholds what it may reach. */
+function patternIsAttributable(pattern) {
+    return _longestFragment(String(pattern || '').split('\u0000').join('')) !== '';
+}
+
 function _family(language) {
     return langTraits(language)?.reflectionApi?.family || language;
 }
@@ -713,6 +953,7 @@ function reflectionPatternIndex(index) {
     const lengths = new Set();
     let entryCount = 0;
     const moduleScoped = new Map();
+    const keyParameterSites = [];
     for (const [file, sites] of byFile) {
         const fe = index.files.get(file);
         if (!fe) continue;
@@ -728,6 +969,11 @@ function reflectionPatternIndex(index) {
                 }
                 continue;
             }
+            if (site.keyParameter && !site.patterns) {
+                keyParameterSites.push({ file, relativePath: fe.relativePath,
+                    language: fe.language, family: _family(fe.language), site });
+                continue;
+            }
             if (!site.patterns) continue;
             for (const pattern of site.patterns) {
                 const frag = _longestFragment(pattern);
@@ -740,7 +986,8 @@ function reflectionPatternIndex(index) {
             }
         }
     }
-    const result = { byFragment, lengths: [...lengths].sort((a, b) => a - b), entryCount, moduleScoped };
+    const result = { byFragment, lengths: [...lengths].sort((a, b) => a - b), entryCount, moduleScoped,
+        keyParameterSites, quoted: new Map(), keyNames: new Map() };
     index._reflectionPatternIndex = result;
     return result;
 }
@@ -755,8 +1002,12 @@ function patternEntriesFor(index, name, language, file = null) {
             if (globMatches(entry.pattern, name)) out.push(entry);
         }
     }
-    if (pidx.entryCount === 0) return out;
     const family = language ? _family(language) : null;
+    for (const entry of pidx.keyParameterSites) {
+        if (family && entry.family !== family) continue;
+        if (_keyParameterPasses(index, pidx, entry, name)) out.push({ ...entry, pattern: name });
+    }
+    if (pidx.entryCount === 0) return out;
     const seenFrag = new Set();
     for (const len of pidx.lengths) {
         if (len > name.length) break;
@@ -862,6 +1113,20 @@ function resetReflectionIndex(index) {
     index._reflectionPatternIndex = null;
 }
 
+/** Exact AST string literals, for conservative same-file dynamic dispatch.
+ * This does not prove that a literal flows to a reflection call. */
+function reflectionLiteralNames(tree) {
+    const names = new Map();
+    if (!tree) return names;
+    for (const node of tree.rootNode.descendantsOfType([...STRING_NODES])) {
+        const value = classifyNameExpression(node);
+        if (value.name && !value.dynamic && !names.has(value.name)) {
+            names.set(value.name, node.startPosition.row + 1);
+        }
+    }
+    return names;
+}
+
 module.exports = {
     WILD,
     stringAlternatives,
@@ -873,5 +1138,8 @@ module.exports = {
     reflectionEntryReaches,
     reflectionPatternReferences,
     reflectionPatternIndex,
+    patternIsAttributable,
     resetReflectionIndex,
+    reflectionLiteralNames,
+    resolveKeyParameter,
 };

package/core/rename-token-syntax.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const crypto = require('crypto');
+const cache = require('./cache');
+const { indexedContent, parseViewParts, syntaxMode, SYNTAX_FAMILIES } = require('./source-memo');
+const { langTraits } = require('../languages');
+
+/** Cache AST-proved positions only; the caller resolves each binding anew. */
+function callTokenSyntax(index, file, entry, content, range, name, line, derive) {
+    if (index.isProvenanceFactIndex || !entry?.hash ||
+        !langTraits(entry.language)?.physicalCallTokenSyntax ||
+        !Number.isInteger(range.start) || !Number.isInteger(range.end) ||
+        range.start < 0 || range.end <= range.start || !Number.isInteger(line) || line <= 0) return derive();
+    const tree = index._peekParsedTree?.(file, entry?.language);
+    const state = sourceState(index, file, entry, content, tree);
+    if (!state?.mode) return derive();
+    let facts = state.names.get(name);
+    if (!facts) {
+        const value = cache.getUsageResult(index, file, name, state.mode);
+        const rows = Array.isArray(value) && value.every(row => Array.isArray(row) &&
+            row.length === 4 && row.every(Number.isInteger) &&
+            row[0] >= 0 && row[1] > row[0] && row[2] > 0 && row[3] >= 0)
+            ? value.slice() : [];
+        const positions = new Map();
+        let duplicate = false;
+        for (const row of rows) {
+            const key = `${row[0]}:${row[1]}:${row[2]}`;
+            if (positions.has(key)) duplicate = true;
+            positions.set(key, row[3]);
+        }
+        facts = duplicate ? { rows: [], positions: new Map() } : { rows, positions };
+        state.names.set(name, facts);
+    }
+    const key = `${range.start}:${range.end}:${line}`;
+    const stored = facts.positions.get(key);
+    state.lines ||= content.split('\n');
+    const lineText = state.lines[line - 1] || '';
+    if (!state.lineStarts) {
+        let at = 0;
+        state.lineStarts = state.lines.map(text => { const start = at; at += text.length + 1; return start; });
+    }
+    const lineStart = state.lineStarts[line - 1];
+    const inRange = column => Number.isInteger(lineStart) && lineStart + column >= range.start &&
+        lineStart + column + name.length <= range.end;
+    if (!tree && stored !== undefined && inRange(stored) &&
+        lineText.slice(stored, stored + name.length) === name) return stored;
+    const column = derive();
+    if (column === stored) return column;
+    if (Number.isInteger(column) && column >= 0 && inRange(column) && Number.isInteger(range.start) &&
+        Number.isInteger(range.end) && range.end > range.start && Number.isInteger(line) &&
+        line > 0 && lineText.slice(column, column + name.length) === name) {
+        const rows = facts.rows.filter(row =>
+            row[0] !== range.start || row[1] !== range.end || row[2] !== line);
+        rows.push([range.start, range.end, line, column]);
+        facts.rows = rows;
+        facts.positions.set(key, column);
+        cache.storeUsageResult(index, file, name, state.mode, rows);
+    }
+    return column;
+}
+
+/** The selected declaration is a fresh input; only its physical name column is saved. */
+function declarationTokenSyntax(index, file, entry, content, line, name, definition, allIdentifiers = true) {
+    if (index.isProvenanceFactIndex || !entry?.hash ||
+        !langTraits(entry.language)?.physicalCallTokenSyntax) return null;
+    const tree = index._peekParsedTree?.(file, entry?.language);
+    const state = sourceState(index, file, entry, content, tree);
+    if (!state?.mode) return null;
+    let identity;
+    try {
+        const description = JSON.stringify([allIdentifiers, definition || null], (_key, value) =>
+            value && typeof value === 'object' && !Array.isArray(value)
+                ? Object.fromEntries(Object.keys(value).sort().map(key => [key, value[key]])) : value);
+        identity = crypto.createHash('sha256').update(description).digest('hex');
+    }
+    catch { return null; }
+    const mode = state.mode.replace(`${SYNTAX_FAMILIES.callToken.prefix}:`, `${SYNTAX_FAMILIES.declarationToken.prefix}:`) +
+        `:${line}:${identity}`;
+    const saved = cache.getUsageResult(index, file, name, mode);
+    state.lines ||= content.split('\n');
+    const text = state.lines[line - 1] || '';
+    const valid = value => Array.isArray(value) && value.length === 1 &&
+        Number.isInteger(value[0]) && value[0] >= 0 &&
+        text.slice(value[0], value[0] + name.length) === name;
+    return {
+        columns: !tree && valid(saved) ? saved.slice() : null,
+        save(columns) {
+            if (valid(columns) && (!valid(saved) || saved[0] !== columns[0])) {
+                cache.storeUsageResult(index, file, name, mode, columns.slice());
+            }
+        },
+    };
+}
+
+function sourceState(index, file, entry, content, tree) {
+    if (index.isProvenanceFactIndex || !entry?.hash || !index._usageResultCache ||
+        !langTraits(entry.language)?.physicalCallTokenSyntax) return null;
+    const memo = index._opMemo?.('callTokenSyntax', () => new Map());
+    let state = memo?.get(file);
+    // Preserve the existing query-tree LRU and avoid rehashing a hot tree.
+    if (!state && tree) return null;
+    if (!state || state.content !== content || state.hash !== entry.hash) {
+        const eligible = indexedContent(index, file, entry, content);
+        const mode = eligible ? syntaxMode('callToken', parseViewParts(entry)) : null;
+        state = { content, hash: entry.hash, mode, names: new Map(), lines: null };
+        memo?.set(file, state);
+    }
+    return state;
+}
+
+module.exports = { callTokenSyntax, declarationTokenSyntax };

package/core/reporting.js

@@ -15,6 +15,11 @@ const { summarizeCommandTrust } = require('./trust-matrix');
 const { projectComputedDispatch } = require('./ast-analysis');
 const { langTraits } = require('../languages');
 
+// Modules read lazily (load cycles), each resolved once: a require() per
+// call in hot paths was measurable (fix #436).
+let lazySharedModuleCache = null;
+const lazySharedModule = () => lazySharedModuleCache || (lazySharedModuleCache = require('./shared'));
+
 function matchesReportingScope(index, relativePath, options = {}) {
     if (!relativePath) return false;
     if (options.file && !relativePath.includes(options.file)) return false;
@@ -124,6 +129,7 @@ function getStats(index, options = {}) {
         // Ensure the calls cache is fully populated before counting.
         // First-time stats --hot may need to parse files to extract calls;
         // subsequent runs use the persisted calls cache.
+        require('./cache').ensureCallsCacheLoaded(index);
         if (typeof index.buildCalleeIndex === 'function' && !index.calleeIndex) {
             index.buildCalleeIndex();
         }
@@ -209,7 +215,7 @@ function getStats(index, options = {}) {
         // candidate set, the exact count, AND the upper bound (a bound that
         // still counted them stopped the early exit from firing, so the
         // orientation fell back to its approximate refinement budget).
-        const { inlineTestRanges, lineInRanges } = require('./shared');
+        const { inlineTestRanges, lineInRanges } = lazySharedModule();
         const inlineTestRangesByFile = new Map();
         const inInlineTest = (file, line) => {
             if (!file || !line) return false;
@@ -227,7 +233,7 @@ function getStats(index, options = {}) {
         // the exact passes never scan them (every per-site verdict is
         // file-local). Orientation on django spent most of its time
         // resolving the test suite's calls, which it then discarded.
-        const { isTestPath } = require('./shared');
+        const { isTestPath } = lazySharedModule();
         const countableFile = (filePath) => {
             if (!scopedPaths.has(filePath)) return false;
             const fileEntry = index.files.get(filePath);
@@ -307,7 +313,7 @@ function getStats(index, options = {}) {
                 if (upper === 0) continue;
                 if (index.files.get(symbol.file)?.isBundled) continue;
                 if (options.productionCallsOnly &&
-                    (require('./shared').isTestPath(symbol.relativePath) ||
+                    (lazySharedModule().isTestPath(symbol.relativePath) ||
                         inInlineTest(symbol.file, symbol.startLine))) continue;
                 const identity = `${symbol.file}:${symbol.startLine}:${name}:` +
                     `${symbol.className || symbol.receiver || ''}:${symbol.params || ''}`;
@@ -418,7 +424,7 @@ function getStats(index, options = {}) {
         const testPath = (file) => {
             let verdict = testPathMemo.get(file);
             if (verdict === undefined) {
-                verdict = require('./shared').isTestPath(file);
+                verdict = lazySharedModule().isTestPath(file);
                 testPathMemo.set(file, verdict);
             }
             return verdict;
@@ -744,7 +750,7 @@ function doctor(index, options = {}) {
     // Reflection/eval signals come from the shared text-blind-spot counter
     // (core/shared.js) — the SAME routine detectCompleteness uses for the about
     // footer, so the two never drift (field-report #2). Occurrence counts.
-    const { hasTextBlindspots, countTextBlindspots } = require('./shared');
+    const { hasTextBlindspots, countTextBlindspots } = lazySharedModule();
 
     const computedDispatch = projectComputedDispatch(index);
     for (const [filePath, fe] of index.files) {
@@ -1130,7 +1136,7 @@ function orient(index, options = {}) {
         in: options.in,
         exclude: options.exclude,
     };
-    const { isTestPath } = require('./shared');
+    const { isTestPath } = lazySharedModule();
     const hasProductionFiles = [...index.files.values()].some(fileEntry => {
         const relativePath = fileEntry.relativePath;
         return relativePath &&
@@ -1172,7 +1178,7 @@ function orient(index, options = {}) {
     let entrypoints = null;
     try {
         const { detectEntrypoints } = require('./entrypoints');
-        const { addTestExclusions } = require('./shared');
+        const { addTestExclusions } = lazySharedModule();
         const orientExclude = Array.isArray(options.exclude)
             ? options.exclude
             : (options.exclude

package/core/request-helpers.js

@@ -43,6 +43,8 @@ const JS_HTTP_PACKAGES = [
 ];
 const JS_HTTP_GLOBAL_CALLS = new Set(['fetch']);
 const JS_HTTP_GLOBAL_CTORS = new Set(['XMLHttpRequest', 'EventSource']);
+const JS_HTTP_CLIENT_TYPES = new Set(['AxiosInstance', 'AxiosStatic', 'KyInstance',
+    'Got', 'GotInstance', 'HttpClient', 'Dispatcher', 'Agent']);
 const PY_HTTP_MODULES = [
     'requests', 'httpx', 'aiohttp', 'urllib3', 'urllib.request', 'http.client', 'niquests', 'treq',
 ];
@@ -173,7 +175,7 @@ class RequestHelperProof {
     }
 
     /** Proof for the function expression being called. */
-    jsCallee(file, fn, depth, factory = false) {
+    jsCallee(file, fn, depth) {
         if (!fn || depth > MAX_RESOLVE) return unknown('depth');
         if (fn.type === 'identifier') {
             const decl = findDecl(this.sess, file, fn.text, fn);
@@ -201,9 +203,7 @@ class RequestHelperProof {
             // the method reads as one (`client.post`, `instance.request`);
             // a server built on an HTTP stack (`app.route(...)`) is not a
             // client.
-            // A factory call on a client value (`axios.create()`) yields a
-            // client value too.
-            if (!factory && (!prop || !CLIENT_METHOD.test(prop))) return unknown('method-not-request');
+            if (!prop || !CLIENT_METHOD.test(prop)) return unknown('method-not-request');
             return this.jsValue(file, obj, depth + 1);
         }
         if (fn.type === 'call_expression') return this.jsValue(file, fn, depth + 1);
@@ -296,7 +296,7 @@ class RequestHelperProof {
                     const spec = this.requireSpecOf({ valueNode: e });
                     return isHttpPackage(spec, JS_HTTP_PACKAGES) ? PROVEN : unknown('receiver-unproven');
                 }
-                return this.jsCallee(file, callee, depth + 1, true);
+                return this.jsFactory(file, callee, depth + 1);
             }
             default:
                 return unknown('receiver-unproven');
@@ -314,6 +314,59 @@ class RequestHelperProof {
         return last;
     }
 
+    /** A request result or server is not a client just because the function
+     *  that produced it uses an HTTP package. Follow factory return values. */
+    jsFactory(file, callee, depth) {
+        if (!callee || depth > MAX_RESOLVE) return unknown('receiver-unproven');
+        if (callee.type === 'member_expression') {
+            const name = field(callee, 'property')?.text;
+            if (name === 'create' || name === 'extend') {
+                return this.jsValue(file, unwrap(field(callee, 'object')), depth + 1);
+            }
+            return unknown('factory-unproven');
+        }
+        if (callee.type !== 'identifier') return unknown('factory-unproven');
+        const decl = findDecl(this.sess, file, callee.text, callee);
+        let target = decl ? { file, value: decl.count === 1 ? decl.valueNode : null } : null;
+        if (!decl) {
+            const binding = this.jsBinding(file, callee.text);
+            if (binding) {
+                if (binding.binding.module?.startsWith('@hey-api/client-') ||
+                    binding.binding.module === 'openapi-fetch') return PROVEN;
+                const rec = this.jsImportRecord(file, binding.binding, binding.original);
+                if (rec) target = { file: rec.file, value: rec.decl?.valueNode || rec.valueNode };
+            }
+        }
+        const fn = unwrap(target?.value);
+        if (!fn || !JS_FUNCTION_TYPES.has(fn.type)) return unknown('factory-unproven');
+        const body = field(fn, 'body');
+        if (!body) return unknown('factory-unproven');
+        const values = [];
+        const visit = node => {
+            if (node.type === 'return_statement') {
+                values.push(node.namedChild(0));
+                return;
+            }
+            for (const child of namedChildren(node)) {
+                if (!JS_FUNCTION_TYPES.has(child.type) && child.type !== 'class_declaration') visit(child);
+            }
+        };
+        if (body.type === 'statement_block') visit(body);
+        else values.push(body);
+        if (!values.length) return unknown('factory-unproven');
+        const proven = values.every(value => {
+            const v = unwrap(value);
+            if (v?.type !== 'object') return this.jsValue(target.file, v, depth + 1).proven;
+            const methods = namedChildren(v).filter(member =>
+                CLIENT_METHOD.test((field(member, 'key') || field(member, 'name'))?.text || ''));
+            return methods.length > 0 && methods.every(member => {
+                const impl = member.type === 'method_definition' ? member : unwrap(field(member, 'value'));
+                return impl && JS_FUNCTION_TYPES.has(impl.type) && this.jsFunction(target.file, impl, 0).proven;
+            });
+        });
+        return proven ? PROVEN : unknown('factory-unproven');
+    }
+
     /** A parameter proves a client only through its declared type or default. */
     jsParam(file, decl, depth) {
         const holder = decl.nameNode.parent;
@@ -321,7 +374,8 @@ class RequestHelperProof {
         if (typeNode) {
             const m = typeNode.text.replace(/^:\s*/, '').match(/^([A-Za-z_$][\w$]*)/);
             const b = m ? this.jsBinding(file, m[1]) : null;
-            if (b && isHttpPackage(b.binding.module, JS_HTTP_PACKAGES)) return PROVEN;
+            if (b && isHttpPackage(b.binding.module, JS_HTTP_PACKAGES) &&
+                JS_HTTP_CLIENT_TYPES.has(b.original)) return PROVEN;
         }
         const dflt = holder ? (field(holder, 'value') || field(holder, 'right')) : null;
         if (dflt) return this.jsValue(file, dflt, depth + 1);
@@ -374,6 +428,8 @@ class RequestHelperProof {
             return !!b && isHttpPackage(b.binding.module, JS_HTTP_PACKAGES);
         }
         if (callee.type === 'member_expression') {
+            if (CLIENT_METHOD.test(field(callee, 'property')?.text || '') &&
+                this.jsValue(file, unwrap(field(callee, 'object')), 0).proven) return true;
             let root = unwrap(field(callee, 'object'));
             while (root && root.type === 'member_expression') root = unwrap(field(root, 'object'));
             if (!root || root.type !== 'identifier') return false;
@@ -558,4 +614,4 @@ function locateCall(root, start, end, type) {
     return node;
 }
 
-module.exports = { RequestHelperProof, JS_HTTP_PACKAGES, PY_HTTP_MODULES };
+module.exports = { RequestHelperProof, JS_HTTP_PACKAGES, PY_HTTP_MODULES, pyImportedFunction };