@specific.dev/spectest 0.90.2 → 0.91.0

package/src/index.ts

@@ -253,6 +253,8 @@ export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
 export interface ServiceConfig {
   /** Image definition: registry pull or inline build. */
   image: ServiceImage;
+  /** @internal Images built by the harness and loaded into this component. */
+  imageBuilds?: readonly ComponentImageBuild[];
   /**
    * Shell command to run (sh -c). Defaults to the image's CMD. NB: this
    * **replaces the image's entrypoint** with `/bin/sh -c` — an
@@ -1158,10 +1160,13 @@ export interface ServiceTls {
   port: number;
 }
 
-export type ServiceImage =
+/** @internal Normalized wire representation; legacy definitions remain accepted. */
+export type NormalizedServiceImage =
   | { type: "registry"; reference: string }
   | {
       type: "dockerfile";
+      /** Optional full local image reference. */
+      reference?: string;
       /**
        * Path of a Dockerfile in your repo, relative to the project root
        * (where `spectest/` lives) — `"Dockerfile"`, `"apps/api/Dockerfile"`.
@@ -1204,6 +1209,8 @@ export type ServiceImage =
     }
   | {
       type: "dockerfile";
+      /** Optional full local image reference. */
+      reference?: string;
       /**
        * Dockerfile contents, built as if the file sat outside the build
        * context (it is never written into your repo). The context is the
@@ -1233,6 +1240,38 @@ export type ServiceImage =
       buildArgs?: Readonly<Record<string, string>>;
     };
 
+/** Dockerfile build options shared by services and Kubernetes images. */
+export type BuildImage = (
+  | Omit<Extract<NormalizedServiceImage, { type: "dockerfile"; path: string }>, "type">
+  | Omit<Extract<NormalizedServiceImage, { type: "dockerfile"; content: string }>, "type">
+) & {
+  /** Full image reference, e.g. "k8s.internal:5000/runtime:spectest".
+   * Optional for a service; required for a Kubernetes build. This names a
+   * local image and does not publish it to a registry. */
+  reference?: string;
+};
+
+/** A registry reference or Dockerfile build. Tagged objects from older SDKs
+ * remain accepted for compatibility; new definitions do not need `type`. */
+export type ServiceImage = string | BuildImage | NormalizedServiceImage;
+
+/** @internal Keep the wire format compatible with existing control planes. */
+export function normalizeServiceImage(image: ServiceImage): NormalizedServiceImage {
+  if (typeof image === "string") return { type: "registry", reference: image };
+  if (!image || typeof image !== "object" || Array.isArray(image)) throw new Error("image must be a registry reference or Dockerfile build");
+  if ("type" in image) {
+    if (image.type !== "registry" && image.type !== "dockerfile") throw new Error("unsupported image type");
+    return image;
+  }
+  return { ...image, type: "dockerfile" };
+}
+
+/** @internal Serializes build-only work with the owning component. */
+export interface ComponentImageBuild {
+  reference: string;
+  image: BuildImage;
+}
+
 /** A Dockerfile `ARG` name: what `docker build --build-arg` accepts as a key. */
 const BUILD_ARG_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
@@ -1274,8 +1313,13 @@ const BUILD_TARGET_RE = /^[^\s]+$/;
  * checks go through the project-file resolver, so the same rules as
  * `ctx.readProjectFile` apply.
  */
-export function validateServiceImage(serviceName: string, image: ServiceImage): ServiceImage {
+export function validateServiceImage(serviceName: string, input: ServiceImage): NormalizedServiceImage {
+  const image = normalizeServiceImage(input);
+  const reference = typeof input === "string" ? input : "reference" in input ? input.reference : undefined;
+  if (reference !== undefined && (typeof reference !== "string" || !reference || reference.startsWith("-") || /[\s\x00]/.test(reference))) throw new Error(`service "${serviceName}" image reference must be a non-empty image name without whitespace`);
   if (image.type !== "dockerfile") return image;
+  if (reference?.includes("@")) throw new Error(`service "${serviceName}" build reference must be an image name/tag, not a digest`);
+  if (image.exclude !== undefined && (!Array.isArray(image.exclude) || image.exclude.some(e => typeof e !== "string"))) throw new Error(`service "${serviceName}" image exclude must be an array of glob patterns`);
   validateBuildArgs(serviceName, image.buildArgs);
   const hasPath = typeof image.path === "string";
   const hasContent = typeof image.content === "string";
@@ -1286,7 +1330,7 @@ export function validateServiceImage(serviceName: string, image: ServiceImage):
   }
   if (!hasPath && !hasContent) {
     throw new Error(
-      `service "${serviceName}" image { type: "dockerfile" } needs \`path\` (a Dockerfile in your repo, relative to the project root) or \`content\``,
+      `service "${serviceName}" image build needs \`path\` (a Dockerfile in your repo, relative to the project root) or \`content\``,
     );
   }
   if (hasPath) {
@@ -2491,6 +2535,7 @@ export function defineEnvironment<
   const { fakes, services: rawServices, ...rest } = input;
   const expanded = expandServiceGroups(rawServices);
   for (const [key, svc] of Object.entries(expanded)) {
+    for (const build of svc.imageBuilds ?? []) validateServiceImage(`${key} image ${build.reference}`, build.image);
     expanded[key] = applyCoverageAdapters(key, {
       ...svc,
       image: validateServiceImage(key, svc.image),