work around api extractor package resolution

.api-reports/api-report-utilities_globals.api.md

@@ -4,9 +4,10 @@
 
 ```ts
 
-import { __DEV__ as __DEV___2 } from '@apollo/client/utilities/globals/environment';
 import { InvariantError } from 'ts-invariant';
 
+// @public (undocumented)
+const __DEV___2: boolean;
 export { __DEV___2 as __DEV__ }
 
 // @public (undocumented)

api-extractor.json

@@ -5,7 +5,7 @@
   "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
   "projectFolder": ".",
   "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
-  "bundledPackages": [],
+  "bundledPackages": ["@apollo/client"],
   "newlineKind": "lf",
   "enumMemberOrder": "preserve",
 

config/apiExtractor.ts

@@ -9,6 +9,7 @@ import { parseArgs } from "node:util";
 import fs from "node:fs";
 import { entryPoints, buildDocEntryPoints } from "./entryPoints.ts";
 import { readFileSync } from "fs";
+import { withPseudoNodeModules } from "./helpers.ts";
 
 const parsed = parseArgs({
   options: {
@@ -61,29 +62,29 @@ try {
       })
     );
 
-    buildReport(entryPointFile, "docModel");
+    await buildReport(entryPointFile, "docModel");
   }
 
   if (parsed.values.generate?.includes("apiReport")) {
-    entryPoints.map((entryPoint) => {
+    for (const entryPoint of entryPoints) {
       const path = entryPoint.dirs.join("/");
       const mainEntryPointFilePath =
         `<projectFolder>/dist/${path}/index.d.ts`.replace("//", "/");
       console.log(
         "\n\nCreating API extractor report for " + mainEntryPointFilePath
       );
-      buildReport(
+      await buildReport(
         mainEntryPointFilePath,
         "apiReport",
         `api-report${path ? "-" + path.replace(/\//g, "_") : ""}.api.md`
       );
-    });
+    }
   }
 } finally {
   fs.rmSync(tempDir, { recursive: true });
 }
 
-function buildReport(
+async function buildReport(
   mainEntryPointFilePath: string,
   mode: "apiReport" | "docModel",
   reportFileName = ""
@@ -117,10 +118,12 @@ function buildReport(
     configObjectFullPath,
   });
 
-  const extractorResult = Extractor.invoke(extractorConfig, {
-    localBuild: process.env.CI === undefined || process.env.CI === "false",
-    showVerboseMessages: true,
-  });
+  const extractorResult = await withPseudoNodeModules(() =>
+    Extractor.invoke(extractorConfig, {
+      localBuild: process.env.CI === undefined || process.env.CI === "false",
+      showVerboseMessages: true,
+    })
+  );
 
   let succeededAdditionalChecks = true;
   if (fs.existsSync(extractorConfig.reportFilePath)) {

config/build.ts

@@ -38,7 +38,7 @@ const buildSteps = {
   typescript: compileTs,
   babelTransform,
   updateVersion,
-  //inlineInheritDoc,
+  inlineInheritDoc,
   processInvariants,
   postprocessDist,
   verifyVersion,

config/entryPoints.ts

@@ -30,10 +30,8 @@ export const buildDocEntryPoints = (
 ) => {
   const acc = entryPoints.map((entryPoint) => {
     return `export * from "${path.join(
-      options.rootDir,
-      options.targetDir,
-      ...entryPoint.dirs,
-      `index.${options.jsExt}`
+      "@apollo/client",
+      ...entryPoint.dirs
     )}";`;
   });
   acc.push(

config/helpers.ts

@@ -2,14 +2,14 @@ import * as path from "path";
 import * as recast from "recast";
 import * as parser from "recast/parsers/babel.js";
 import * as tsParser from "recast/parsers/typescript.js";
-import glob from "glob";
-import { glob as nodeGlob } from "node:fs/promises";
+import { glob as nodeGlob, unlink } from "node:fs/promises";
 import { readFile, rm } from "node:fs/promises";
 import * as assert from "node:assert";
 // @ts-ignore unfortunately we don't have types for this as it's JS with JSDoc
 // eslint-disable-next-line import/no-unresolved
 import * as sorcery from "sorcery";
 import { relative } from "node:path";
+import { mkdir, rmdir, symlink } from "node:fs/promises";
 
 export const distDir = path.resolve(import.meta.dirname, "..", "dist");
 
@@ -100,3 +100,25 @@ export async function applyRecast({
     await chain.write();
   }
 }
+
+/**
+ * creates a pseudo "dist/node_modules" folder with
+ * "dist/node_modules/@apollo/client" symlinked to "dist"
+ * so that tools can pick up the client package as an "external" package
+ */
+export async function withPseudoNodeModules<T>(fn: () => T) {
+  const dist = path.join(import.meta.dirname, "..", "dist");
+  const node_modules = path.join(dist, "node_modules");
+  const parent = path.join(node_modules, "@apollo");
+  const link = path.join(parent, "client");
+
+  try {
+    await mkdir(parent, { recursive: true });
+    await unlink(link).catch(() => {});
+    await symlink(dist, link);
+
+    return await fn();
+  } finally {
+    await rmdir(node_modules, { recursive: true });
+  }
+}

config/inlineInheritDoc.ts

@@ -29,11 +29,11 @@ import { ApiModel, ApiDocumentedItem } from "@microsoft/api-extractor-model";
 import { DeclarationReference } from "@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js";
 import { StringBuilder, TSDocEmitter } from "@microsoft/tsdoc";
 
-import { applyRecast } from "./helpers.ts";
+import { applyRecast, withPseudoNodeModules } from "./helpers.ts";
 import { visit } from "recast";
 import type { BuildStep, BuildStepOptions } from "./build.ts";
 
-import fs from "node:fs";
+import fs, { mkdirSync, symlinkSync } from "node:fs";
 import path from "node:path";
 import {
   Extractor,
@@ -46,7 +46,7 @@ export const inlineInheritDoc: BuildStep = async (options) => {
     "Processing {@inheritDoc <canonicalReference>} comments in .d.ts files."
   );
 
-  const model = loadApiModel(options);
+  const model = await withPseudoNodeModules(() => loadApiModel(options));
   await processComments(model, options);
 };
 
@@ -78,6 +78,13 @@ function loadApiModel(options: BuildStepOptions) {
   try {
     const entryPointFile = path.join(tempDir, "entry.d.ts");
     fs.writeFileSync(entryPointFile, buildDocEntryPoints(options));
+    mkdirSync(path.join(tempDir, "node_modules", "@apollo"), {
+      recursive: true,
+    });
+    symlinkSync(
+      options.packageRoot,
+      path.join(tempDir, "node_modules", "@apollo", "client")
+    );
 
     // Load and parse the api-extractor.json file
     const configObjectFullPath = path.resolve(