@astryxdesign/cli 0.7.11 → 0.7.12-canary.ccb4a6d

package/api/swizzle/_moduleGraph.mjs

@@ -0,0 +1,795 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file swizzle.copy module graph — decides, for each module a component
+ * reaches, whether the copy imports it from the owner package's public
+ * exports or carries it in the output.
+ *
+ * @input the owner package's source root and `exports` map, the component folder
+ * @output the files the copy holds, each with its rewritten source
+ * @position api/swizzle adapter helper; the copy leaf reaches it through _adapter.mjs
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {isBuiltin} from 'node:module';
+import {packageOf} from '../../foundation/render/served-packages.mjs';
+import {parse} from '@babel/parser';
+import {
+  inspectPackageExport,
+  sourceExportTarget,
+} from '../../foundation/discovery/package-exports.mjs';
+import {
+  moduleExportOrigins,
+  resolveLocalModule,
+} from '../../foundation/discovery/module-exports.mjs';
+import {
+  allTargets,
+  isRecord,
+  subpathDeclaration,
+} from '../../foundation/integrations/exports-subpaths.mjs';
+
+/** The extensions an extensionless import may name, in resolution order. */
+const CODE_FILE = /\.[cm]?[jt]sx?$/;
+const DECLARATION_FILE = /\.d\.[cm]?ts$/;
+const STYLEX_FILE = /\.stylex\.[cm]?[jt]sx?$/;
+
+/** @param {string} file */
+const toPosix = file => file.split(path.sep).join('/');
+
+/**
+ * The file an import names, or null when no file is there.
+ * @param {string} fromFile absolute path of the importing file
+ * @param {string} specifier a relative specifier
+ * @param {Map<string, string|null>} cache resolutions already made in this copy
+ * @returns {string|null}
+ */
+function resolveRelative(fromFile, specifier, cache) {
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  const known = cache.get(base);
+  if (known !== undefined) return known;
+  const found = resolveLocalModule(specifier, fromFile);
+  cache.set(base, found);
+  return found;
+}
+
+/**
+ * @typedef {object} ImportSpecifier
+ * @property {string} imported the exported name (`default` for a default import)
+ * @property {string} local
+ * @property {boolean} typeOnly
+ *
+ * @typedef {object} ModuleReference
+ * @property {'named'|'namespace'|'sideEffect'|'dynamic'|'reexportAll'|'reexportNamed'} kind
+ * @property {string} source the specifier as written
+ * @property {number} start statement (or, for `import()`, string literal) start
+ * @property {number} end
+ * @property {boolean} typeOnly the whole statement is `import type` / `export type`
+ * @property {ImportSpecifier[]} specifiers
+ * @property {string} [namespace] the local name of `* as X`
+ *
+ * @typedef {object} ParsedModule
+ * @property {string} code
+ * @property {ModuleReference[]} references
+ * @property {Set<string>} declares names the module declares and exports
+
+ */
+
+/**
+ * A module's source and every module reference in it: static imports and
+ * re-exports, `import()` calls, and `import('…')` types.
+ * @param {string} file
+ * @returns {ParsedModule}
+ */
+function parseModule(file) {
+  const code = fs.readFileSync(file, 'utf-8');
+  /** @type {ParsedModule} */
+  const parsed = {code, references: [], declares: new Set()};
+  if (!CODE_FILE.test(file)) return parsed;
+  const ast = parse(code, {
+    sourceType: 'module',
+    errorRecovery: true,
+    plugins: /\.[cm]?tsx?$/.test(file) ? ['typescript', 'jsx'] : ['jsx'],
+  });
+  const {references} = parsed;
+  // Babel's node types mark positions optional; a parsed file always has them.
+  for (const node of /** @type {any[]} */ (ast.program.body)) {
+    for (const d of node.declaration?.declarations ?? [node.declaration]) {
+      if (node.type === 'ExportNamedDeclaration' && d?.id?.name)
+        parsed.declares.add(d.id.name);
+    }
+    if (node.type === 'ImportDeclaration') {
+      const typeOnly = node.importKind === 'type';
+      const base = {
+        source: node.source.value,
+        start: node.start,
+        end: node.end,
+        typeOnly,
+      };
+      const namespace = node.specifiers.find(
+        (/** @type {any} */ s) => s.type === 'ImportNamespaceSpecifier',
+      );
+      const named = node.specifiers.filter(
+        (/** @type {any} */ s) => s.type !== 'ImportNamespaceSpecifier',
+      );
+      if (node.specifiers.length === 0) {
+        references.push({...base, kind: 'sideEffect', specifiers: []});
+      } else if (namespace && named.length === 0) {
+        references.push({
+          ...base,
+          kind: 'namespace',
+          specifiers: [],
+          namespace: namespace.local.name,
+        });
+      } else if (!namespace) {
+        references.push({
+          ...base,
+          kind: 'named',
+          specifiers: named.map((/** @type {any} */ s) => ({
+            imported:
+              s.type === 'ImportDefaultSpecifier'
+                ? 'default'
+                : s.imported.type === 'StringLiteral'
+                  ? s.imported.value
+                  : s.imported.name,
+            local: s.local.name,
+            typeOnly: typeOnly || s.importKind === 'type',
+          })),
+        });
+      } else {
+        // `import X, * as Y from` names the whole module.
+        references.push({...base, kind: 'namespace', specifiers: []});
+      }
+    } else if (node.type === 'ExportAllDeclaration') {
+      references.push({
+        kind: 'reexportAll',
+        source: node.source.value,
+        start: node.start,
+        end: node.end,
+        typeOnly: node.exportKind === 'type',
+        specifiers: [],
+      });
+    } else if (node.type === 'ExportNamedDeclaration' && node.source) {
+      const typeOnly = node.exportKind === 'type';
+      references.push({
+        kind: 'reexportNamed',
+        source: node.source.value,
+        start: node.start,
+        end: node.end,
+        typeOnly,
+        specifiers: node.specifiers.map((/** @type {any} */ s) => ({
+          imported: s.type === 'ExportNamespaceSpecifier' ? '*' : s.local.name,
+          local:
+            s.exported.type === 'StringLiteral'
+              ? s.exported.value
+              : s.exported.name,
+          typeOnly: typeOnly || s.exportKind === 'type',
+        })),
+      });
+    }
+  }
+  visitDynamicReferences(ast.program, literal => {
+    references.push({
+      kind: 'dynamic',
+      source: literal.value,
+      start: literal.start,
+      end: literal.end,
+      typeOnly: false,
+      specifiers: [],
+    });
+  });
+  return parsed;
+}
+
+/**
+ * Call `onLiteral` with the string literal of every `import('…')` call and
+ * `import('…')` type under a node.
+ * @param {any} node
+ * @param {(literal: {value: string, start: number, end: number}) => void} onLiteral
+ */
+function visitDynamicReferences(node, onLiteral) {
+  if (node == null || typeof node !== 'object') return;
+  if (Array.isArray(node)) {
+    for (const child of node) visitDynamicReferences(child, onLiteral);
+    return;
+  }
+  if (
+    node.type === 'CallExpression' &&
+    node.callee?.type === 'Import' &&
+    node.arguments[0]?.type === 'StringLiteral'
+  ) {
+    onLiteral(node.arguments[0]);
+  } else if (
+    node.type === 'ImportExpression' &&
+    node.source?.type === 'StringLiteral'
+  ) {
+    onLiteral(node.source);
+  } else if (node.type === 'TSImportType') {
+    const literal =
+      node.argument?.type === 'TSLiteralType'
+        ? node.argument.literal
+        : node.argument;
+    if (literal?.type === 'StringLiteral') onLiteral(literal);
+  }
+  for (const key of Object.keys(node)) {
+    if (
+      key === 'loc' ||
+      key === 'leadingComments' ||
+      key === 'trailingComments' ||
+      key === 'innerComments'
+    )
+      continue;
+    const value = node[key];
+    if (value && typeof value === 'object')
+      visitDynamicReferences(value, onLiteral);
+  }
+}
+
+/**
+ * @typedef {'value' | 'type'} ExportKind `value` reads runtime exports only;
+ *   `type` reads type-only exports too
+ *
+ * @typedef {(file: string, kind: ExportKind) => Map<string, {file: string, name: string}>} OriginsOf
+ *   every name a module exports, with where it is declared
+ *
+ * @typedef {Map<string, Array<{subpath: string, name: string}>>} ExportersByOrigin
+ *   `file#name` of a declaration -> the subpaths that export it, and as what
+ *
+ * @typedef {object} PublicSurface
+ * @property {Record<ExportKind, ExportersByOrigin>} byOrigin the subpaths
+ *   that export each declaration as a value, and as a value or a type
+ * @property {Map<string, string>} byFile source file -> the subpath that
+ *   exports exactly that file
+ * @property {Record<string, unknown>|undefined} exportsField
+ */
+
+/**
+ * Every public subpath of a package with the source file under `root` that
+ * the shared export readers give it. `./internal/*` is never public.
+ * @param {{exports?: unknown}} pkg
+ * @param {string} packageDir
+ * @param {string} root
+ * @returns {Array<[string, string]>}
+ */
+function exportedSourceFiles(pkg, packageDir, root) {
+  const exportsField = pkg.exports;
+  const subpathMap =
+    isRecord(exportsField) &&
+    Object.keys(exportsField).some(key => key.startsWith('.'));
+  const candidates = new Set(['.']);
+  if (subpathMap) {
+    for (const [key, value] of Object.entries(exportsField)) {
+      if (!key.includes('*')) {
+        candidates.add(key);
+        continue;
+      }
+      for (const subpath of wildcardSubpaths(packageDir, root, key, value)) {
+        candidates.add(subpath);
+      }
+    }
+  }
+  /** @type {Array<[string, string]>} */
+  const found = [];
+  for (const subpath of candidates) {
+    if (/^\.\/internal(\/|$)/.test(subpath)) continue;
+    const inspected = inspectPackageExport(pkg, packageDir, subpath);
+    if (!inspected.exported) continue;
+    const file =
+      sourceExportTarget(pkg, packageDir, subpath) ?? inspected.target;
+    if (
+      file &&
+      file.startsWith(root + path.sep) &&
+      !DECLARATION_FILE.test(file)
+    ) {
+      found.push([subpath, file]);
+    }
+  }
+  return found;
+}
+
+/**
+ * The subpaths a `*` key names: one per file its target patterns match.
+ * @param {string} packageDir
+ * @param {string} root
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+function wildcardSubpaths(packageDir, root, key, value) {
+  /** @type {string[]} */
+  const subpaths = [];
+  for (const pattern of allTargets(value)) {
+    if (!pattern.startsWith('./') || !pattern.includes('*')) continue;
+    const fixed = pattern.slice(2, pattern.indexOf('*'));
+    const base = path.resolve(
+      packageDir,
+      fixed.slice(0, fixed.lastIndexOf('/') + 1),
+    );
+    if (!base.startsWith(root) || !fs.existsSync(base)) continue;
+    for (const entry of fs.readdirSync(base, {
+      recursive: true,
+      withFileTypes: true,
+    })) {
+      if (!entry.isFile()) continue;
+      const file = path.join(entry.parentPath, entry.name);
+      if (path.relative(base, file).split(path.sep).includes('node_modules'))
+        continue;
+      const rel = toPosix(path.relative(packageDir, file));
+      if (!rel.startsWith(fixed)) continue;
+      const rest = rel.slice(fixed.length);
+      for (let end = 1; end <= rest.length; end++) {
+        const star = rest.slice(0, end);
+        if (pattern.slice(2).replaceAll('*', star) === rel) {
+          subpaths.push(key.replace('*', star));
+          break;
+        }
+      }
+    }
+  }
+  return subpaths;
+}
+
+/**
+ * The owner package's public surface, read from its `exports` map: each
+ * subpath with a `source` condition under the source root, and the
+ * declarations it exports. `./internal/*` subpaths are not public.
+ * @param {string} packageDir
+ * @param {string} srcRoot
+ * @param {OriginsOf} originsOf
+ * @returns {PublicSurface}
+ */
+function publicSurfaceOf(packageDir, srcRoot, originsOf) {
+  /** @type {{exports?: unknown}} */
+  let pkg;
+  try {
+    pkg = JSON.parse(
+      fs.readFileSync(path.join(packageDir, 'package.json'), 'utf-8'),
+    );
+  } catch {
+    pkg = {};
+  }
+  const exportsField =
+    pkg.exports && typeof pkg.exports === 'object'
+      ? /** @type {Record<string, unknown>} */ (pkg.exports)
+      : undefined;
+  /** @type {PublicSurface['byOrigin']} */
+  const byOrigin = {value: new Map(), type: new Map()};
+  /** @type {PublicSurface['byFile']} */
+  const byFile = new Map();
+  for (const [subpath, sourceFile] of exportedSourceFiles(
+    pkg,
+    packageDir,
+    srcRoot,
+  )) {
+    byFile.set(sourceFile, subpath);
+    if (!CODE_FILE.test(sourceFile)) continue;
+    for (const kind of /** @type {const} */ (['value', 'type'])) {
+      for (const [name, origin] of originsOf(sourceFile, kind)) {
+        const key = `${origin.file}#${origin.name}`;
+        const list = byOrigin[kind].get(key) ?? [];
+        list.push({subpath, name});
+        byOrigin[kind].set(key, list);
+      }
+    }
+  }
+  return {byOrigin, byFile, exportsField};
+}
+
+/**
+ * A specifier that is either fixed (a public subpath) or computed from where
+ * two copied files land.
+ * @typedef {string | {from: string, to: string}} SpecifierChoice
+ *
+ * @typedef {object} PlannedEdit
+ * @property {number} start
+ * @property {number} end
+ * @property {(specifierOf: (choice: SpecifierChoice) => string) => string} render
+ *
+ * @typedef {object} CopyPlan
+ * @property {Map<string, {code: string, edits: PlannedEdit[]}>} files every
+ *   file the copy holds (absolute source path), with the edits its imports need
+ * @property {Map<string, Set<string>>} dependsOn file -> carried files its
+ *   computed specifiers point at
+ * @property {Record<string, string>} dependencies each npm package the copied
+ *   files import, other than the owner package and Node's built-in modules,
+ *   with the range the owner package declares
+ */
+
+/**
+ * Follow a component's module graph from its entry files and decide what the
+ * copy holds. A module inside the component folder is copied. A module
+ * outside it is reached through the owner package's public exports when every
+ * name taken from it is public there; otherwise the module that defines the
+ * name is copied, and imported by relative path. Tests, stories and docs are
+ * never reached, so they are never copied.
+ *
+ * @param {object} options
+ * @param {string} options.packageDir the owner package root
+ * @param {string} options.srcRoot its source root
+ * @param {string} options.componentDir
+ * @param {string} options.ownerPackage
+ * @param {string[]} options.entries absolute entry files of the component
+ * @returns {CopyPlan}
+ */
+export function planCopy({
+  packageDir,
+  srcRoot,
+  componentDir,
+  ownerPackage,
+  entries,
+}) {
+  // Every read is cached for this copy only, so a later copy sees the
+  // package as it is then.
+  const exportMemos = {value: new Map(), type: new Map()};
+  /** @type {OriginsOf} */
+  const originsOf = (file, kind) =>
+    moduleExportOrigins(file, {
+      types: kind === 'type',
+      memo: exportMemos[kind],
+    });
+  /** @param {string} file @param {string} name */
+  const originOf = (file, name) => originsOf(file, 'type').get(name) ?? null;
+  /**
+   * The subpaths that export a module's export: as a value when the import
+   * takes a value, since a type-only export is erased at runtime.
+   * @param {string} file
+   * @param {string} name
+   * @param {boolean} typeOnly
+   */
+  const exportersOf = (file, name, typeOnly) => {
+    const origin = originOf(file, name);
+    if (!origin) return [];
+    const kind = typeOnly ? 'type' : 'value';
+    return surface.byOrigin[kind].get(`${origin.file}#${origin.name}`) ?? [];
+  };
+  /**
+   * The name a module exports one of its own bindings under, or null.
+   * @param {{file: string, name: string}} origin
+   */
+  const exportNameOf = origin => {
+    for (const [name, found] of originsOf(origin.file, 'type')) {
+      if (found.file === origin.file && found.name === origin.name) return name;
+    }
+    return null;
+  };
+  /** @type {Map<string, string|null>} */
+  const resolutions = new Map();
+  const surface = publicSurfaceOf(packageDir, srcRoot, originsOf);
+  /** @type {CopyPlan['files']} */
+  const files = new Map();
+  /** @type {CopyPlan['dependsOn']} */
+  const dependsOn = new Map();
+  /** @type {Set<string>} */
+  const packages = new Set();
+  const queue = [...entries];
+  const queued = new Set(queue);
+  /** @param {string} file */
+  const enqueue = file => {
+    if (!queued.has(file)) {
+      queued.add(file);
+      queue.push(file);
+    }
+  };
+  /** @param {string} file */
+  const inComponent = file => file.startsWith(componentDir + path.sep);
+  /** @param {string} file */
+  const inSource = file => file.startsWith(srcRoot + path.sep);
+
+  /**
+   * The subpath that exports every name a module exports, with the same
+   * definition. An exactly exported file is its own subpath.
+   * @param {string} file
+   * @returns {string|null}
+   */
+  const subpathCoveringModule = file => {
+    const exact = surface.byFile.get(file);
+    if (exact) return exact;
+    const names = [...originsOf(file, 'type').keys()];
+    if (names.length === 0) return null;
+    const values = originsOf(file, 'value');
+    const options = names.map(name =>
+      exportersOf(file, name, !values.has(name))
+        .filter(o => o.name === name)
+        .map(o => o.subpath),
+    );
+    const common = options.reduce((acc, list) =>
+      acc.filter(s => list.includes(s)),
+    );
+    return STYLEX_FILE.test(file) ? null : pickSubpath(common, file);
+  };
+
+  /**
+   * The public subpath to take a name from. A StyleX module is imported by
+   * its own exported path, because the StyleX compiler resolves styles and
+   * variables from the real module; when that path is not exported, there is
+   * no public import.
+   * @param {string[]} subpaths subpaths that export the name
+   * @param {string} target the module the import names
+   * @param {string} [originFile] the module that defines the name
+   * @returns {string|null}
+   */
+  const choosePublic = (subpaths, target, originFile) => {
+    const exact = originFile ? surface.byFile.get(originFile) : undefined;
+    if (exact && subpaths.includes(exact)) return exact;
+    if (
+      STYLEX_FILE.test(target) ||
+      (originFile && STYLEX_FILE.test(originFile))
+    )
+      return null;
+    return pickSubpath(subpaths, target);
+  };
+
+  /**
+   * Prefer the subpath of the module's top folder, then the package root.
+   * @param {string[]} subpaths
+   * @param {string} file
+   * @returns {string|null}
+   */
+  const pickSubpath = (subpaths, file) => {
+    if (subpaths.length === 0) return null;
+    const top = `./${toPosix(path.relative(srcRoot, file)).split('/')[0]}`;
+    return (
+      subpaths.find(s => s === top) ??
+      subpaths.find(s => s === '.') ??
+      [...subpaths].sort((a, b) => a.length - b.length)[0]
+    );
+  };
+
+  /** @param {string} subpath */
+  const publicSpecifier = subpath =>
+    subpath === '.' ? ownerPackage : `${ownerPackage}/${subpath.slice(2)}`;
+
+  /**
+   * Carry a module in the copy.
+   * @param {string} from
+   * @param {string} to
+   * @returns {SpecifierChoice}
+   */
+  const carry = (from, to) => {
+    enqueue(to);
+    const deps = dependsOn.get(from) ?? new Set();
+    deps.add(to);
+    dependsOn.set(from, deps);
+    return {from, to};
+  };
+
+  while (queue.length > 0) {
+    const file = /** @type {string} */ (queue.shift());
+    const parsed = parseModule(file);
+    /** @type {PlannedEdit[]} */
+    const edits = [];
+    files.set(file, {code: parsed.code, edits});
+    if (!CODE_FILE.test(file)) continue;
+    for (const ref of parsed.references) {
+      if (!ref.source.startsWith('.')) {
+        const builtin = ref.source.startsWith('node:') || isBuiltin(ref.source);
+        const name = packageOf(ref.source);
+        if (!builtin && name !== ownerPackage) packages.add(name);
+        continue;
+      }
+      const target = resolveRelative(file, ref.source, resolutions);
+      // A dangling import is left for the build to report.
+      if (!target) continue;
+      if (inComponent(target)) {
+        // Files of the component keep their relative imports of each other.
+        if (inComponent(file)) enqueue(target);
+        else edits.push(sourceEdit(parsed.code, ref, carry(file, target)));
+        continue;
+      }
+      if (!CODE_FILE.test(target) || !inSource(target)) {
+        // An asset, such as `../../locales/en.json` or a stylesheet, that the
+        // package exports by its own path is imported from the package.
+        const subpath = `./${toPosix(path.relative(packageDir, target))}`;
+        if (
+          subpathDeclaration(surface.exportsField, subpath).state === 'declared'
+        ) {
+          edits.push(
+            sourceEdit(parsed.code, ref, `${ownerPackage}/${subpath.slice(2)}`),
+          );
+          continue;
+        }
+        // An unexported asset in the source is carried; one outside it is
+        // left for the build to report.
+        if (!inSource(target)) continue;
+        edits.push(sourceEdit(parsed.code, ref, carry(file, target)));
+        continue;
+      }
+      edits.push(planReference(file, parsed.code, ref, target));
+    }
+  }
+  return {files, dependsOn, dependencies: declaredRanges(packageDir, packages)};
+
+  /**
+   * Decide one reference that leaves the component folder.
+   * @param {string} file
+   * @param {string} code
+   * @param {ModuleReference} ref
+   * @param {string} target
+   * @returns {PlannedEdit}
+   */
+  function planReference(file, code, ref, target) {
+    if (ref.kind !== 'named' && ref.kind !== 'reexportNamed') {
+      const covering = subpathCoveringModule(target);
+      return sourceEdit(
+        code,
+        ref,
+        covering ? publicSpecifier(covering) : carry(file, target),
+      );
+    }
+    /** @type {Array<{choice: SpecifierChoice, specs: ImportSpecifier[]}>} */
+    const groups = [];
+    /** @param {SpecifierChoice} choice @param {ImportSpecifier} spec */
+    const add = (choice, spec) => {
+      const same = groups.find(g =>
+        typeof choice === 'string'
+          ? g.choice === choice
+          : typeof g.choice !== 'string' && g.choice.to === choice.to,
+      );
+      if (same) same.specs.push(spec);
+      else groups.push({choice, specs: [spec]});
+    };
+    for (const spec of ref.specifiers) {
+      if (spec.imported === '*') {
+        const covering = subpathCoveringModule(target);
+        add(covering ? publicSpecifier(covering) : carry(file, target), spec);
+        continue;
+      }
+      const origin = originOf(target, spec.imported);
+      const publicOptions = exportersOf(target, spec.imported, spec.typeOnly);
+      const chosen = choosePublic(
+        publicOptions.map(o => o.subpath),
+        target,
+        origin?.file,
+      );
+      if (chosen) {
+        const exported = /** @type {{name: string}} */ (
+          publicOptions.find(o => o.subpath === chosen)
+        ).name;
+        add(publicSpecifier(chosen), {...spec, imported: exported});
+      } else {
+        // Take the name from the module that defines it, so the copy carries
+        // that module and not a whole barrel. An origin names a binding, so
+        // the import uses the name that module exports it under.
+        // A module that declares the name itself, even as an alias, is carried.
+        const definingExport =
+          origin &&
+          origin.file !== target &&
+          inSource(origin.file) &&
+          !parseModule(target).declares.has(spec.imported)
+            ? exportNameOf(origin)
+            : null;
+        if (origin && definingExport != null) {
+          add(carry(file, origin.file), {...spec, imported: definingExport});
+        } else {
+          add(carry(file, target), spec);
+        }
+      }
+    }
+    // One source and the same names: keep the statement as written and swap
+    // only its specifier.
+    const unchangedNames =
+      groups.length === 1 &&
+      groups[0].specs.every(
+        (spec, i) => spec.imported === ref.specifiers[i].imported,
+      );
+    if (unchangedNames) return sourceEdit(code, ref, groups[0].choice);
+    return {
+      start: ref.start,
+      end: ref.end,
+      render: specifierOf => renderStatements(ref, groups, specifierOf),
+    };
+  }
+}
+
+/**
+ * The version range the owner package declares for each npm package the copy
+ * imports, by name; `*` for one it does not declare.
+ * @param {string} packageDir
+ * @param {Iterable<string>} names
+ * @returns {Record<string, string>}
+ */
+function declaredRanges(packageDir, names) {
+  /** @type {Record<string, Record<string, string>>} */
+  let manifest = {};
+  try {
+    manifest = JSON.parse(
+      fs.readFileSync(path.join(packageDir, 'package.json'), 'utf-8'),
+    );
+  } catch {
+    // An unreadable manifest declares nothing.
+  }
+  /** @type {Record<string, string>} */
+  const ranges = {};
+  for (const name of [...names].sort()) {
+    ranges[name] =
+      manifest.dependencies?.[name] ??
+      manifest.optionalDependencies?.[name] ??
+      manifest.peerDependencies?.[name] ??
+      '*';
+  }
+  return ranges;
+}
+
+/**
+ * An edit that replaces only the string literal of a reference.
+ * @param {string} code
+ * @param {ModuleReference} ref
+ * @param {SpecifierChoice} choice
+ * @returns {PlannedEdit}
+ */
+function sourceEdit(code, ref, choice) {
+  const slice = code.slice(ref.start, ref.end);
+  const quoted = new RegExp(
+    `(['"])${ref.source.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\1`,
+  );
+  const m = slice.match(quoted);
+  const at = m && m.index != null ? ref.start + m.index : ref.start;
+  const length = m ? m[0].length : 0;
+  const quote = m ? m[1] : "'";
+  return {
+    start: at,
+    end: at + length,
+    render: specifierOf =>
+      m ? `${quote}${specifierOf(choice)}${quote}` : slice,
+  };
+}
+
+/**
+ * The statements that replace one named import or re-export, one per source.
+ * @param {ModuleReference} ref
+ * @param {Array<{choice: SpecifierChoice, specs: ImportSpecifier[]}>} groups
+ * @param {(choice: SpecifierChoice) => string} specifierOf
+ */
+function renderStatements(ref, groups, specifierOf) {
+  const keyword = ref.kind === 'reexportNamed' ? 'export' : 'import';
+  const statements = [];
+  for (const {choice, specs} of groups) {
+    const specifier = specifierOf(choice);
+    const star = specs.find(s => s.imported === '*');
+    if (star) statements.push(`export * as ${star.local} from '${specifier}';`);
+    const named = specs.filter(s => s.imported !== '*');
+    if (named.length === 0) continue;
+    const allType = ref.typeOnly || named.every(s => s.typeOnly);
+    const parts = named.map(s => {
+      const prefix = !allType && s.typeOnly ? 'type ' : '';
+      return s.imported === s.local
+        ? `${prefix}${s.local}`
+        : `${prefix}${s.imported} as ${s.local}`;
+    });
+    const head = `${keyword} ${allType ? 'type ' : ''}`;
+    const oneLine = `${head}{${parts.join(', ')}} from '${specifier}';`;
+    statements.push(
+      oneLine.length <= 80
+        ? oneLine
+        : `${head}{\n${parts.map(p => `  ${p},`).join('\n')}\n} from '${specifier}';`,
+    );
+  }
+  return statements.join('\n');
+}
+
+/**
+ * The source of a planned file with its edits applied.
+ * @param {{code: string, edits: PlannedEdit[]}} planned
+ * @param {(choice: SpecifierChoice) => string} specifierOf
+ */
+export function renderFile(planned, specifierOf) {
+  let out = planned.code;
+  for (const edit of [...planned.edits].sort((a, b) => b.start - a.start)) {
+    out =
+      out.slice(0, edit.start) + edit.render(specifierOf) + out.slice(edit.end);
+  }
+  return out;
+}
+
+/**
+ * The relative specifier from one written file to another.
+ * @param {string} fromDest
+ * @param {string} toDest
+ */
+export function relativeSpecifierBetween(fromDest, toDest) {
+  let rel = toPosix(path.relative(path.dirname(fromDest), toDest));
+  rel = DECLARATION_FILE.test(toDest)
+    ? rel.replace(/\.d\.[cm]?ts$/, '')
+    : rel.replace(/\.(?:[cm]?[jt]sx?)$/, '');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}