@k8slens/package-build 3.0.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8slens/package-build",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "lens": {
     "env": "agnostic",
     "layer": "infrastructure",
@@ -41,7 +41,8 @@
     }
   },
   "bin": {
-    "lens-package-build": "bin/package-build"
+    "lens-package-build": "bin/package-build",
+    "lens-extension-dependencies-check": "bin/extension-dependencies-check"
   },
   "files": [
     "index.js",
@@ -50,7 +51,7 @@
     "dist"
   ],
   "scripts": {
-    "build:infrastructure:code": "esbuild --bundle index.ts --outfile=dist/index.js --external:node:* --external:postcss --external:postcss-modules --external:esbuild --external:fast-glob --external:sass --external:yargs --external:tailwindcss --format=cjs",
+    "build:infrastructure:code": "esbuild --bundle index.ts --outfile=dist/index.js --external:node:* --external:postcss --external:postcss-modules --external:esbuild --external:fast-glob --external:sass --external:yargs --external:semver --external:tailwindcss --format=cjs",
     "build:infrastructure:types": "tsc --project .",
     "build:infrastructure": "npm run build:infrastructure:code; npm run build:infrastructure:types",
     "lint": "lens-verify-code-style",
@@ -65,13 +66,15 @@
     "postcss": "^8.5.18",
     "postcss-modules": "^6.0.1",
     "sass": "^1.89.0",
+    "semver": "^7.7.2",
     "tailwindcss": "^3.4.17",
     "yargs": "^17.7.2"
   },
   "devDependencies": {
     "@async-fn/jest": "^1.6.4",
-    "@k8slens/typescript": "^8.0.0",
-    "@lensapp/jest": "^7.2.0"
+    "@k8slens/typescript": "^8.1.0",
+    "@lensapp/jest": "^7.2.0",
+    "@types/semver": "^7.7.0"
   },
   "publishConfig": {
     "access": "public",
@@ -82,6 +85,7 @@
       "build:infrastructure": {
         "inputs": [
           "{projectRoot}/bin/package-build",
+          "{projectRoot}/bin/extension-dependencies-check",
           "{projectRoot}/index.ts",
           "{projectRoot}/src/**/*.ts"
         ],

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

@@ -0,0 +1,259 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { checkExtensionDependencies, extensionDependenciesCheck } from "./extension-dependencies-check";
+
+const originalArgv = process.argv;
+
+describe("checking an extension's dependency ranges against the versions Lens serves", () => {
+  let directory: string;
+  let packageJsonPath: string;
+  let versionsFilePath: string;
+  let logged: string[];
+
+  beforeEach(() => {
+    directory = mkdtempSync(path.join(tmpdir(), "extension-dependencies-check-"));
+    packageJsonPath = path.join(directory, "package.json");
+    versionsFilePath = path.join(directory, "extension-dependency-versions.json");
+    logged = [];
+  });
+
+  afterEach(() => {
+    rmSync(directory, { recursive: true, force: true });
+  });
+
+  const check = ({ fix = false } = {}) =>
+    checkExtensionDependencies({ packageJsonPath, versionsFilePath, fix, log: (line) => logged.push(line) });
+
+  const givenPackageJson = (packageJson: object) =>
+    writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+
+  const givenLensServes = (versions: Record<string, string>) =>
+    writeFileSync(versionsFilePath, JSON.stringify(versions));
+
+  describe("given Lens on this machine has written no versions, when checked", () => {
+    let exitCode: number;
+
+    beforeEach(() => {
+      givenPackageJson({ dependencies: { "some-package": "^999.0.0" } });
+
+      exitCode = check();
+    });
+
+    it("passes", () => {
+      expect(exitCode).toBe(0);
+    });
+
+    it("says in one line that the check was skipped, naming the file it looked for", () => {
+      expect(logged).toEqual([
+        `Skipped checking dependency ranges against Lens: no "${versionsFilePath}", which Lens writes when it runs on this machine.`,
+      ]);
+    });
+  });
+
+  describe("given ranges that include every version Lens serves, when checked", () => {
+    let exitCode: number;
+
+    beforeEach(() => {
+      givenLensServes({ "some-package": "1.2.0", "@some-scope/some-other-package": "2.0.0-beta.1" });
+
+      givenPackageJson({
+        dependencies: { "some-package": "^1.0.0", "some-package-lens-does-not-serve": "^999.0.0" },
+        peerDependencies: { "@some-scope/some-other-package": "^2.0.0-beta.0" },
+      });
+
+      exitCode = check();
+    });
+
+    it("passes", () => {
+      expect(exitCode).toBe(0);
+    });
+
+    it("says every range includes the version Lens serves", () => {
+      expect(logged).toEqual([
+        `Every dependency range includes the version Lens serves (read from "${versionsFilePath}").`,
+      ]);
+    });
+  });
+
+  describe("given a range in dependencies that excludes the version Lens serves, when checked", () => {
+    let exitCode: number;
+
+    beforeEach(() => {
+      givenLensServes({ react: "19.2.0" });
+      givenPackageJson({ dependencies: { react: "^19.3.1" } });
+
+      exitCode = check();
+    });
+
+    it("fails", () => {
+      expect(exitCode).toBe(1);
+    });
+
+    it("names the range, the version Lens serves, the range to declare instead and how to fix it", () => {
+      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, "react": "^19.3.1" does not include Lens's 19.2.0, declare "^19.2.0"`,
+          `Run "npx lens-extension-dependencies-check --fix" to rewrite them, then "npm install".`,
+        ].join("\n"),
+      ]);
+    });
+  });
+
+  describe("given several ranges that exclude the versions Lens serves, when checked", () => {
+    let exitCode: number;
+
+    beforeEach(() => {
+      givenLensServes({ react: "19.2.0", mobx: "6.13.0", "@k8slens/injectable": "26.0.0" });
+
+      givenPackageJson({
+        dependencies: { react: "^19.3.1", "@k8slens/injectable": "^26.0.0" },
+        peerDependencies: { mobx: "^7.0.0" },
+      });
+
+      exitCode = check();
+    });
+
+    it("fails", () => {
+      expect(exitCode).toBe(1);
+    });
+
+    it("lists every one of them", () => {
+      expect(logged.join("\n")).toContain(
+        [
+          `  in dependencies, "react": "^19.3.1" does not include Lens's 19.2.0, declare "^19.2.0"`,
+          `  in peerDependencies, "mobx": "^7.0.0" does not include Lens's 6.13.0, declare "^6.13.0"`,
+        ].join("\n"),
+      );
+    });
+  });
+
+  describe("given a range in dependencies that Lens does not read, as peerDependencies declares one Lens accepts, when checked", () => {
+    let exitCode: number;
+
+    beforeEach(() => {
+      givenLensServes({ react: "19.2.0" });
+
+      givenPackageJson({
+        dependencies: { react: "^19.3.1" },
+        peerDependencies: { react: "^19.0.0" },
+      });
+
+      exitCode = check();
+    });
+
+    it("passes, as Lens would load the extension", () => {
+      expect(exitCode).toBe(0);
+    });
+  });
+
+  describe("given a range in devDependencies only that excludes the version Lens serves, when checked", () => {
+    let exitCode: number;
+
+    beforeEach(() => {
+      givenLensServes({ react: "19.2.0" });
+      givenPackageJson({ devDependencies: { react: "^19.3.1" } });
+
+      exitCode = check();
+    });
+
+    it("passes, as Lens does not read devDependencies", () => {
+      expect(exitCode).toBe(0);
+    });
+
+    it("warns that the extension builds against another version than it runs on", () => {
+      expect(logged).toContain(
+        `Warning: in devDependencies, "react": "^19.3.1" does not include Lens's 19.2.0, declare "^19.2.0". The extension builds against another version than it runs on.`,
+      );
+    });
+  });
+
+  describe("given ranges that exclude the versions Lens serves, when fixed", () => {
+    let exitCode: number;
+
+    beforeEach(() => {
+      givenLensServes({ react: "19.2.0", mobx: "6.13.0", "@k8slens/injectable": "26.0.0" });
+
+      givenPackageJson({
+        name: "some-extension",
+        dependencies: { react: "^19.3.1", "@k8slens/injectable": "^26.0.0", "some-package": "^1.0.0" },
+        peerDependencies: { mobx: "^7.0.0" },
+        devDependencies: { react: "^19.3.1" },
+      });
+
+      exitCode = check({ fix: true });
+    });
+
+    it("passes", () => {
+      expect(exitCode).toBe(0);
+    });
+
+    it("rewrites each of them to the caret range of the version Lens serves, leaving everything else as it was", () => {
+      expect(readFileSync(packageJsonPath, "utf-8")).toBe(
+        `${JSON.stringify(
+          {
+            name: "some-extension",
+            dependencies: { react: "^19.2.0", "@k8slens/injectable": "^26.0.0", "some-package": "^1.0.0" },
+            peerDependencies: { mobx: "^6.13.0" },
+            devDependencies: { react: "^19.2.0" },
+          },
+          null,
+          2,
+        )}\n`,
+      );
+    });
+
+    it("says what it rewrote and to reinstall", () => {
+      expect(logged).toEqual([
+        `Rewrote "react" in dependencies from "^19.3.1" to "^19.2.0".`,
+        `Rewrote "mobx" in peerDependencies from "^7.0.0" to "^6.13.0".`,
+        `Rewrote "react" in devDependencies from "^19.3.1" to "^19.2.0".`,
+        `Run "npm install" so node_modules has the versions Lens serves.`,
+      ]);
+    });
+
+    it("when checked again, passes", () => {
+      expect(check()).toBe(0);
+    });
+  });
+
+  it("given every range includes the version Lens serves, when fixed, leaves package.json untouched", () => {
+    givenLensServes({ react: "19.2.0" });
+    writeFileSync(packageJsonPath, '{\n    "dependencies": { "react": "^19.0.0" }\n}\n');
+
+    check({ fix: true });
+
+    expect(readFileSync(packageJsonPath, "utf-8")).toBe('{\n    "dependencies": { "react": "^19.0.0" }\n}\n');
+  });
+
+  describe("given the environment names the versions file, when the command runs with --fix in the extension's directory", () => {
+    let exitCode: number;
+
+    beforeEach(() => {
+      givenLensServes({ react: "19.2.0" });
+      givenPackageJson({ dependencies: { react: "^19.3.1" } });
+
+      jest.spyOn(process, "cwd").mockReturnValue(directory);
+      jest.spyOn(console, "log").mockImplementation(() => {});
+      process.env.LENS_EXTENSION_DEPENDENCY_VERSIONS_FILE = versionsFilePath;
+      process.argv = ["some-node", "lens-extension-dependencies-check", "--fix"];
+
+      exitCode = extensionDependenciesCheck();
+    });
+
+    afterEach(() => {
+      jest.restoreAllMocks();
+      delete process.env.LENS_EXTENSION_DEPENDENCY_VERSIONS_FILE;
+      process.argv = originalArgv;
+    });
+
+    it("passes", () => {
+      expect(exitCode).toBe(0);
+    });
+
+    it("rewrites the range in the extension's package.json to the version in that file", () => {
+      expect(JSON.parse(readFileSync(packageJsonPath, "utf-8"))).toEqual({ dependencies: { react: "^19.2.0" } });
+    });
+  });
+});

package/src/extension-dependencies-check.ts

@@ -0,0 +1,158 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import semver from "semver";
+
+/** Overrides where the check reads the versions Lens serves, e.g. to check against another Lens than the one on this machine. */
+export const extensionDependencyVersionsFileEnvironmentVariable = "LENS_EXTENSION_DEPENDENCY_VERSIONS_FILE";
+
+// 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 = () =>
+  path.join(
+    homedir(),
+    ".k8slens",
+    "extensions",
+    "extension-development-instructions",
+    "extension-dependency-versions.json",
+  );
+
+const commandName = "lens-extension-dependencies-check";
+
+type Section = "dependencies" | "peerDependencies" | "devDependencies";
+
+type PackageJson = Partial<Record<Section, Record<string, string>>>;
+
+export interface CheckExtensionDependenciesParams {
+  readonly packageJsonPath: string;
+  readonly versionsFilePath: string;
+  readonly fix: boolean;
+  readonly log: (line: string) => void;
+}
+
+interface Mismatch {
+  readonly section: Section;
+  readonly name: string;
+  readonly declaredRange: string;
+  readonly hostVersion: string;
+}
+
+// The rule Lens applies before it lets an extension require a package it serves.
+const isSatisfied = (hostVersion: string, declaredRange: string) =>
+  semver.satisfies(hostVersion, declaredRange, { includePrerelease: true });
+
+const describeMismatch = ({ name, declaredRange, hostVersion }: Mismatch) =>
+  `"${name}": "${declaredRange}" does not include Lens's ${hostVersion}, declare "^${hostVersion}"`;
+
+const readVersions = (versionsFilePath: string): Record<string, string> | undefined => {
+  try {
+    return JSON.parse(readFileSync(versionsFilePath, "utf-8"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return undefined;
+    }
+
+    throw error;
+  }
+};
+
+const mismatchesOf = (packageJson: PackageJson, versions: Record<string, string>) =>
+  (["dependencies", "peerDependencies", "devDependencies"] as const).flatMap((section) =>
+    Object.entries(packageJson[section] ?? {}).flatMap(([name, declaredRange]): Mismatch[] => {
+      const hostVersion = versions[name];
+
+      return hostVersion !== undefined && !isSatisfied(hostVersion, declaredRange)
+        ? [{ section, name, declaredRange, hostVersion }]
+        : [];
+    }),
+  );
+
+const indentationOf = (json: string) => /^([ \t]+)"/m.exec(json)?.[1] ?? 2;
+
+/**
+ * Checks the ranges an extension's package.json declares for the packages Lens serves to
+ * extensions against the versions the Lens on this machine serves, with the rule Lens applies
+ * before loading the extension. A range Lens would refuse in `dependencies` or `peerDependencies`
+ * 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.
+ */
+export const checkExtensionDependencies = ({
+  packageJsonPath,
+  versionsFilePath,
+  fix,
+  log,
+}: CheckExtensionDependenciesParams): number => {
+  const versions = readVersions(versionsFilePath);
+
+  if (!versions) {
+    log(
+      `Skipped checking dependency ranges against Lens: no "${versionsFilePath}", which Lens writes when it runs on this machine.`,
+    );
+
+    return 0;
+  }
+
+  const packageJsonText = readFileSync(packageJsonPath, "utf-8");
+  const packageJson: PackageJson = JSON.parse(packageJsonText);
+  const mismatches = mismatchesOf(packageJson, versions);
+
+  if (fix) {
+    if (mismatches.length === 0) {
+      log("Nothing to fix: every dependency range includes the version Lens serves.");
+
+      return 0;
+    }
+
+    for (const { section, name, declaredRange, hostVersion } of mismatches) {
+      packageJson[section] = { ...packageJson[section], [name]: `^${hostVersion}` };
+      log(`Rewrote "${name}" in ${section} from "${declaredRange}" to "^${hostVersion}".`);
+    }
+
+    writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, indentationOf(packageJsonText))}\n`);
+    log('Run "npm install" so node_modules has the versions Lens serves.');
+
+    return 0;
+  }
+
+  // Lens reads the range from peerDependencies over dependencies, as the extension declares it there.
+  const refusedByLens = mismatches.filter(
+    ({ section, name }) =>
+      section === "peerDependencies" || (section === "dependencies" && !packageJson.peerDependencies?.[name]),
+  );
+
+  const devOnly = mismatches.filter(({ section }) => section === "devDependencies");
+
+  for (const mismatch of devOnly) {
+    log(
+      `Warning: in devDependencies, ${describeMismatch(mismatch)}. The extension builds against another version than it runs on.`,
+    );
+  }
+
+  if (refusedByLens.length === 0) {
+    log(`Every dependency range includes the version Lens serves (read from "${versionsFilePath}").`);
+
+    return 0;
+  }
+
+  log(
+    [
+      `Lens would refuse to load this extension. These ranges in package.json do not include the version Lens serves (read from "${versionsFilePath}"):`,
+      ...refusedByLens.map((mismatch) => `  in ${mismatch.section}, ${describeMismatch(mismatch)}`),
+      `Run "npx ${commandName} --fix" to rewrite them, then "npm install".`,
+    ].join("\n"),
+  );
+
+  return 1;
+};
+
+/** The `lens-extension-dependencies-check [--fix]` command, run in the extension's directory. */
+export const extensionDependenciesCheck = (): number =>
+  checkExtensionDependencies({
+    packageJsonPath: path.resolve(process.cwd(), "package.json"),
+    versionsFilePath: process.env[extensionDependencyVersionsFileEnvironmentVariable] || defaultVersionsFilePath(),
+    fix: process.argv.slice(2).includes("--fix"),
+    log: (line) => console.log(line),
+  });

package/src/package-build.ts

@@ -165,15 +165,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("/");