sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Bundle/ PurePlugin.ts

import * as fs from "node:fs/promises";
import * as path from "node:path";
import type {
  CallExpression,
  ExportDefaultDeclaration,
  ExportNamedDeclaration,
  Expression,
  ExpressionStatement,
  NewExpression,
  Program,
  Statement,
  VariableDeclaration,
} from "@oxc-project/types";
import picomatch from "picomatch";
import type * as rolldown from "rolldown";

/**
 * `rolldown` and `rolldown/parseAst` load `@rolldown/binding-*` at module
 * scope, so they are imported lazily on first use — importing this module
 * (e.g. via the `alchemy/Bundle` barrel) must never load the native
 * binding (#562).
 */
const loadRolldown = () => import("rolldown");
const loadParseAst = () => import("rolldown/parseAst");

/**
 * Default packages whose modules will receive `/*#__PURE__*\/` annotations.
 * Mirrors what `effect-smol` ships via `babel-plugin-annotate-pure-calls`
 * applied to its own `dist/` output.
 *
 * `alchemy` is included so its own resources (which consist almost entirely
 * of `Effect.fn(...)`, `Context.Service(...)(...)`, `Layer.effect(...)` and
 * `Data.TaggedError(...)` top-level calls) become tree-shakeable. The
 * package already declares `"sideEffects": false`, so it is safe.
 *
 * `@distilled.cloud/*` is included so the generated SDK service modules
 * (large files of top-level `const op = make(...)` operation definitions)
 * tree-shake down to the operations a Worker actually calls. Every
 * distilled package declares `"sideEffects": false`.
 */
export const DEFAULT_PURE_PACKAGES: ReadonlyArray<string> = [
  "effect",
  "@effect/*",
  "alchemy",
  "@alchemy.run/*",
  "@distilled.cloud/*",
];

/**
 * Options for {@link purePlugin}.
 */
export interface PurePluginOptions {
  /**
   * Extra package names or globs to annotate, in addition to
   * {@link DEFAULT_PURE_PACKAGES}. Globs are matched with picomatch
   * against the package name (e.g. `effect`, `@effect/cluster`).
   *
   * Listing a package that declares `"sideEffects": false` (or `[]`)
   * in its `package.json` opts it into full annotation, including
   * top-level calls whose result is discarded — see {@link purePlugin}.
   */
  readonly packages?: ReadonlyArray<string>;
  /**
   * If true, the configured `packages` list replaces the defaults
   * entirely instead of extending them.
   * @default false
   */
  readonly replaceDefaults?: boolean;
  /**
   * If true, also marks matched modules as side-effect free
   * (mirrors `"sideEffects": []` in package.json), so rolldown drops
   * unused re-exports from those packages.
   * @default true
   */
  readonly markSideEffectFree?: boolean;
}

const PURE_COMMENT = "/*#__PURE__*/ ";
const SUPPORTED_FILE_RE = /\.(?:m?[jt]sx?|cjs|cts)$/;

/**
 * Rolldown plugin that injects `/*#__PURE__*\/` annotations on top-level
 * call/new expressions of modules belonging to the configured packages,
 * enabling tree-shaking of `effect`, `@effect/*`, and any user-listed
 * packages without requiring a babel post-build pass.
 *
 * Annotation is strictly explicit: only {@link DEFAULT_PURE_PACKAGES} and
 * packages listed via `packages` are touched. Listing a package that
 * declares `sideEffects: false` / `[]` is a deliberate opt-in to full
 * annotation, including discarded-result statement calls (#949). The
 * package owning the bundle entry gets no special treatment — apps that
 * want their own bound calls tree-shaken list themselves explicitly.
 */
export const purePlugin = (options: PurePluginOptions = {}): rolldown.Plugin => {
  const patterns = options.replaceDefaults
    ? [...(options.packages ?? DEFAULT_PURE_PACKAGES)]
    : [...DEFAULT_PURE_PACKAGES, ...(options.packages ?? [])];
  const markSideEffectFreeOpt = options.markSideEffectFree ?? true;
  const isMatch = picomatch(patterns);
  // Per-bundle cache of directory -> owning package metadata.
  // Avoids walking the filesystem for every module of a large package.
  const pkgInfoCache = new Map<string, PackageInfo | null>();
  // Resolved absolute paths of entry modules. Marking an entry module as
  // `moduleSideEffects: false` makes rolldown treat its top-level
  // statements (including `console.log` etc.) as eliminable, often
  // collapsing the whole bundle. We always preserve entries' side
  // effects, regardless of the package they belong to.
  const entryPaths = new Set<string>();

  return {
    name: "alchemy:annotate-pure",
    options(opts) {
      for (const input of inputFilePaths(opts)) entryPaths.add(input);
      return null;
    },
    transform: {
      filter: { id: SUPPORTED_FILE_RE },
      async handler(code, id, meta) {
        const cleanId = stripIdSuffix(id);
        const info = await resolvePackageInfo(path.dirname(cleanId), pkgInfoCache);
        // A nameless package.json (e.g. a nested `dist/package.json`
        // holding only `{"type": "module"}`) can't be matched against the
        // configured patterns — fall back to the path-derived
        // `node_modules/<pkg>` name when one exists.
        const name = info?.name ?? packageNameFromId(cleanId);
        if (name === null || !isMatch(name)) return null;

        // Only override `moduleSideEffects` when the owning package
        // explicitly opts in via `sideEffects: false` / `[]`. Marking
        // arbitrary modules side-effect-free could erase intentional
        // registrations / mutations the author made at the top level of
        // files in packages that did not declare so.
        const isEntry = entryPaths.has(cleanId);
        const sideEffectFreePkg = isSideEffectFree(info?.sideEffects);
        const markSideEffectFree = markSideEffectFreeOpt && !isEntry && sideEffectFreePkg;

        const anchors = await collectPureAnchorsCached(code, cleanId);
        // Annotating a call whose result is BOUND (variable initializer,
        // export) only lets the minifier drop it when the binding itself
        // is unused — safe everywhere. Annotating a call whose result is
        // DISCARDED (a bare expression statement like `app.get("/", h)`)
        // is an instruction to delete the call under minification, so it
        // is only applied when the owning package explicitly declared
        // itself side-effect free, and never to entry modules, whose side
        // effects we always preserve (#949).
        const annotateDiscarded = !isEntry && sideEffectFreePkg;
        const positions =
          anchors === null
            ? []
            : annotateDiscarded
              ? [...anchors.bound, ...anchors.discarded]
              : anchors.bound;
        if (positions.length === 0) {
          // Metadata-only result: omitting `code` tells rolldown the
          // source was NOT transformed, so no sourcemap is expected and
          // no SOURCEMAP_BROKEN warning is emitted.
          return markSideEffectFree ? { moduleSideEffects: false } : null;
        }
        // `meta.magicString` is rolldown's native (Rust) MagicString over
        // `code`. Returning it as `code` hands sourcemap generation to
        // rolldown's native side (computed on a background thread). The
        // fallback covers direct hook invocations (unit tests).
        const s = meta.magicString ?? new (await loadRolldown()).RolldownMagicString(code);
        for (const anchor of positions) s.appendLeft(anchor, PURE_COMMENT);
        return {
          code: s,
          moduleSideEffects: markSideEffectFree ? false : null,
        };
      },
    },
  };
};

/** Strips rolldown's `?query` / `#hash` suffixes from a module id. */
const stripIdSuffix = (id: string): string => id.replace(/[?#].*$/, "");

/**
 * Returns the absolute paths of every real entry module declared on the
 * rolldown input options. Handles all three input shapes (string, array,
 * `{ name -> path }` record) and skips `\0`-prefixed virtual ids (e.g.
 * the ones `virtualEntryPlugin` substitutes in its `pre` options hook).
 */
function inputFilePaths(opts: rolldown.InputOptions): string[] {
  const raw: unknown[] =
    typeof opts.input === "string"
      ? [opts.input]
      : Array.isArray(opts.input)
        ? opts.input
        : opts.input && typeof opts.input === "object"
          ? Object.values(opts.input)
          : [];
  const cwd = opts.cwd ?? process.cwd();
  return raw
    .filter((entry): entry is string => typeof entry === "string" && !entry.startsWith("\0"))
    .map((entry) => path.resolve(cwd, entry));
}

/**
 * Metadata extracted from a `package.json`. `name` may be `null` when the
 * file exists but has no `"name"` field (rare, but possible for private
 * subpackage roots).
 */
export interface PackageInfo {
  readonly name: string | null;
  readonly sideEffects: unknown;
}

/**
 * Resolves the owning {@link PackageInfo} for a directory by walking up
 * to the nearest `package.json`. This is what makes the plugin work for
 * workspace-linked sources (e.g. our own `packages/alchemy/src/**` when
 * consumers import via the `worker`/`bun` conditions which resolve to
 * `.ts`).
 *
 * Caches both positive and negative results per directory. Every visited
 * directory is a descendant-or-self of the directory where the walk
 * stops (found `package.json`, cache hit, `node_modules` boundary, or
 * filesystem root), so backfilling all of them with the result never
 * poisons sibling packages.
 */
export async function resolvePackageInfo(
  startDir: string,
  cache: Map<string, PackageInfo | null>,
): Promise<PackageInfo | null> {
  let dir = path.resolve(startDir);
  const visited: string[] = [];
  let result: PackageInfo | null = null;
  // Hard ceiling to prevent runaway walks on weird paths.
  for (let i = 0; i < 64; i++) {
    // Never walk above a `node_modules` boundary: the owning package of a
    // `node_modules/<pkg>/...` id lives at or below `<pkg>`. Climbing past
    // it can latch onto an unrelated package.json higher up (e.g. a stray
    // one at the filesystem root).
    if (path.basename(dir) === "node_modules") break;
    const cached = cache.get(dir);
    if (cached !== undefined) {
      result = cached;
      break;
    }
    visited.push(dir);
    const info = await readPackageJson(path.join(dir, "package.json"));
    if (info !== null) {
      result = info;
      break;
    }
    const parent = path.dirname(dir);
    if (parent === dir) break;
    dir = parent;
  }
  for (const v of visited) cache.set(v, result);
  return result;
}

async function readPackageJson(file: string): Promise<PackageInfo | null> {
  try {
    const contents = await fs.readFile(file, "utf8");
    const json = JSON.parse(contents) as {
      name?: unknown;
      sideEffects?: unknown;
    };
    return {
      name: typeof json.name === "string" ? json.name : null,
      sideEffects: json.sideEffects,
    };
  } catch {
    // package.json missing or unreadable.
    return null;
  }
}

/**
 * Mirrors how rolldown / rollup interpret the `sideEffects` package.json
 * field. We only treat `false` and `[]` as "fully side-effect free"; an
 * array of files or `true` is treated as not safe to auto-annotate the
 * whole package.
 */
function isSideEffectFree(value: unknown): boolean {
  if (value === false) return true;
  if (Array.isArray(value) && value.length === 0) return true;
  return false;
}

/**
 * Extracts the npm package name from a resolved module id by walking back to
 * the last `node_modules/` segment. Handles scoped packages. This is the
 * fast path that does not hit the filesystem; it works for ordinary
 * `node_modules/<pkg>/...` ids but NOT for workspace-linked sources whose
 * resolved path is e.g. `<repo>/packages/alchemy/src/Bundle/PurePlugin.ts`.
 *
 * @example
 *   packageNameFromId("/proj/node_modules/effect/dist/Effect.js")
 *     // => "effect"
 *   packageNameFromId("/proj/node_modules/@effect/cluster/dist/index.js")
 *     // => "@effect/cluster"
 */
export function packageNameFromId(id: string): string | null {
  const normalized = id.replace(/\\/g, "/");
  const idx = normalized.lastIndexOf("/node_modules/");
  if (idx === -1) return null;
  const rest = normalized.slice(idx + "/node_modules/".length);
  const parts = rest.split("/");
  if (parts.length === 0 || parts[0] === "") return null;
  if (parts[0].startsWith("@")) {
    if (parts.length < 2) return null;
    return `${parts[0]}/${parts[1]}`;
  }
  return parts[0];
}

/**
 * Process-wide memo of {@link collectPureAnchors} results keyed by module id.
 *
 * Parsing with oxc dominates the plugin's main-thread CPU (it showed up as
 * ~60% of the profile of a test run), and the same modules — effect/alchemy
 * dist files — are re-scanned for EVERY bundle built in the process. The
 * single-process test runner builds dozens of worker bundles per run, so
 * this cache eliminates all repeat parses. The stored `code` is compared on
 * lookup, so a changed file (e.g. dev watch mode) never serves a stale
 * result.
 */
const anchorsCache = new Map<
  string,
  { readonly code: string; readonly anchors: PureAnchors | null }
>();
const ANCHORS_CACHE_MAX = 10_000;

const collectPureAnchorsCached = async (
  code: string,
  filename: string,
): Promise<PureAnchors | null> => {
  const cached = anchorsCache.get(filename);
  if (cached !== undefined && cached.code === code) {
    return cached.anchors;
  }
  const anchors = await collectPureAnchors(code, filename);
  if (anchorsCache.size >= ANCHORS_CACHE_MAX) {
    anchorsCache.clear();
  }
  anchorsCache.set(filename, { code, anchors });
  return anchors;
};

/**
 * Offsets at which `/*#__PURE__*\/` may be inserted, split by whether the
 * call's result is consumed.
 */
export interface PureAnchors {
  /**
   * Calls whose result is bound — variable initializers, exports,
   * assignment right-hand sides. Annotating these only lets the minifier
   * drop the call when the binding itself is unused, so it is safe for
   * any module.
   */
  readonly bound: number[];
  /**
   * Top-level calls whose result is discarded (bare expression
   * statements such as `app.get("/", handler)`). Annotating these tells
   * the minifier the whole statement is deletable, so they are only safe
   * in packages that explicitly declare `sideEffects: false` / `[]`.
   */
  readonly discarded: number[];
}

/**
 * Parses `code` and returns the offsets at which `/*#__PURE__*\/` must be
 * inserted — before every top-level `CallExpression` callee / `new`
 * keyword — classified by whether the call result is bound or discarded.
 * Returns `null` if the file does not need to be modified (parse failure
 * or no annotations needed).
 */
export async function collectPureAnchors(
  code: string,
  filename: string,
): Promise<PureAnchors | null> {
  const { parseAst } = await loadParseAst();
  let program: Program;
  try {
    // Use TS lang so the parser tolerates TS syntax (`as`, `satisfies`,
    // non-null assertions) even when scanning published .js dist files
    // — TS is a strict superset of JS for our purposes here.
    program = parseAst(code, { sourceType: "module", lang: "ts" }, filename);
  } catch {
    return null;
  }

  const bound: number[] = [];
  const discarded: number[] = [];

  const visitCall = (call: CallExpression | NewExpression, isDiscarded: boolean) => {
    if (isIIFE(call)) return;
    // For `new X()`, anchor BEFORE the `new` keyword so we get
    // `/*#__PURE__*/ new X()` (matches babel-plugin-annotate-pure-calls).
    const anchor = call.type === "NewExpression" ? call.start : call.callee.start;
    if (alreadyAnnotated(code, anchor)) return;
    (isDiscarded ? discarded : bound).push(anchor);
  };

  const visitExpression = (expr: Expression | null | undefined, isDiscarded: boolean) => {
    if (!expr) return;
    switch (expr.type) {
      case "CallExpression":
      case "NewExpression":
        visitCall(expr, isDiscarded);
        return;
      case "SequenceExpression": {
        // All but the last expression's results are always discarded;
        // the last one takes the surrounding context.
        const exprs = expr.expressions;
        for (let i = 0; i < exprs.length; i++) {
          visitExpression(exprs[i], i < exprs.length - 1 ? true : isDiscarded);
        }
        return;
      }
      case "ParenthesizedExpression":
        visitExpression(expr.expression, isDiscarded);
        return;
      case "LogicalExpression":
        visitExpression(expr.left, isDiscarded);
        visitExpression(expr.right, isDiscarded);
        return;
      case "ConditionalExpression":
        visitExpression(expr.consequent, isDiscarded);
        visitExpression(expr.alternate, isDiscarded);
        return;
      case "AssignmentExpression":
        // The right-hand side's result is stored in the target, so it is
        // bound even when the assignment appears in statement position.
        visitExpression(expr.right, false);
        return;
      case "TSAsExpression":
      case "TSSatisfiesExpression":
      case "TSNonNullExpression":
      case "TSTypeAssertion":
        visitExpression(expr.expression, isDiscarded);
        return;
      case "ChainExpression": {
        const inner = expr.expression;
        if (inner.type === "CallExpression") visitCall(inner, isDiscarded);
        return;
      }
      default:
        return;
    }
  };

  const visitTopLevel = (node: Statement) => {
    switch (node.type) {
      case "ExpressionStatement":
        visitExpression((node as ExpressionStatement).expression, true);
        return;
      case "VariableDeclaration":
        for (const decl of (node as VariableDeclaration).declarations) {
          visitExpression(decl.init, false);
        }
        return;
      case "ExportNamedDeclaration": {
        const decl = (node as ExportNamedDeclaration).declaration;
        if (decl) visitTopLevel(decl as Statement);
        return;
      }
      case "ExportDefaultDeclaration": {
        const decl = (node as ExportDefaultDeclaration).declaration;
        if (
          decl &&
          decl.type !== "FunctionDeclaration" &&
          decl.type !== "ClassDeclaration" &&
          decl.type !== "TSInterfaceDeclaration"
        ) {
          visitExpression(decl as Expression, false);
        }
        return;
      }
      default:
        return;
    }
  };

  for (const node of program.body) {
    // Directive nodes (e.g. "use strict") have type "ExpressionStatement"
    // with a `directive` field and a string literal expression — they
    // cannot contain calls, so visiting them is a safe no-op.
    visitTopLevel(node as Statement);
  }

  return bound.length === 0 && discarded.length === 0 ? null : { bound, discarded };
}

function isIIFE(node: CallExpression | NewExpression): boolean {
  let callee: Expression = node.callee;
  while (callee.type === "ParenthesizedExpression") {
    callee = callee.expression;
  }
  return callee.type === "FunctionExpression" || callee.type === "ArrowFunctionExpression";
}

function alreadyAnnotated(code: string, pos: number): boolean {
  const start = Math.max(0, pos - 32);
  const slice = code.slice(start, pos);
  return slice.includes("/*#__PURE__*/") || slice.includes("/*@__PURE__*/");
}