walker.ts

import assert from 'assert';
import fs from 'fs/promises';
import path from 'path';
import module, { builtinModules } from 'module';
import picomatch from 'picomatch';
import { globSync } from 'tinyglobby';

import {
  ALIAS_AS_RELATIVE,
  ALIAS_AS_RESOLVABLE,
  STORE_BLOB,
  STORE_CONTENT,
  STORE_LINKS,
  STORE_STAT,
  isDotJS,
  isDotJSON,
  isDotNODE,
  isPackageJson,
  unlikelyJavascript,
  normalizePath,
  toNormalizedRealPath,
  isESMFile,
} from './common';

import { pc } from './colors';
import { follow } from './follow';
import { log, wasReported } from './log';
import * as detector from './detector';
import { transformESMtoCJS, rewriteMjsRequirePaths } from './esm-transformer';
import {
  ConfigDictionary,
  FileRecord,
  FileRecords,
  Marker,
  Patches,
  PackageJson,
  SymLinks,
  WalkerParams,
} from './types';
import pkgOptions from './options';

export type { Marker, WalkerParams };

interface Task {
  file: string;
  data?: unknown;
  reason?: string;
  marker?: Marker;
  store: number;
}

interface Derivative {
  alias: string;
  mayExclude?: boolean;
  mustExclude?: boolean;
  aliasType: number;
  fromDependencies?: boolean;
}

// Note: as a developer, you can set the PKG_STRICT_VER variable.
//       this will turn on some assertion in the walker code below
//       to assert that each file content/state that we appending
//       to the virtual file system applies to  a real file,
//       not a symlink.
//       By default assertion are disabled as they can have a
//       performance hit.
const strictVerify = Boolean(process.env.PKG_STRICT_VER);

const win32 = process.platform === 'win32';

// Extensions to try when resolving modules
// Includes .mjs to support ESM files that get transformed to .js
const MODULE_RESOLVE_EXTENSIONS = ['.js', '.json', '.node', '.mjs'];

/**
 * Checks if a module is a core module
 * module.isBuiltin is available in Node.js 16.17.0 or later. Use that if available
 * as prefix-only modules (those starting with 'node:') can only be checked that way.
 */
function isBuiltin(moduleName: string) {
  if (
    Reflect.has(module, 'isBuiltin') &&
    typeof module.isBuiltin === 'function'
  ) {
    return module.isBuiltin(moduleName);
  }

  const moduleNameWithoutPrefix = moduleName.startsWith('node:')
    ? moduleName.slice(5)
    : moduleName;

  return builtinModules.includes(moduleNameWithoutPrefix);
}

function isPublic(config: PackageJson) {
  if (config.private) {
    return false;
  }

  const { licenses } = config;
  let { license } = config;

  if (licenses) {
    license = licenses;
  }

  if (license && !Array.isArray(license)) {
    license = typeof license === 'string' ? license : license.type;
  }

  if (Array.isArray(license)) {
    license = license.map((c) => String(c.type || c)).join(',');
  }

  if (!license) {
    return false;
  }

  if (/^\(/.test(license)) {
    license = license.slice(1);
  }

  if (/\)$/.test(license)) {
    license = license.slice(0, -1);
  }

  license = license.toLowerCase();
  const allLicenses = Array.prototype.concat(
    license.split(' or '),
    license.split(' and '),
    license.split('/'),
    license.split(','),
  );
  let result = false;
  const foss = [
    'isc',
    'mit',
    'apache-2.0',
    'apache 2.0',
    'public domain',
    'bsd',
    'bsd-2-clause',
    'bsd-3-clause',
    'wtfpl',
    'cc-by-3.0',
    'x11',
    'artistic-2.0',
    'gplv3',
    'mpl',
    'mplv2.0',
    'unlicense',
    'apache license 2.0',
    'zlib',
    'mpl-2.0',
    'nasa-1.3',
    'apache license, version 2.0',
    'lgpl-2.1+',
    'cc0-1.0',
  ];

  for (const c of allLicenses) {
    result = foss.indexOf(c) >= 0;

    if (result) {
      break;
    }
  }

  return result;
}

function upon(p: string, base: string) {
  if (typeof p !== 'string') {
    throw wasReported('Config items must be strings. See examples');
  }

  let negate = false;

  if (p[0] === '!') {
    p = p.slice(1);
    negate = true;
  }

  p = path.join(base, p);

  if (win32) {
    p = p.replace(/\\/g, '/');
  }

  if (negate) {
    p = `!${p}`;
  }

  return p;
}

function collect(ps: string[]) {
  return globSync(ps, { absolute: true, dot: true });
}

function expandFiles(efs: string | string[], base: string) {
  if (!Array.isArray(efs)) {
    efs = [efs];
  }

  efs = collect(efs.map((p) => upon(p, base)));

  return efs;
}

async function stepRead(record: FileRecord) {
  if (strictVerify) {
    assert(record.file === toNormalizedRealPath(record.file));
  }

  let body;

  try {
    body = await fs.readFile(record.file);
  } catch (error) {
    const exception = error as NodeJS.ErrnoException;
    log.error(`Cannot read file, ${exception.code}`, record.file);
    throw wasReported(exception.message);
  }

  record.body = body;
}

// Strip BOM and shebang from the file body.
//
// IMPORTANT: leave `record.body` untouched on no-op. Reassigning it (e.g.
// `record.body = body.toString('utf8')`) would convert Buffer → string even
// when nothing was stripped, defeating the in-memory body reuse optimization
// in `sea-assets.ts`: the SEA archive writer trusts that an unmodified body
// equals the disk content byte-for-byte, so we must not silently retype it.
function stepStrip(record: FileRecord) {
  const original = (record.body || '').toString('utf8');
  let body = original;

  if (/^\ufeff/.test(body)) {
    body = body.replace(/^\ufeff/, '');
  }

  if (/^#!/.test(body)) {
    body = body.replace(/^#![^\n]*\n/, '\n');
  }

  if (body !== original) {
    record.body = body;
  }
}

function stepDetect(
  record: FileRecord,
  marker: Marker,
  derivatives: Derivative[],
) {
  let { body = '' } = record;

  if (body instanceof Buffer) {
    body = body.toString();
  }

  try {
    detector.detect(
      body,
      (node, trying) => {
        const { toplevel } = marker;
        let d = detector.visitorSuccessful(node) as unknown as Derivative;

        if (d) {
          if (d.mustExclude) {
            return false;
          }

          d.mayExclude = d.mayExclude || trying;
          derivatives.push(d);

          return false;
        }

        d = detector.visitorNonLiteral(node) as unknown as Derivative;

        if (d) {
          if (typeof d === 'object' && d.mustExclude) {
            return false;
          }

          const debug = !toplevel || d.mayExclude || trying;
          const level = debug ? 'debug' : 'warn';
          log[level](`Cannot resolve '${d.alias}'`, [
            record.file,
            'Dynamic require may fail at run time, because the requested file',
            'is unknown at compilation time and not included into executable.',
            "Use a string literal as an argument for 'require', or leave it",
            "as is and specify the resolved file name in 'scripts' option.",
          ]);
          return false;
        }

        d = detector.visitorMalformed(node) as unknown as Derivative;

        if (d) {
          // there is no 'mustExclude'
          const debug = !toplevel || trying;
          const level = debug ? 'debug' : 'warn'; // there is no 'mayExclude'
          log[level](`Malformed requirement for '${d.alias}'`, [record.file]);
          return false;
        }

        d = detector.visitorUseSCWD(node) as unknown as Derivative;

        if (d) {
          // there is no 'mustExclude'
          const level = 'debug'; // there is no 'mayExclude'
          log[level](`Path.resolve(${d.alias}) is ambiguous`, [
            record.file,
            "It resolves relatively to 'process.cwd' by default, however",
            "you may want to use 'path.dirname(require.main.filename)'",
          ]);

          return false;
        }

        return true; // can i go inside?
      },
      record.file,
    );
  } catch (error) {
    log.error((error as Error).message, record.file);
    throw wasReported((error as Error).message);
  }
}

/**
 * Find a common junction point between a symlink and the real file path.
 *
 * @param {string} file The file path, including symlink(s).
 * @param {string} realFile The real path to the file.
 *
 * @throws {Error} If no common junction point is found prior to hitting the
 *                 filesystem root.
 */
async function findCommonJunctionPoint(file: string, realFile: string) {
  // find common denominator => where the link changes
  while (true) {
    const stats = await fs.lstat(file);

    if (stats.isSymbolicLink()) {
      return { file, realFile };
    }

    file = path.dirname(file);
    realFile = path.dirname(realFile);

    // If the directory is /, break out of the loop and log an error.
    if (
      file === path.parse(file).root ||
      realFile === path.parse(realFile).root
    ) {
      throw new Error(
        'Reached root directory without finding a common junction point',
      );
    }
  }
}

class Walker {
  private params: WalkerParams;

  private symLinks: SymLinks;

  private patches: Patches;

  private tasks: Task[];

  private records: FileRecords;

  private dictionary: ConfigDictionary;

  constructor() {
    this.tasks = [];
    this.records = {};
    this.dictionary = {};
    this.patches = {};
    this.params = {};
    this.symLinks = {};
  }

  appendRecord({ file, store }: Task) {
    if (this.records[file]) {
      return;
    }

    if (
      store === STORE_BLOB ||
      store === STORE_CONTENT ||
      store === STORE_LINKS
    ) {
      // make sure we have a real file
      if (strictVerify) {
        assert(file === toNormalizedRealPath(file));
      }
    }

    this.records[file] = { file };
  }

  private append(task: Task) {
    if (strictVerify) {
      assert(typeof task.file === 'string');
      assert(task.file === normalizePath(task.file));
    }

    this.appendRecord(task);
    this.tasks.push(task);

    const what = {
      [STORE_BLOB]: 'Bytecode of',
      [STORE_CONTENT]: 'Content of',
      [STORE_LINKS]: 'Directory',
      [STORE_STAT]: 'Stat info of',
    }[task.store];

    if (task.reason) {
      log.debug(
        `${what} ${task.file} is added to queue. It was required from ${task.reason}`,
      );
    } else {
      log.debug(`${what} ${task.file} is added to queue.`);
    }
  }

  async appendSymlink(file: string, realFile: string) {
    const a = await findCommonJunctionPoint(file, realFile);
    file = a.file;
    realFile = a.realFile;

    if (!this.symLinks[file]) {
      const dn = path.dirname(file);
      this.appendFileInFolder({
        file: dn,
        store: STORE_LINKS,
        data: path.basename(file),
      });

      log.debug(`adding symlink ${file}  => ${path.relative(file, realFile)}`);
      this.symLinks[file] = realFile;

      this.appendStat({
        file: realFile,
        store: STORE_STAT,
      });
      this.appendStat({
        file: dn,
        store: STORE_STAT,
      });
      this.appendStat({
        file,
        store: STORE_STAT,
      });
    }
  }

  appendStat(task: Task) {
    assert(task.store === STORE_STAT);
    this.append(task);
  }

  appendFileInFolder(task: Task) {
    if (strictVerify) {
      assert(task.store === STORE_LINKS);
      assert(typeof task.file === 'string');
    }
    const realFile = toNormalizedRealPath(task.file);
    if (realFile === task.file) {
      this.append(task);
      return;
    }
    this.append({ ...task, file: realFile });
    this.appendStat({
      file: task.file,
      store: STORE_STAT,
    });
    this.appendStat({
      file: path.dirname(task.file),
      store: STORE_STAT,
    });
  }

  async appendBlobOrContent(task: Task) {
    if (strictVerify) {
      assert(task.file === normalizePath(task.file));
    }

    assert(task.store === STORE_BLOB || task.store === STORE_CONTENT);

    // In SEA mode, always store as content (no V8 bytecode compilation)
    if (this.params.seaMode && task.store === STORE_BLOB) {
      task.store = STORE_CONTENT;
    }

    assert(typeof task.file === 'string');
    const realFile = toNormalizedRealPath(task.file);

    const { ignore } = pkgOptions.get();
    if (ignore) {
      // check if the file matches one of the ignore regex patterns
      const match = picomatch.isMatch(realFile, ignore, {
        windows: win32,
      });

      if (match) {
        log.debug(
          `Ignoring file: ${realFile} due to top level config ignore pattern`,
        );
        return;
      }
    }

    if (realFile === task.file) {
      this.append(task);
      return;
    }

    this.append({ ...task, file: realFile });
    await this.appendSymlink(task.file, realFile);
    this.appendStat({
      file: task.file,
      store: STORE_STAT,
    });
  }

  async appendFilesFromConfig(marker: Marker) {
    const { config, configPath, base } = marker;
    const pkgConfig = config?.pkg;

    if (pkgConfig) {
      let { scripts } = pkgConfig;

      if (scripts) {
        scripts = expandFiles(scripts, base);

        for (const script of scripts) {
          const stat = await fs.stat(script);

          if (stat.isFile()) {
            if (!isDotJS(script) && !isDotJSON(script) && !isDotNODE(script)) {
              log.warn("Non-javascript file is specified in 'scripts'.", [
                'Pkg will probably fail to parse. Specify *.js in glob.',
                script,
              ]);
            }

            await this.appendBlobOrContent({
              file: normalizePath(script),
              marker,
              store: STORE_BLOB,
              reason: configPath,
            });
          }
        }
      }

      let { assets } = pkgConfig;

      if (assets) {
        assets = expandFiles(assets, base);

        for (const asset of assets) {
          log.debug(' Adding asset : .... ', asset);
          const stat = await fs.stat(asset);

          if (stat.isFile()) {
            await this.appendBlobOrContent({
              file: normalizePath(asset),
              marker,
              store: STORE_CONTENT,
              reason: configPath,
            });
          }
        }
      }
    } else if (config) {
      let { files } = config;

      if (files) {
        files = expandFiles(files, base);

        for (let file of files) {
          file = normalizePath(file);
          const stat = await fs.stat(file);

          if (stat.isFile()) {
            // 1) remove sources of top-level(!) package 'files' i.e. ship as BLOB
            // 2) non-source (non-js) files of top-level package are shipped as CONTENT
            // 3) parsing some js 'files' of non-top-level packages fails, hence all CONTENT
            if (marker.toplevel) {
              await this.appendBlobOrContent({
                file,
                marker,
                store: isDotJS(file) ? STORE_BLOB : STORE_CONTENT,
                reason: configPath,
              });
            } else {
              await this.appendBlobOrContent({
                file,
                marker,
                store: STORE_CONTENT,
                reason: configPath,
              });
            }
          }
        }
      }
    }
  }

  async stepActivate(marker: Marker, derivatives: Derivative[]) {
    if (!marker) {
      assert(false);
    }

    if (marker.activated) {
      return;
    }

    const { config, base } = marker;

    if (!config) {
      assert(false);
    }

    const { name } = config;

    if (name) {
      const d = this.dictionary[name];

      if (d) {
        if (
          typeof config.dependencies === 'object' &&
          typeof d.dependencies === 'object'
        ) {
          Object.assign(config.dependencies, d.dependencies);
          delete d.dependencies;
        }

        Object.assign(config, d);
        marker.hasDictionary = true;
      }
    }

    const { dependencies } = config;

    if (typeof dependencies === 'object') {
      for (const dependency in dependencies) {
        // it may be `undefined` - overridden
        // in dictionary (see publicsuffixlist)
        if (dependencies[dependency]) {
          derivatives.push({
            alias: dependency,
            aliasType: ALIAS_AS_RESOLVABLE,
            fromDependencies: true,
          });

          derivatives.push({
            alias: `${dependency}/package.json`,
            aliasType: ALIAS_AS_RESOLVABLE,
            fromDependencies: true,
          });
        }
      }
    }

    const pkgConfig = config.pkg;

    if (pkgConfig) {
      const { patches } = pkgConfig;

      if (patches) {
        for (const key in patches) {
          if (patches[key]) {
            const p = path.join(base, key);
            this.patches[p] = patches[key];
          }
        }
      }

      const { deployFiles } = pkgConfig;

      if (deployFiles) {
        marker.hasDeployFiles = true;

        for (const deployFile of deployFiles) {
          const type = deployFile[2] || 'file';
          log.warn(`Cannot include ${type} %1 into executable.`, [
            `The ${type} must be distributed with executable as %2.`,
            `%1: ${path.relative(
              process.cwd(),
              path.join(base, deployFile[0]),
            )}`,
            `%2: path-to-executable/${deployFile[1]}`,
          ]);
        }
      }

      if (pkgConfig.log) {
        pkgConfig.log(log, { packagePath: base });
      }
    }

    await this.appendFilesFromConfig(marker);
    marker.public = isPublic(config);

    if (!marker.public && marker.toplevel) {
      marker.public = this.params.publicToplevel;
    }

    if (!marker.public && !marker.toplevel && this.params.publicPackages) {
      marker.public =
        this.params.publicPackages[0] === '*' ||
        (!!name && this.params.publicPackages.indexOf(name) !== -1);
    }

    marker.activated = true;
    // assert no further work with config
    delete marker.config;
  }

  hasPatch(record: FileRecord) {
    const patch = this.patches[record.file];

    if (!patch) {
      return;
    }

    return true;
  }

  needsSeaRead(record: FileRecord): boolean {
    return (
      !!this.params.seaMode && (isDotJS(record.file) || isESMFile(record.file))
    );
  }

  stepPatch(record: FileRecord) {
    const patch = this.patches[record.file];

    if (!patch) {
      return;
    }

    let body = (record.body || '').toString('utf8');

    for (let i = 0; i < patch.length; i += 2) {
      if (typeof patch[i] === 'object') {
        if (patch[i].do === 'erase') {
          body = patch[i + 1];
        } else if (patch[i].do === 'prepend') {
          body = patch[i + 1] + body;
        } else if (patch[i].do === 'append') {
          body += patch[i + 1];
        }
      } else if (typeof patch[i] === 'string') {
        // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
        // function escapeRegExp
        const esc = patch[i].replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
        const regexp = new RegExp(esc, 'g');
        body = body.replace(regexp, patch[i + 1]);
      }
    }

    record.body = body;
  }

  async stepDerivatives_ALIAS_AS_RELATIVE(
    record: FileRecord,
    marker: Marker,
    derivative: Derivative,
  ) {
    const file = normalizePath(
      path.join(path.dirname(record.file), derivative.alias),
    );

    let stat;

    try {
      stat = await fs.stat(file);
    } catch (error) {
      const { toplevel } = marker;
      const exception = error as NodeJS.ErrnoException;
      const debug = !toplevel && exception.code === 'ENOENT';
      const level = debug ? 'debug' : 'warn';
      log[level](`Cannot stat, ${exception.code}`, [
        file,
        `The file was required from '${record.file}'`,
      ]);
    }

    if (stat && stat.isFile()) {
      await this.appendBlobOrContent({
        file,
        marker,
        store: STORE_CONTENT,
        reason: record.file,
      });
    }
  }

  async stepDerivatives_ALIAS_AS_RESOLVABLE(
    record: FileRecord,
    marker: Marker,
    derivative: Derivative,
  ) {
    const newPackages: { packageJson: string; marker?: Marker }[] = [];

    const catchReadFile = (file: string) => {
      assert(isPackageJson(file), `walker: ${file} must be package.json`);
      newPackages.push({ packageJson: file });
    };

    const catchPackageFilter = (config: PackageJson, base: string) => {
      const newPackage = newPackages[newPackages.length - 1];
      newPackage.marker = {
        config,
        configPath: newPackage.packageJson,
        base,
      };
    };

    let newFile = '';
    let failure: Error | undefined;

    const basedir = path.dirname(record.file);
    try {
      newFile = await follow(derivative.alias, {
        basedir,
        // default is extensions: ['.js'], but
        // it is not enough because 'typos.json'
        // is not taken in require('./typos')
        // in 'normalize-package-data/lib/fixer.js'
        // Also include .mjs to support ESM files that get transformed to .js
        extensions: MODULE_RESOLVE_EXTENSIONS,
        catchReadFile,
        catchPackageFilter,
      });
    } catch (error) {
      failure = error as Error;
    }

    if (failure) {
      const { toplevel } = marker;
      const mainNotFound =
        newPackages.length > 0 && !newPackages[0].marker?.config?.main;
      const debug =
        !toplevel ||
        derivative.mayExclude ||
        (mainNotFound && derivative.fromDependencies);
      const level = debug ? 'debug' : 'warn';

      if (mainNotFound) {
        const message = "Entry 'main' not found in %1";
        log[level](message, [
          `%1: ${newPackages[0].packageJson}`,
          `%2: ${record.file}`,
        ]);
      } else {
        log[level](`${pc.yellow(failure.message)}  in ${record.file}`);
      }

      return;
    }

    let newPackageForNewRecords;

    for (const newPackage of newPackages) {
      let newFile2;

      try {
        newFile2 = await follow(derivative.alias, {
          basedir: path.dirname(record.file),
          extensions: MODULE_RESOLVE_EXTENSIONS,
          ignoreFile: newPackage.packageJson,
        });
        if (strictVerify) {
          assert(newFile2 === normalizePath(newFile2));
        }
      } catch (_) {
        // not setting is enough
      }

      if (newFile2 !== newFile) {
        newPackageForNewRecords = newPackage;
        break;
      }
    }

    // Add all discovered package.json files, not just the one determined by the double-resolution logic
    // This is necessary because ESM resolution may bypass the standard packageFilter mechanism
    // However, only include package.json files that are either:
    // 1. Inside node_modules (dependencies)
    // 2. Inside the base directory of the current marker (application being packaged)
    // This prevents including pkg's own package.json when used from source
    for (const newPackage of newPackages) {
      if (newPackage.marker) {
        const file = newPackage.packageJson;
        const isInNodeModules = file.includes(
          `${path.sep}node_modules${path.sep}`,
        );
        const isInMarkerBase = marker.base && file.startsWith(marker.base);

        if (isInNodeModules || isInMarkerBase) {
          await this.appendBlobOrContent({
            file,
            marker: newPackage.marker,
            store: STORE_CONTENT,
            reason: record.file,
          });
        }
      }
    }

    // Keep the original logic for determining the marker for the resolved file
    if (newPackageForNewRecords) {
      if (strictVerify) {
        assert(
          newPackageForNewRecords.packageJson ===
            normalizePath(newPackageForNewRecords.packageJson),
        );
      }
    }

    await this.appendBlobOrContent({
      file: newFile,
      marker: newPackageForNewRecords ? newPackageForNewRecords.marker : marker,
      store: STORE_BLOB,
      reason: record.file,
    });

    // Also include files from other export conditions (e.g., module-sync, import)
    // that Node.js may resolve to at runtime instead of the default/require entry.
    // Without this, .mjs files referenced by module-sync would be missing from the snapshot.
    const effectiveMarker = newPackageForNewRecords
      ? newPackageForNewRecords.marker
      : marker;
    if (effectiveMarker?.configPath) {
      await this.includeAlternateExportEntries(
        effectiveMarker,
        newFile,
        record.file,
      );
    }
  }

  /**
   * Include alternate export entry points (module-sync, import) from a package's
   * exports field. These files may be loaded by Node.js at runtime instead of the
   * default/require entry, so they must be in the snapshot.
   */
  private async includeAlternateExportEntries(
    marker: Marker | undefined,
    resolvedFile: string,
    reason: string,
  ) {
    if (!marker?.configPath || !marker.config) return;

    const pkgExports = (marker.config as Record<string, unknown>).exports;
    if (!pkgExports) return;

    const pkgDir = path.dirname(marker.configPath);
    const alternateFiles = this.collectAlternateExportFiles(pkgExports);

    for (const relFile of alternateFiles) {
      const absFile = normalizePath(path.resolve(pkgDir, relFile));
      // Skip the file we already resolved
      if (absFile === resolvedFile) continue;

      try {
        const stat = await fs.stat(absFile);
        if (stat.isFile()) {
          await this.appendBlobOrContent({
            file: absFile,
            marker,
            store: STORE_CONTENT,
            reason,
          });
        }
      } catch {
        // File doesn't exist, skip
      }
    }
  }

  /**
   * Collect file paths from export conditions that Node.js may use at runtime.
   * Specifically targets module-sync and import conditions.
   */
  private collectAlternateExportFiles(
    exports: unknown,
    files: Set<string> = new Set(),
  ): Set<string> {
    if (typeof exports === 'string') {
      if (exports.endsWith('.mjs')) files.add(exports);
      return files;
    }

    if (Array.isArray(exports)) {
      for (const item of exports) {
        this.collectAlternateExportFiles(item, files);
      }
      return files;
    }

    if (exports && typeof exports === 'object') {
      for (const [key, value] of Object.entries(exports)) {
        // Include files from conditions that Node.js may use at runtime
        if (key === 'module-sync' || key === 'import') {
          if (typeof value === 'string') {
            files.add(value);
          }
        }
        // Recurse into nested conditions and subpath patterns
        if (typeof value === 'object' || typeof value === 'string') {
          this.collectAlternateExportFiles(value, files);
        }
      }
    }

    return files;
  }

  async stepDerivatives(
    record: FileRecord,
    marker: Marker,
    derivatives: Derivative[],
  ) {
    for (const derivative of derivatives) {
      // TODO: actually use the target node version
      if (isBuiltin(derivative.alias)) continue;

      switch (derivative.aliasType) {
        case ALIAS_AS_RELATIVE:
          await this.stepDerivatives_ALIAS_AS_RELATIVE(
            record,
            marker,
            derivative,
          );
          break;
        case ALIAS_AS_RESOLVABLE:
          await this.stepDerivatives_ALIAS_AS_RESOLVABLE(
            record,
            marker,
            derivative,
          );
          break;
        default:
          assert(false, `walker: unknown aliasType ${derivative.aliasType}`);
      }
    }
  }

  async step_STORE_ANY(record: FileRecord, marker: Marker, store: number) {
    if (strictVerify) {
      assert(record.file === toNormalizedRealPath(record.file));
    }
    if (record[store] !== undefined) return;
    record[store] = false; // default is discard

    this.appendStat({
      file: record.file,
      store: STORE_STAT,
    });

    const derivatives1: Derivative[] = [];
    await this.stepActivate(marker, derivatives1);
    await this.stepDerivatives(record, marker, derivatives1);

    if (store === STORE_BLOB) {
      if (unlikelyJavascript(record.file) || isDotNODE(record.file)) {
        await this.appendBlobOrContent({
          file: record.file,
          marker,
          store: STORE_CONTENT,
        });
        return; // discard
      }

      if (marker.public || marker.hasDictionary) {
        await this.appendBlobOrContent({
          file: record.file,
          marker,
          store: STORE_CONTENT,
        });
      }
    }

    const needsSeaRead = this.needsSeaRead(record);

    // Also read .mjs STORE_CONTENT files so they can be transformed to CJS
    const needsMjsTransform =
      store === STORE_CONTENT &&
      !this.params.seaMode &&
      record.file.endsWith('.mjs') &&
      isESMFile(record.file);

    if (
      store === STORE_BLOB ||
      needsSeaRead ||
      (store === STORE_CONTENT && isPackageJson(record.file)) ||
      needsMjsTransform ||
      this.hasPatch(record)
    ) {
      if (!record.body) {
        await stepRead(record);
        this.stepPatch(record);

        if (store === STORE_BLOB || needsSeaRead) {
          stepStrip(record);
        }
      }

      // Patch package.json files to add synthetic main field if needed
      if (
        store === STORE_CONTENT &&
        isPackageJson(record.file) &&
        record.body
      ) {
        try {
          const pkgContent = JSON.parse(record.body.toString('utf8'));
          let modified = false;

          // If package has exports but no main, add a synthetic main field
          if (pkgContent.exports && !pkgContent.main) {
            // Try to get main from marker.config first (set by catchPackageFilter in follow.ts)
            if (marker.config?.main) {
              pkgContent.main = marker.config.main;
              modified = true;
            } else {
              // Fallback: try to infer main from exports field
              const { exports } = pkgContent;
              if (typeof exports === 'string') {
                pkgContent.main = exports;
                modified = true;
              } else if (exports && typeof exports === 'object') {
                // Handle conditional exports
                if (exports['.']) {
                  if (typeof exports['.'] === 'string') {
                    pkgContent.main = exports['.'];
                    modified = true;
                  } else if (typeof exports['.'] === 'object') {
                    // Try to get the best entry point for CJS
                    // Prefer: require > node > default
                    let mainEntry: string | undefined;

                    if (
                      typeof exports['.'].require === 'string' &&
                      exports['.'].require
                    ) {
                      mainEntry = exports['.'].require;
                    } else if (
                      typeof exports['.'].node === 'string' &&
                      exports['.'].node
                    ) {
                      mainEntry = exports['.'].node;
                    } else if (
                      typeof exports['.'].default === 'string' &&
                      exports['.'].default
                    ) {
                      mainEntry = exports['.'].default;
                    }

                    if (mainEntry) {
                      pkgContent.main = mainEntry;
                      modified = true;
                    }
                  }
                }
              }
            }
          }

          // If package has "type": "module", we need to change it to "commonjs"
          // because we transform all ESM files to CJS before bytecode compilation
          if (pkgContent.type === 'module' && !this.params.seaMode) {
            pkgContent.type = 'commonjs';
            modified = true;
          }

          // Only rewrite if we made changes
          if (modified) {
            record.body = Buffer.from(
              JSON.stringify(pkgContent, null, 2),
              'utf8',
            );
          }
        } catch (_error) {
          // Ignore JSON parsing errors
        }
      }

      // Transform ESM to CJS before bytecode compilation
      // Check all JS-like files (.js, .mjs, .cjs) but only transform ESM ones
      // Also transform .mjs files stored as STORE_CONTENT (e.g., from dependencies)
      // to prevent Node.js from loading them as ESM at runtime
      if (
        (store === STORE_BLOB || needsMjsTransform) &&
        !this.params.seaMode &&
        record.body &&
        (isDotJS(record.file) || record.file.endsWith('.mjs'))
      ) {
        if (isESMFile(record.file)) {
          try {
            const result = transformESMtoCJS(
              record.body.toString('utf8'),
              record.file,
            );
            if (result.isTransformed) {
              record.body = Buffer.from(result.code, 'utf8');
              // Mark .mjs files as transformed so packer can rename them to .js
              if (record.file.endsWith('.mjs')) {
                record.wasTransformed = true;
              }
            }
          } catch (error) {
            const message =
              error instanceof Error ? error.message : String(error);
            throw new Error(
              `Failed to transform ESM module to CJS for file "${record.file}": ${message}`,
            );
          }
        }
      }

      if (store === STORE_BLOB || needsSeaRead) {
        const derivatives2: Derivative[] = [];
        stepDetect(record, marker, derivatives2);
        await this.stepDerivatives(record, marker, derivatives2);

        // After dependencies are resolved, rewrite .mjs require paths to .js
        // since the packer renames .mjs files to .js in the snapshot.
        // Skip in SEA mode — ESM-to-CJS transform is not applied there.
        if (!this.params.seaMode && record.wasTransformed && record.body) {
          record.body = Buffer.from(
            rewriteMjsRequirePaths(record.body.toString('utf8')),
            'utf8',
          );
        }
      }

      // Also rewrite .mjs require paths for STORE_CONTENT files that were transformed
      if (needsMjsTransform && record.wasTransformed && record.body) {
        record.body = Buffer.from(
          rewriteMjsRequirePaths(record.body.toString('utf8')),
          'utf8',
        );
      }
    }

    record[store] = true;
  }

  step_STORE_LINKS(record: FileRecord, data: unknown) {
    if (strictVerify) {
      assert(
        record.file === toNormalizedRealPath(record.file),
        ' expecting real file !!!',
      );
    }

    if (record[STORE_LINKS]) {
      record[STORE_LINKS].push(data);
      return;
    }

    record[STORE_LINKS] = [data];

    if (record[STORE_STAT]) {
      return;
    }
    this.appendStat({
      file: record.file,
      store: STORE_STAT,
    });
  }

  async step_STORE_STAT(record: FileRecord) {
    if (record[STORE_STAT]) return;

    const realPath = toNormalizedRealPath(record.file);
    if (realPath !== record.file) {
      this.appendStat({
        file: realPath,
        store: STORE_STAT,
      });
    }

    try {
      const valueStat = await fs.stat(record.file);

      const value = {
        mode: valueStat.mode,
        size: valueStat.isFile() ? valueStat.size : 0,
        isFileValue: valueStat.isFile(),
        isDirectoryValue: valueStat.isDirectory(),
        isSocketValue: valueStat.isSocket(),
        isSymbolicLinkValue: valueStat.isSymbolicLink(),
      };
      record[STORE_STAT] = value;
    } catch (error) {
      const exception = error as NodeJS.ErrnoException;
      log.error(`Cannot stat, ${exception.code}`, record.file);
      throw wasReported(exception.message);
    }

    if (path.dirname(record.file) !== record.file) {
      // root directory
      this.appendFileInFolder({
        file: path.dirname(record.file),
        store: STORE_LINKS,
        data: path.basename(record.file),
      });
    }
  }

  async step(task: Task) {
    const { file, store, data } = task;
    const record = this.records[file];

    switch (store) {
      case STORE_BLOB:
      case STORE_CONTENT:
        await this.step_STORE_ANY(record, task.marker!, store);
        break;
      case STORE_LINKS:
        this.step_STORE_LINKS(record, data);
        break;
      case STORE_STAT:
        await this.step_STORE_STAT(record);
        break;
      default:
        assert(false, `walker: unknown store ${store}`);
    }
  }

  async readDictionary(marker: Marker) {
    if (this.params.noDictionary?.[0] === '*') {
      return;
    }
    const dd = path.join(__dirname, '../dictionary');
    const files = await fs.readdir(dd);

    for (const file of files) {
      if (/\.js$/.test(file)) {
        const name = file.slice(0, -3);

        if (this.params.noDictionary?.includes(file)) {
          continue;
        }
        // eslint-disable-next-line @typescript-eslint/no-require-imports
        const config = require(path.join(dd, file));
        this.dictionary[name] = config;
      }
    }

    const pkgConfig = marker.config?.pkg;

    if (pkgConfig) {
      const { dictionary } = pkgConfig;

      if (dictionary) {
        for (const name in dictionary) {
          if (dictionary[name]) {
            this.dictionary[name] = { pkg: dictionary[name] };
          }
        }
      }
    }
  }

  async start(
    marker: Marker,
    entrypoint: string,
    addition: string | undefined,
    params: WalkerParams,
  ) {
    this.params = params;
    this.symLinks = {};

    await this.readDictionary(marker);

    entrypoint = normalizePath(entrypoint);

    await this.appendBlobOrContent({
      file: entrypoint,
      marker,
      store: STORE_BLOB,
    });

    if (addition) {
      addition = normalizePath(addition);
      await this.appendBlobOrContent({
        file: addition,
        marker,
        store: STORE_CONTENT,
      });
    }

    const { tasks } = this;

    for (let i = 0; i < tasks.length; i += 1) {
      // NO MULTIPLE WORKERS! THIS WILL LEAD TO NON-DETERMINISTIC
      // ORDER. one-by-one fifo is the only way to iterate tasks
      await this.step(tasks[i]);
    }

    return {
      symLinks: this.symLinks,
      records: this.records,
      entrypoint: normalizePath(entrypoint),
    };
  }
}

export default async function walker(...args: Parameters<Walker['start']>) {
  const w = new Walker();
  return w.start(...args);
}