onbuzz 5.1.0 → 5.3.0

package/src/tools/importAnalysis/callableChecker.js

@@ -0,0 +1,599 @@
+/**
+ * Callable checker — static detection of "<x> is not a function" /
+ * "<obj>.<method> is not a function" runtime TypeErrors.
+ *
+ * These errors fire at runtime when you call a value that isn't callable: a
+ * renamed/removed export, a default-vs-named import mix-up, a typo'd method, or
+ * a value (object/string/instance) invoked as a function. In dynamic JS the
+ * callee can come from anywhere, so NO static tool catches every case without
+ * false positives. This module catches the subset that resolves through the
+ * import/export graph and through simple local bindings, and tags every finding
+ * with a CONFIDENCE so consumers can tell certain findings from speculative
+ * ones:
+ *
+ *   high   — resolved through the import/export graph (a fully-enumerable local
+ *            module), or a local binding provably bound to a non-callable value
+ *            and never reassigned. Safe to act on.
+ *   medium — a local instance (`new Foo()`) or local object literal whose member
+ *            set is known and doesn't contain the called method.
+ *   low    — best-effort: the target module isn't fully enumerable (has a
+ *            wildcard re-export) so the symbol *might* exist; treat as a hint.
+ *
+ * Anything we can't resolve confidently is skipped, not guessed.
+ *
+ * Pure + fs-free: callers pass file contents in, which keeps it unit-testable.
+ */
+
+import { parse } from '@babel/parser';
+import _traverse from '@babel/traverse';
+
+// @babel/traverse ships CJS; under ESM the callable is on `.default`.
+const traverse = _traverse.default || _traverse;
+
+const BASE_PLUGINS = [
+  'jsx',
+  'classProperties',
+  'classPrivateProperties',
+  'classPrivateMethods',
+  'objectRestSpread',
+  'optionalChaining',
+  'nullishCoalescingOperator',
+  'dynamicImport',
+  'topLevelAwait',
+  'decorators-legacy',
+  'importAssertions',
+];
+
+/** Kinds a binding/export can resolve to. function/class are callable-ish. */
+const CALLABLE_KINDS = new Set(['function', 'class', 'unknown']);
+
+/**
+ * Parse source to a Babel AST. Returns null on unrecoverable parse failure
+ * (the file is then skipped rather than crashing the whole analysis).
+ * @param {string} code
+ * @param {{ts?: boolean}} [opts]
+ * @returns {object|null}
+ */
+export function parseModule(code, { ts = false } = {}) {
+  const plugins = ts ? [...BASE_PLUGINS, 'typescript'] : [...BASE_PLUGINS];
+  try {
+    return parse(code, {
+      sourceType: 'unambiguous',
+      allowReturnOutsideFunction: true,
+      errorRecovery: true,
+      plugins,
+    });
+  } catch {
+    return null;
+  }
+}
+
+/** True for the AST node kinds that produce a directly-callable value. */
+function initKind(node) {
+  if (!node) return 'unknown';
+  switch (node.type) {
+    case 'ArrowFunctionExpression':
+    case 'FunctionExpression':
+      return 'function';
+    case 'ClassExpression':
+      return 'class';
+    case 'ObjectExpression':
+      return 'object';
+    case 'NewExpression':
+      return 'instance';
+    case 'ArrayExpression':
+    case 'StringLiteral':
+    case 'NumericLiteral':
+    case 'BooleanLiteral':
+    case 'NullLiteral':
+    case 'BigIntLiteral':
+    case 'TemplateLiteral':
+      return 'value';
+    // Could resolve to a function at runtime → don't guess.
+    case 'CallExpression':
+    case 'MemberExpression':
+    case 'Identifier':
+    case 'ConditionalExpression':
+    case 'LogicalExpression':
+    case 'AwaitExpression':
+    default:
+      return 'unknown';
+  }
+}
+
+/** A non-callable kind is one where calling it throws "is not a function". */
+function isNonCallable(kind) {
+  return kind === 'object' || kind === 'value' || kind === 'instance';
+}
+
+/** Member-expression / identifier callee → readable text for messages. */
+export function calleeToString(node) {
+  if (!node) return '<unknown>';
+  if (node.type === 'Identifier') return node.name;
+  if (node.type === 'ThisExpression') return 'this';
+  if (node.type === 'MemberExpression') {
+    const obj = calleeToString(node.object);
+    const prop = node.computed
+      ? '[…]'
+      : node.property?.name ?? '<prop>';
+    return `${obj}.${prop}`;
+  }
+  return '<expr>';
+}
+
+/** Collect the member names (and kinds) declared in an ObjectExpression. */
+function objectMembers(objNode) {
+  const members = new Map();
+  let complete = true;
+  for (const prop of objNode.properties || []) {
+    if (prop.type === 'SpreadElement') {
+      complete = false; // ...spread merges unknown keys
+      continue;
+    }
+    if ((prop.type === 'ObjectMethod' || prop.type === 'ObjectProperty') && prop.computed) {
+      complete = false; // { [expr]: … } — key is not statically known
+      continue;
+    }
+    if (prop.type === 'ObjectMethod' && prop.key) {
+      members.set(prop.key.name ?? String(prop.key.value), prop.kind === 'get' ? 'unknown' : 'function');
+    } else if (prop.type === 'ObjectProperty' && prop.key) {
+      const name = prop.key.name ?? (prop.key.value != null ? String(prop.key.value) : null);
+      if (name != null) members.set(name, initKind(prop.value));
+    }
+  }
+  return { members, complete };
+}
+
+/** Method names (and that they're functions) declared on a class body. */
+function classMethods(classNode) {
+  const methods = new Map();
+  // A superclass we don't resolve here, or any computed member name, means the
+  // member set is not fully enumerable.
+  let complete = !classNode.superClass;
+  for (const el of classNode.body?.body || []) {
+    if (el.computed && (el.type === 'ClassMethod' || el.type === 'ClassPrivateMethod' || el.type === 'ClassProperty')) {
+      complete = false;
+      continue;
+    }
+    if ((el.type === 'ClassMethod' || el.type === 'ClassPrivateMethod') && el.key) {
+      const name = el.key.name ?? String(el.key.value);
+      // getters return arbitrary values; don't assume callable.
+      methods.set(name, el.kind === 'get' ? 'unknown' : 'function');
+    } else if (el.type === 'ClassProperty' && el.key) {
+      methods.set(el.key.name ?? String(el.key.value), initKind(el.value));
+    }
+  }
+  return { methods, complete };
+}
+
+/** Lightweight recursive AST walk invoking visit(node) for every node. */
+function walk(node, visit) {
+  if (!node || typeof node.type !== 'string') return;
+  visit(node);
+  for (const key of Object.keys(node)) {
+    if (key === 'loc' || key === 'start' || key === 'end' || key === 'leadingComments' || key === 'trailingComments') continue;
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const c of child) if (c && typeof c.type === 'string') walk(c, visit);
+    } else if (child && typeof child.type === 'string') {
+      walk(child, visit);
+    }
+  }
+}
+
+/**
+ * Extract, from a parsed module, everything the cross-file checker needs:
+ * its imports, top-level bindings (with kinds + reassignment), declared
+ * classes/objects, and its export table (name→kind) with a `fullyEnumerable`
+ * flag.
+ * @param {object} ast
+ * @returns {object}
+ */
+export function collectModuleInfo(ast) {
+  const imports = new Map();      // localName → { type, source, importedName }
+  const bindings = new Map();     // localName → { kind, reassigned, instanceOf?, members?, membersComplete? }
+  const classes = new Map();      // className → { methods:Map, complete }
+  const exportsTable = new Map(); // exportedName → { kind }
+  let fullyEnumerable = true;     // false once we hit export*/dynamic exports
+  let hasDefault = false;
+  let defaultKind = 'unknown';
+  // Shape of the DEFAULT export value, for `import api from …; api.foo()`:
+  //   { kind:'object', members:Map, complete:bool } | { kind:'instance', instanceOf } | null
+  let defaultShape = null;
+
+  const body = ast?.program?.body || [];
+
+  // ---- Pass 1: imports, top-level declarations, class/object shapes ----
+  const setBinding = (name, info) => {
+    if (bindings.has(name)) bindings.get(name).reassigned = true;
+    else bindings.set(name, { reassigned: false, ...info });
+  };
+
+  // Register a Function/Class/Variable declaration into bindings + classes.
+  // Used both for bare top-level decls and for `export <decl>` (unwrapped).
+  const registerDeclaration = (decl) => {
+    if (!decl) return;
+    if (decl.type === 'FunctionDeclaration' && decl.id) {
+      setBinding(decl.id.name, { kind: 'function' });
+    } else if (decl.type === 'ClassDeclaration' && decl.id) {
+      setBinding(decl.id.name, { kind: 'class' });
+      classes.set(decl.id.name, classMethods(decl));
+    } else if (decl.type === 'VariableDeclaration') {
+      for (const d of decl.declarations) {
+        if (d.id.type !== 'Identifier') continue; // skip destructuring
+        const info = { kind: initKind(d.init) };
+        if (d.init?.type === 'ObjectExpression') {
+          const { members, complete } = objectMembers(d.init);
+          info.members = members;
+          info.membersComplete = complete;
+        } else if (d.init?.type === 'NewExpression' && d.init.callee?.type === 'Identifier') {
+          info.instanceOf = d.init.callee.name;
+        } else if (d.init?.type === 'ClassExpression') {
+          classes.set(d.id.name, classMethods(d.init));
+        }
+        setBinding(d.id.name, info);
+      }
+    }
+  };
+
+  for (const node of body) {
+    if (node.type === 'ImportDeclaration') {
+      const source = node.source.value;
+      for (const spec of node.specifiers) {
+        if (spec.type === 'ImportDefaultSpecifier') {
+          imports.set(spec.local.name, { type: 'default', source, importedName: 'default' });
+        } else if (spec.type === 'ImportNamespaceSpecifier') {
+          imports.set(spec.local.name, { type: 'namespace', source, importedName: '*' });
+        } else if (spec.type === 'ImportSpecifier') {
+          imports.set(spec.local.name, {
+            type: 'named',
+            source,
+            importedName: spec.imported.name ?? spec.imported.value,
+          });
+        }
+      }
+    } else if (node.type === 'ExportNamedDeclaration' && node.declaration) {
+      registerDeclaration(node.declaration);            // export const/function/class …
+    } else if (node.type === 'ExportDefaultDeclaration' && node.declaration?.type === 'ClassDeclaration' && node.declaration.id) {
+      classes.set(node.declaration.id.name, classMethods(node.declaration)); // export default class Foo
+    } else {
+      registerDeclaration(node);                          // bare top-level decl
+    }
+  }
+
+  // Re-scan for ANY reassignment so we never flag a binding that later changes.
+  walk(ast.program, (n) => {
+    if (n.type === 'AssignmentExpression' && n.left.type === 'Identifier' && bindings.has(n.left.name)) {
+      const b = bindings.get(n.left.name);
+      b.reassigned = true;
+      // If reassigned to a function/unknown, treat as callable from now on.
+      const k = initKind(n.right);
+      if (CALLABLE_KINDS.has(k)) b.kind = 'unknown';
+    }
+  });
+
+  // ---- Pass 2: export table ----
+  const kindForExportedLocal = (name) => {
+    if (bindings.has(name)) return bindings.get(name).kind;
+    if (imports.has(name)) return 'unknown'; // re-exported import; don't guess
+    return 'unknown';
+  };
+
+  for (const node of body) {
+    switch (node.type) {
+      case 'ExportNamedDeclaration': {
+        if (node.source) {
+          // `export { a, b } from './x'` — names known, kinds not.
+          for (const spec of node.specifiers) {
+            exportsTable.set(spec.exported.name ?? spec.exported.value, { kind: 'unknown' });
+          }
+          break;
+        }
+        if (node.declaration) {
+          const decl = node.declaration;
+          if (decl.type === 'FunctionDeclaration' && decl.id) {
+            exportsTable.set(decl.id.name, { kind: 'function' });
+          } else if (decl.type === 'ClassDeclaration' && decl.id) {
+            exportsTable.set(decl.id.name, { kind: 'class' });
+          } else if (decl.type === 'VariableDeclaration') {
+            for (const d of decl.declarations) {
+              if (d.id.type === 'Identifier') exportsTable.set(d.id.name, { kind: initKind(d.init) });
+            }
+          }
+        }
+        for (const spec of node.specifiers || []) {
+          if (spec.type === 'ExportSpecifier') {
+            const exported = spec.exported.name ?? spec.exported.value;
+            const local = spec.local?.name ?? exported;
+            exportsTable.set(exported, { kind: kindForExportedLocal(local) });
+          }
+        }
+        break;
+      }
+      case 'ExportDefaultDeclaration': {
+        hasDefault = true;
+        const d = node.declaration;
+        if (d.type === 'FunctionDeclaration') defaultKind = 'function';
+        else if (d.type === 'ClassDeclaration') defaultKind = 'class';
+        else if (d.type === 'Identifier') {
+          defaultKind = kindForExportedLocal(d.name);
+          defaultShape = shapeOfLocal(d.name, bindings);
+        } else {
+          defaultKind = initKind(d);
+          if (d.type === 'ObjectExpression') {
+            const { members, complete } = objectMembers(d);
+            defaultShape = { kind: 'object', members, complete };
+          } else if (d.type === 'NewExpression' && d.callee?.type === 'Identifier') {
+            defaultShape = { kind: 'instance', instanceOf: d.callee.name };
+          }
+        }
+        exportsTable.set('default', { kind: defaultKind });
+        break;
+      }
+      case 'ExportAllDeclaration':
+        fullyEnumerable = false; // `export * from …` — names unknowable here
+        break;
+    }
+  }
+
+  // ---- CommonJS exports (best-effort, AST-level) ----
+  walk(ast.program, (n) => {
+    if (n.type !== 'AssignmentExpression' || n.left.type !== 'MemberExpression') return;
+    const left = n.left;
+    const obj = left.object;
+    const prop = !left.computed ? left.property?.name : null;
+    // module.exports = …
+    if (obj.type === 'Identifier' && obj.name === 'module' && prop === 'exports') {
+      hasDefault = true;
+      if (n.right.type === 'ObjectExpression') {
+        const { members, complete } = objectMembers(n.right);
+        for (const [k, v] of members) exportsTable.set(k, { kind: v });
+        if (!complete) fullyEnumerable = false;
+        defaultShape = { kind: 'object', members, complete };
+      } else {
+        defaultKind = initKind(n.right);
+        exportsTable.set('default', { kind: defaultKind });
+        if (n.right.type === 'NewExpression' && n.right.callee?.type === 'Identifier') {
+          defaultShape = { kind: 'instance', instanceOf: n.right.callee.name };
+        }
+      }
+    } else if (obj.type === 'Identifier' && obj.name === 'exports' && prop) {
+      // exports.foo = …
+      exportsTable.set(prop, { kind: initKind(n.right) });
+    } else if (
+      obj.type === 'MemberExpression' && !obj.computed &&
+      obj.object.type === 'Identifier' && obj.object.name === 'module' &&
+      obj.property.name === 'exports' && prop
+    ) {
+      // module.exports.foo = …
+      exportsTable.set(prop, { kind: initKind(n.right) });
+    }
+  });
+
+  return { imports, bindings, classes, exportsTable, fullyEnumerable, hasDefault, defaultKind, defaultShape };
+}
+
+/** Shape ({object|instance}) of a local binding, for default-export resolution. */
+function shapeOfLocal(name, bindings) {
+  const b = bindings.get(name);
+  if (!b) return null;
+  if (b.members) return { kind: 'object', members: b.members, complete: b.membersComplete };
+  if (b.instanceOf) return { kind: 'instance', instanceOf: b.instanceOf };
+  return null;
+}
+
+/**
+ * Analyze one parsed module's call sites against the project's module table.
+ *
+ * @param {object} args
+ * @param {object} args.ast            Parsed AST of the file under analysis.
+ * @param {object} args.info           collectModuleInfo(ast) for this file.
+ * @param {string} args.file           Display path for findings.
+ * @param {(owner:object, source:string)=>object|null} args.resolve
+ *        Maps (owning module info, import source string) to the imported
+ *        module's `info` object, or null for external/unresolved. The owner is
+ *        threaded so sources resolve relative to whichever module declared the
+ *        import (a default-instance's class is imported in the EXPORTING module,
+ *        not the file under analysis).
+ * @returns {Array<{file,line,column,callee,reason,confidence}>}
+ */
+export function analyzeCalls({ ast, info, file, resolve }) {
+  const findings = [];
+  const add = (node, callee, reason, confidence) => {
+    findings.push({
+      file,
+      line: node.loc?.start?.line ?? null,
+      column: node.loc?.start?.column ?? null,
+      callee,
+      reason,
+      confidence,
+    });
+  };
+
+  // Scope-aware: a name is only the module-level import/binding when it is NOT
+  // shadowed by a closer scope (function param, local const/let/var, catch
+  // param, block-scoped decl). getBinding returns the nearest declaration; if
+  // that lives outside the Program scope, the call refers to the local, which
+  // we don't track — so we skip rather than risk a false positive.
+  const isModuleLevel = (path, name) => {
+    const binding = path.scope.getBinding(name);
+    return !binding || binding.scope.block.type === 'Program';
+  };
+
+  const visitCall = (path) => {
+    const node = path.node;
+    const callee = node.callee;
+    if (!callee) return;
+
+    // ---- callee is a bare identifier: foo() ----
+    if (callee.type === 'Identifier') {
+      const name = callee.name;
+      if (!isModuleLevel(path, name)) return; // shadowed by a local binding
+      const imp = info.imports.get(name);
+      if (imp) {
+        checkImportedCall({ imp, asMethod: null, node, calleeText: name, owner: info, resolve, add });
+        return;
+      }
+      const b = info.bindings.get(name);
+      if (b && !b.reassigned && isNonCallable(b.kind)) {
+        add(node, name, `'${name}' is ${article(b.kind)} ${b.kind}, not a function`, 'high');
+      }
+      return;
+    }
+
+    // ---- callee is a member expression: obj.method() ----
+    if ((callee.type === 'MemberExpression' || callee.type === 'OptionalMemberExpression') && !callee.computed) {
+      const objNode = callee.object;
+      const method = callee.property?.name;
+      if (!method || objNode.type !== 'Identifier') return; // skip this.x(), a.b.c(), computed
+      const objName = objNode.name;
+      if (!isModuleLevel(path, objName)) return; // receiver shadowed by a local
+      const calleeText = `${objName}.${method}`;
+
+      const imp = info.imports.get(objName);
+      if (imp) {
+        checkImportedCall({ imp, asMethod: method, node, calleeText, owner: info, resolve, add });
+        return;
+      }
+
+      const b = info.bindings.get(objName);
+      if (!b || b.reassigned) return;
+
+      // local object literal: const o = { a, b }; o.missing()
+      if (b.members && b.membersComplete) {
+        if (!b.members.has(method)) {
+          add(node, calleeText, `'${objName}' has no member '${method}'`, 'medium');
+        } else if (isNonCallable(b.members.get(method))) {
+          add(node, calleeText, `'${objName}.${method}' is not a function`, 'medium');
+        }
+        return;
+      }
+
+      // local instance: const x = new Foo(); x.missing()
+      if (b.instanceOf) {
+        const cls = resolveClass(b.instanceOf, info, resolve);
+        if (cls && cls.complete) {
+          if (!cls.methods.has(method)) {
+            add(node, calleeText, `'${b.instanceOf}' instance has no method '${method}'`, 'medium');
+          } else if (isNonCallable(cls.methods.get(method))) {
+            add(node, calleeText, `'${objName}.${method}' is not a function`, 'medium');
+          }
+        }
+      }
+    }
+  };
+
+  traverse(ast, {
+    CallExpression: visitCall,
+    OptionalCallExpression: visitCall,
+  });
+
+  return findings;
+}
+
+/**
+ * Resolve a class by name to its {methods, complete}, locally or via a NAMED
+ * import. Default-imported classes are skipped (we don't track the default's
+ * original class name across modules) — returning null means "don't flag",
+ * which keeps us from emitting false positives.
+ */
+function resolveClass(className, owner, resolve) {
+  if (owner.classes.has(className)) return owner.classes.get(className);
+  const imp = owner.imports.get(className);
+  if (!imp || imp.type !== 'named') return null;
+  const mod = resolve(owner, imp.source);
+  if (!mod) return null;
+  return mod.classes.get(imp.importedName) || null;
+}
+
+/**
+ * Shared logic for a call whose receiver (or callee) is an imported binding.
+ * Handles the three import flavours with their correct runtime semantics:
+ *   - namespace (`import * as M`): M.x is named export x; M() is calling the
+ *     namespace object (never a function).
+ *   - default   (`import api`): api itself is the default export VALUE; api.x is
+ *     a property of that value (resolved via the module's default shape), NOT a
+ *     named export.
+ *   - named     (`import { foo }`): foo() invokes named export foo.
+ */
+function checkImportedCall({ imp, asMethod, node, calleeText, owner, resolve, add }) {
+  const mod = resolve(owner, imp.source);
+  if (!mod) return; // external / unresolved / unparsed → can't know
+
+  // ---------- direct call of the imported binding: foo() / M() / default() ----------
+  if (asMethod === null) {
+    if (imp.type === 'namespace') {
+      add(node, calleeText, `'${calleeText}' is a module namespace object, not a function`, 'high');
+      return;
+    }
+    const wantName = imp.type === 'default' ? 'default' : imp.importedName;
+    const entry = mod.exportsTable.get(wantName);
+    if (entry) {
+      if (isNonCallable(entry.kind)) {
+        add(node, calleeText, `'${calleeText}' is ${article(entry.kind)} ${entry.kind} export, not a function`, 'high');
+      }
+      return;
+    }
+    reportMissing(mod, imp, wantName, node, calleeText, add);
+    return;
+  }
+
+  // ---------- member call on the imported binding: M.x() / api.x() ----------
+  if (imp.type === 'namespace') {
+    // M.x → named export x of the module.
+    const entry = mod.exportsTable.get(asMethod);
+    if (entry) {
+      if (isNonCallable(entry.kind)) {
+        add(node, calleeText, `'${calleeText}' is ${article(entry.kind)} ${entry.kind} export, not a function`, 'high');
+      }
+      return;
+    }
+    reportMissing(mod, imp, asMethod, node, calleeText, add);
+    return;
+  }
+
+  if (imp.type === 'default') {
+    // api.x → property of the default-export VALUE. Resolve its shape; skip if
+    // unknown (avoids false positives on opaque default exports).
+    const shape = mod.defaultShape;
+    if (!shape) return;
+    if (shape.kind === 'object' && shape.complete) {
+      if (!shape.members.has(asMethod)) {
+        add(node, calleeText, `default export of '${imp.source}' has no member '${asMethod}'`, 'medium');
+      } else if (isNonCallable(shape.members.get(asMethod))) {
+        add(node, calleeText, `'${calleeText}' is not a function`, 'medium');
+      }
+      return;
+    }
+    if (shape.kind === 'instance') {
+      const cls = resolveClass(shape.instanceOf, mod, resolve);
+      if (cls && cls.complete) {
+        if (!cls.methods.has(asMethod)) {
+          add(node, calleeText, `default export instance of '${imp.source}' has no method '${asMethod}'`, 'medium');
+        } else if (isNonCallable(cls.methods.get(asMethod))) {
+          add(node, calleeText, `'${calleeText}' is not a function`, 'medium');
+        }
+      }
+      return;
+    }
+    return;
+  }
+
+  // imp.type === 'named' with a member call (foo.bar()): foo is the named export
+  // value; bar is its property. Too deep to resolve safely → skip.
+}
+
+/** Emit a "not exported / not found" finding, downgraded for wildcard modules. */
+function reportMissing(mod, imp, wantName, node, calleeText, add) {
+  if (mod.fullyEnumerable) {
+    add(node, calleeText, `'${calleeText}' — '${wantName}' is not exported by '${imp.source}'`, 'high');
+  } else {
+    add(node, calleeText, `'${calleeText}' — '${wantName}' not found in '${imp.source}' (has wildcard re-exports; may be valid)`, 'low');
+  }
+}
+
+function article(kind) {
+  return /^[aeiou]/.test(kind) ? 'an' : 'a';
+}
+
+export default { parseModule, collectModuleInfo, analyzeCalls, calleeToString };