Ekklesia/surfaces/shell/tests/dashboard-routes.test.ts

// @vitest-environment node
import { readFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { describe, expect, it } from "vitest";
import {
  DASHBOARD_PAGE_PREFIXES,
  dashboardPath,
  isDashboardPagePath,
  parseDashboardPath,
} from "../src/dashboard-routes.js";

const packageDirectory = path.dirname(path.dirname(fileURLToPath(import.meta.url)));

describe("the Dashboard URL space", () => {
  it("reserves exactly the platform's page namespaces, frozen", () => {
    expect(Object.isFrozen(DASHBOARD_PAGE_PREFIXES)).toBe(true);
    expect(DASHBOARD_PAGE_PREFIXES).toEqual(["/modules", "/settings", "/account"]);
  });

  it("never reserves a namespace the API, display host, or host assets already own", () => {
    for (const prefix of DASHBOARD_PAGE_PREFIXES) {
      for (const owned of ["/api", "/display", "/assets"]) {
        expect(prefix === owned || prefix.startsWith(`${owned}/`), prefix).toBe(false);
        expect(owned.startsWith(`${prefix}/`), prefix).toBe(false);
      }
    }
  });

  it("recognizes the root and every path inside a reserved namespace as a Dashboard page", () => {
    for (const pathname of [
      "/",
      "/modules",
      "/modules/",
      "/modules/signage",
      "/modules/signage/timelines/abc",
      "/settings",
      "/settings/displays/add",
      "/account",
      "/account/appearance",
    ]) {
      expect(isDashboardPagePath(pathname), pathname).toBe(true);
    }
  });

  it("does not claim anything outside them, including look-alike prefixes", () => {
    for (const pathname of [
      "",
      "/api/v1/principal",
      "/display/signage",
      "/assets/ekklesia-dashboard/app.js",
      "/modulesx",
      "/settings-old",
      "/accounts",
      "/index.html",
      "/login",
      "modules/signage",
    ]) {
      expect(isDashboardPagePath(pathname), pathname).toBe(false);
    }
  });
});

describe("parseDashboardPath", () => {
  it("makes the root the Overview", () => {
    expect(parseDashboardPath("/")).toEqual({ kind: "overview" });
  });

  it("names a module page by its id, tolerating one trailing slash", () => {
    expect(parseDashboardPath("/modules/signage")).toEqual({
      kind: "module",
      moduleId: "signage",
    });
    expect(parseDashboardPath("/modules/signage/")).toEqual({
      kind: "module",
      moduleId: "signage",
    });
  });

  it("decodes a percent-encoded segment, so an id is compared as the server spells it", () => {
    expect(parseDashboardPath("/modules/sign%61ge")).toEqual({
      kind: "module",
      moduleId: "signage",
    });
  });

  it("treats every other shape as not found rather than guessing", () => {
    for (const pathname of [
      "",
      "/modules",
      "/modules/",
      "/modules//",
      "//modules/signage",
      "/modules/signage//",
      // A module's own sub-pages need a contract that does not exist yet (ADR 0057).
      "/modules/signage/timelines",
      "/modules/%E0%A4%A",
      "/settings",
      "/settings/displays",
      "/account",
      "/overview",
      "/index.html",
    ]) {
      expect(parseDashboardPath(pathname), pathname).toEqual({ kind: "not-found" });
    }
  });
});

describe("dashboardPath", () => {
  it("spells each route canonically", () => {
    expect(dashboardPath({ kind: "overview" })).toBe("/");
    expect(dashboardPath({ kind: "module", moduleId: "signage" })).toBe("/modules/signage");
  });

  it("encodes a module id so it can never escape its own segment", () => {
    expect(dashboardPath({ kind: "module", moduleId: "a/../b" })).toBe("/modules/a%2F..%2Fb");
    expect(parseDashboardPath(dashboardPath({ kind: "module", moduleId: "a/../b" }))).toEqual({
      kind: "module",
      moduleId: "a/../b",
    });
  });

  it("round-trips through the parser", () => {
    for (const route of [
      { kind: "overview" } as const,
      { kind: "module", moduleId: "example" } as const,
    ]) {
      expect(parseDashboardPath(dashboardPath(route))).toEqual(route);
      expect(isDashboardPagePath(dashboardPath(route))).toBe(true);
    }
  });
});

describe("the route locator is published for the API that serves the page", () => {
  it("is a narrow package subpath, not the shell root barrel", async () => {
    const manifest = JSON.parse(
      await readFile(path.join(packageDirectory, "package.json"), "utf8"),
    ) as { exports?: Record<string, unknown> };
    expect(manifest.exports?.["./dashboard-routes"]).toEqual({
      import: "./dist/dashboard-routes.js",
      types: "./dist/dashboard-routes.d.ts",
    });
  });
});