feat: initial centralized image reference parser

d3vco · d3vco · commit 077241f43481 · 2026-02-19T14:02:01.000-05:00
diff --git a/lib/image-reference.ts b/lib/image-reference.ts
@@ -0,0 +1,82 @@
+/**
+ * Centralized image reference parsing for OCI image names.
+ * Uses OCI distribution-style regexes to parse name, registry, tag, and digest.
+ */
+
+// Full reference: optional registry, repository path, optional tag, optional digest.
+// Capture groups: 1 = name (repo path including optional registry), 2 = tag, 3 = digest.
+const imageReferencePattern = String.raw`^((?:(?:(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])(?:\.(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]))*|\[(?:[a-fA-F0-9:]+)\])(?::[0-9]+)?/)?[a-z0-9]+(?:(?:[._]|__|[-]+)[a-z0-9]+)*(?:/[a-z0-9]+(?:(?:[._]|__|[-]+)[a-z0-9]+)*)*)(?::([a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}))?(?:@([A-Za-z][A-Za-z0-9]*(?:[-_+.][A-Za-z][A-Za-z0-9]*)*[:][a-fA-F0-9]{32,}))?$`;
+const imageReferenceRegex = new RegExp(imageReferencePattern);
+
+// Registry prefix only. Requires '.' or localhost to distinguish registry from repository.
+// Capture group 1 = registry hostname (no trailing '/' or '@').
+const imageRegistryPattern = String.raw`^((?:(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])(?:\.(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]))+|\[(?:[a-fA-F0-9:]+)\]|localhost)(?::[0-9]+)?)(?:/|@)`;
+const imageRegistryRegex = new RegExp(imageRegistryPattern);
+
+export interface ParsedImageReference {
+  /** Repository path (e.g. nginx, library/nginx) */
+  repository: string;
+  /** Registry hostname (e.g. gcr.io, registry-1.docker.io); undefined if none */
+  registry?: string;
+  /** Tag (e.g. latest, 1.23.0); undefined if only digest or neither */
+  tag?: string;
+  /** Inline digest (e.g. sha256:abc...); undefined if not present */
+  digest?: string;
+}
+
+/**
+ * Parse an OCI image reference into repository, registry, tag, and digest.
+ *
+ * @param reference - Image reference string (e.g. nginx:1.23.0@sha256:..., gcr.io/nginx:latest)
+ * @returns ParsedImageReference
+ * @throws "image name is empty" if reference is empty
+ * @throws "image repository contains uppercase letter" if repo path has uppercase
+ * @throws "invalid image reference format" if format is invalid
+ */
+export function parseImageReference(reference: string): ParsedImageReference {
+  if (reference === "") {
+    throw new Error("image name is empty");
+  }
+
+  const groups = imageReferenceRegex.exec(reference);
+  if (groups === null) {
+    const lowerMatch = imageReferenceRegex.exec(reference.toLowerCase());
+    if (lowerMatch !== null) {
+      throw new Error("image repository contains uppercase letter");
+    }
+    throw new Error("invalid image reference format");
+  }
+
+  let repository = groups[1];
+  const tag = groups[2];
+  const digest = groups[3];
+
+  let registry: string | undefined;
+  const registryMatch = imageRegistryRegex.exec(repository);
+  if (registryMatch !== null) {
+    registry = registryMatch[1];
+    repository = repository.slice(registry.length + 1);
+  }
+
+  return {
+    repository,
+    registry,
+    tag: tag ?? undefined,
+    digest: digest ?? undefined,
+  };
+}
+
+/**
+ * Validate a Docker/OCI image reference without throwing.
+ *
+ * @param reference - Image reference string to validate
+ * @returns true if parseImageReference would succeed, false otherwise
+ */
+export function isValidImageReference(reference: string): boolean {
+  try {
+    parseImageReference(reference);
+    return true;
+  } catch {
+    return false;
+  }
+}
diff --git a/test/lib/image-reference.spec.ts b/test/lib/image-reference.spec.ts
@@ -0,0 +1,215 @@
+import {
+  parseImageReference,
+  isValidImageReference,
+} from "../../lib/image-reference";
+
+const validSha256 =
+  "sha256:abcd1234567890abcd1234567890abcd1234567890abcd1234567890abcd1234";
+
+describe("image-reference", () => {
+  describe("parseImageReference", () => {
+    describe("valid image references", () => {
+      it("parses image with tag only", () => {
+        expect(parseImageReference("nginx:latest")).toEqual({
+          repository: "nginx",
+          registry: undefined,
+          tag: "latest",
+          digest: undefined,
+        });
+      });
+
+      it("parses image with semantic tag", () => {
+        expect(parseImageReference("nginx:1.23.0")).toEqual({
+          repository: "nginx",
+          registry: undefined,
+          tag: "1.23.0",
+          digest: undefined,
+        });
+      });
+
+      it("parses image without tag or digest (repository only)", () => {
+        expect(parseImageReference("nginx")).toEqual({
+          repository: "nginx",
+          registry: undefined,
+          tag: undefined,
+          digest: undefined,
+        });
+      });
+
+      it("parses image with digest only", () => {
+        expect(parseImageReference(`nginx@${validSha256}`)).toEqual({
+          repository: "nginx",
+          registry: undefined,
+          tag: undefined,
+          digest: validSha256,
+        });
+      });
+
+      it("parses image with tag and digest (name:tag@digest)", () => {
+        expect(
+          parseImageReference(`nginx:1.23.0@${validSha256}`),
+        ).toEqual({
+          repository: "nginx",
+          registry: undefined,
+          tag: "1.23.0",
+          digest: validSha256,
+        });
+      });
+
+      it("parses image with registry (gcr.io)", () => {
+        expect(parseImageReference("gcr.io/project/nginx:latest")).toEqual({
+          repository: "project/nginx",
+          registry: "gcr.io",
+          tag: "latest",
+          digest: undefined,
+        });
+      });
+
+      it("parses image with registry and digest", () => {
+        expect(
+          parseImageReference(`gcr.io/project/nginx:1.23.0@${validSha256}`),
+        ).toEqual({
+          repository: "project/nginx",
+          registry: "gcr.io",
+          tag: "1.23.0",
+          digest: validSha256,
+        });
+      });
+
+      it("parses localhost registry with port", () => {
+        expect(
+          parseImageReference("localhost:5000/foo/bar:tag"),
+        ).toEqual({
+          repository: "foo/bar",
+          registry: "localhost:5000",
+          tag: "tag",
+          digest: undefined,
+        });
+      });
+
+      it("parses docker.io style registry", () => {
+        expect(
+          parseImageReference("docker.io/calico/cni:release-v3.14"),
+        ).toEqual({
+          repository: "calico/cni",
+          registry: "docker.io",
+          tag: "release-v3.14",
+          digest: undefined,
+        });
+      });
+
+      it("parses library/ prefix (Docker Hub official images)", () => {
+        expect(parseImageReference("library/nginx:latest")).toEqual({
+          repository: "library/nginx",
+          registry: undefined,
+          tag: "latest",
+          digest: undefined,
+        });
+      });
+
+      it("parses docker.io/library/ prefix (Docker Hub official images)", () => {
+        expect(parseImageReference("docker.io/library/nginx:latest")).toEqual({
+          repository: "library/nginx",
+          registry: "docker.io",
+          tag: "latest",
+          digest: undefined,
+        });
+      });
+
+      it("parses repository with dots and dashes", () => {
+        expect(parseImageReference("my.repo/image-name:tag")).toEqual({
+          repository: "image-name",
+          registry: "my.repo",
+          tag: "tag",
+          digest: undefined,
+        });
+      });
+
+      it("parses IPv6 registry", () => {
+        expect(
+          parseImageReference("[::1]:5000/foo/bar:latest"),
+        ).toEqual({
+          repository: "foo/bar",
+          registry: "[::1]:5000",
+          tag: "latest",
+          digest: undefined,
+        });
+      });
+
+      it("parses tag with dots and dashes", () => {
+        expect(parseImageReference("nginx:1.23.0-alpha")).toEqual({
+          repository: "nginx",
+          registry: undefined,
+          tag: "1.23.0-alpha",
+          digest: undefined,
+        });
+      });
+    });
+
+    describe("invalid image references", () => {
+      it("throws for empty string", () => {
+        expect(() => parseImageReference("")).toThrow("image name is empty");
+      });
+
+      it("throws for invalid format (no repository)", () => {
+        expect(() => parseImageReference(":tag")).toThrow(
+          "invalid image reference format",
+        );
+      });
+
+      it("throws for invalid format (leading slash)", () => {
+        expect(() => parseImageReference("/test:unknown")).toThrow(
+          "invalid image reference format",
+        );
+      });
+
+      it("throws for uppercase in repository", () => {
+        expect(() => parseImageReference("UPPERCASE")).toThrow(
+          "image repository contains uppercase letter",
+        );
+      });
+
+      it("throws for uppercase in repository path with registry", () => {
+        expect(() => parseImageReference("gcr.io/Project/nginx")).toThrow(
+          "image repository contains uppercase letter",
+        );
+      });
+
+      it("throws for invalid digest (too short)", () => {
+        expect(() =>
+          parseImageReference("nginx@sha256:abc"),
+        ).toThrow("invalid image reference format");
+      });
+
+      it("throws for malformed reference", () => {
+        expect(() => parseImageReference("image:")).toThrow(
+          "invalid image reference format",
+        );
+      });
+    });
+  });
+
+  describe("isValidImageReference", () => {
+    it("returns true for valid references", () => {
+      expect(isValidImageReference("nginx:latest")).toBe(true);
+      expect(isValidImageReference("nginx")).toBe(true);
+      expect(
+        isValidImageReference(`nginx:1.23.0@${validSha256}`),
+      ).toBe(true);
+      expect(isValidImageReference("gcr.io/project/nginx:latest")).toBe(true);
+    });
+
+    it("returns false for empty string", () => {
+      expect(isValidImageReference("")).toBe(false);
+    });
+
+    it("returns false for invalid format", () => {
+      expect(isValidImageReference(":tag")).toBe(false);
+      expect(isValidImageReference("/invalid")).toBe(false);
+    });
+
+    it("returns false for uppercase in repository", () => {
+      expect(isValidImageReference("UPPERCASE")).toBe(false);
+    });
+  });
+});
