@platforma-sdk/package-builder-lib 1.3.0 → 1.4.1

package/src/core/__tests__/docker-coverage.test.ts

@@ -0,0 +1,319 @@
+// Regression tests for the "released software with no docker image" guard (MILAB-6872).
+//
+// The trap: an image is autogenerated only for python and conda artifacts, so a
+// java / R / binary entrypoint without an explicit `docker:` block publishes a
+// descriptor the k8s runner cannot use, and the command fails at runtime with
+// "docker image is not specified". Every installation is k8s-based.
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type winston from "winston";
+import { PackageInfo } from "../package-info";
+import { Core } from "../core";
+import {
+  assertDockerCoverage,
+  descriptorHasNoDockerVariant,
+  softwareEntrypointsWithoutDocker,
+  type DockerCoverage,
+} from "../docker-coverage";
+import { NO_SOFTWARE_PLACEHOLDER } from "../../defaults";
+
+const mockLogger = {
+  info: vi.fn(),
+  warn: vi.fn(),
+  debug: vi.fn(),
+  error: vi.fn(),
+} as unknown as winston.Logger;
+
+// The autogenerated python image resolves its run environment through
+// node_modules, which a /tmp fixture does not have. The coverage check only asks
+// whether the docker companion exists, so the options it would carry are stubbed.
+vi.mock("../docker-python", () => ({
+  prepareDockerOptions: vi.fn().mockReturnValue({
+    context: "/tmp/test-context",
+    dockerfile: "/tmp/test-dockerfile",
+    entrypoint: [],
+  }),
+}));
+
+const JAVA_ARTIFACT = {
+  type: "java",
+  registry: "test-registry",
+  environment: "@platforma-open/milaboratories.runenv-java-corretto:21.0.2.13.1",
+  root: "./dld",
+};
+
+const javaEntrypoint = (withDocker: boolean) => ({
+  binary: { artifact: JAVA_ARTIFACT, cmd: ["java", "-jar", "{pkg}/tool.jar"] },
+  ...(withDocker
+    ? { docker: { artifact: { context: "dld" }, cmd: ["java", "-jar", "/app/tool.jar"] } }
+    : {}),
+});
+
+const pythonEntrypoint = {
+  binary: {
+    artifact: {
+      type: "python",
+      registry: "test-registry",
+      environment: "@platforma-open/milaboratories.runenv-python-3:3.12.10",
+      root: "./src",
+      dependencies: { toolset: "pip", requirements: "requirements.txt" },
+    },
+    cmd: ["python", "{pkg}/main.py"],
+  },
+};
+
+describe("softwareEntrypointsWithoutDocker", () => {
+  let tempDir: string;
+  let packageRoot: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join("/tmp", "docker-coverage-test-"));
+    packageRoot = path.join(tempDir, "package");
+    fs.mkdirSync(packageRoot, { recursive: true });
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+  });
+
+  const uncovered = (blockSoftware: Record<string, unknown>): string[] => {
+    fs.writeFileSync(
+      path.join(packageRoot, "package.json"),
+      JSON.stringify(
+        { name: "test-package", version: "1.0.0", "block-software": blockSoftware },
+        null,
+        2,
+      ),
+    );
+    return softwareEntrypointsWithoutDocker(
+      new PackageInfo(mockLogger, { packageRoot }).entrypoints,
+    );
+  };
+
+  it("flags a java entrypoint with no docker block", () => {
+    expect(uncovered({ entrypoints: { main: javaEntrypoint(false) } })).toEqual(["main"]);
+  });
+
+  it("passes a java entrypoint that declares docker explicitly", () => {
+    expect(uncovered({ entrypoints: { main: javaEntrypoint(true) } })).toEqual([]);
+  });
+
+  it("passes python, whose image is autogenerated", () => {
+    expect(uncovered({ entrypoints: { main: pythonEntrypoint } })).toEqual([]);
+  });
+
+  it("passes a docker-only entrypoint", () => {
+    expect(
+      uncovered({
+        entrypoints: { main: { docker: { artifact: { context: "dld" }, cmd: ["tool"] } } },
+      }),
+    ).toEqual([]);
+  });
+
+  // The ':docker' suffix marks the companion PackageInfo generates, but entrypoint
+  // names are barely constrained, so a package may declare one called 'main:docker'.
+  // Reading the suffix as "generated, already covered" would let it hide there.
+  it("flags a binary-only entrypoint that is itself named with the companion suffix", () => {
+    expect(uncovered({ entrypoints: { "main:docker": javaEntrypoint(false) } })).toEqual([
+      "main:docker",
+    ]);
+  });
+
+  it("passes an entrypoint named with the suffix once it declares an image", () => {
+    expect(uncovered({ entrypoints: { "main:docker": javaEntrypoint(true) } })).toEqual([]);
+  });
+
+  it("skips run environments, whose image is baked into the software that uses them", () => {
+    expect(
+      uncovered({
+        entrypoints: {
+          jre: {
+            environment: {
+              artifact: {
+                registry: "test-registry",
+                runtime: "java",
+                "java-version": "21",
+                roots: { "linux-x64": "./env" },
+                binDir: ".",
+              },
+            },
+          },
+        },
+      }),
+    ).toEqual([]);
+  });
+
+  it("skips assets, which are data and not runnable", () => {
+    expect(
+      uncovered({
+        entrypoints: { data: { asset: { registry: "test-registry", root: "./data" } } },
+      }),
+    ).toEqual([]);
+  });
+
+  it("names only the uncovered entrypoints of a mixed package", () => {
+    expect(
+      uncovered({
+        entrypoints: {
+          "java-tool": javaEntrypoint(false),
+          "java-tool-dockerized": javaEntrypoint(true),
+          "python-tool": pythonEntrypoint,
+        },
+      }),
+    ).toEqual(["java-tool"]);
+  });
+
+  it("defaults requireDocker to true and honours an explicit opt-out", () => {
+    const write = (blockSoftware: Record<string, unknown>) => {
+      fs.writeFileSync(
+        path.join(packageRoot, "package.json"),
+        JSON.stringify({ name: "p", version: "1.0.0", "block-software": blockSoftware }, null, 2),
+      );
+      return new PackageInfo(mockLogger, { packageRoot }).requireDocker;
+    };
+
+    expect(write({ entrypoints: { main: javaEntrypoint(false) } })).toBe(true);
+    expect(write({ requireDocker: false, entrypoints: { main: javaEntrypoint(false) } })).toBe(
+      false,
+    );
+  });
+
+  // A dev-local build describes software by filesystem path, so a missing image cannot
+  // hurt anyone on a cluster — and blocking it would fail a block's own tests
+  // (`build:dev-local`, and `test`'s binary-only build) on a release rule.
+  it("leaves a dev-local build alone, whose descriptors never reach a cluster", () => {
+    const ci = process.env.CI;
+    process.env.CI = "true";
+
+    fs.writeFileSync(
+      path.join(packageRoot, "package.json"),
+      JSON.stringify({
+        name: "test-package",
+        version: "1.0.0",
+        "block-software": { entrypoints: { main: javaEntrypoint(false) } },
+      }),
+    );
+
+    const core = new Core(mockLogger, { packageRoot });
+    core.buildMode = "dev-local";
+    try {
+      expect(() => core.assertDockerCoverage()).not.toThrow();
+      core.buildMode = "dev-remote";
+      expect(() => core.assertDockerCoverage()).toThrow(/produce no docker image/);
+      core.buildMode = "release";
+      expect(() => core.assertDockerCoverage()).toThrow(/produce no docker image/);
+    } finally {
+      if (ci === undefined) delete process.env.CI;
+      else process.env.CI = ci;
+    }
+  });
+
+  it("stops a CI build before it writes the descriptor", () => {
+    const ci = process.env.CI;
+    process.env.CI = "true";
+
+    fs.writeFileSync(
+      path.join(packageRoot, "package.json"),
+      JSON.stringify({
+        name: "test-package",
+        version: "1.0.0",
+        "block-software": { entrypoints: { main: javaEntrypoint(false) } },
+      }),
+    );
+
+    const core = new Core(mockLogger, { packageRoot });
+    try {
+      expect(() => core.buildSwJsonFiles()).toThrow(/produce no docker image/);
+    } finally {
+      if (ci === undefined) delete process.env.CI;
+      else process.env.CI = ci;
+    }
+  });
+});
+
+describe("descriptorHasNoDockerVariant", () => {
+  const binary = { type: "java", registry: "milaboratories", package: "sw/1.0.0.tgz", cmd: ["x"] };
+
+  it("flags a rendered descriptor with only a binary variant", () => {
+    expect(descriptorHasNoDockerVariant({ binary })).toBe(true);
+  });
+
+  it("passes a descriptor that carries an image", () => {
+    expect(descriptorHasNoDockerVariant({ binary, docker: { tag: "reg/img:tag" } })).toBe(false);
+  });
+
+  it("passes a run environment, which is not runnable software", () => {
+    expect(descriptorHasNoDockerVariant({ runEnv: { type: "java" } })).toBe(false);
+  });
+
+  it("passes a dev-mode descriptor, which points at a directory and never runs on a cluster", () => {
+    expect(descriptorHasNoDockerVariant({ local: { path: "/src" }, isDev: true })).toBe(false);
+  });
+
+  it("passes the no-software placeholder", () => {
+    expect(
+      descriptorHasNoDockerVariant({
+        isDev: true,
+        binary: { type: "binary", registry: NO_SOFTWARE_PLACEHOLDER, cmd: ["true"] },
+      }),
+    ).toBe(false);
+  });
+
+  it("ignores anything that is not a descriptor object", () => {
+    expect(descriptorHasNoDockerVariant(null)).toBe(false);
+    expect(descriptorHasNoDockerVariant("{}")).toBe(false);
+  });
+});
+
+const UNCOVERED: DockerCoverage = {
+  softwareWithoutDocker: ["main"],
+  requirementWaived: false,
+};
+
+describe("assertDockerCoverage", () => {
+  let ci: string | undefined;
+
+  beforeEach(() => {
+    ci = process.env.CI;
+    process.env.CI = "true";
+  });
+
+  afterEach(() => {
+    if (ci === undefined) delete process.env.CI;
+    else process.env.CI = ci;
+  });
+
+  it("throws when CI describes software no k8s install can run", () => {
+    expect(() => assertDockerCoverage(UNCOVERED)).toThrow(/produce no docker image/);
+  });
+
+  it("names the uncovered entrypoints", () => {
+    expect(() =>
+      assertDockerCoverage({ ...UNCOVERED, softwareWithoutDocker: ["main", "low-memory"] }),
+    ).toThrow(/low-memory/);
+  });
+
+  it("points at the requireDocker opt-out", () => {
+    expect(() => assertDockerCoverage(UNCOVERED)).toThrow(/"requireDocker": false/);
+  });
+
+  it("accepts a package that declared itself binary-only", () => {
+    expect(() => assertDockerCoverage({ ...UNCOVERED, requirementWaived: true })).not.toThrow();
+  });
+
+  it("accepts a package whose software is fully covered", () => {
+    expect(() => assertDockerCoverage({ ...UNCOVERED, softwareWithoutDocker: [] })).not.toThrow();
+  });
+
+  it("stays out of the way outside CI, where a partial package is normal mid-edit", () => {
+    delete process.env.CI;
+    expect(() => assertDockerCoverage(UNCOVERED)).not.toThrow();
+  });
+});

package/src/core/core.ts

@@ -15,6 +15,7 @@ import * as util from "./util";
 import * as archive from "./archive";
 import * as storage from "./storage";
 import * as docker from "./docker";
+import * as dockerCoverage from "./docker-coverage";
 import { tmpSpecFile } from "./docker-conda";
 
 export class Core {
@@ -212,6 +213,31 @@ export class Core {
     }
   }
 
+  /**
+   * Fails a CI build that would describe software no kubernetes installation can run.
+   *
+   * `buildSwJsonFiles` calls this on the selection it is about to write, so no path
+   * can skip it. Callers may also invoke it up front — the answer comes from the
+   * package's declaration alone, so a CI run that is going to fail can fail before
+   * it spends minutes building archives and images.
+   *
+   * Only builds that write a registry descriptor answer for coverage. A dev-local
+   * build (`build:dev-local`, and the `test` script's binary-only build) describes
+   * software by filesystem path: it never reaches a cluster, so a missing image
+   * cannot hurt anyone there, and failing those runs would block a block's tests on
+   * a release rule. Release and dev-remote builds do publish, and are checked.
+   */
+  public assertDockerCoverage(options?: { entrypoints?: Map<string, entrypoint.Entrypoint> }) {
+    if (!util.producesRegistryDescriptor(this.buildMode)) return;
+
+    dockerCoverage.assertDockerCoverage({
+      softwareWithoutDocker: dockerCoverage.softwareEntrypointsWithoutDocker(
+        options?.entrypoints ?? this.entrypoints,
+      ),
+      requirementWaived: !this.pkgInfo.requireDocker,
+    });
+  }
+
   // Get entrypoints defined in package.json, transform them to local or release (depending on `buildMode`)
   // sw.json entrypoint descriptors, and write them to ./dist/tengo/sw.json or as.json next to the package.json.
   public buildSwJsonFiles(options?: {
@@ -220,6 +246,7 @@ export class Core {
     sources?: util.SoftwareSource[];
     requireAllArtifacts?: boolean;
     noSoftware?: boolean;
+    skipDockerCoverage?: boolean;
   }) {
     const index = this.packageEntrypointsIndex;
 
@@ -242,6 +269,16 @@ export class Core {
       entrypoints = entrypoints.filter(([epName, _]) => entrypointNames.includes(epName));
     }
 
+    // The descriptor is the contract the backend reads, so this is the last point at
+    // which a software entrypoint with no docker image can still be stopped. Judged
+    // over the selection being described, so a targeted build answers only for what
+    // it writes. Skipped where this build produces no software of its own: the
+    // placeholder path describes none, and `skipDockerCoverage` is for a caller
+    // pointing the descriptor at an artifact someone else already released.
+    if (!options?.noSoftware && !options?.skipDockerCoverage) {
+      this.assertDockerCoverage({ entrypoints: new Map(entrypoints) });
+    }
+
     const infos = options?.noSoftware
       ? this.renderer.renderPlaceholderEntrypoints(new Map(entrypoints))
       : this.renderer.renderSoftwareEntrypoints(this.buildMode, new Map(entrypoints), {

package/src/core/docker-coverage.ts

@@ -0,0 +1,112 @@
+// Guard against releasing software that cannot run where we deploy it.
+//
+// Nothing else requires a docker variant: an image is autogenerated only for
+// `python` and `conda` artifacts (`artifacts.dockerAutogenTypes`), so a `java`,
+// `R` or plain `binary` entrypoint without an explicit `docker:` block writes a
+// descriptor carrying `binary` and nothing else. Every Platforma installation
+// is kubernetes-based, and the k8s runner has no binary fallback — it fails the
+// command with a bare "docker image is not specified". CI stays green, the
+// defect surfaces the first time a user runs the block (MILAB-6872).
+//
+// So: in CI, describing a software entrypoint that produces no image is an
+// error, unless the package declares itself binary-only with
+// `"block-software": { "requireDocker": false }`.
+//
+// The check reads the package's declaration, not what this particular run
+// built: `--variant binary` and other partial builds are legitimate, a
+// misdeclared entrypoint is not.
+
+import * as defaults from "../defaults";
+import * as docker from "./docker";
+import * as envs from "./envs";
+import type * as entrypoint from "./schemas/entrypoints";
+import * as util from "./util";
+
+export type DockerCoverage = {
+  /** Names of software entrypoints that produce no docker image. */
+  softwareWithoutDocker: string[];
+  /** Package opted out with `"block-software": { "requireDocker": false }`. */
+  requirementWaived: boolean;
+};
+
+/**
+ * The software entrypoints among `entrypoints` that yield no docker image.
+ *
+ * `entrypoints` is expected in the shape `PackageInfo.entrypoints` produces:
+ * one entry per declared entrypoint plus a virtual `<name>:docker` companion
+ * carrying the image, explicit or autogenerated. So a missing companion is the
+ * whole signal.
+ *
+ * Run environments and assets are not software and never carry an image of
+ * their own (a python image bakes its environment in), so they are skipped. So
+ * are references, which re-export a descriptor this package neither builds nor
+ * can fix — `SwJsonRenderer.copySwJson` warns about those instead.
+ */
+export function softwareEntrypointsWithoutDocker(
+  entrypoints: Map<string, entrypoint.Entrypoint>,
+): string[] {
+  const uncovered: string[] = [];
+
+  for (const [name, ep] of entrypoints.entries()) {
+    if (ep.type !== "software") continue;
+
+    // This entry *is* an image: the virtual companion, or a docker-only entrypoint.
+    // Told apart by artifact type rather than by the ':docker' name suffix —
+    // entrypoint names are barely constrained, so `main:docker` is a legal name for a
+    // declared entrypoint, and reading the suffix as "generated companion" would let a
+    // binary-only entrypoint hide behind it. Pairing stays consistent either way: a
+    // declared `main:docker` is answered by the companion key `main:docker:docker`,
+    // which is exactly what PackageInfo generates for it.
+    if (ep.artifact.type === "docker") continue;
+
+    if (entrypoints.has(docker.entrypointName(name))) continue;
+
+    uncovered.push(name);
+  }
+
+  return uncovered;
+}
+
+/**
+ * True when an already-rendered descriptor describes runnable software carrying no
+ * image — the shape no kubernetes installation can run.
+ *
+ * Reads the descriptor rather than a package declaration, for the one case where the
+ * declaration is out of reach: a reference entrypoint, whose descriptor is copied
+ * verbatim from the package that owns it.
+ */
+export function descriptorHasNoDockerVariant(descriptor: unknown): boolean {
+  if (typeof descriptor !== "object" || descriptor === null) return false;
+
+  const d = descriptor as {
+    binary?: { registry?: unknown };
+    docker?: unknown;
+    local?: unknown;
+  };
+
+  // No `binary` means a run environment or an asset; `docker` means it is covered;
+  // `local` is a dev-mode descriptor, which points at a directory rather than a
+  // registry and never runs on a cluster.
+  if (d.binary === undefined || d.docker !== undefined || d.local !== undefined) return false;
+
+  // The `variant=none` placeholder describes a package built without software at all.
+  return d.binary.registry !== defaults.NO_SOFTWARE_PLACEHOLDER;
+}
+
+/** Throws when CI is about to describe software that no k8s install can run. */
+export function assertDockerCoverage(coverage: DockerCoverage): void {
+  if (!envs.isCI()) return;
+  if (coverage.requirementWaived) return;
+  if (coverage.softwareWithoutDocker.length === 0) return;
+
+  const list = coverage.softwareWithoutDocker.map((name) => `    - ${name}`).join("\n");
+
+  throw util.CLIError(
+    `These software entrypoints produce no docker image, so no kubernetes installation ` +
+      `can run them:\n${list}\n` +
+      `  An image is autogenerated only for 'python' and 'conda' artifacts. Give each ` +
+      `entrypoint above an explicit 'docker' block next to its 'binary' one.\n` +
+      `  If this package really is meant to be binary-only, declare that with ` +
+      `"block-software": { "requireDocker": false }.`,
+  );
+}

package/src/core/docker.ts

@@ -114,13 +114,6 @@ export function build(
       // regardless of host arch (cross-compile via qemu on non-x64 hosts).
       "--platform",
       defaults.DOCKER_BUILD_PLATFORM,
-      // Disable buildkit's SLSA provenance + SBOM attestations. They embed
-      // build-time timestamps into the manifest list, which produces a fresh
-      // image digest on every build of identical source. That breaks the
-      // content-addressable tag scheme (every dev rebuild re-pushes a new
-      // tag) and defeats publishDockerImage's `remoteImageExists` smart-skip.
-      "--provenance=false",
-      "--sbom=false",
       "-t",
       tag,
       context,
@@ -138,6 +131,8 @@ export function build(
       env: {
         ...process.env, // PATH variable from parent process affects execution
         HOME: process.env.HOME || os.homedir(), // Ensure HOME is set
+        // Disables buildx default provenance so the image ID stays stable; podman ignores it.
+        BUILDX_NO_DEFAULT_ATTESTATIONS: "1",
       },
     },
   );

package/src/core/package-info.ts

@@ -37,6 +37,12 @@ const packageJsonSchema = z.object({
 
     artifacts: artifacts.artifactIndexSchema.optional(),
     entrypoints: entrypoints.entrypointListSchema,
+
+    // Opt out of the "every software entrypoint needs a docker image" rule for a
+    // package that is deliberately binary-only. Kept here rather than behind a CLI
+    // flag or env var: the exception belongs to the package, where it is reviewable,
+    // not to whichever CI run happens to build it. See core/docker-coverage.ts.
+    requireDocker: z.boolean().optional(),
   }),
 });
 type packageJson = z.infer<typeof packageJsonSchema>;
@@ -133,6 +139,11 @@ export class PackageInfo {
     return this.pkgJson.private ?? false;
   }
 
+  /** Whether every software entrypoint of this package must ship a docker image. */
+  get requireDocker(): boolean {
+    return this.pkgJson["block-software"].requireDocker ?? true;
+  }
+
   get binaryRegistries(): binaryRegistryPresets {
     return this.pkgJson["block-software"].registries?.binary ?? {};
   }

package/src/core/sw-json-render.ts

@@ -7,6 +7,7 @@ import type * as swJson from "./schemas/sw-json";
 import type * as entrypoint from "./schemas/entrypoints";
 import * as util from "./util";
 import * as docker from "./docker";
+import * as dockerCoverage from "./docker-coverage";
 import * as defaults from "../defaults";
 import { descriptorFilePath } from "./resolver";
 import { resolveRunEnvironment } from "./resolver";
@@ -179,6 +180,30 @@ export class SwJsonRenderer {
     const dstSwInfoPath = descriptorFilePath(this.pkgInfo.packageRoot, epType, epName);
     util.ensureDirsExist(path.dirname(dstSwInfoPath));
     fs.copyFileSync(srcFile, dstSwInfoPath);
+
+    if (epType === "software") this.warnIfNoDockerVariant(epName, srcFile);
+  }
+
+  /**
+   * A reference re-exports another package's descriptor verbatim, so the docker-coverage
+   * check cannot judge it from this package's declaration — and must not fail on it: the
+   * owning package may have declared itself binary-only on purpose, and that waiver does
+   * not travel inside the descriptor. Warn, naming what to fix and where.
+   */
+  private warnIfNoDockerVariant(epName: string, srcFile: string) {
+    let descriptor: unknown;
+    try {
+      descriptor = JSON.parse(fs.readFileSync(srcFile, "utf-8"));
+    } catch {
+      return; // an unreadable descriptor is the copy's problem to report, not this warning's
+    }
+
+    if (!dockerCoverage.descriptorHasNoDockerVariant(descriptor)) return;
+
+    this.logger.warn(
+      `referenced entrypoint '${epName}' carries no docker image, so no kubernetes ` +
+        `installation can run it. Fix it in the package that owns ${srcFile}.`,
+    );
   }
 
   private renderLocalPackage(

package/src/index.ts

@@ -5,6 +5,12 @@ export * as util from "./core/util";
 export * as envs from "./core/envs";
 export * as defaults from "./defaults";
 export { assertDockerPushIntent, type PushIntent } from "./core/push-guard";
+export {
+  assertDockerCoverage,
+  softwareEntrypointsWithoutDocker,
+  descriptorHasNoDockerVariant,
+  type DockerCoverage,
+} from "./core/docker-coverage";
 
 /** The logger the engine and its callers pass around. */
 export type Logger = winston.Logger;
@@ -24,6 +30,7 @@ export type Builder = Pick<
   | "version"
   | "isPrivate"
   | "selectedDockerPackages"
+  | "assertDockerCoverage"
   | "buildDockerImages"
   | "buildSoftwareArchives"
   | "buildSwJsonFiles"