@k8slens/package-build 3.2.0 → 3.4.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/extension-dependencies-check.ts

@@ -9,7 +9,7 @@ export const extensionDependencyVersionsFileEnvironmentVariable = "LENS_EXTENSIO
 // Lens writes this file beside its extension-development README every time it loads. The name is
 // repeated from `extensionDependencyVersionsFileName` of Lens's dynamic-features contracts, which a
 // published build tool cannot depend on.
-const defaultVersionsFilePath = () =>
+export const defaultVersionsFilePath = () =>
   path.join(
     homedir(),
     ".k8slens",
@@ -29,6 +29,8 @@ export interface CheckExtensionDependenciesParams {
   readonly versionsFilePath: string;
   readonly fix: boolean;
   readonly log: (line: string) => void;
+  /** Fails, instead of passing, when Lens has written no versions to check against: what publishing needs. */
+  readonly requireVersions?: boolean;
 }
 
 interface Mismatch {
@@ -77,16 +79,25 @@ const indentationOf = (json: string) => /^([ \t]+)"/m.exec(json)?.[1] ?? 2;
  * fails the check; one in `devDependencies` only warns, as Lens never reads those. With `fix`,
  * rewrites every such range, in all three, to the caret range of the version Lens serves.
  *
- * @returns the exit code: 0 when Lens would load the extension, or when there is nothing to check against.
+ * @returns the exit code: 0 when Lens would load the extension, or when there is nothing to check against and `requireVersions` is not set.
  */
 export const checkExtensionDependencies = ({
   packageJsonPath,
   versionsFilePath,
   fix,
   log,
+  requireVersions = false,
 }: CheckExtensionDependenciesParams): number => {
   const versions = readVersions(versionsFilePath);
 
+  if (!versions && requireVersions) {
+    log(
+      `Cannot check the dependency ranges against Lens: no "${versionsFilePath}", which Lens writes when it runs on this machine. Start Lens once, or name the versions of another Lens in ${extensionDependencyVersionsFileEnvironmentVariable}.`,
+    );
+
+    return 1;
+  }
+
   if (!versions) {
     log(
       `Skipped checking dependency ranges against Lens: no "${versionsFilePath}", which Lens writes when it runs on this machine.`,

package/src/extension-publish-check.test.ts

@@ -0,0 +1,286 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { checkExtensionPublishing, extensionPublishCheck } from "./extension-publish-check";
+
+describe("checking an extension is fit to publish, before npm publishes it", () => {
+  let directory: string;
+  let packageJsonPath: string;
+  let versionsFilePath: string;
+  let packedFiles: string[];
+  let logged: string[];
+
+  beforeEach(() => {
+    directory = mkdtempSync(path.join(tmpdir(), "extension-publish-check-"));
+    packageJsonPath = path.join(directory, "package.json");
+    versionsFilePath = path.join(directory, "extension-dependency-versions.json");
+    packedFiles = ["package.json", "dist/index.js"];
+    logged = [];
+
+    givenLensServes({ "some-package": "1.2.0" });
+  });
+
+  afterEach(() => {
+    rmSync(directory, { recursive: true, force: true });
+  });
+
+  it("given an extension fit to publish, passes", () => {
+    givenPackageJson(fitToPublish);
+
+    expect(check()).toBe(0);
+  });
+
+  describe("given npm would pack the extension without its built entrypoint, when checked", () => {
+    let exitCode: number;
+
+    beforeEach(() => {
+      givenPackageJson(fitToPublish);
+      packedFiles = ["package.json", "src/index.ts"];
+
+      exitCode = check();
+    });
+
+    it("fails", () => {
+      expect(exitCode).toBe(1);
+    });
+
+    it("names the entrypoint, and how to have npm pack it", () => {
+      expect(logged).toContain(
+        'npm would publish the extension without its entrypoint "./dist/index.js", and Lens could not install it. Build first, and list the built directory in "files" of package.json, such as "files": ["dist"].',
+      );
+    });
+  });
+
+  describe("given the entrypoint is named in exports, finds it packed by that name", () => {
+    it.each([
+      ["as the exports themselves", { exports: "./dist/index.js" }],
+      ['as the "." of exports', { exports: { ".": "./dist/index.js" } }],
+      ['as the default condition of "."', { exports: { ".": { default: "./dist/index.js" } } }],
+      ['as the require condition of "."', { exports: { ".": { require: "./dist/index.js" } } }],
+    ])("%s", (_, entrypoint) => {
+      givenPackageJson({ ...fitToPublish, main: "./irrelevant-main.js", ...entrypoint });
+
+      expect(check()).toBe(0);
+    });
+  });
+
+  it('given exports without "." of their own, finds the entrypoint named in main packed', () => {
+    givenPackageJson({ ...fitToPublish, exports: { "./package.json": "./package.json" } });
+
+    expect(check()).toBe(0);
+  });
+
+  it("given npm lists the packed files with Windows separators, finds the entrypoint packed", () => {
+    givenPackageJson(fitToPublish);
+    packedFiles = ["package.json", "dist\\index.js"];
+
+    expect(check()).toBe(0);
+  });
+
+  describe("given package.json names no entrypoint, when checked", () => {
+    let exitCode: number;
+
+    beforeEach(() => {
+      givenPackageJson({ ...fitToPublish, main: undefined });
+
+      exitCode = check();
+    });
+
+    it("fails", () => {
+      expect(exitCode).toBe(1);
+    });
+
+    it("says what to name", () => {
+      expect(logged).toContain(
+        'package.json names no entrypoint: set "main" to the built file Lens loads, such as "./dist/index.js".',
+      );
+    });
+  });
+
+  it("given main is not a path, says the extension names no entrypoint", () => {
+    givenPackageJson({ ...fitToPublish, main: 42 });
+
+    check();
+
+    expect(logged).toContain(
+      'package.json names no entrypoint: set "main" to the built file Lens loads, such as "./dist/index.js".',
+    );
+  });
+
+  describe("given a range Lens would refuse, when checked", () => {
+    let exitCode: number;
+
+    beforeEach(() => {
+      givenPackageJson({ ...fitToPublish, dependencies: { "some-package": "^1.2.1" } });
+
+      exitCode = check();
+    });
+
+    it("fails", () => {
+      expect(exitCode).toBe(1);
+    });
+
+    it("names the range and the one to declare instead", () => {
+      expect(logged).toContainEqual(
+        expect.stringContaining(
+          '  in dependencies, "some-package": "^1.2.1" does not include Lens\'s 1.2.0, declare "^1.2.0"',
+        ),
+      );
+    });
+  });
+
+  describe("given Lens on this machine has written no versions, when checked", () => {
+    let exitCode: number;
+
+    beforeEach(() => {
+      givenPackageJson(fitToPublish);
+      rmSync(versionsFilePath);
+
+      exitCode = check();
+    });
+
+    it("fails, as publishing unchecked ranges is how an extension no Lens loads reaches users", () => {
+      expect(exitCode).toBe(1);
+    });
+
+    it("says how to give it versions to check against", () => {
+      expect(logged).toContain(
+        `Cannot check the dependency ranges against Lens: no "${versionsFilePath}", which Lens writes when it runs on this machine. Start Lens once, or name the versions of another Lens in LENS_EXTENSION_DEPENDENCY_VERSIONS_FILE.`,
+      );
+    });
+  });
+
+  describe("given a prerelease version", () => {
+    beforeEach(() => {
+      givenPackageJson({ ...fitToPublish, version: "0.0.0-stage" });
+    });
+
+    describe("when checked for publishing as the latest version", () => {
+      let exitCode: number;
+
+      beforeEach(() => {
+        exitCode = check();
+      });
+
+      it("fails", () => {
+        expect(exitCode).toBe(1);
+      });
+
+      it("says to publish it under a tag of its own, or as a release", () => {
+        expect(logged).toContain(
+          '0.0.0-stage is a prerelease, which would become the version users see and install by default. Publish it with "--tag next", or raise "version" in package.json to a release.',
+        );
+      });
+    });
+
+    it("when checked for publishing explicitly as latest, fails", () => {
+      expect(check({ distTag: "latest" })).toBe(1);
+    });
+
+    it("when checked for publishing under a tag of its own, passes", () => {
+      expect(check({ distTag: "next" })).toBe(0);
+    });
+  });
+
+  it("given every kind of problem at once, says each of them, then that it will not publish", () => {
+    givenPackageJson({ ...fitToPublish, version: "0.0.0-stage", dependencies: { "some-package": "^2.0.0" } });
+    packedFiles = ["package.json"];
+
+    check();
+
+    expect(logged).toEqual([
+      [
+        `Lens would refuse to load this extension. These ranges in package.json do not include the version Lens serves (read from "${versionsFilePath}"):`,
+        '  in dependencies, "some-package": "^2.0.0" does not include Lens\'s 1.2.0, declare "^1.2.0"',
+        'Run "npx lens-extension-dependencies-check --fix" to rewrite them, then "npm install".',
+      ].join("\n"),
+      'npm would publish the extension without its entrypoint "./dist/index.js", and Lens could not install it. Build first, and list the built directory in "files" of package.json, such as "files": ["dist"].',
+      '0.0.0-stage is a prerelease, which would become the version users see and install by default. Publish it with "--tag next", or raise "version" in package.json to a release.',
+      "Not publishing: fix the above, and publish again.",
+    ]);
+  });
+
+  describe("as the command npm runs before publishing", () => {
+    let commandsRun: { command: string; directory: string }[];
+    let npmPrints: string;
+
+    beforeEach(() => {
+      commandsRun = [];
+      npmPrints = JSON.stringify([{ files: [{ path: "package.json" }, { path: "dist/index.js" }] }]);
+      givenPackageJson(fitToPublish);
+    });
+
+    const runCommand = ({ environment = {} }: { environment?: Record<string, string> } = {}) =>
+      extensionPublishCheck({
+        directory,
+        environment: { LENS_EXTENSION_DEPENDENCY_VERSIONS_FILE: versionsFilePath, ...environment },
+        runCommand: (command, inDirectory) => {
+          commandsRun.push({ command, directory: inDirectory });
+
+          return npmPrints;
+        },
+        log: (line) => logged.push(line),
+      });
+
+    it("asks npm, in the extension's directory and running none of its scripts, what it would pack", () => {
+      runCommand();
+
+      expect(commandsRun).toEqual([{ command: "npm pack --dry-run --json --ignore-scripts", directory }]);
+    });
+
+    it("reads what npm would pack past whatever npm prints before it", () => {
+      npmPrints = `npm warn some-warning\n${npmPrints}`;
+
+      expect(runCommand()).toBe(0);
+    });
+
+    it("given npm prints no listing, finds nothing packed", () => {
+      npmPrints = "";
+
+      runCommand();
+
+      expect(logged).toContainEqual(expect.stringContaining("without its entrypoint"));
+    });
+
+    it("checks the ranges against the versions the environment names", () => {
+      writeFileSync(path.join(directory, "other-lens-versions.json"), JSON.stringify({ "some-package": "9.0.0" }));
+      givenPackageJson({ ...fitToPublish, dependencies: { "some-package": "^1.2.0" } });
+
+      expect(
+        runCommand({
+          environment: { LENS_EXTENSION_DEPENDENCY_VERSIONS_FILE: path.join(directory, "other-lens-versions.json") },
+        }),
+      ).toBe(1);
+    });
+
+    it("given npm publishes a prerelease under a tag of its own, passes", () => {
+      givenPackageJson({ ...fitToPublish, version: "0.0.0-stage" });
+
+      expect(runCommand({ environment: { npm_config_tag: "next" } })).toBe(0);
+    });
+  });
+
+  const fitToPublish = {
+    version: "0.1.0",
+    main: "./dist/index.js",
+    dependencies: { "some-package": "^1.2.0" },
+  };
+
+  function check({ distTag }: { distTag?: string } = {}) {
+    return checkExtensionPublishing({
+      packageJsonPath,
+      versionsFilePath,
+      packedFiles: () => packedFiles,
+      distTag,
+      log: (line) => logged.push(line),
+    });
+  }
+
+  function givenPackageJson(packageJson: object) {
+    writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+  }
+
+  function givenLensServes(versions: Record<string, string>) {
+    writeFileSync(versionsFilePath, JSON.stringify(versions));
+  }
+});

package/src/extension-publish-check.ts

@@ -0,0 +1,177 @@
+import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import semver from "semver";
+import {
+  checkExtensionDependencies,
+  defaultVersionsFilePath,
+  extensionDependencyVersionsFileEnvironmentVariable,
+} from "./extension-dependencies-check";
+
+/** The dist-tag a prerelease is published under, so it never becomes the version users install by default. */
+export const prereleaseDistTag = "next";
+
+export interface CheckExtensionPublishingParams {
+  readonly packageJsonPath: string;
+  readonly versionsFilePath: string;
+  /** The paths npm would pack, relative to the extension's directory, as `npm pack --dry-run` lists them. */
+  readonly packedFiles: () => readonly string[];
+  /** The dist-tag npm is publishing under, when one was given. */
+  readonly distTag: string | undefined;
+  readonly log: (line: string) => void;
+}
+
+// The same reading of a manifest as Lens's own when it installs an extension, so what is checked
+// here is what Lens will load. Lens's own Publish repeats it, as neither can depend on the other.
+const relativeEntrypointOf = (packageJson: Record<string, unknown>): string | undefined => {
+  const { exports, main } = packageJson;
+
+  if (exports === undefined || exports === null) {
+    return typeof main === "string" ? main : undefined;
+  }
+
+  if (typeof exports === "string") {
+    return exports;
+  }
+
+  const defaultInExports = (exports as Record<string, unknown>)["."];
+
+  if (typeof defaultInExports === "string") {
+    return defaultInExports;
+  }
+
+  if (typeof defaultInExports === "object" && defaultInExports !== null) {
+    const conditions = defaultInExports as Record<string, unknown>;
+    const conditional = conditions.default ?? conditions.require;
+
+    if (typeof conditional === "string") {
+      return conditional;
+    }
+  }
+
+  return typeof main === "string" ? main : undefined;
+};
+
+// The same reading of a path as Lens's own Publish, which checks what npm would pack too: "./dist\\index.js" is "dist/index.js".
+const normalized = (relativePath: string) =>
+  relativePath
+    .replaceAll("\\", "/")
+    .split("/")
+    .filter((segment) => segment !== "" && segment !== ".")
+    .join("/");
+
+const checkEntrypointIsPacked = (packageJson: Record<string, unknown>, packedFiles: () => readonly string[]) => {
+  const entrypoint = relativeEntrypointOf(packageJson);
+
+  if (entrypoint === undefined) {
+    return 'package.json names no entrypoint: set "main" to the built file Lens loads, such as "./dist/index.js".';
+  }
+
+  if (!packedFiles().map(normalized).includes(normalized(entrypoint))) {
+    return `npm would publish the extension without its entrypoint "${entrypoint}", and Lens could not install it. Build first, and list the built directory in "files" of package.json, such as "files": ["dist"].`;
+  }
+
+  return undefined;
+};
+
+const checkPrereleaseIsTagged = (version: unknown, distTag: string | undefined) => {
+  const isPrerelease = typeof version === "string" && (semver.prerelease(version) ?? []).length > 0;
+
+  if (!isPrerelease || (distTag !== undefined && distTag !== "latest")) {
+    return undefined;
+  }
+
+  return `${version} is a prerelease, which would become the version users see and install by default. Publish it with "--tag ${prereleaseDistTag}", or raise "version" in package.json to a release.`;
+};
+
+/**
+ * Checks an extension is fit to publish, before npm publishes it: that what npm packs has the
+ * entrypoint Lens loads, that Lens would accept every range the extension declares for a package
+ * Lens serves, and that a prerelease is not published as the latest version. Fails when Lens has
+ * written no versions to check the ranges against, as publishing unchecked is how an extension
+ * reaches users that no Lens loads.
+ *
+ * @returns the exit code: 0 when the extension is fit to publish.
+ */
+export const checkExtensionPublishing = ({
+  packageJsonPath,
+  versionsFilePath,
+  packedFiles,
+  distTag,
+  log,
+}: CheckExtensionPublishingParams): number => {
+  const packageJson: Record<string, unknown> = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+
+  const problems = [
+    checkEntrypointIsPacked(packageJson, packedFiles),
+    checkPrereleaseIsTagged(packageJson.version, distTag),
+  ].filter((problem) => problem !== undefined);
+
+  const dependenciesExitCode = checkExtensionDependencies({
+    packageJsonPath,
+    versionsFilePath,
+    fix: false,
+    log,
+    requireVersions: true,
+  });
+
+  for (const problem of problems) {
+    log(problem);
+  }
+
+  if (problems.length > 0 || dependenciesExitCode !== 0) {
+    log("Not publishing: fix the above, and publish again.");
+
+    return 1;
+  }
+
+  return 0;
+};
+
+/**
+ * The paths `npm pack --dry-run --json` says it would pack, from what it printed: one entry per
+ * package packed, listing its files, after whatever lines npm writes before it. None when npm
+ * printed no listing.
+ */
+export const packedFilesOf = (output: string): string[] => {
+  const listingStart = output.indexOf("[");
+
+  if (listingStart === -1) {
+    return [];
+  }
+
+  const [packed] = JSON.parse(output.slice(listingStart)) as { files?: { path: string }[] }[];
+
+  return packed?.files?.map((file) => file.path) ?? [];
+};
+
+export interface ExtensionPublishCheckParams {
+  /** The extension's directory, where npm runs its scripts. */
+  readonly directory: string;
+  /** The environment npm runs the script in. */
+  readonly environment: Readonly<Record<string, string | undefined>>;
+  /** Runs a command in a directory, giving back what it printed. */
+  readonly runCommand: (command: string, directory: string) => string;
+  readonly log: (line: string) => void;
+}
+
+/**
+ * The `lens-extension-publish-check` command, run in the extension's directory, as its
+ * `prepublishOnly` script: npm runs it before every publish, and gives up publishing when it fails.
+ */
+export const extensionPublishCheck = (
+  { directory, environment, runCommand, log }: ExtensionPublishCheckParams = {
+    directory: process.cwd(),
+    environment: process.env,
+    runCommand: (command, cwd) => execSync(command, { cwd, encoding: "utf-8" }),
+    log: (line) => console.log(line),
+  },
+): number =>
+  checkExtensionPublishing({
+    packageJsonPath: path.resolve(directory, "package.json"),
+    versionsFilePath: environment[extensionDependencyVersionsFileEnvironmentVariable] || defaultVersionsFilePath(),
+    packedFiles: () => packedFilesOf(runCommand("npm pack --dry-run --json --ignore-scripts", directory)),
+    // What npm tells the scripts it runs of `npm publish --tag <tag>`.
+    distTag: environment.npm_config_tag || undefined,
+    log,
+  });