@specific.dev/spectest 0.76.1 → 0.77.0

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> = {