@checkstack/gitops-backend 0.1.0

package/src/kind-registry.test.ts

@@ -0,0 +1,262 @@
+import { describe, it, expect } from "bun:test";
+import { z } from "zod";
+import { createEntityKindRegistry } from "./kind-registry";
+import { CHECKSTACK_API_VERSION } from "@checkstack/gitops-common";
+
+describe("EntityKindRegistry", () => {
+  it("registers a kind and retrieves it", () => {
+    const registry = createEntityKindRegistry();
+    const specSchema = z.object({ description: z.string().optional() });
+
+    registry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      specSchema,
+      reconcile: async () => ({ entityId: "test-id" }),
+    });
+
+    const kind = registry.getKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+    });
+    expect(kind).toBeDefined();
+    expect(kind?.kind).toBe("System");
+  });
+
+  it("throws on duplicate kind registration", () => {
+    const registry = createEntityKindRegistry();
+    const def = {
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      specSchema: z.object({}),
+      reconcile: async () => ({ entityId: "test-id" }),
+    };
+
+    registry.registerKind(def);
+    expect(() => registry.registerKind(def)).toThrow(/already registered/);
+  });
+
+  it("registers a kind extension", () => {
+    const registry = createEntityKindRegistry();
+
+    registry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      specSchema: z.object({ description: z.string().optional() }),
+      reconcile: async () => ({ entityId: "test-id" }),
+    });
+
+    registry.registerKindExtension({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      namespace: "healthcheck",
+      specSchema: z.array(z.object({ ref: z.string() })).optional(),
+      reconcile: async () => {},
+    });
+
+    const extensions = registry.getExtensions({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+    });
+    expect(extensions).toHaveLength(1);
+    expect(extensions[0].namespace).toBe("healthcheck");
+  });
+
+  it("throws on duplicate extension namespace", () => {
+    const registry = createEntityKindRegistry();
+
+    registry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      specSchema: z.object({}),
+      reconcile: async () => ({ entityId: "test-id" }),
+    });
+
+    const extDef = {
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      namespace: "healthcheck",
+      specSchema: z.object({}).optional(),
+      reconcile: async () => {},
+    };
+
+    registry.registerKindExtension(extDef);
+    expect(() => registry.registerKindExtension(extDef)).toThrow(
+      /already registered/,
+    );
+  });
+
+  it("allows registering extensions before the kind itself", () => {
+    const registry = createEntityKindRegistry();
+
+    // Extension first
+    registry.registerKindExtension({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      namespace: "healthcheck",
+      specSchema: z.array(z.object({ ref: z.string() })).optional(),
+      reconcile: async () => {},
+    });
+
+    // Kind after
+    registry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      specSchema: z.object({ description: z.string().optional() }),
+      reconcile: async () => ({ entityId: "test-id" }),
+    });
+
+    const kind = registry.getKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+    });
+    expect(kind).toBeDefined();
+
+    const extensions = registry.getExtensions({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+    });
+    expect(extensions).toHaveLength(1);
+  });
+
+  it("builds a merged spec schema with extensions", () => {
+    const registry = createEntityKindRegistry();
+
+    registry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      specSchema: z.object({ description: z.string().optional() }),
+      reconcile: async () => ({ entityId: "test-id" }),
+    });
+
+    registry.registerKindExtension({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      namespace: "healthcheck",
+      specSchema: z.array(z.object({ ref: z.string() })).optional(),
+      reconcile: async () => {},
+    });
+
+    const merged = registry.getMergedSpecSchema({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+    });
+
+    // Should validate base spec fields
+    const result1 = merged.safeParse({ description: "test" });
+    expect(result1.success).toBe(true);
+
+    // Should validate extension namespace fields
+    const result2 = merged.safeParse({
+      description: "test",
+      healthcheck: [{ ref: "my-check" }],
+    });
+    expect(result2.success).toBe(true);
+
+    // Extension namespace should be optional
+    const result3 = merged.safeParse({});
+    expect(result3.success).toBe(true);
+  });
+
+  it("lists all registered kinds", () => {
+    const registry = createEntityKindRegistry();
+
+    registry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      specSchema: z.object({}),
+      reconcile: async () => ({ entityId: "test-id" }),
+    });
+
+    registry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "Healthcheck",
+      specSchema: z.object({}),
+      reconcile: async () => ({ entityId: "test-id" }),
+    });
+
+    expect(registry.getKinds()).toHaveLength(2);
+  });
+
+  it("returns empty array for extensions of unregistered kind", () => {
+    const registry = createEntityKindRegistry();
+    const extensions = registry.getExtensions({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "Unknown",
+    });
+    expect(extensions).toHaveLength(0);
+  });
+
+  describe("describeKinds", () => {
+    it("returns JSON Schema representations of registered kinds", () => {
+      const registry = createEntityKindRegistry();
+
+      registry.registerKind({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "System",
+        specSchema: z.object({
+          description: z.string().optional(),
+          tier: z.enum(["critical", "standard"]),
+        }),
+        reconcile: async () => ({ entityId: "test-id" }),
+      });
+
+      const described = registry.describeKinds();
+      expect(described).toHaveLength(1);
+
+      const sys = described[0];
+      expect(sys.apiVersion).toBe(CHECKSTACK_API_VERSION);
+      expect(sys.kind).toBe("System");
+      expect(sys.specSchema).toBeDefined();
+      expect(sys.extensions).toHaveLength(0);
+
+      // Verify JSON Schema structure
+      const schema = sys.specSchema as Record<string, unknown>;
+      expect(schema.type).toBe("object");
+      const props = schema.properties as Record<string, Record<string, unknown>>;
+      expect(props.description).toBeDefined();
+      expect(props.tier).toBeDefined();
+    });
+
+    it("includes extensions in the description", () => {
+      const registry = createEntityKindRegistry();
+
+      registry.registerKind({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "System",
+        specSchema: z.object({ description: z.string().optional() }),
+        reconcile: async () => ({ entityId: "test-id" }),
+      });
+
+      registry.registerKindExtension({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "System",
+        namespace: "healthcheck",
+        specSchema: z.array(z.object({ ref: z.string() })).optional(),
+        reconcile: async () => {},
+      });
+
+      const described = registry.describeKinds();
+      expect(described).toHaveLength(1);
+      expect(described[0].extensions).toHaveLength(1);
+      expect(described[0].extensions[0].namespace).toBe("healthcheck");
+      expect(described[0].extensions[0].specSchema).toBeDefined();
+    });
+
+    it("skips kinds without a base definition", () => {
+      const registry = createEntityKindRegistry();
+
+      // Only register an extension — no base kind
+      registry.registerKindExtension({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Orphaned",
+        namespace: "test",
+        specSchema: z.object({}).optional(),
+        reconcile: async () => {},
+      });
+
+      const described = registry.describeKinds();
+      expect(described).toHaveLength(0);
+    });
+  });
+});

package/src/kind-registry.ts

@@ -0,0 +1,191 @@
+import { z } from "zod";
+import { toJsonSchema } from "@checkstack/backend-api";
+import type {
+  EntityKindDefinition,
+  EntityKindExtensionDefinition,
+  EntityKindRegistry,
+} from "@checkstack/gitops-common";
+
+/** Internal storage for a registered kind with its extensions. */
+interface RegisteredKind {
+  definition: EntityKindDefinition<unknown> | undefined;
+  extensions: Map<string, EntityKindExtensionDefinition<unknown>>;
+}
+
+/** Composite key for looking up kinds by apiVersion + kind. */
+function kindKey(params: { apiVersion: string; kind: string }): string {
+  return `${params.apiVersion}::${params.kind}`;
+}
+
+/**
+ * Creates a new Entity Kind Registry.
+ * This is the backing implementation for the `entityKindExtensionPoint`.
+ */
+export function createEntityKindRegistry() {
+  const kinds = new Map<string, RegisteredKind>();
+
+  const registry: EntityKindRegistry & {
+    /** Get a registered kind definition. */
+    getKind: (params: {
+      apiVersion: string;
+      kind: string;
+    }) => EntityKindDefinition<unknown> | undefined;
+    /** Get all extensions for a kind. */
+    getExtensions: (params: {
+      apiVersion: string;
+      kind: string;
+    }) => EntityKindExtensionDefinition<unknown>[];
+    /** Get the merged spec schema (base + all extensions). */
+    getMergedSpecSchema: (params: {
+      apiVersion: string;
+      kind: string;
+    }) => z.ZodType<unknown>;
+    /** List all registered kinds. */
+    getKinds: () => EntityKindDefinition<unknown>[];
+    /** Describe all registered kinds with JSON Schema representations. */
+    describeKinds: () => Array<{
+      apiVersion: string;
+      kind: string;
+      specSchema: Record<string, unknown>;
+      extensions: Array<{
+        namespace: string;
+        specSchema: Record<string, unknown>;
+      }>;
+    }>;
+  } = {
+    registerKind<TSpec>(definition: EntityKindDefinition<TSpec>) {
+      const key = kindKey(definition);
+      const existing = kinds.get(key);
+
+      if (existing?.definition) {
+        throw new Error(
+          `Entity kind "${definition.kind}" (${definition.apiVersion}) is already registered`,
+        );
+      }
+
+      if (existing) {
+        // Extensions were registered before the kind — attach the definition
+        existing.definition = definition as EntityKindDefinition<unknown>;
+      } else {
+        kinds.set(key, {
+          definition: definition as EntityKindDefinition<unknown>,
+          extensions: new Map(),
+        });
+      }
+    },
+
+    registerKindExtension<TExtensionSpec>(
+      definition: EntityKindExtensionDefinition<TExtensionSpec>,
+    ) {
+      const key = kindKey(definition);
+      const registered = kinds.get(key);
+
+      if (!registered) {
+        // Allow registering extensions before the kind itself.
+        // The kind might be registered by a plugin that loads later.
+        kinds.set(key, {
+          definition: undefined,
+          extensions: new Map([
+            [
+              definition.namespace,
+              definition as EntityKindExtensionDefinition<unknown>,
+            ],
+          ]),
+        });
+        return;
+      }
+
+      if (registered.extensions.has(definition.namespace)) {
+        throw new Error(
+          `Extension namespace "${definition.namespace}" for kind "${definition.kind}" (${definition.apiVersion}) is already registered`,
+        );
+      }
+
+      registered.extensions.set(
+        definition.namespace,
+        definition as EntityKindExtensionDefinition<unknown>,
+      );
+    },
+
+    getKind(params) {
+      return kinds.get(kindKey(params))?.definition;
+    },
+
+    getExtensions(params) {
+      const registered = kinds.get(kindKey(params));
+      if (!registered) return [];
+      return [...registered.extensions.values()];
+    },
+
+    getMergedSpecSchema(params) {
+      const registered = kinds.get(kindKey(params));
+      if (!registered?.definition) {
+        throw new Error(
+          `Cannot build merged schema: kind "${params.kind}" (${params.apiVersion}) has no base definition`,
+        );
+      }
+
+      // Start with the base spec schema
+      let merged = registered.definition
+        .specSchema as z.ZodObject<z.ZodRawShape>;
+
+      // Merge each extension's schema under its namespace key
+      for (const [namespace, ext] of registered.extensions) {
+        merged = merged.extend({
+          [namespace]: ext.specSchema,
+        }) as z.ZodObject<z.ZodRawShape>;
+      }
+
+      return merged;
+    },
+
+    getKinds() {
+      return [...kinds.values()]
+        .map((r) => r.definition)
+        .filter((d): d is EntityKindDefinition<unknown> => d !== undefined);
+    },
+
+    describeKinds() {
+      const result: Array<{
+        apiVersion: string;
+        kind: string;
+        specSchema: Record<string, unknown>;
+        extensions: Array<{
+          namespace: string;
+          specSchema: Record<string, unknown>;
+        }>;
+      }> = [];
+
+      for (const registered of kinds.values()) {
+        if (!registered.definition) continue;
+
+        const def = registered.definition;
+        const baseSchema = toJsonSchema(
+          def.specSchema as z.ZodTypeAny,
+        );
+
+        const extensions = [...registered.extensions.entries()].map(
+          ([namespace, ext]) => ({
+            namespace,
+            specSchema: toJsonSchema(ext.specSchema as z.ZodTypeAny),
+          }),
+        );
+
+        result.push({
+          apiVersion: def.apiVersion,
+          kind: def.kind,
+          specSchema: baseSchema,
+          extensions,
+        });
+      }
+
+      return result;
+    },
+  };
+
+  return registry;
+}
+
+export type InternalEntityKindRegistry = ReturnType<
+  typeof createEntityKindRegistry
+>;