@k8slens/package-build 3.3.0 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8slens/package-build",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "lens": {
     "env": "agnostic",
     "layer": "infrastructure",
@@ -42,7 +42,8 @@
   },
   "bin": {
     "lens-package-build": "bin/package-build",
-    "lens-extension-dependencies-check": "bin/extension-dependencies-check"
+    "lens-extension-dependencies-check": "bin/extension-dependencies-check",
+    "lens-extension-publish-check": "bin/extension-publish-check"
   },
   "files": [
     "index.js",
@@ -88,6 +89,7 @@
         "inputs": [
           "{projectRoot}/bin/package-build",
           "{projectRoot}/bin/extension-dependencies-check",
+          "{projectRoot}/bin/extension-publish-check",
           "{projectRoot}/index.ts",
           "{projectRoot}/src/**/*.ts"
         ],

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,
+  });