cgraphx 2.0.1 → 2.0.3

package/dist/core/code/engine/core/ingestion/languages/typescript/cjs-export-assignment.js

@@ -0,0 +1,535 @@
+"use strict";
+/**
+ * Shadowed CommonJS export-assignment detection (issue #2723).
+ *
+ * The CJS declaration rules in the JS/TS scope queries bind the bare property
+ * name of `exports.X = function () {}` / `module.exports.X = (a) => a` into the
+ * enclosing module scope, so importers resolve to it by name. That is the whole
+ * point of #2723 — without it the graph node exists and nothing resolves to it.
+ *
+ * But a file may ALSO declare that same name lexically:
+ *
+ *   function dup(v) { return v; }
+ *   exports.dup = function (v) { return !v; };
+ *   function callIt(v) { return dup(v); }
+ *
+ * Then the module scope holds TWO declarations named `dup`, the name is
+ * ambiguous, and the resolver drops `callIt -> dup` altogether — an edge that
+ * resolved fine before #2723. A silently missing caller is worse than the gap
+ * #2723 set out to close, so the emitter drops the CJS declaration in exactly
+ * this case: the lexical declaration already supplies the module-scope name,
+ * so importers still resolve, and intra-module resolution is unchanged from
+ * before #2723.
+ *
+ * Only the `@declaration.function` match is suppressed. The graph node comes
+ * from a separate query (`tree-sitter-queries.ts`) and collapses onto the
+ * lexical declaration's node by name anyway, so no node is lost.
+ *
+ * Shared by both the JavaScript and TypeScript capture emitters — every
+ * grammar node named here (`assignment_expression`, `member_expression`,
+ * `property_identifier`, `function_declaration`, `lexical_declaration`,
+ * `variable_declaration`, `export_statement`) exists in both
+ * `tree-sitter-javascript` and `tree-sitter-typescript`.
+ *
+ * Pure given the input nodes. No I/O, no globals; the cache is keyed on the
+ * root node it derives from, so it cannot outlive its tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isModuleLevelThisAssignment = isModuleLevelThisAssignment;
+exports.isModuleLevelThisExport = isModuleLevelThisExport;
+exports.moduleLevelThisExportName = moduleLevelThisExportName;
+exports.cjsExportedNameFor = cjsExportedNameFor;
+exports.isUndeclarableThisMemberValue = isUndeclarableThisMemberValue;
+exports.isUnexportedMemberAssignmentValue = isUnexportedMemberAssignmentValue;
+exports.isShadowedCjsExportAssignment = isShadowedCjsExportAssignment;
+exports.cjsExportedName = cjsExportedName;
+exports.defaultExportNameCollides = defaultExportNameCollides;
+exports.isShadowedCjsExportAssignmentNode = isShadowedCjsExportAssignmentNode;
+/**
+ * Module-scope declared names per program root.
+ *
+ * Memoized because the emitter asks once per CJS export match: a file with
+ * 1000 `exports.X = function () {}` lines would otherwise re-walk the top
+ * level 1000 times, which is the O(n²) shape that has bitten this repo's
+ * scope capture before. Keyed on the root `SyntaxNode`, so it is dropped with
+ * the tree.
+ */
+const moduleScopeNamesByRoot = new WeakMap();
+/** Declaration nodes whose name binds directly in the enclosing scope. */
+const NAMED_DECLARATION_TYPES = new Set([
+    'function_declaration',
+    'generator_function_declaration',
+    'class_declaration',
+]);
+/** Declaration nodes that carry one or more `variable_declarator` children. */
+const VARIABLE_DECLARATION_TYPES = new Set(['lexical_declaration', 'variable_declaration']);
+/**
+ * Identifiers bound to the exports object at module scope, per program root.
+ *
+ * `const e = exports;` / `const e = module.exports;` makes `e.foo = fn` an
+ * export just as surely as `exports.foo = fn`. The queries cannot express
+ * "an identifier that happens to alias exports", so they match any identifier
+ * receiver and the emitters prune here.
+ *
+ * Memoized for the same reason as {@link moduleScopeDeclaredNames}: asked once
+ * per candidate assignment, and a large CommonJS module has many.
+ */
+const exportAliasesByRoot = new WeakMap();
+/** Nodes that introduce their own binding scope for the purposes below. */
+const BINDING_SCOPE_NODE_TYPES = new Set([
+    'function_declaration',
+    'generator_function_declaration',
+    'function_expression',
+    'generator_function',
+    'arrow_function',
+    'method_definition',
+]);
+/**
+ * True when the identifier `name` is SHADOWED by a local binding somewhere
+ * between `node` and the module root — a parameter, or a `var`/`let`/`const`
+ * declared inside an enclosing function.
+ *
+ * This is the difference between reading source and understanding it. The
+ * canonical UMD wrapper takes the exports object as a PARAMETER:
+ *
+ *   (function (exports) { exports.publicApi = function () {}; })(this);
+ *
+ * A text comparison sees `exports` and claims a module export. It is a local
+ * binding, so the assignment exports nothing — and treating it as an export
+ * both invents a symbol and, because the name then collides with the real
+ * module scope, deletes call edges that resolved before (#2729 review F2).
+ */
+function isShadowedByLocalBinding(node, name) {
+    for (let scope = node.parent; scope !== null; scope = scope.parent) {
+        if (!BINDING_SCOPE_NODE_TYPES.has(scope.type))
+            continue;
+        // Parameters of this function.
+        const params = scope.childForFieldName('parameters');
+        if (params !== null && declaresName(params, name))
+            return true;
+        // `var`/`let`/`const` declared directly in this function's body.
+        const body = scope.childForFieldName('body');
+        if (body !== null) {
+            for (const stmt of body.namedChildren) {
+                if (!VARIABLE_DECLARATION_TYPES.has(stmt.type))
+                    continue;
+                if (declaresName(stmt, name))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/** True when `subtree` binds `name` as an identifier (parameter or declarator). */
+function declaresName(subtree, name) {
+    const stack = [subtree];
+    while (stack.length > 0) {
+        const n = stack.pop();
+        if (n === undefined)
+            continue;
+        if (n.type === 'identifier' && n.text === name)
+            return true;
+        // Do not descend into nested function bodies — their bindings are not ours.
+        if (n !== subtree && BINDING_SCOPE_NODE_TYPES.has(n.type))
+            continue;
+        for (const child of n.namedChildren)
+            stack.push(child);
+    }
+    return false;
+}
+/**
+ * True when `node` is the `exports` / `module.exports` object itself AND that
+ * name is not shadowed by a local binding at this site.
+ */
+function isExportsObjectExpression(node) {
+    if (node.type === 'identifier') {
+        return node.text === 'exports' && !isShadowedByLocalBinding(node, 'exports');
+    }
+    if (node.type !== 'member_expression')
+        return false;
+    return (node.childForFieldName('object')?.text === 'module' &&
+        node.childForFieldName('property')?.text === 'exports' &&
+        !isShadowedByLocalBinding(node, 'module'));
+}
+/** The set of module-scope identifiers aliasing the exports object. */
+function exportAliases(root) {
+    const cached = exportAliasesByRoot.get(root);
+    if (cached !== undefined)
+        return cached;
+    const aliases = new Set();
+    for (const child of root.namedChildren) {
+        if (!VARIABLE_DECLARATION_TYPES.has(child.type))
+            continue;
+        for (const declarator of child.namedChildren) {
+            if (declarator.type !== 'variable_declarator')
+                continue;
+            const name = declarator.childForFieldName('name');
+            const value = declarator.childForFieldName('value');
+            if (name === null || name.type !== 'identifier' || value === null)
+                continue;
+            if (isExportsObjectExpression(value))
+                aliases.add(name.text);
+        }
+    }
+    exportAliasesByRoot.set(root, aliases);
+    return aliases;
+}
+/** Whether each program root is a CommonJS module, memoized. */
+const isCommonJsByRoot = new WeakMap();
+/** Function forms that BIND their own `this` (every form except an arrow). */
+const THIS_BINDING_NODE_TYPES = new Set([
+    'function_declaration',
+    'generator_function_declaration',
+    'function_expression',
+    'generator_function',
+    'method_definition',
+    'class_declaration',
+    'class',
+]);
+/**
+ * True when the file is a CommonJS module, so module-level `this` is
+ * `module.exports` rather than `undefined`.
+ *
+ * This gate is load-bearing, not decoration: `this.foo = fn` at the top level
+ * of an ESM file assigns to `undefined` and exports nothing, so indexing it as
+ * an export would be wrong for every `.mjs`, every `"type": "module"` package,
+ * and every `.ts` that compiles to ESM. An `import`/`export` statement makes
+ * the file unambiguously ESM; otherwise a `require()` call or an
+ * `exports`/`module` reference marks it CommonJS. A file with neither signal
+ * is left alone — silence is not evidence of CommonJS.
+ */
+function isCommonJsModule(root, filePath) {
+    // The extension settles it outright where Node itself does: `.cjs`/`.cts` are
+    // CommonJS whatever the body contains, `.mjs`/`.mts` are ESM. Without this a
+    // `.cjs` file whose only content is `this.x = fn` carries no AST signal and
+    // was classified non-CommonJS, silently dropping the export (#2729 review F14).
+    if (filePath !== undefined) {
+        if (/\.(cjs|cts)$/.test(filePath))
+            return true;
+        if (/\.(mjs|mts)$/.test(filePath))
+            return false;
+    }
+    const cached = isCommonJsByRoot.get(root);
+    if (cached !== undefined)
+        return cached;
+    let sawCjsSignal = false;
+    const visit = (node) => {
+        // An ESM statement settles it immediately: top-level `this` is undefined.
+        if (node.type === 'import_statement' || node.type === 'export_statement')
+            return false;
+        if (node.type === 'identifier' && (node.text === 'exports' || node.text === 'module'))
+            sawCjsSignal = true;
+        if (node.type === 'call_expression' && node.childForFieldName('function')?.text === 'require')
+            sawCjsSignal = true;
+        for (const child of node.namedChildren)
+            if (!visit(child))
+                return false;
+        return true;
+    };
+    const result = visit(root) && sawCjsSignal;
+    isCommonJsByRoot.set(root, result);
+    return result;
+}
+/**
+ * True when `assignment` is a `this.X = <function>` at MODULE level — i.e. no
+ * `this`-binding function encloses it — inside a CommonJS module, which makes
+ * it an export of `X`.
+ *
+ * Arrow functions are transparent here: ECMA-262 gives an arrow
+ * `[[ThisMode]] = lexical`, so a top-level arrow's `this` is still the
+ * module's. Every other function form binds its own receiver and stops the
+ * walk — that is an instance member, handled as a Method instead.
+ */
+/**
+ * True when `assignment` is a `this.X = <callable>` at MODULE level, regardless
+ * of module system.
+ *
+ * Distinct from {@link isModuleLevelThisExport}, which additionally requires the
+ * file to be CommonJS. A module-level `this` member in ESM (or in a file with no
+ * module-system signal) is neither an export nor an instance member — `this` is
+ * `undefined` there — so it should produce nothing rather than an ownerless
+ * `Method` node (#2729 review F13).
+ */
+function isModuleLevelThisAssignment(assignment) {
+    const left = assignment.type === 'assignment_expression' ? assignment.childForFieldName('left') : null;
+    if (left === null || left.type !== 'member_expression')
+        return false;
+    if (left.childForFieldName('object')?.type !== 'this')
+        return false;
+    const right = assignment.childForFieldName('right');
+    if (right === null || !CALLABLE_VALUE_TYPES.has(right.type))
+        return false;
+    for (let anc = assignment.parent; anc !== null; anc = anc.parent) {
+        if (THIS_BINDING_NODE_TYPES.has(anc.type))
+            return false;
+    }
+    return true;
+}
+function isModuleLevelThisExport(assignment, root, filePath) {
+    const left = assignment.type === 'assignment_expression' ? assignment.childForFieldName('left') : null;
+    if (left === null || left.type !== 'member_expression')
+        return false;
+    if (left.childForFieldName('object')?.type !== 'this')
+        return false;
+    for (let anc = assignment.parent; anc !== null; anc = anc.parent) {
+        if (THIS_BINDING_NODE_TYPES.has(anc.type))
+            return false;
+    }
+    return isCommonJsModule(root, filePath);
+}
+/** The property name of a module-level `this.X = fn` export, or null. */
+function moduleLevelThisExportName(assignment, root, filePath) {
+    if (!isModuleLevelThisExport(assignment, root, filePath))
+        return null;
+    const property = assignment.childForFieldName('left')?.childForFieldName('property');
+    return property?.type === 'property_identifier' ? property.text : null;
+}
+/** Right-hand-side node types that make a binding CALLABLE. */
+const CALLABLE_VALUE_TYPES = new Set([
+    'arrow_function',
+    'function_expression',
+    'generator_function',
+]);
+/**
+ * Collect the CALLABLE names `node` binds into its enclosing scope, into `out`.
+ *
+ * Callable-only is load-bearing. The guard exists to stop TWO declarations of
+ * one callable name making the name ambiguous, which drops the intra-module
+ * call edge. A non-callable binding cannot be a call target and so cannot
+ * create that ambiguity — including it instead deletes a genuine export:
+ *
+ *   let cache = null;
+ *   exports.cache = function (v) { cache = v; return cache; };
+ *
+ * With every module-scope name collected, `cache` matched the `let` and the
+ * export vanished entirely — no node, no edge (#2729 review F8).
+ */
+function collectDeclaredNames(node, out) {
+    if (NAMED_DECLARATION_TYPES.has(node.type)) {
+        const name = node.childForFieldName('name');
+        if (name !== null && name.type === 'identifier')
+            out.add(name.text);
+        return;
+    }
+    if (VARIABLE_DECLARATION_TYPES.has(node.type)) {
+        for (const declarator of node.namedChildren) {
+            if (declarator.type !== 'variable_declarator')
+                continue;
+            const name = declarator.childForFieldName('name');
+            // Destructuring patterns bind several names; they never collide with a
+            // CJS export assignment's single property name in a way this guard
+            // needs to model, so only plain identifiers are collected.
+            if (name === null || name.type !== 'identifier')
+                continue;
+            const value = declarator.childForFieldName('value');
+            if (value !== null && CALLABLE_VALUE_TYPES.has(value.type))
+                out.add(name.text);
+        }
+        return;
+    }
+    // `export function f() {}` / `export const f = …` — the binding is the
+    // wrapped declaration's, so recurse one level through the wrapper.
+    if (node.type === 'export_statement') {
+        const declaration = node.childForFieldName('declaration');
+        if (declaration !== null)
+            collectDeclaredNames(declaration, out);
+    }
+}
+/** The set of names declared at module scope (top level) of `root`. */
+function moduleScopeDeclaredNames(root) {
+    const cached = moduleScopeNamesByRoot.get(root);
+    if (cached !== undefined)
+        return cached;
+    const names = new Set();
+    for (const child of root.namedChildren)
+        collectDeclaredNames(child, names);
+    moduleScopeNamesByRoot.set(root, names);
+    return names;
+}
+/**
+ * The property name of the `exports.X = …` / `module.exports.X = …` assignment
+ * whose right-hand side is `node`, or null when `node` is not such a value.
+ *
+ * Mirrors the receiver pinning in the scope queries: a bare `exports` receiver,
+ * or a `module.exports` member expression. Any other receiver (`Foo.prototype`,
+ * `this`, an aliased `const e = exports`) returns null, so this guard never
+ * fires for a construct the CJS declaration rules did not create.
+ */
+function cjsExportedPropertyName(node, root) {
+    const assignment = node.parent;
+    if (assignment === null || assignment.type !== 'assignment_expression')
+        return null;
+    if (assignment.childForFieldName('right')?.id !== node.id)
+        return null;
+    const left = assignment.childForFieldName('left');
+    if (left === null || left.type !== 'member_expression')
+        return null;
+    const property = left.childForFieldName('property');
+    if (property === null || property.type !== 'property_identifier')
+        return null;
+    const receiver = left.childForFieldName('object');
+    if (receiver === null)
+        return null;
+    if (isExportsObjectExpression(receiver))
+        return property.text;
+    // An identifier aliasing the exports object (`const e = exports; e.foo = fn`).
+    // The alias is a MODULE-scope binding, so it only means "exports" where it is
+    // not shadowed — `const e = exports; function f(e) { e.x = fn }` assigns to
+    // the parameter, not to the module (#2729 review F2).
+    if (receiver.type === 'identifier' &&
+        root !== undefined &&
+        exportAliases(root).has(receiver.text) &&
+        !isShadowedByLocalBinding(receiver, receiver.text))
+        return property.text;
+    return null;
+}
+/**
+ * The name this assignment exports, or null when it exports nothing.
+ *
+ * Takes the VALUE node (the function literal) and the program root, because
+ * alias resolution is a whole-file question. Used by the capture emitters to
+ * keep the widened `<identifier>.X = fn` match only when the receiver really
+ * is the exports object.
+ */
+function cjsExportedNameFor(node, root) {
+    return cjsExportedPropertyName(node, root);
+}
+/**
+ * True when `node` is the value of a `this.X = fn` assignment that declares
+ * NOTHING at module scope — either because a function encloses it (an instance
+ * member, which gets a Method + owner edge instead) or because the file is not
+ * CommonJS (top-level `this` is undefined in ESM).
+ */
+function isUndeclarableThisMemberValue(node, root) {
+    const assignment = node.parent;
+    if (assignment === null || assignment.type !== 'assignment_expression')
+        return false;
+    if (assignment.childForFieldName('right')?.id !== node.id)
+        return false;
+    const left = assignment.childForFieldName('left');
+    if (left === null || left.type !== 'member_expression')
+        return false;
+    if (left.childForFieldName('object')?.type !== 'this')
+        return false;
+    return !isModuleLevelThisExport(assignment, root);
+}
+/**
+ * True when `node` is the value of a `<identifier>.<member> = fn` assignment
+ * whose receiver is NOT the exports object — the over-match the widened
+ * member-assignment rule accepts so an `exports` alias can be recognised.
+ *
+ * Such a receiver declares nothing at module scope: `obj.handler = fn` binds a
+ * property of `obj`, not a module symbol named `handler`. Prototype and `this`
+ * receivers are not identifiers, so they never reach this guard and keep their
+ * own (Method) treatment.
+ */
+function isUnexportedMemberAssignmentValue(node, root) {
+    const assignment = node.parent;
+    if (assignment === null || assignment.type !== 'assignment_expression')
+        return false;
+    if (assignment.childForFieldName('right')?.id !== node.id)
+        return false;
+    const left = assignment.childForFieldName('left');
+    if (left === null || left.type !== 'member_expression')
+        return false;
+    if (left.childForFieldName('object')?.type !== 'identifier')
+        return false;
+    return cjsExportedPropertyName(node, root) === null;
+}
+/**
+ * True when `node` (an `arrow_function` / `function_expression` /
+ * `generator_function`) is the value of a CJS export assignment whose property
+ * name is ALREADY declared at module scope of `root`.
+ *
+ * False for a CJS export whose name is declared only by the assignment (the
+ * ordinary #2723 case — the declaration must be emitted), and false for
+ * anything that is not a CJS export assignment at all.
+ */
+function isShadowedCjsExportAssignment(node, root) {
+    const exportedName = cjsExportedName(node, root);
+    if (exportedName === null)
+        return false;
+    return moduleScopeDeclaredNames(root).has(exportedName);
+}
+/**
+ * The module-scope name this assignment value exports, across EVERY export
+ * form — direct `exports.X`, `module.exports.X`, an alias receiver, a
+ * module-level `this.X`, and the anonymous/named default export.
+ *
+ * One entry point so the shadow guard cannot silently miss a form. Previously
+ * it consulted only the direct path: the alias path was skipped because `root`
+ * was not forwarded, `this` never reached it at all, and the default export had
+ * no check — three holes that each dropped a real call edge or, for the
+ * default, fabricated a self-recursive one (#2729 review F3/F4).
+ */
+function cjsExportedName(value, root) {
+    const direct = cjsExportedPropertyName(value, root);
+    if (direct !== null)
+        return direct;
+    const assignment = value.parent;
+    if (assignment === null || assignment.type !== 'assignment_expression')
+        return null;
+    if (assignment.childForFieldName('right')?.id !== value.id)
+        return null;
+    // Module-level `this.X = fn` in CommonJS — `this` IS `module.exports`.
+    const viaThis = moduleLevelThisExportName(assignment, root);
+    if (viaThis !== null)
+        return viaThis;
+    // `module.exports = fn` — the whole module is the callable. A named function
+    // expression names itself; an anonymous one takes the file-derived name,
+    // which the caller supplies since a tree has no file path.
+    if (isCjsDefaultExportAssignmentNode(assignment)) {
+        return assignment.childForFieldName('right')?.childForFieldName('name')?.text ?? null;
+    }
+    return null;
+}
+/** `module.exports = <callable>`, named or anonymous. */
+function isCjsDefaultExportAssignmentNode(assignment) {
+    const right = assignment.childForFieldName('right');
+    if (right === null || !CALLABLE_VALUE_TYPES.has(right.type))
+        return false;
+    const left = assignment.childForFieldName('left');
+    if (left === null || left.type !== 'member_expression')
+        return false;
+    return (left.childForFieldName('object')?.text === 'module' &&
+        left.childForFieldName('property')?.text === 'exports');
+}
+/**
+ * True when the DERIVED default-export name collides with a callable the module
+ * already declares.
+ *
+ * `format.js` containing `function format() {}` plus an anonymous
+ * `module.exports = function () { return format(v); }` merged both onto one
+ * node, and the inner call to `format` then resolved to the merged node —
+ * fabricating a self-recursion edge present in no source (#2729 review F4).
+ * A fabricated edge is worse than a missing one: it misleads `impact` with a
+ * caller that does not exist.
+ */
+function defaultExportNameCollides(assignment, root, derivedName) {
+    if (!isCjsDefaultExportAssignmentNode(assignment))
+        return false;
+    return moduleScopeDeclaredNames(root).has(derivedName);
+}
+/**
+ * Same question as {@link isShadowedCjsExportAssignment}, asked of the
+ * ASSIGNMENT node rather than its value — the shape `provider.labelOverride`
+ * receives, since the graph-node capture is anchored on the assignment.
+ *
+ * Used to drop the graph node too, not just the scope declaration. When the
+ * shadowed name is a `function`, the node collapsed onto the lexical
+ * declaration's node anyway (same label, same id), but a `class Dup {}` plus
+ * `exports.Dup = function () {}` produced `Class:f:Dup` AND an orphan
+ * `Function:f:Dup` — a node nothing can reach, because the declaration that
+ * would have made it reachable is suppressed by the rule above.
+ */
+function isShadowedCjsExportAssignmentNode(node, root) {
+    if (node.type !== 'assignment_expression')
+        return false;
+    const value = node.childForFieldName('right');
+    if (value === null)
+        return false;
+    return isShadowedCjsExportAssignment(value, root);
+}
+// `Foo.prototype.bar = function () {}` is handled as a MEMBER assignment — see
+// `prototypeAssignmentOwnerName` / `findMemberAssignmentOwnerInfo` in
+// `utils/ast-helpers.ts`, next to the object-literal owner helper it mirrors.