@k8slens/package-build 2.2.3 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8slens/package-build",
-  "version": "2.2.3",
+  "version": "3.1.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,26 +51,30 @@
     "dist"
   ],
   "scripts": {
-    "build:infrastructure:code": "esbuild --bundle index.ts --outfile=dist/index.js --external:node:* --external:postcss --external:esbuild --external:fast-glob --external:esbuild-sass-plugin --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",
     "clean": "exit 0",
-    "check-types:tests": "lens-types-build --checkTypesTests"
+    "check-types:tests": "lens-types-build --checkTypesTests",
+    "test:unit": "jest"
   },
   "dependencies": {
     "esbuild": "^0.25.4",
-    "esbuild-sass-plugin": "^3.3.1",
     "fast-glob": "^3.3.3",
     "lodash": "^4.17.21",
     "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": "^7.2.0"
+    "@k8slens/typescript": "^8.0.0",
+    "@lensapp/jest": "^7.2.0",
+    "@types/semver": "^7.7.0"
   },
   "publishConfig": {
     "access": "public",
@@ -80,6 +85,7 @@
       "build:infrastructure": {
         "inputs": [
           "{projectRoot}/bin/package-build",
+          "{projectRoot}/bin/extension-dependencies-check",
           "{projectRoot}/index.ts",
           "{projectRoot}/src/**/*.ts"
         ],

package/src/__fixtures__/package-with-undeclared-dependency/index.js

@@ -0,0 +1 @@
+import "overlayscrollbars/overlayscrollbars.css";

package/src/__fixtures__/package-with-undeclared-dependency/manifest.json

@@ -0,0 +1,6 @@
+{
+  "name": "@some-scope/package-with-undeclared-dependency",
+  "dependencies": {
+    "@k8slens/stylesheet-contracts": "^1.0.0"
+  }
+}

package/src/__fixtures__/package-without-dependency/index.js

@@ -0,0 +1 @@
+import "./some.scss";

package/src/__fixtures__/package-without-dependency/manifest.json

@@ -0,0 +1,3 @@
+{
+  "name": "@some-scope/package-without-dependency"
+}

package/src/__fixtures__/package-without-dependency/some.scss

@@ -0,0 +1,3 @@
+.some {
+  color: red;
+}

package/src/__fixtures__/styled-package/_partial.scss

@@ -0,0 +1 @@
+$partialColor: purple;

package/src/__fixtures__/styled-package/empty.scss

@@ -0,0 +1 @@
+$unused: 1;

package/src/__fixtures__/styled-package/fonts/some-font.ttf

@@ -0,0 +1 @@
+not really a font

package/src/__fixtures__/styled-package/fonts.scss

@@ -0,0 +1,8 @@
+@font-face {
+  font-family: "Some Font";
+  src: url("./fonts/some-font.ttf") format("truetype");
+}
+
+.missing {
+  background: url("./missing.png");
+}

package/src/__fixtures__/styled-package/global.scss

@@ -0,0 +1,3 @@
+.global {
+  color: red;
+}

package/src/__fixtures__/styled-package/importer.scss

@@ -0,0 +1,5 @@
+@import "./partial";
+
+.importer {
+  color: $partialColor;
+}

package/src/__fixtures__/styled-package/index.js

@@ -0,0 +1,10 @@
+export * as ofDependency from "overlayscrollbars/overlayscrollbars.css";
+
+export * as global from "./global.scss";
+export * as someModule from "./some.module.scss";
+export * as importer from "./importer.scss";
+export * as empty from "./empty.scss";
+export * as plain from "./plain.css";
+export * as plainModule from "./plain.module.css";
+export * as tilde from "./tilde.scss";
+export * as fonts from "./fonts.scss";

package/src/__fixtures__/styled-package/manifest.json

@@ -0,0 +1,7 @@
+{
+  "name": "@some-scope/styled-package",
+  "dependencies": {
+    "@k8slens/stylesheet-contracts": "^1.0.0",
+    "overlayscrollbars": "*"
+  }
+}

package/src/__fixtures__/styled-package/plain.css

@@ -0,0 +1,3 @@
+.plain {
+  color: black;
+}

package/src/__fixtures__/styled-package/plain.module.css

@@ -0,0 +1,3 @@
+.plainLocal {
+  color: white;
+}

package/src/__fixtures__/styled-package/some.module.scss

@@ -0,0 +1,7 @@
+.some {
+  color: blue;
+
+  .nested {
+    color: green;
+  }
+}

package/src/__fixtures__/styled-package/tilde.scss

@@ -0,0 +1,7 @@
+@import "~include-media/dist/include-media";
+
+.tilde {
+  @include media(">=100px") {
+    color: red;
+  }
+}

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

@@ -1,11 +1,10 @@
 import { type Plugin, build } from "esbuild";
 import path from "node:path";
-import { sassPlugin, postcssModules } from "esbuild-sass-plugin";
 import { readFileSync } from "node:fs";
 import { builtinModules as rawBuiltinModules } from "node:module";
 import yargs from "yargs";
 import { globImportPlugin } from "./glob-import-plugin";
-import tailwindcss from "tailwindcss";
+import { stylesheetPlugin } from "./stylesheet-plugin";
 import { partition } from "lodash";
 
 const CWD = process.cwd();
@@ -199,22 +198,15 @@ export const packageBuild = async () => {
       target: "node16",
       sourcemap: "inline",
       plugins: [
+        // First: a dependency's stylesheet is compiled into the bundle, not left external.
+        stylesheetPlugin({
+          packageName: packageJson.name,
+          packageDirectory: CWD,
+          declaredDependencies: new Set(Object.keys(packageJson.dependencies ?? {})),
+        }),
         ensureCorrectImportsPlugin,
         externalImagesPlugin,
         globImportPlugin(),
-        sassPlugin({
-          filter: /\.module\.scss$/,
-          transform: postcssModules(
-            {
-              basedir: __dirname,
-              generateScopedName: "[name]__[local]___[hash:base64:5]",
-            },
-            [tailwindcss],
-          ),
-        }),
-        sassPlugin({
-          filter: /\.scss$/,
-        }),
         nativeNodeModulesPlugin,
       ],
       loader: {