@checkstack/dependency-backend 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @checkstack/dependency-backend
 
+## 1.1.0
+
+### Minor Changes
+
+- f6f9a5c: Add a GitOps `System.dependencies` extension and lock the matching UI.
+
+  Each entry references an upstream system by ref and tunes the impact:
+
+  ```yaml
+  apiVersion: checkstack.io/v1alpha1
+  kind: System
+  metadata: { name: payments-api }
+  spec:
+    dependencies:
+      - targetRef: { kind: System, name: payments-db }
+        impactType: critical
+        transitive: false
+        label: "primary store"
+  ```
+
+  The reconciler diffs the YAML-declared edges against the persisted ones
+  where this system is the source and converges via
+  create / update / delete. GitOps is the source of truth, so any edges
+  no longer listed are removed. Refs that resolve to the source system
+  itself are rejected; refs that fail to resolve abort the diff before
+  any mutation.
+
+  UI gates:
+
+  - The `DependencyEditor` (system editor drawer) hides Add and disables
+    Edit/Delete on upstream rows when the source system is GitOps-managed.
+    Downstream rows are gated per-row by the _other_ system's lock.
+  - The `DependencyMap` blocks `onConnect` when the source is locked,
+    surfaces a "Managed by GitOps" notice in the edge editor panel, and
+    disables Save/Delete there.
+
+### Patch Changes
+
+- Updated dependencies [42abfff]
+- Updated dependencies [f6f9a5c]
+- Updated dependencies [1ef2e79]
+  - @checkstack/common@0.9.0
+  - @checkstack/gitops-common@0.3.0
+  - @checkstack/gitops-backend@0.3.0
+  - @checkstack/incident-common@1.1.0
+  - @checkstack/maintenance-common@1.1.0
+  - @checkstack/catalog-common@2.1.0
+  - @checkstack/catalog-backend@1.1.0
+  - @checkstack/backend-api@0.15.1
+  - @checkstack/dependency-common@1.0.2
+  - @checkstack/healthcheck-backend@1.0.4
+  - @checkstack/healthcheck-common@1.0.2
+  - @checkstack/notification-common@1.0.2
+  - @checkstack/signal-common@0.2.2
+
 ## 1.0.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/dependency-backend",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -14,26 +14,28 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.14.1",
-    "@checkstack/dependency-common": "1.0.0",
-    "@checkstack/catalog-common": "2.0.0",
-    "@checkstack/catalog-backend": "1.0.1",
-    "@checkstack/healthcheck-common": "1.0.0",
-    "@checkstack/healthcheck-backend": "1.0.2",
-    "@checkstack/maintenance-common": "1.0.0",
-    "@checkstack/incident-common": "1.0.0",
-    "@checkstack/notification-common": "1.0.0",
-    "@checkstack/signal-common": "0.2.0",
-    "@checkstack/common": "0.7.0",
+    "@checkstack/backend-api": "0.15.0",
+    "@checkstack/dependency-common": "1.0.1",
+    "@checkstack/catalog-common": "2.0.1",
+    "@checkstack/catalog-backend": "1.0.2",
+    "@checkstack/healthcheck-common": "1.0.1",
+    "@checkstack/healthcheck-backend": "1.0.3",
+    "@checkstack/maintenance-common": "1.0.1",
+    "@checkstack/incident-common": "1.0.1",
+    "@checkstack/notification-common": "1.0.1",
+    "@checkstack/signal-common": "0.2.1",
+    "@checkstack/gitops-backend": "0.2.8",
+    "@checkstack/gitops-common": "0.2.2",
+    "@checkstack/common": "0.8.0",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
     "@orpc/server": "^1.13.2"
   },
   "devDependencies": {
-    "@checkstack/drizzle-helper": "0.0.4",
-    "@checkstack/scripts": "0.1.2",
-    "@checkstack/test-utils-backend": "0.1.23",
-    "@checkstack/tsconfig": "0.0.6",
+    "@checkstack/drizzle-helper": "0.0.5",
+    "@checkstack/scripts": "0.3.0",
+    "@checkstack/test-utils-backend": "0.1.24",
+    "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "drizzle-kit": "^0.31.10",
     "typescript": "^5.0.0"

package/src/dependency-gitops-kinds.test.ts

@@ -0,0 +1,356 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import type { ReconcileContext } from "@checkstack/gitops-common";
+import type { Dependency } from "@checkstack/dependency-common";
+import type { DependencyService } from "./services/dependency-service";
+import { buildSystemDependenciesExtension } from "./dependency-gitops-kinds";
+
+const noopLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+const buildContext = (
+  overrides: Partial<ReconcileContext> = {},
+): ReconcileContext =>
+  ({
+    logger: noopLogger,
+    resolveEntityRef: async () => undefined,
+    resolveSecretsBySchema: async ({ value }) => ({
+      resolved: value,
+      warnings: [],
+    }),
+    ...overrides,
+  }) as ReconcileContext;
+
+const refResolver =
+  (table: Record<string, string>) =>
+  async ({ entityName }: { kind: string; entityName: string }) =>
+    table[entityName];
+
+const dep = (
+  id: string,
+  sourceSystemId: string,
+  targetSystemId: string,
+  overrides: Partial<Dependency> = {},
+): Dependency => ({
+  id,
+  sourceSystemId,
+  targetSystemId,
+  impactType: "degraded",
+  transitive: false,
+  label: null,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  ...overrides,
+});
+
+const stubService = (existing: Dependency[] = []) => {
+  let store = [...existing];
+  const getDependencies = mock(
+    async ({
+      systemId,
+      direction,
+    }: {
+      systemId: string;
+      direction?: "upstream" | "downstream" | "both";
+    }) => {
+      if (direction === "upstream") {
+        return store.filter((d) => d.sourceSystemId === systemId);
+      }
+      if (direction === "downstream") {
+        return store.filter((d) => d.targetSystemId === systemId);
+      }
+      return store.filter(
+        (d) => d.sourceSystemId === systemId || d.targetSystemId === systemId,
+      );
+    },
+  );
+  const createDependency = mock(
+    async (input: {
+      sourceSystemId: string;
+      targetSystemId: string;
+      impactType: "informational" | "degraded" | "critical";
+      transitive?: boolean;
+      label?: string;
+    }) => {
+      const created = dep(
+        `dep-${store.length + 1}`,
+        input.sourceSystemId,
+        input.targetSystemId,
+        {
+          impactType: input.impactType,
+          transitive: input.transitive ?? false,
+          label: input.label ?? null,
+        },
+      );
+      store.push(created);
+      return created;
+    },
+  );
+  const updateDependency = mock(
+    async (input: {
+      id: string;
+      systemId: string;
+      impactType?: "informational" | "degraded" | "critical";
+      transitive?: boolean;
+      label?: string | null;
+    }) => {
+      store = store.map((d) =>
+        d.id === input.id
+          ? {
+              ...d,
+              impactType: input.impactType ?? d.impactType,
+              transitive: input.transitive ?? d.transitive,
+              label: input.label === undefined ? d.label : input.label,
+            }
+          : d,
+      );
+      return store.find((d) => d.id === input.id);
+    },
+  );
+  const deleteDependency = mock(async (id: string) => {
+    const before = store.length;
+    store = store.filter((d) => d.id !== id);
+    return store.length < before;
+  });
+  return {
+    getDependencies,
+    createDependency,
+    updateDependency,
+    deleteDependency,
+    service: {
+      getDependencies,
+      createDependency,
+      updateDependency,
+      deleteDependency,
+    } as unknown as DependencyService,
+    get current() {
+      return store;
+    },
+  };
+};
+
+describe("buildSystemDependenciesExtension", () => {
+  let stub: ReturnType<typeof stubService>;
+  let extension: ReturnType<typeof buildSystemDependenciesExtension>;
+
+  beforeEach(() => {
+    stub = stubService();
+    extension = buildSystemDependenciesExtension({
+      getService: () => stub.service,
+    });
+  });
+
+  it("registers under System kind, namespace 'dependencies'", () => {
+    expect(extension.kind).toBe("System");
+    expect(extension.namespace).toBe("dependencies");
+  });
+
+  it("creates declared dependencies on first sync", async () => {
+    await extension.reconcile({
+      entity: {} as never,
+      entityId: "sys-payments",
+      extensionSpec: [
+        {
+          targetRef: { kind: "System", name: "db" },
+          impactType: "critical",
+          transitive: false,
+        },
+        {
+          targetRef: { kind: "System", name: "cache" },
+          impactType: "degraded",
+          transitive: true,
+          label: "fast path",
+        },
+      ],
+      context: buildContext({
+        resolveEntityRef: refResolver({ db: "sys-db", cache: "sys-cache" }),
+      }),
+    });
+
+    expect(stub.createDependency).toHaveBeenCalledTimes(2);
+    expect(stub.createDependency).toHaveBeenNthCalledWith(1, {
+      sourceSystemId: "sys-payments",
+      targetSystemId: "sys-db",
+      impactType: "critical",
+      transitive: false,
+      label: undefined,
+      healthCheckRules: [],
+    });
+    expect(stub.createDependency).toHaveBeenNthCalledWith(2, {
+      sourceSystemId: "sys-payments",
+      targetSystemId: "sys-cache",
+      impactType: "degraded",
+      transitive: true,
+      label: "fast path",
+      healthCheckRules: [],
+    });
+  });
+
+  it("removes dependencies that are no longer declared", async () => {
+    stub = stubService([
+      dep("d1", "sys-payments", "sys-db"),
+      dep("d2", "sys-payments", "sys-cache"),
+    ]);
+    extension = buildSystemDependenciesExtension({
+      getService: () => stub.service,
+    });
+
+    await extension.reconcile({
+      entity: {} as never,
+      entityId: "sys-payments",
+      extensionSpec: [
+        {
+          targetRef: { kind: "System", name: "db" },
+          impactType: "degraded",
+          transitive: false,
+        },
+      ],
+      context: buildContext({
+        resolveEntityRef: refResolver({ db: "sys-db" }),
+      }),
+    });
+
+    expect(stub.deleteDependency).toHaveBeenCalledTimes(1);
+    expect(stub.deleteDependency).toHaveBeenCalledWith("d2");
+    expect(stub.createDependency).not.toHaveBeenCalled();
+  });
+
+  it("updates an existing edge when impactType, transitive, or label changes", async () => {
+    stub = stubService([
+      dep("d1", "sys-payments", "sys-db", {
+        impactType: "degraded",
+        transitive: false,
+        label: null,
+      }),
+    ]);
+    extension = buildSystemDependenciesExtension({
+      getService: () => stub.service,
+    });
+
+    await extension.reconcile({
+      entity: {} as never,
+      entityId: "sys-payments",
+      extensionSpec: [
+        {
+          targetRef: { kind: "System", name: "db" },
+          impactType: "critical",
+          transitive: true,
+          label: "primary",
+        },
+      ],
+      context: buildContext({
+        resolveEntityRef: refResolver({ db: "sys-db" }),
+      }),
+    });
+
+    expect(stub.updateDependency).toHaveBeenCalledWith({
+      id: "d1",
+      systemId: "sys-payments",
+      impactType: "critical",
+      transitive: true,
+      label: "primary",
+    });
+  });
+
+  it("is a no-op when an edge already matches the spec", async () => {
+    stub = stubService([
+      dep("d1", "sys-payments", "sys-db", {
+        impactType: "critical",
+        transitive: false,
+        label: null,
+      }),
+    ]);
+    extension = buildSystemDependenciesExtension({
+      getService: () => stub.service,
+    });
+
+    await extension.reconcile({
+      entity: {} as never,
+      entityId: "sys-payments",
+      extensionSpec: [
+        {
+          targetRef: { kind: "System", name: "db" },
+          impactType: "critical",
+          transitive: false,
+        },
+      ],
+      context: buildContext({
+        resolveEntityRef: refResolver({ db: "sys-db" }),
+      }),
+    });
+
+    expect(stub.updateDependency).not.toHaveBeenCalled();
+    expect(stub.createDependency).not.toHaveBeenCalled();
+    expect(stub.deleteDependency).not.toHaveBeenCalled();
+  });
+
+  it("treats an empty/undefined spec as 'remove all my upstream deps'", async () => {
+    stub = stubService([
+      dep("d1", "sys-payments", "sys-db"),
+      dep("d2", "sys-other", "sys-payments"), // downstream — must NOT be touched
+    ]);
+    extension = buildSystemDependenciesExtension({
+      getService: () => stub.service,
+    });
+
+    await extension.reconcile({
+      entity: {} as never,
+      entityId: "sys-payments",
+      extensionSpec: [],
+      context: buildContext(),
+    });
+
+    expect(stub.deleteDependency).toHaveBeenCalledTimes(1);
+    expect(stub.deleteDependency).toHaveBeenCalledWith("d1");
+  });
+
+  it("rejects refs that resolve to the source system itself", async () => {
+    await expect(
+      extension.reconcile({
+        entity: {} as never,
+        entityId: "sys-payments",
+        extensionSpec: [
+          {
+            targetRef: { kind: "System", name: "self" },
+            impactType: "degraded",
+            transitive: false,
+          },
+        ],
+        context: buildContext({
+          resolveEntityRef: refResolver({ self: "sys-payments" }),
+        }),
+      }),
+    ).rejects.toThrow(/cannot depend on itself/);
+  });
+
+  it("aborts the diff when a ref cannot be resolved (no mutations)", async () => {
+    stub = stubService([dep("d1", "sys-payments", "sys-db")]);
+    extension = buildSystemDependenciesExtension({
+      getService: () => stub.service,
+    });
+
+    await expect(
+      extension.reconcile({
+        entity: {} as never,
+        entityId: "sys-payments",
+        extensionSpec: [
+          {
+            targetRef: { kind: "System", name: "missing" },
+            impactType: "degraded",
+            transitive: false,
+          },
+        ],
+        context: buildContext({
+          resolveEntityRef: async () => undefined,
+        }),
+      }),
+    ).rejects.toThrow(/Cannot resolve System ref "missing"/);
+
+    expect(stub.deleteDependency).not.toHaveBeenCalled();
+    expect(stub.createDependency).not.toHaveBeenCalled();
+    expect(stub.updateDependency).not.toHaveBeenCalled();
+  });
+});

package/src/dependency-gitops-kinds.ts

@@ -0,0 +1,173 @@
+import { z } from "zod";
+import {
+  CHECKSTACK_API_VERSION,
+  type EntityKindExtensionDefinition,
+  type EntityKindRegistry,
+  type ReconcileContext,
+} from "@checkstack/gitops-common";
+import { ImpactTypeSchema } from "@checkstack/dependency-common";
+import type { DependencyService } from "./services/dependency-service";
+
+interface DependencyGitOpsKindsDeps {
+  /** Lazy accessor — populated during init(), invoked at reconcile time. */
+  getService: () => DependencyService;
+}
+
+// ─── System.dependencies extension ──────────────────────────────────────────
+//
+// Declares upstream dependencies for a System. GitOps is the source of truth:
+// the reconciler diffs the YAML-declared edges against the persisted ones for
+// this system and applies create/update/delete to converge.
+//
+// `targetRef` references another System by name; `kind` is constrained to the
+// literal "System" so the relationship is self-documenting.
+
+const systemRefSchema = z
+  .object({
+    kind: z.literal("System"),
+    name: z.string().min(1),
+  })
+  .describe("Reference to the upstream System this system depends on.");
+
+const dependencyEntrySchema = z.object({
+  targetRef: systemRefSchema,
+  impactType: ImpactTypeSchema.optional().default("degraded"),
+  transitive: z.boolean().optional().default(false),
+  label: z.string().optional(),
+});
+
+const systemDependenciesExtensionSchema = z
+  .array(dependencyEntrySchema)
+  .optional();
+
+type SystemDependenciesExtension = z.infer<
+  typeof systemDependenciesExtensionSchema
+>;
+
+const edgeKey = (sourceId: string, targetId: string) =>
+  `${sourceId}->${targetId}`;
+
+export function buildSystemDependenciesExtension(
+  deps: DependencyGitOpsKindsDeps,
+): EntityKindExtensionDefinition<SystemDependenciesExtension> {
+  return {
+    apiVersion: CHECKSTACK_API_VERSION,
+    kind: "System",
+    namespace: "dependencies",
+    specSchema: systemDependenciesExtensionSchema,
+
+    reconcile: async ({
+      extensionSpec,
+      entityId,
+      context,
+    }: {
+      extensionSpec: SystemDependenciesExtension;
+      entityId: string;
+      context: ReconcileContext;
+    }) => {
+      const service = deps.getService();
+      const sourceSystemId = entityId;
+      const desired = extensionSpec ?? [];
+
+      // Resolve all target refs up-front so a single bad ref aborts the diff
+      // before we mutate anything.
+      const resolved: Array<{
+        targetSystemId: string;
+        impactType: "informational" | "degraded" | "critical";
+        transitive: boolean;
+        label: string | null;
+      }> = [];
+      for (const entry of desired) {
+        const targetSystemId = await context.resolveEntityRef({
+          kind: entry.targetRef.kind,
+          entityName: entry.targetRef.name,
+        });
+        if (!targetSystemId) {
+          throw new Error(
+            `Cannot resolve System ref "${entry.targetRef.name}" — ensure the upstream system exists`,
+          );
+        }
+        if (targetSystemId === sourceSystemId) {
+          throw new Error(
+            `Dependency target "${entry.targetRef.name}" resolves to the same system as the source — a system cannot depend on itself`,
+          );
+        }
+        resolved.push({
+          targetSystemId,
+          impactType: entry.impactType,
+          transitive: entry.transitive,
+          label: entry.label ?? null,
+        });
+      }
+
+      // Existing edges where this system is the source (upstream deps).
+      const existing = await service.getDependencies({
+        systemId: sourceSystemId,
+        direction: "upstream",
+      });
+
+      const existingByTarget = new Map(
+        existing.map((dep) => [edgeKey(dep.sourceSystemId, dep.targetSystemId), dep]),
+      );
+      const desiredKeys = new Set(
+        resolved.map((r) => edgeKey(sourceSystemId, r.targetSystemId)),
+      );
+
+      // Remove edges that are no longer declared.
+      for (const [key, dep] of existingByTarget) {
+        if (!desiredKeys.has(key)) {
+          await service.deleteDependency(dep.id);
+          context.logger.info(
+            `GitOps: removed dependency ${dep.sourceSystemId} → ${dep.targetSystemId}`,
+          );
+        }
+      }
+
+      // Add or update declared edges.
+      for (const entry of resolved) {
+        const key = edgeKey(sourceSystemId, entry.targetSystemId);
+        const current = existingByTarget.get(key);
+        if (!current) {
+          await service.createDependency({
+            sourceSystemId,
+            targetSystemId: entry.targetSystemId,
+            impactType: entry.impactType,
+            transitive: entry.transitive,
+            label: entry.label ?? undefined,
+            healthCheckRules: [],
+          });
+          context.logger.info(
+            `GitOps: created dependency ${sourceSystemId} → ${entry.targetSystemId} (${entry.impactType})`,
+          );
+          continue;
+        }
+
+        const needsUpdate =
+          current.impactType !== entry.impactType ||
+          current.transitive !== entry.transitive ||
+          (current.label ?? null) !== entry.label;
+        if (needsUpdate) {
+          await service.updateDependency({
+            id: current.id,
+            systemId: sourceSystemId,
+            impactType: entry.impactType,
+            transitive: entry.transitive,
+            label: entry.label,
+          });
+          context.logger.info(
+            `GitOps: updated dependency ${sourceSystemId} → ${entry.targetSystemId}`,
+          );
+        }
+      }
+    },
+  };
+}
+
+export function registerDependencyGitOpsKinds({
+  kindRegistry,
+  ...deps
+}: DependencyGitOpsKindsDeps & {
+  kindRegistry: EntityKindRegistry;
+}): void {
+  kindRegistry.registerKindExtension(buildSystemDependenciesExtension(deps));
+}

package/src/index.ts

@@ -20,6 +20,8 @@ import { NotificationApi } from "@checkstack/notification-common";
 import { catalogHooks } from "@checkstack/catalog-backend";
 import { healthCheckHooks } from "@checkstack/healthcheck-backend";
 import { evaluateAndNotifyDownstream } from "./notifications";
+import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
+import { registerDependencyGitOpsKinds } from "./dependency-gitops-kinds";
 
 // =============================================================================
 // Plugin Definition
@@ -34,6 +36,18 @@ export default createBackendPlugin({
       dependencyGroupSubscription,
     ]);
 
+    // ─── GitOps Entity Kind Registration ─────────────────────────────
+    let gitopsService: DependencyService | undefined;
+    const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
+    registerDependencyGitOpsKinds({
+      kindRegistry,
+      getService: () => {
+        if (!gitopsService)
+          throw new Error("DependencyService not initialized");
+        return gitopsService;
+      },
+    });
+
     env.registerInit({
       schema,
       deps: {
@@ -51,6 +65,7 @@ export default createBackendPlugin({
         const service = new DependencyService(
           database as SafeDatabase<typeof schema>,
         );
+        gitopsService = service;
         const warningService = new WarningEvaluationService();
 
         const router = createRouter({

package/tsconfig.json

@@ -22,6 +22,12 @@
     {
       "path": "../drizzle-helper"
     },
+    {
+      "path": "../gitops-backend"
+    },
+    {
+      "path": "../gitops-common"
+    },
     {
       "path": "../healthcheck-backend"
     },