@specific.dev/spectest 0.76.0 → 0.77.0

package/src/harness/build-context.ts

@@ -47,10 +47,24 @@ export function isGeneratedDockerignore(text: string): boolean {
   return text.startsWith(GENERATED_DOCKERIGNORE_HEADER);
 }
 
+/**
+ * The project's own ignore rules for one build, chosen the way BuildKit
+ * chooses them: a `<Dockerfile>.dockerignore` next to the Dockerfile wins
+ * outright, else the context root's `.dockerignore`, else nothing. The two
+ * are never merged — a Dockerfile-adjacent file is the whole rule set for
+ * that build, exactly as `docker build` reads it.
+ */
+export function pickProjectIgnore(
+  adjacent: string | null,
+  contextRoot: string | null,
+): string | null {
+  return adjacent ?? contextRoot;
+}
+
 /**
  * Ignore rules for one dockerfile build, in precedence order: our
- * defaults, then the project's own `.dockerignore` verbatim, then that
- * service's `exclude`.
+ * defaults, then the project's own ignore file verbatim (see
+ * {@link pickProjectIgnore}), then that service's `exclude`.
  *
  * **The order is load-bearing**, because of the `**`-plus-negations idiom
  * that monorepos use to keep a build context small:
@@ -113,44 +127,69 @@ export function unionDockerignore(
   return [GENERATED_DOCKERIGNORE_HEADER, ...DEFAULT_DOCKERIGNORE, ...extras].join("\n") + "\n";
 }
 
+/**
+ * Everything one dockerfile build reads, resolved from the project: the
+ * Dockerfile's bytes (from `path` or `content`), the context directory
+ * (project-root-relative, `.` by default), the composed ignore rules, the
+ * stage to stop at, and the build args. The harness resolves this once per
+ * service and both the dedup key and the build itself work from it.
+ */
+export interface ResolvedBuild {
+  /** The Dockerfile text. */
+  content: string;
+  /** Project-root-relative build context directory (`.` for the root). */
+  context: string;
+  /** The generated `<Dockerfile>.dockerignore` text. */
+  ignore: string;
+  /** `--target` stage, if any. */
+  target?: string;
+  buildArgs?: Readonly<Record<string, string>>;
+}
+
 /**
  * Identity of a dockerfile build within one bootstrap, so services sharing
  * an image definition (an api and a worker on the same codebase with
  * different entrypoints) build once and the rest just re-tag.
  *
- * The build **context** is an input too, but it isn't hashed: the context
- * is `/workspace`, which is fixed within a bootstrap and mutable between
- * them, so this key is only ever valid inside one workspace generation.
- * The dedup map is cleared per bootstrap for exactly that reason.
+ * The context *directory* is part of the key, but its *contents* are not:
+ * `/workspace` is fixed within a bootstrap and mutable between them, so
+ * this key is only ever valid inside one workspace generation. The dedup
+ * map is cleared per bootstrap for exactly that reason.
  */
 export interface Hasher {
   update(s: string): Hasher;
   digest(encoding: "hex"): string;
 }
 
-export function buildContentKey(
-  createHasher: () => Hasher,
-  image: { content: string; exclude?: readonly string[]; buildArgs?: Readonly<Record<string, string>> },
-): string {
+export function buildContentKey(createHasher: () => Hasher, build: ResolvedBuild): string {
   return (
     createHasher()
-      .update(image.content)
-      // A separator that cannot occur in either field. Without it a
-      // Dockerfile whose text ends with an exclude list would hash the
+      .update(build.content)
+      // A separator that cannot occur in any field. Without it a
+      // Dockerfile whose text ends with an ignore list would hash the
       // same as that Dockerfile with the list actually set, and two
       // genuinely different builds would collapse into one.
       .update("\0")
-      .update(JSON.stringify(image.exclude ?? []))
+      .update(build.context)
+      .update("\0")
+      .update(build.ignore)
+      .update("\0")
+      .update(build.target ?? "")
       // Build args are an input to the image (an ARG picks the base image,
       // the NODE_ENV of an install step…), so two services on one
       // Dockerfile with different args must not share a build. Sorted, so
       // key order in the user's object doesn't split identical builds.
       .update("\0")
-      .update(JSON.stringify(buildArgFlags(image.buildArgs)))
+      .update(JSON.stringify(buildArgFlags(build.buildArgs)))
       .digest("hex")
   );
 }
 
+/** `--target <stage>`, or nothing. A plain client flag every builder takes. */
+export function buildTargetFlags(target: string | undefined): string[] {
+  return target ? ["--target", target] : [];
+}
+
 /** `--build-arg NAME=value` pairs, in a stable (sorted) order. */
 export function buildArgFlags(buildArgs: Readonly<Record<string, string>> | undefined): string[] {
   return Object.entries(buildArgs ?? {})

package/src/index.ts

@@ -5,7 +5,7 @@
 // over HTTP.
 
 import { strict as nodeAssert } from "node:assert";
-import { readFileSync } from "node:fs";
+import { statSync } from "node:fs";
 
 import { recordAssertion, safeSerialize } from "./recorder.js";
 import { adoptNullishTag, readRaw, readTag } from "./inspect.js";
@@ -1138,17 +1138,33 @@ export type ServiceImage =
        * Path of a Dockerfile in your repo, relative to the project root
        * (where `spectest/` lives) — `"Dockerfile"`, `"apps/api/Dockerfile"`.
        * This is the preferred form: the test environment builds the same
-       * Dockerfile production does, so the two cannot drift. The build
-       * context is always the project root, as with
-       * `docker build -f apps/api/Dockerfile .`, so `COPY` / `ADD` resolve
-       * against the repo root wherever the file sits. The file is read when
-       * the environment loads; a missing file fails the load and names the
-       * path. Mutually exclusive with `content`.
+       * Dockerfile production does, so the two cannot drift. The file is
+       * read from the repo at build time; a missing file fails the
+       * environment load and names the path. Mutually exclusive with
+       * `content`.
+       *
+       * Ignore rules come from the repo the way `docker build` reads them:
+       * a `<Dockerfile>.dockerignore` beside this file, else the context
+       * directory's `.dockerignore`. `exclude` adds to whichever applied.
        */
       path: string;
       content?: never;
+      /**
+       * Build context directory, relative to the project root. Defaults to
+       * the project root, as with `docker build -f apps/api/Dockerfile .`.
+       * `"apps/api"` is `docker build apps/api`: `COPY` / `ADD` resolve
+       * against that directory, and so do the ignore rules.
+       */
+      context?: string;
       /** Extra glob patterns to exclude from the build context. */
       exclude?: readonly string[];
+      /**
+       * Stage to build, as `docker build --target <stage>`. Lets a
+       * production Dockerfile keep a final stage the tests never need (an
+       * ops layer, a slow install) while the environment stops at the
+       * stage before it.
+       */
+      target?: string;
       /**
        * `--build-arg` values for the Dockerfile's `ARG`s — `{ NODE_ENV: "test" }`.
        * Build-time only: they are not in the container's environment (use
@@ -1161,16 +1177,24 @@ export type ServiceImage =
   | {
       type: "dockerfile";
       /**
-       * Dockerfile contents, written verbatim into the build context. The
-       * build context is the project root (where `spectest/` lives), so any
-       * `COPY` / `ADD` references resolve relative to that directory.
-       * Prefer `path`, which points at the Dockerfile your repo already has.
-       * Mutually exclusive with `path`.
+       * Dockerfile contents, built as if the file sat outside the build
+       * context (it is never written into your repo). The context is the
+       * project root (where `spectest/` lives) unless `context` says
+       * otherwise, and `COPY` / `ADD` resolve against it. Prefer `path`,
+       * which points at the Dockerfile your repo already has. Mutually
+       * exclusive with `path`.
        */
       content: string;
       path?: never;
+      /**
+       * Build context directory, relative to the project root. Defaults to
+       * the project root. The context's own `.dockerignore` applies.
+       */
+      context?: string;
       /** Extra glob patterns to exclude from the build context. */
       exclude?: readonly string[];
+      /** Stage to build, as `docker build --target <stage>`. */
+      target?: string;
       /**
        * `--build-arg` values for the Dockerfile's `ARG`s — `{ NODE_ENV: "test" }`.
        * Build-time only: they are not in the container's environment (use
@@ -1203,20 +1227,27 @@ function validateBuildArgs(serviceName: string, buildArgs: Readonly<Record<strin
   }
 }
 
+/** A Dockerfile stage name, as `--target` accepts it: no whitespace. */
+const BUILD_TARGET_RE = /^[^\s]+$/;
+
 /**
- * Resolve a service's `image` to the form the harness builds: a `path`
- * Dockerfile is read from the repo and becomes `content`. The wire config
- * therefore never carries `path` — the control plane and the daemon's build
- * code only ever see Dockerfile bytes, and the warm-template hash covers
- * them because the file is part of the project tree.
+ * Check a service's `image` at config time, so a mistake fails the
+ * environment load with a message that names it, instead of a build
+ * minutes later. Nothing is rewritten: a `path` Dockerfile stays a path,
+ * and the harness reads it — and the ignore file beside it — from the
+ * repo when it builds (`daemon.ts::resolveDockerfileBuild`). The wire
+ * config therefore carries `path`, `context` and `target` as written; the
+ * control plane only tells a Dockerfile build from a registry pull, and
+ * the warm-template hash covers the files because they are part of the
+ * project tree.
  *
- * Runs at config time (`defineEnvironment`, and the daemon's runtime
- * `startService` twin), inside the VM, where the repo sits at the project
- * root. The read goes through the project-file resolver, so the same rules
- * as `ctx.readProjectFile` apply (a `spectest/.envignore`d path is refused
+ * Runs in `defineEnvironment`, and in the daemon's runtime `startService`
+ * twin, inside the VM, where the repo sits at the project root. Existence
+ * checks go through the project-file resolver, so the same rules as
+ * `ctx.readProjectFile` apply (a `spectest/.envignore`d path is refused
  * instead of read stale).
  */
-export function resolveServiceImage(serviceName: string, image: ServiceImage): ServiceImage {
+export function validateServiceImage(serviceName: string, image: ServiceImage): ServiceImage {
   if (image.type !== "dockerfile") return image;
   validateBuildArgs(serviceName, image.buildArgs);
   const hasPath = typeof image.path === "string";
@@ -1231,20 +1262,35 @@ export function resolveServiceImage(serviceName: string, image: ServiceImage): S
       `service "${serviceName}" image { type: "dockerfile" } needs \`path\` (a Dockerfile in your repo, relative to the project root) or \`content\``,
     );
   }
-  if (!hasPath) return image;
-  const file = resolveExistingProjectPath(image.path as string, `service "${serviceName}" Dockerfile`);
-  let content: string;
-  try {
-    content = readFileSync(file, "utf8");
-  } catch (e) {
-    throw new Error(
-      `service "${serviceName}" Dockerfile ${JSON.stringify(image.path)} could not be read: ${(e as Error).message}`,
-    );
+  if (hasPath) {
+    const file = resolveExistingProjectPath(image.path as string, `service "${serviceName}" Dockerfile`);
+    if (!statSync(file).isFile()) {
+      throw new Error(
+        `service "${serviceName}" Dockerfile ${JSON.stringify(image.path)} is not a file — \`path\` names the Dockerfile itself, \`context\` names the directory to build from`,
+      );
+    }
+  }
+  if (image.context !== undefined) {
+    if (typeof image.context !== "string" || image.context === "") {
+      throw new Error(
+        `service "${serviceName}" image context must be a directory path relative to the project root (\`"."\` for the root)`,
+      );
+    }
+    const dir = resolveExistingProjectPath(image.context, `service "${serviceName}" build context`);
+    if (!statSync(dir).isDirectory()) {
+      throw new Error(
+        `service "${serviceName}" build context ${JSON.stringify(image.context)} is not a directory`,
+      );
+    }
+  }
+  if (image.target !== undefined) {
+    if (typeof image.target !== "string" || !BUILD_TARGET_RE.test(image.target)) {
+      throw new Error(
+        `service "${serviceName}" image target must be a Dockerfile stage name (\`FROM … AS <name>\`); got ${JSON.stringify(image.target)}`,
+      );
+    }
   }
-  const lowered: ServiceImage = { type: "dockerfile", content };
-  if (image.exclude !== undefined) lowered.exclude = image.exclude;
-  if (image.buildArgs !== undefined) lowered.buildArgs = image.buildArgs;
-  return lowered;
+  return image;
 }
 
 // Coverage adapters live in `coverage.ts`; the type is re-declared here
@@ -2389,7 +2435,7 @@ export function defineEnvironment<
   for (const [key, svc] of Object.entries(expanded)) {
     expanded[key] = applyCoverageAdapters(key, {
       ...svc,
-      image: resolveServiceImage(key, svc.image),
+      image: validateServiceImage(key, svc.image),
     });
   }
   const config: EnvironmentConfig<S> = {