@checkstack/dependency-backend 0.2.0

package/src/services/dependency-service.ts

@@ -0,0 +1,376 @@
+import { eq, or, and, inArray } from "drizzle-orm";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import * as schema from "../schema";
+import {
+  dependencies,
+  dependencyHealthCheckRules,
+  nodePositions,
+} from "../schema";
+import type {
+  Dependency,
+  CreateDependencyInput,
+  UpdateDependencyInput,
+  NodePosition,
+} from "@checkstack/dependency-common";
+
+type Db = SafeDatabase<typeof schema>;
+
+function generateId(): string {
+  return crypto.randomUUID();
+}
+
+export class DependencyService {
+  constructor(private db: Db) {}
+
+  /**
+   * Get all dependencies for a system in the specified direction.
+   */
+  async getDependencies({
+    systemId,
+    direction = "both",
+  }: {
+    systemId: string;
+    direction?: "upstream" | "downstream" | "both";
+  }): Promise<Dependency[]> {
+    let condition;
+    if (direction === "upstream") {
+      condition = eq(dependencies.sourceSystemId, systemId);
+    } else if (direction === "downstream") {
+      condition = eq(dependencies.targetSystemId, systemId);
+    } else {
+      condition = or(
+        eq(dependencies.sourceSystemId, systemId),
+        eq(dependencies.targetSystemId, systemId),
+      );
+    }
+
+    const rows = await this.db.select().from(dependencies).where(condition);
+    return this.enrichWithRules(rows);
+  }
+
+  /**
+   * Get all dependencies in the system (for the canvas).
+   */
+  async getAllDependencies(): Promise<Dependency[]> {
+    const rows = await this.db.select().from(dependencies);
+    return this.enrichWithRules(rows);
+  }
+
+  /**
+   * Create a new dependency with cycle detection.
+   * Throws if the dependency would create a circular chain.
+   */
+  async createDependency(input: CreateDependencyInput): Promise<Dependency> {
+    // Check for duplicate edge
+    const [existing] = await this.db
+      .select()
+      .from(dependencies)
+      .where(
+        and(
+          eq(dependencies.sourceSystemId, input.sourceSystemId),
+          eq(dependencies.targetSystemId, input.targetSystemId),
+        ),
+      );
+
+    if (existing) {
+      throw new Error(
+        `Dependency already exists between ${input.sourceSystemId} and ${input.targetSystemId}`,
+      );
+    }
+
+    // Cycle detection: check if adding this edge would create a cycle
+    const cyclePath = await this.detectCycle({
+      sourceSystemId: input.sourceSystemId,
+      targetSystemId: input.targetSystemId,
+    });
+
+    if (cyclePath) {
+      throw new Error(
+        `Cannot create dependency: would form a circular chain: ${cyclePath.join(" → ")}`,
+      );
+    }
+
+    const id = generateId();
+    await this.db.insert(dependencies).values({
+      id,
+      sourceSystemId: input.sourceSystemId,
+      targetSystemId: input.targetSystemId,
+      impactType: input.impactType,
+      transitive: input.transitive ?? false,
+      // eslint-disable-next-line unicorn/no-null -- Drizzle SQL column is nullable
+      label: input.label ?? null,
+    });
+
+    // Create health check rules if provided
+    if (input.healthCheckRules && input.healthCheckRules.length > 0) {
+      for (const rule of input.healthCheckRules) {
+        await this.db.insert(dependencyHealthCheckRules).values({
+          id: generateId(),
+          dependencyId: id,
+          healthCheckId: rule.healthCheckId,
+          overrideImpactType: rule.overrideImpactType,
+        });
+      }
+    }
+
+    const result = await this.getDependencyById(id);
+    if (!result) {
+      throw new Error("Failed to create dependency");
+    }
+    return result;
+  }
+
+  /**
+   * Update an existing dependency.
+   */
+  async updateDependency(
+    input: UpdateDependencyInput,
+  ): Promise<Dependency | undefined> {
+    const [existing] = await this.db
+      .select()
+      .from(dependencies)
+      .where(eq(dependencies.id, input.id));
+
+    if (!existing) return undefined;
+
+    const updateData: Partial<typeof dependencies.$inferInsert> = {
+      updatedAt: new Date(),
+    };
+    if (input.impactType !== undefined) updateData.impactType = input.impactType;
+    if (input.transitive !== undefined) updateData.transitive = input.transitive;
+    if (input.label !== undefined) updateData.label = input.label;
+
+    await this.db
+      .update(dependencies)
+      .set(updateData)
+      .where(eq(dependencies.id, input.id));
+
+    // Replace health check rules if provided
+    if (input.healthCheckRules !== undefined) {
+      await this.db
+        .delete(dependencyHealthCheckRules)
+        .where(eq(dependencyHealthCheckRules.dependencyId, input.id));
+
+      for (const rule of input.healthCheckRules) {
+        await this.db.insert(dependencyHealthCheckRules).values({
+          id: generateId(),
+          dependencyId: input.id,
+          healthCheckId: rule.healthCheckId,
+          overrideImpactType: rule.overrideImpactType,
+        });
+      }
+    }
+
+    return this.getDependencyById(input.id);
+  }
+
+  /**
+   * Delete a dependency.
+   */
+  async deleteDependency(id: string): Promise<boolean> {
+    const [existing] = await this.db
+      .select()
+      .from(dependencies)
+      .where(eq(dependencies.id, id));
+
+    if (!existing) return false;
+
+    // Cascade delete handles health check rules
+    await this.db.delete(dependencies).where(eq(dependencies.id, id));
+    return true;
+  }
+
+  /**
+   * Remove all dependencies referencing a system (both as source and target).
+   * Called when a system is deleted from the catalog.
+   */
+  async removeSystemDependencies(systemId: string): Promise<void> {
+    await this.db
+      .delete(dependencies)
+      .where(
+        or(
+          eq(dependencies.sourceSystemId, systemId),
+          eq(dependencies.targetSystemId, systemId),
+        ),
+      );
+  }
+
+  /**
+   * Get a single dependency by ID with health check rules.
+   */
+  async getDependencyById(id: string): Promise<Dependency | undefined> {
+    const [row] = await this.db
+      .select()
+      .from(dependencies)
+      .where(eq(dependencies.id, id));
+
+    if (!row) return undefined;
+
+    const rules = await this.db
+      .select()
+      .from(dependencyHealthCheckRules)
+      .where(eq(dependencyHealthCheckRules.dependencyId, id));
+
+    return {
+      ...row,
+      // eslint-disable-next-line unicorn/no-null -- Drizzle SQL column is nullable
+      label: row.label ?? null,
+      healthCheckRules: rules.length > 0 ? rules : undefined,
+    };
+  }
+
+  // ===========================================================================
+  // NODE POSITIONS
+  // ===========================================================================
+
+  /**
+   * Get saved node positions for a user.
+   */
+  async getNodePositions(userId: string): Promise<NodePosition[]> {
+    const rows = await this.db
+      .select()
+      .from(nodePositions)
+      .where(eq(nodePositions.userId, userId));
+
+    return rows.map((r) => ({
+      systemId: r.systemId,
+      x: r.x,
+      y: r.y,
+    }));
+  }
+
+  /**
+   * Save node positions for a user (replace all).
+   */
+  async saveNodePositions({
+    userId,
+    positions,
+  }: {
+    userId: string;
+    positions: NodePosition[];
+  }): Promise<void> {
+    // Delete existing positions for this user
+    await this.db
+      .delete(nodePositions)
+      .where(eq(nodePositions.userId, userId));
+
+    // Insert new positions
+    for (const pos of positions) {
+      await this.db.insert(nodePositions).values({
+        id: generateId(),
+        userId,
+        systemId: pos.systemId,
+        x: pos.x,
+        y: pos.y,
+      });
+    }
+  }
+
+  // ===========================================================================
+  // CYCLE DETECTION
+  // ===========================================================================
+
+  /**
+   * Detect if adding an edge from source → target would create a cycle.
+   * Uses DFS from the target system following existing edges.
+   * Returns the cycle path if found, or undefined if safe.
+   */
+  async detectCycle({
+    sourceSystemId,
+    targetSystemId,
+  }: {
+    sourceSystemId: string;
+    targetSystemId: string;
+  }): Promise<string[] | undefined> {
+    // Load all edges for traversal
+    const allEdges = await this.db
+      .select({
+        sourceSystemId: dependencies.sourceSystemId,
+        targetSystemId: dependencies.targetSystemId,
+      })
+      .from(dependencies);
+
+    // Build adjacency map: for each system, which systems does it depend on (upstream)?
+    // Edge direction: source depends on target, so source → target
+    // To detect cycles, we follow: target → (what depends on target as its upstream)
+    // i.e., we need to check: can we reach sourceSystemId by following edges from targetSystemId?
+    // An edge (A, B) means A depends on B. If we're adding (source, target),
+    // we need to check if following existing edges from source as a target,
+    // we can reach target. More precisely: does target already transitively depend on source?
+
+    // Build: for each node, what are its upstream dependencies (targetSystemId values)?
+    const upstreamMap = new Map<string, string[]>();
+    for (const edge of allEdges) {
+      const existing = upstreamMap.get(edge.sourceSystemId) ?? [];
+      existing.push(edge.targetSystemId);
+      upstreamMap.set(edge.sourceSystemId, existing);
+    }
+
+    // DFS: starting from targetSystemId, follow its upstream dependencies
+    // If we reach sourceSystemId, there's a cycle
+    const visited = new Set<string>();
+    const path: string[] = [sourceSystemId, targetSystemId];
+
+    const dfs = (current: string): string[] | undefined => {
+      if (current === sourceSystemId) {
+        return path;
+      }
+
+      if (visited.has(current)) {
+        return undefined;
+      }
+      visited.add(current);
+
+      const upstreams = upstreamMap.get(current) ?? [];
+      for (const upstream of upstreams) {
+        path.push(upstream);
+        const result = dfs(upstream);
+        if (result) return result;
+        path.pop();
+      }
+
+      return undefined;
+    };
+
+    return dfs(targetSystemId);
+  }
+
+  // ===========================================================================
+  // HELPERS
+  // ===========================================================================
+
+  /**
+   * Enrich dependency rows with their health check rules.
+   */
+  private async enrichWithRules(
+    rows: (typeof dependencies.$inferSelect)[],
+  ): Promise<Dependency[]> {
+    if (rows.length === 0) return [];
+
+    const ids = rows.map((r) => r.id);
+    const allRules = await this.db
+      .select()
+      .from(dependencyHealthCheckRules)
+      .where(inArray(dependencyHealthCheckRules.dependencyId, ids));
+
+    const rulesByDep = new Map<
+      string,
+      (typeof dependencyHealthCheckRules.$inferSelect)[]
+    >();
+    for (const rule of allRules) {
+      const existing = rulesByDep.get(rule.dependencyId) ?? [];
+      existing.push(rule);
+      rulesByDep.set(rule.dependencyId, existing);
+    }
+
+    return rows.map((row) => {
+      const rules = rulesByDep.get(row.id);
+      return {
+        ...row,
+        // eslint-disable-next-line unicorn/no-null -- Drizzle SQL column is nullable
+        label: row.label ?? null,
+        healthCheckRules: rules && rules.length > 0 ? rules : undefined,
+      };
+    });
+  }
+}

package/src/services/warning-evaluation-service.ts

@@ -0,0 +1,305 @@
+import type {
+  Dependency,
+  DependencyWarning,
+  DerivedState,
+  ImpactType,
+} from "@checkstack/dependency-common";
+
+/**
+ * Upstream system status as reported by the platform.
+ */
+export interface SystemStatus {
+  systemId: string;
+  systemName: string;
+  /** Overall system status: operational, degraded, or down */
+  status: "operational" | "degraded" | "down";
+  /** Per-health-check statuses (for advanced rules) */
+  healthCheckStatuses?: Array<{
+    healthCheckId: string;
+    status: "healthy" | "degraded" | "unhealthy";
+  }>;
+}
+
+/**
+ * Evaluates derived dependency warnings based on system statuses.
+ * This is a pure computation engine — it does not fetch data itself.
+ */
+export class WarningEvaluationService {
+  /**
+   * Evaluate dependency warnings for a set of systems.
+   *
+   * @param systemIds - The systems to evaluate
+   * @param allDependencies - All dependency edges in the system
+   * @param systemStatuses - Current status of all referenced systems
+   * @returns Map of systemId → DependencyWarning (only for systems with warnings)
+   */
+  evaluateWarnings({
+    systemIds,
+    allDependencies,
+    systemStatuses,
+  }: {
+    systemIds: string[];
+    allDependencies: Dependency[];
+    systemStatuses: Map<string, SystemStatus>;
+  }): Map<string, DependencyWarning> {
+    const warnings = new Map<string, DependencyWarning>();
+
+    for (const systemId of systemIds) {
+      const warning = this.evaluateSystem({
+        systemId,
+        allDependencies,
+        systemStatuses,
+        visited: new Set<string>(),
+      });
+
+      if (warning) {
+        warnings.set(systemId, warning);
+      }
+    }
+
+    return warnings;
+  }
+
+  /**
+   * Evaluate a single system's dependency warning.
+   */
+  evaluateSystem({
+    systemId,
+    allDependencies,
+    systemStatuses,
+    visited,
+  }: {
+    systemId: string;
+    allDependencies: Dependency[];
+    systemStatuses: Map<string, SystemStatus>;
+    visited: Set<string>;
+  }): DependencyWarning | undefined {
+    // Cycle guard: prevent infinite loops in transitive evaluation
+    if (visited.has(systemId)) {
+      return undefined;
+    }
+    visited.add(systemId);
+
+    // Find all dependencies where this system is the source (downstream)
+    const upstreamDeps = allDependencies.filter(
+      (d) => d.sourceSystemId === systemId,
+    );
+
+    if (upstreamDeps.length === 0) {
+      return undefined;
+    }
+
+    let worstDerivedState: DerivedState | undefined;
+    const affectedUpstreams: DependencyWarning["affectedUpstreams"] = [];
+
+    for (const dep of upstreamDeps) {
+      const upstreamStatus = systemStatuses.get(dep.targetSystemId);
+      if (!upstreamStatus) continue;
+
+      // Determine the effective upstream status
+      let effectiveStatus = upstreamStatus.status;
+
+      // For transitive dependencies, consider the upstream's own derived warnings
+      if (dep.transitive) {
+        const upstreamWarning = this.evaluateSystem({
+          systemId: dep.targetSystemId,
+          allDependencies,
+          systemStatuses,
+          visited: new Set(visited), // Fresh copy to allow fan-out
+        });
+
+        if (upstreamWarning) {
+          // Promote the effective status based on upstream's worst warning
+          effectiveStatus = this.promoteStatus({
+            ownStatus: effectiveStatus,
+            warningState: upstreamWarning.derivedState,
+          });
+        }
+      }
+
+      // Evaluate impact based on the dependency configuration
+      const derivedState = this.evaluateDependencyImpact({
+        dependency: dep,
+        upstreamStatus: effectiveStatus,
+        upstreamHealthChecks: upstreamStatus.healthCheckStatuses,
+      });
+
+      if (derivedState) {
+        affectedUpstreams.push({
+          systemId: dep.targetSystemId,
+          systemName: upstreamStatus.systemName,
+          ownStatus: effectiveStatus,
+          impactType: dep.impactType,
+          dependencyLabel: dep.label,
+        });
+
+        worstDerivedState = this.worstState(worstDerivedState, derivedState);
+      }
+    }
+
+    if (!worstDerivedState || affectedUpstreams.length === 0) {
+      return undefined;
+    }
+
+    return {
+      systemId,
+      derivedState: worstDerivedState,
+      affectedUpstreams,
+    };
+  }
+
+  /**
+   * Evaluate the impact of a single dependency based on upstream status.
+   * Returns the derived state, or undefined if no impact.
+   */
+  private evaluateDependencyImpact({
+    dependency,
+    upstreamStatus,
+    upstreamHealthChecks,
+  }: {
+    dependency: Dependency;
+    upstreamStatus: "operational" | "degraded" | "down";
+    upstreamHealthChecks?: Array<{
+      healthCheckId: string;
+      status: "healthy" | "degraded" | "unhealthy";
+    }>;
+  }): DerivedState | undefined {
+    // If upstream is operational, no impact
+    if (upstreamStatus === "operational") {
+      return undefined;
+    }
+
+    // If the dependency has health check rules, evaluate those instead
+    if (
+      dependency.healthCheckRules &&
+      dependency.healthCheckRules.length > 0 &&
+      upstreamHealthChecks
+    ) {
+      return this.evaluateHealthCheckRules({
+        rules: dependency.healthCheckRules,
+        healthCheckStatuses: upstreamHealthChecks,
+      });
+    }
+
+    // Apply the impact matrix based on overall status
+    return this.applyImpactMatrix({
+      impactType: dependency.impactType,
+      upstreamStatus,
+    });
+  }
+
+  /**
+   * Evaluate health check rules for a dependency.
+   * Returns the worst derived state from matching rules, or undefined.
+   */
+  private evaluateHealthCheckRules({
+    rules,
+    healthCheckStatuses,
+  }: {
+    rules: NonNullable<Dependency["healthCheckRules"]>;
+    healthCheckStatuses: Array<{
+      healthCheckId: string;
+      status: "healthy" | "degraded" | "unhealthy";
+    }>;
+  }): DerivedState | undefined {
+    let worstState: DerivedState | undefined;
+
+    for (const rule of rules) {
+      const checkStatus = healthCheckStatuses.find(
+        (s) => s.healthCheckId === rule.healthCheckId,
+      );
+
+      // If the check is not found or is healthy, skip
+      if (!checkStatus || checkStatus.status === "healthy") continue;
+
+      // Map health check status to upstream status equivalent
+      const upstreamEquivalent =
+        checkStatus.status === "unhealthy" ? "down" : "degraded";
+
+      const state = this.applyImpactMatrix({
+        impactType: rule.overrideImpactType,
+        upstreamStatus: upstreamEquivalent,
+      });
+
+      if (state) {
+        worstState = this.worstState(worstState, state);
+      }
+    }
+
+    return worstState;
+  }
+
+  /**
+   * Apply the impact matrix to determine derived state.
+   *
+   * | Impact Type   | Upstream degraded  | Upstream down      |
+   * |---------------|--------------------|--------------------|
+   * | informational | info               | info               |
+   * | degraded      | degraded           | degraded           |
+   * | critical      | degraded           | down               |
+   */
+  private applyImpactMatrix({
+    impactType,
+    upstreamStatus,
+  }: {
+    impactType: ImpactType;
+    upstreamStatus: "degraded" | "down";
+  }): DerivedState {
+    switch (impactType) {
+      case "informational": {
+        return "info";
+      }
+      case "degraded": {
+        return "degraded";
+      }
+      case "critical": {
+        return upstreamStatus === "down" ? "down" : "degraded";
+      }
+    }
+  }
+
+  /**
+   * Promote a system's own status based on its upstream warning state.
+   * Used for transitive evaluation.
+   */
+  private promoteStatus({
+    ownStatus,
+    warningState,
+  }: {
+    ownStatus: "operational" | "degraded" | "down";
+    warningState: DerivedState;
+  }): "operational" | "degraded" | "down" {
+    const statusOrder: Record<string, number> = {
+      operational: 0,
+      info: 0, // info doesn't change the status
+      degraded: 1,
+      down: 2,
+    };
+
+    const ownLevel = statusOrder[ownStatus] ?? 0;
+    const warningLevel = statusOrder[warningState] ?? 0;
+
+    if (warningLevel > ownLevel) {
+      return warningState === "down" ? "down" : "degraded";
+    }
+    return ownStatus;
+  }
+
+  /**
+   * Return the worst of two derived states.
+   */
+  private worstState(
+    a: DerivedState | undefined,
+    b: DerivedState,
+  ): DerivedState {
+    if (!a) return b;
+
+    const order: Record<DerivedState, number> = {
+      info: 0,
+      degraded: 1,
+      down: 2,
+    };
+
+    return order[a] >= order[b] ? a : b;
+  }
+}