Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

6.4 KB
Raw Blame
// @vitest-environment node
import { describe, expect, test } from "vitest";
import {
  resolveGuide,
  validateGuideJourney,
  validateGuideJourneys,
} from "./resolve";
import type {
  GuideContext,
  GuideJourney,
  GuideStepDefinition,
  GuideStepId,
} from "./types";

const STEP_IDS: GuideStepId[] = [
  "create-project",
  "connect-instance",
  "explore-database",
  "query-data",
  "create-database-change",
  "mark-sensitive-data",
  "add-member",
];

const createContext = (
  overrides: Partial<GuideContext> = {}
): GuideContext => ({
  hasProject: false,
  hasInstance: false,
  hasExploredDatabase: false,
  hasRunStatement: false,
  hasCreatedChangeIssue: false,
  hasMarkedSensitiveData: false,
  isSaaS: false,
  hasOtherHumanUser: false,
  hasOtherWorkspaceMember: false,
  projectName: "",
  instanceName: "",
  databaseProjectName: "",
  databaseName: "",
  route: { name: "workspace.home", params: {} },
  ...overrides,
});

const completionById: Record<GuideStepId, keyof GuideContext> = {
  "create-project": "hasProject",
  "connect-instance": "hasInstance",
  "explore-database": "hasExploredDatabase",
  "query-data": "hasRunStatement",
  "create-database-change": "hasCreatedChangeIssue",
  "mark-sensitive-data": "hasMarkedSensitiveData",
  "add-member": "hasOtherWorkspaceMember",
};

const definition = (id: GuideStepId): GuideStepDefinition => ({
  id,
  labelKey: `label.${id}`,
  descriptionKey: `description.${id}`,
  isComplete: (context) => Boolean(context[completionById[id]]),
  matchesRoute: (route) => route.name === `route.${id}`,
  resolveActions: () => ({}),
});

const definitions = STEP_IDS.map(definition);

const generic: GuideJourney = {
  id: "workspace-setup",
  steps: [
    { stepId: "create-project" },
    { stepId: "connect-instance", dependsOn: ["create-project"] },
    { stepId: "explore-database", dependsOn: ["connect-instance"] },
  ],
};

const queryData: GuideJourney = {
  id: "query-data",
  scenarioId: "query-data",
  steps: [
    { stepId: "create-project", kind: "prerequisite" },
    {
      stepId: "connect-instance",
      kind: "prerequisite",
      dependsOn: ["create-project"],
    },
    {
      stepId: "explore-database",
      kind: "prerequisite",
      dependsOn: ["connect-instance"],
    },
    { stepId: "query-data", dependsOn: ["explore-database"] },
  ],
};

describe("validateGuideJourney", () => {
  test("accepts selected and generic graphs", () => {
    expect(() => validateGuideJourney(generic, definitions)).not.toThrow();
    expect(() => validateGuideJourney(queryData, definitions)).not.toThrow();
  });

  test.each([
    ["empty", { ...generic, steps: [] }, "at least one step"],
    [
      "duplicate",
      {
        ...generic,
        steps: [{ stepId: "create-project" }, { stepId: "create-project" }],
      },
      "duplicate step",
    ],
    [
      "unknown",
      { ...generic, steps: [{ stepId: "missing" as GuideStepId }] },
      "unregistered step",
    ],
    [
      "external dependency",
      {
        ...generic,
        steps: [{ stepId: "create-project", dependsOn: ["connect-instance"] }],
      },
      "dependency outside journey",
    ],
    [
      "self dependency",
      {
        ...generic,
        steps: [{ stepId: "create-project", dependsOn: ["create-project"] }],
      },
      "cannot depend on itself",
    ],
  ])("rejects an %s graph", (_name, journey, message) => {
    expect(() =>
      validateGuideJourney(journey as GuideJourney, definitions)
    ).toThrow(message);
  });

  test("rejects duplicate step definition ids", () => {
    expect(() =>
      validateGuideJourney(generic, [
        ...definitions,
        definition("create-project"),
      ])
    ).toThrow("duplicate step definition");
  });

  test("rejects duplicate journey ids", () => {
    expect(() =>
      validateGuideJourneys([generic, generic], definitions)
    ).toThrow("duplicate journey");
  });

  test("rejects duplicate step definitions", () => {
    expect(() =>
      validateGuideJourneys(
        [generic],
        [...definitions, definition("create-project")]
      )
    ).toThrow("duplicate step definition");
  });
});

describe("resolveGuide", () => {
  test("uses generic setup order and dependencies", () => {
    const guide = resolveGuide({
      journey: generic,
      definitions,
      context: createContext(),
    });
    expect(guide.steps.map((step) => step.definition.id)).toEqual([
      "create-project",
      "connect-instance",
      "explore-database",
    ]);
    expect(guide.activeStep?.definition.id).toBe("create-project");
  });

  test("keeps satisfied prerequisites visible", () => {
    const guide = resolveGuide({
      journey: queryData,
      definitions,
      context: createContext({
        hasProject: true,
        hasInstance: true,
        hasExploredDatabase: true,
      }),
    });
    expect(guide.steps.map((step) => step.definition.id)).toEqual([
      "create-project",
      "connect-instance",
      "explore-database",
      "query-data",
    ]);
    expect(guide.steps.slice(0, 3).every((step) => step.done)).toBe(true);
    expect(guide.activeStep?.definition.id).toBe("query-data");
  });

  test("shows the full chain and blocks on missing prerequisites", () => {
    const guide = resolveGuide({
      journey: queryData,
      definitions,
      context: createContext(),
    });
    expect(guide.steps.map((step) => step.definition.id)).toEqual([
      "create-project",
      "connect-instance",
      "explore-database",
      "query-data",
    ]);
    expect(guide.steps[1].blocked).toBe(true);
    expect(guide.steps[3].blocked).toBe(true);
  });

  test("allows a completed visible prerequisite to stay selected", () => {
    const guide = resolveGuide({
      journey: queryData,
      definitions,
      context: createContext({ hasProject: true }),
      selectedStepId: "create-project",
    });
    expect(guide.highlightedStep?.definition.id).toBe("create-project");
    expect(guide.actionStep?.definition.id).toBe("connect-instance");
  });

  test("returns completion without an active action", () => {
    const guide = resolveGuide({
      journey: queryData,
      definitions,
      context: createContext({
        hasProject: true,
        hasInstance: true,
        hasExploredDatabase: true,
        hasRunStatement: true,
      }),
    });
    expect(guide.complete).toBe(true);
    expect(guide.activeStep).toBeUndefined();
    expect(guide.actionStep).toBeUndefined();
  });
});