@k8slens/package-build 3.1.0 → 3.3.0

package/src/declared-imports-plugin.ts

@@ -0,0 +1,137 @@
+import type { Plugin } from "esbuild";
+import { builtinModules as rawBuiltinModules } from "node:module";
+import path from "node:path";
+import { partition } from "lodash";
+
+export interface DeclaredImportsPluginParams {
+  readonly packageDirectory: string;
+  readonly packageJson: {
+    readonly name: string;
+    readonly dependencies?: Record<string, string>;
+    readonly peerDependencies?: Record<string, string>;
+    readonly devDependencies?: Record<string, string>;
+    readonly lens?: { readonly inlinedDependencies?: readonly string[] };
+  };
+}
+
+const isExperimentalModule = (module: string) => module.startsWith("_");
+const alsoAddNodeRefs = (module: string) => [module, `node:${module}`];
+
+const { builtinModules, disallowedBuiltinModules } = (() => {
+  const [disallowed, allowed] = partition(rawBuiltinModules, isExperimentalModule);
+
+  return {
+    disallowedBuiltinModules: new Set(disallowed.flatMap(alsoAddNodeRefs)),
+    builtinModules: new Set(allowed.flatMap(alsoAddNodeRefs)),
+  };
+})();
+
+const getPackageName = (specifier: string) => {
+  const [firstPart, secondPart] = specifier.split("/");
+
+  return specifier.startsWith("@") ? [firstPart, secondPart].join("/") : firstPart;
+};
+
+const bundleIt = null;
+
+/**
+ * Keeps a package's dist to the package's own code: every bare import of the package's own
+ * sources must name a package declared in its dependencies or peerDependencies, and stays a
+ * `require()` of it. Esbuild would otherwise inline the imported package and everything it
+ * imports in turn, shipping a private copy of e.g. MobX or the DI container in the dist, with
+ * module state of its own. A package that inlines something on purpose names it in
+ * `lens.inlinedDependencies` (and declares it as a devDependency).
+ *
+ * A package of the Lens monorepo, which has a `lens` section in its package.json, fails to build
+ * on such an import. Any other package, such as an extension built with this tool, is warned
+ * instead, as its build inlined undeclared imports before and keeps doing so.
+ */
+export const declaredImportsPlugin = ({ packageDirectory, packageJson }: DeclaredImportsPluginParams): Plugin => {
+  const externals = new Set([
+    ...Object.keys(packageJson.dependencies ?? {}),
+    ...Object.keys(packageJson.peerDependencies ?? {}),
+  ]);
+
+  const devDependencies = new Set(Object.keys(packageJson.devDependencies ?? {}));
+  const inlinedDependencies = new Set(packageJson.lens?.inlinedDependencies ?? []);
+
+  const fail = (text: string) => ({ errors: [{ text }] });
+  const isPackageOfMonorepo = packageJson.lens !== undefined;
+  const refuse = (text: string) => (isPackageOfMonorepo ? fail(text) : { warnings: [{ text }] });
+
+  return {
+    name: "declared-imports",
+    setup: (build) => {
+      build.onResolve({ filter: /^\./ }, (args) => {
+        const relativePathToImporter = path.relative(packageDirectory, args.importer);
+        const relativePath = path.relative(packageDirectory, path.resolve(args.resolveDir, args.path));
+
+        if (relativePath.startsWith("..") && !relativePathToImporter.startsWith("..")) {
+          return fail(
+            `Tried to import "${args.path}" from "${relativePathToImporter}" but it is outside of the package.`,
+          );
+        }
+
+        return bundleIt;
+      });
+
+      build.onResolve({ filter: /^[^.]/ }, (args) => {
+        // Only the package's own sources are policed: whatever an inlined dependency imports in
+        // turn is part of that deliberate exception.
+        const relativePathToImporter = path.relative(packageDirectory, args.importer);
+        const importerIsOwnFile =
+          !relativePathToImporter.startsWith("..") &&
+          !path.isAbsolute(relativePathToImporter) &&
+          !relativePathToImporter.split(path.sep).includes("node_modules");
+
+        if (!importerIsOwnFile || !/\.(t|j)sx?$/.test(args.importer)) {
+          return bundleIt;
+        }
+
+        if (disallowedBuiltinModules.has(args.path)) {
+          return fail(
+            `Tried to import "${args.path}" from "${relativePathToImporter}" but it is a disallowed builtin module.`,
+          );
+        }
+
+        if (builtinModules.has(args.path)) {
+          return { external: true, path: args.path };
+        }
+
+        const dependencyName = getPackageName(args.path);
+
+        if (externals.has(dependencyName)) {
+          // The full specifier is kept, as it names an "exports" entry of the dependency.
+          return { external: true, path: args.path };
+        }
+
+        if (inlinedDependencies.has(dependencyName) && devDependencies.has(dependencyName)) {
+          return bundleIt;
+        }
+
+        const where = `"${packageJson.name}" imports "${args.path}" from "${relativePathToImporter}"`;
+
+        if (devDependencies.has(dependencyName)) {
+          return refuse(
+            [
+              `${where}, but "${dependencyName}" is only a devDependency, so the build would inline it, and everything it imports, into dist.`,
+              `Fix: move "${dependencyName}" to "dependencies" (or "peerDependencies") if production code needs it.`,
+              "If it is test machinery, keep the import out of files the entry point reaches.",
+              `If inlining it is deliberate, list "${dependencyName}" in "lens.inlinedDependencies" of package.json.`,
+            ].join("\n"),
+          );
+        }
+
+        if (inlinedDependencies.has(dependencyName)) {
+          return refuse(
+            `${where}, and "lens.inlinedDependencies" lists "${dependencyName}", but it is not a devDependency. Fix: declare it in "devDependencies".`,
+          );
+        }
+
+        return refuse(
+          `${where}, but "${dependencyName}" is not a dependency of the package. Fix: declare it in "dependencies" (or "peerDependencies").`,
+        );
+      });
+    },
+  };
+};

package/src/package-build.ts

@@ -1,105 +1,14 @@
 import { type Plugin, build } from "esbuild";
 import path from "node:path";
 import { readFileSync } from "node:fs";
-import { builtinModules as rawBuiltinModules } from "node:module";
 import yargs from "yargs";
+import { declaredImportsPlugin } from "./declared-imports-plugin";
 import { globImportPlugin } from "./glob-import-plugin";
 import { stylesheetPlugin } from "./stylesheet-plugin";
-import { partition } from "lodash";
 
 const CWD = process.cwd();
 const packageJson = JSON.parse(readFileSync(path.resolve(CWD, "package.json"), "utf-8"));
 
-const isExperimentalModule = (module: string) => module.startsWith("_");
-const alsoAddNodeRefs = (module: string) => [module, `node:${module}`];
-
-const { builtinModules, disallowedBuiltinModules } = (() => {
-  const [disallowed, allowed] = partition(rawBuiltinModules, isExperimentalModule);
-  const disallowedBuiltinModules = new Set(disallowed.flatMap(alsoAddNodeRefs));
-  const builtinModules = new Set(allowed.flatMap(alsoAddNodeRefs));
-
-  return { disallowedBuiltinModules, builtinModules };
-})();
-
-const getPackageName = (path: string) => {
-  const [firstPart, secondPart] = path.split("/");
-
-  if (path.startsWith("@")) {
-    return [firstPart, secondPart].join("/");
-  }
-
-  return firstPart;
-};
-
-const bundleDependency = null;
-
-const ensureCorrectImportsPlugin: Plugin = {
-  name: "ensure-correct-imports",
-  setup: (build) => {
-    build.onResolve({ filter: /^\./ }, (args) => {
-      const fullPath = path.resolve(args.resolveDir, args.path);
-      const relativePathToImporter = path.relative(CWD, args.importer);
-      const relativePath = path.relative(CWD, fullPath);
-
-      if (relativePath.startsWith("..") && !relativePathToImporter.startsWith("..")) {
-        throw new Error(
-          `Tried to import "${args.path}" from "${relativePathToImporter}" but it is outside of the package.`,
-        );
-      }
-
-      return bundleDependency;
-    });
-    build.onResolve({ filter: /^[^.]/ }, async (args) => {
-      // Enforce declared imports only for the package's own sources (.ts/.tsx/.js/.jsx).
-      // Anything imported from outside the package directory — node_modules files or
-      // other workspace packages' dists (whose realpaths live outside node_modules) —
-      // belongs to an already-bundled dependency and must keep bundling freely.
-      const relativePathToImporter = path.relative(CWD, args.importer);
-      const importerIsOwnFile =
-        !relativePathToImporter.startsWith("..") && !relativePathToImporter.split(path.sep).includes("node_modules");
-      const importerIsSourceFile = /\.(t|j)sx?$/.test(args.importer);
-
-      if (!importerIsOwnFile || !importerIsSourceFile) {
-        return bundleDependency;
-      }
-
-      if (disallowedBuiltinModules.has(args.path)) {
-        throw new Error(
-          `Tried to import "${args.path}" from "${args.importer}" but it is a disallowed builtin module.`,
-        );
-      }
-
-      if (builtinModules.has(args.path)) {
-        return {
-          external: true,
-          path: args.path,
-        };
-      }
-
-      const packageName = getPackageName(args.path);
-
-      const isExplicitDependency = packageName in (packageJson.dependencies ?? {});
-      const isExplicitDevDependency = packageName in (packageJson.devDependencies ?? {});
-
-      if (isExplicitDependency) {
-        // Note: Return the full path since we assume that it is a "exports" entry of the dependency found in package.json
-        return {
-          external: true,
-          path: args.path,
-        };
-      }
-
-      if (isExplicitDevDependency) {
-        return bundleDependency;
-      }
-
-      throw new Error(
-        `Tried to import "${args.path}" from "${relativePathToImporter}" but it is not a dependency of the package.`,
-      );
-    });
-  },
-};
-
 const parsedArgs = yargs()
   .options({
     tsconfig: {
@@ -165,15 +74,15 @@ const nativeNodeModulesPlugin: Plugin = {
   },
 };
 
-// Keep .png imports as require() calls in the dist bundle instead of inlining
-// them as base64 data urls, so images ship as files loaded on demand rather
-// than megabytes of string literals in every consuming bundle. The import
-// path is rewritten to stay correct relative to the output file, since the
-// application build resolves it from there with its "file" loader.
+// Keep .png and .webm imports as require() calls in the dist bundle instead of
+// inlining them as base64 data urls, so images and videos ship as files loaded
+// on demand rather than megabytes of string literals in every consuming bundle.
+// The import path is rewritten to stay correct relative to the output file,
+// since the application build resolves it from there with its "file" loader.
 const externalImagesPlugin: Plugin = {
   name: "external-images",
   setup(build) {
-    build.onResolve({ filter: /\.png$/ }, (args) => {
+    build.onResolve({ filter: /\.(png|webm)$/ }, (args) => {
       const absolutePath = path.resolve(args.resolveDir, args.path);
       const outputDirectory = path.dirname(path.resolve(CWD, parsedArgs.outfile));
       const relativePath = path.relative(outputDirectory, absolutePath).split(path.sep).join("/");
@@ -204,7 +113,7 @@ export const packageBuild = async () => {
           packageDirectory: CWD,
           declaredDependencies: new Set(Object.keys(packageJson.dependencies ?? {})),
         }),
-        ensureCorrectImportsPlugin,
+        declaredImportsPlugin({ packageDirectory: CWD, packageJson }),
         externalImagesPlugin,
         globImportPlugin(),
         nativeNodeModulesPlugin,