reverse-engineering-anything/src/domain/referenceSourceRequireBindings.ts

import * as t from "@babel/types";
import { posix } from "node:path";

import { semanticStaticPropertyKey } from "./javascript/javascriptAstValues.js";
import { isUnmodifiedGlobalReference } from "./javascript/javascriptSemanticAmbientWrites.js";
import {
  indexJavaScriptBindingsWithReceiversSteps,
  type JavaScriptReceiverIndex,
} from "./javascript/javascriptSemanticAnalysis.js";
import type { JavaScriptSemanticAnalysisState } from "./javascript/javascriptSemanticState.js";
import {
  semanticRequireCallAt,
  semanticRequireLoaderAt,
  type JavaScriptRequireCallFact,
} from "./javascript/javascriptSemanticRequireOrigin.js";
import {
  completeSemanticSteps,
  traverseJavaScriptAst,
} from "./javascript/javascriptSemanticTraversal.js";
import {
  isExplicitModuleSourcePath,
  javaScriptRuntimeContext,
  type ParsedJavaScriptSource,
} from "./javascript/javascriptSourceParser.js";

/** Package scope observed inside the selected inventory; missing scope stays unknown. */
export type ReferenceSourcePackageType =
  | "module"
  | "commonjs"
  | "unspecified"
  | "unknown";

export type ReferenceSourceRequireResolutionBase =
  | "source-file"
  | { readonly kind: "source-relative-file"; readonly path: string }
  | "unknown";

export interface ReferenceSourceRequireCall {
  readonly arguments: JavaScriptRequireCallFact["arguments"];
  readonly resolutionBase: ReferenceSourceRequireResolutionBase;
}

/** Identify exact calls through a source-owned Node loader and their resolver base. */
export const referenceSourceRequireCalls = (
  file: Pick<ParsedJavaScriptSource, "program">,
  path: string,
  packageType: ReferenceSourcePackageType = "unknown",
): ReadonlyMap<
  t.CallExpression | t.OptionalCallExpression,
  ReferenceSourceRequireCall
> => {
  // Unmarked paths depend on package scope or compiler options. Preserve their
  // candidate CommonJS edges; explicit module paths have no wrapper loader.
  const wrapperMode = commonJsWrapperMode(path, file.program, packageType);
  const index = completeSemanticSteps(
    indexJavaScriptBindingsWithReceiversSteps(
      file.program,
      wrapperMode === "absent" ? undefined : "commonjs-wrapper",
    ),
  );
  const factoryBindings: ReadonlySet<string> = new Set();
  const candidates: {
    readonly call: t.CallExpression | t.OptionalCallExpression;
    readonly identifier: t.Identifier;
    readonly arguments: JavaScriptRequireCallFact["arguments"];
    readonly resolutionBase: ReferenceSourceRequireResolutionBase;
  }[] = [];
  traverseJavaScriptAst(file.program, {
    enter: (node) => {
      if (!t.isCallExpression(node) && !t.isOptionalCallExpression(node))
        return;
      const identifier = callReceiverIdentifier(node.callee);
      if (identifier === undefined) return;
      let fact = semanticRequireLoaderAt(node, index.bindings, factoryBindings);
      if (fact === "create-require") {
        // Definitions identify a possible factory. Its mutable member reads
        // need the shared write index before they can prove an association.
        completeSemanticSteps(index.indexMemberMutationFactsSteps());
        fact = semanticRequireLoaderAt(node, index.bindings, factoryBindings);
      }
      const callFact = semanticRequireCallAt(
        node,
        index.bindings,
        factoryBindings,
      );
      if (callFact === undefined || callFact.loader === "local") return;
      if (fact !== "create-require" && fact !== "commonjs-loader") return;
      if (fact === "commonjs-loader" && wrapperMode === "absent") return;
      const sourceRelativePath = callFact.sourceRelativePath;
      const normalizedSourceRelativePath =
        sourceRelativePath === undefined
          ? undefined
          : posix.normalize(
              posix.join(posix.dirname(path), sourceRelativePath),
            );
      const base: ReferenceSourceRequireResolutionBase =
        callFact.loader === "create-require"
          ? sourceRelativePath === undefined
            ? callFact.sourceRelative === true
              ? "source-file"
              : "unknown"
            : normalizedSourceRelativePath === undefined ||
                normalizedSourceRelativePath === ".." ||
                normalizedSourceRelativePath.startsWith("../")
              ? "unknown"
              : normalizedSourceRelativePath === path
                ? "source-file"
                : {
                    kind: "source-relative-file",
                    path: normalizedSourceRelativePath,
                  }
          : fact === "commonjs-loader" && callFact.loader === "commonjs-loader"
            ? path.endsWith(".js") && wrapperMode === "unknown"
              ? "unknown"
              : "source-file"
            : "unknown";
      const searchBase = requireResolveSearchBase(
        callFact.operation,
        callFact.arguments,
        index.bindings,
        base,
        wrapperMode === "present",
      );
      candidates.push({
        call: node,
        identifier,
        arguments: callFact.arguments,
        resolutionBase: searchBase,
      });
    },
  });
  if (candidates.some(({ call }) => !t.isIdentifier(call.callee)))
    completeSemanticSteps(index.indexMemberMutationFactsSteps());
  return new Map(
    candidates.map(
      ({ call, identifier, arguments: callArguments, resolutionBase }) =>
        [
          call,
          {
            arguments: callArguments,
            resolutionBase:
              !t.isIdentifier(call.callee) &&
              hasPriorMemberMutation(index, call, identifier)
                ? "unknown"
                : resolutionBase,
          },
        ] as const,
    ),
  );
};

/** `require.resolve` options replace the default search paths unless exact current-directory paths are supplied. */
const requireResolveSearchBase = (
  operation: JavaScriptRequireCallFact["operation"],
  callArguments: JavaScriptRequireCallFact["arguments"],
  bindings: JavaScriptSemanticAnalysisState,
  loaderBase: ReferenceSourceRequireResolutionBase,
  hasCommonJsWrapper: boolean,
): ReferenceSourceRequireResolutionBase => {
  const arguments_ = callArguments ?? [];
  if (operation !== "resolve" || arguments_.length < 2) return loaderBase;
  if (arguments_.length !== 2) return "unknown";
  const options = t.isExpression(arguments_[1]) ? arguments_[1] : undefined;
  if (options === undefined || !t.isObjectExpression(options)) return "unknown";
  if (options.properties.length === 0) return loaderBase;
  if (options.properties.length !== 1) return "unknown";
  const property = options.properties[0];
  if (!t.isObjectProperty(property)) return "unknown";
  if (semanticStaticPropertyKey(property.key, property.computed) !== "paths")
    return "unknown";
  const value = t.isExpression(property.value) ? property.value : undefined;
  if (!t.isArrayExpression(value) || value.elements.length !== 1)
    return "unknown";
  const directory = value.elements[0];
  return hasCommonJsWrapper &&
    t.isIdentifier(directory, { name: "__dirname" }) &&
    isUnmodifiedGlobalReference(directory, bindings, "__dirname")
    ? "source-file"
    : "unknown";
};

type CommonJsWrapperMode = "present" | "absent" | "unknown";

const commonJsWrapperMode = (
  path: string,
  program: t.Program,
  packageType: ReferenceSourcePackageType,
): CommonJsWrapperMode => {
  if (path.endsWith(".cjs")) return "present";
  if (isExplicitModuleSourcePath(path)) return "absent";
  if (path.endsWith(".js")) {
    if (packageType === "module") return "absent";
    if (packageType === "commonjs") return "present";
    if (packageType === "unknown") return "unknown";
    if (javaScriptRuntimeContext(program) === "module") return "absent";
    return "present";
  }
  return "unknown";
};

const hasPriorMemberMutation = (
  index: JavaScriptReceiverIndex,
  site: t.CallExpression | t.OptionalCallExpression,
  identifier: t.Identifier,
): boolean => {
  const callee = site.callee;
  const property =
    t.isMemberExpression(callee) || t.isOptionalMemberExpression(callee)
      ? semanticStaticPropertyKey(callee.property, callee.computed)
      : undefined;
  if (property === undefined || property === null) return true;
  const facts = index.effectsForReferenceAt(site, identifier, [property]);
  return (
    !facts.memberEffectsIndexed ||
    facts.effects.some(
      ({ kind, timing }) =>
        (kind === "member-write" || kind === "escape") && timing !== "after",
    )
  );
};

const callReceiverIdentifier = (
  callee: t.Node | null | undefined,
): t.Identifier | undefined => {
  if (t.isIdentifier(callee)) return callee;
  if (
    (t.isMemberExpression(callee) || t.isOptionalMemberExpression(callee)) &&
    t.isIdentifier(callee.object)
  )
    return callee.object;
  return undefined;
};