Ekklesia/tests/public-packages.test.ts

import { readdir, readFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { describe, expect, it } from "vitest";
import { parse } from "yaml";
import {
  PUBLIC_PACKAGE_DISTRIBUTION,
  PUBLIC_PACKAGES,
  packedManifestProblems,
  tarballFileProblems,
} from "../scripts/pack-public-packages.js";

/**
 * The public module-development package boundary (ADR 0053): which packages may be published, what
 * their manifests may say, and what the author-facing SDK exposes. The tarballs themselves are
 * inspected by `pnpm packages:pack` and installed into a standalone module by
 * `scripts/test-standalone-module.sh`.
 */

const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");

type Manifest = Record<string, unknown> & {
  name: string;
  version: string;
  private?: boolean;
  scripts?: Record<string, string>;
  dependencies?: Record<string, string>;
  peerDependencies?: Record<string, string>;
  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
  optionalDependencies?: Record<string, string>;
  devDependencies?: Record<string, string>;
  ekklesia?: Record<string, unknown>;
  files?: string[];
};

async function readJson<T = Manifest>(file: string): Promise<T> {
  return JSON.parse(await readFile(path.join(repositoryRoot, file), "utf8")) as T;
}

async function workspacePackages(): Promise<
  Map<string, { directory: string; manifest: Manifest }>
> {
  const workspace = parse(await readFile(path.join(repositoryRoot, "pnpm-workspace.yaml"), "utf8"));
  const packages = new Map<string, { directory: string; manifest: Manifest }>();
  for (const pattern of workspace.packages as string[]) {
    const directories = pattern.endsWith("/*")
      ? (
          await readdir(path.join(repositoryRoot, pattern.slice(0, -2)), {
            withFileTypes: true,
          }).catch(() => [])
        )
          .filter((entry) => entry.isDirectory())
          .map((entry) => `${pattern.slice(0, -2)}/${entry.name}`)
      : [pattern];
    for (const directory of directories) {
      const manifest = await readJson(`${directory}/package.json`).catch(() => undefined);
      if (manifest) packages.set(manifest.name, { directory, manifest });
    }
  }
  return packages;
}

describe("the public package set", () => {
  it("is exactly the packages that carry the distribution marker, and nothing else is publishable", async () => {
    const packages = await workspacePackages();
    const publicNames = new Set(PUBLIC_PACKAGES.map((entry) => entry.name));
    for (const entry of PUBLIC_PACKAGES) {
      expect(packages.get(entry.name)?.directory, entry.name).toBe(entry.directory);
    }
    for (const [name, { manifest }] of packages) {
      const marked = manifest.ekklesia?.distribution === PUBLIC_PACKAGE_DISTRIBUTION;
      expect(marked, name).toBe(publicNames.has(name));
      // Internal packages stay private, so no publish can ever take them by accident.
      expect(manifest.private === true, name).toBe(!publicNames.has(name));
    }
    expect(packages.get("@ekklesia/core")?.manifest.private).toBe(true);
    expect(packages.get("@ekklesia/module-ui-host")?.manifest.private).toBe(true);
    expect(packages.get("@ekklesia/module-template")?.manifest.private).toBe(true);
  });

  it("uses one coordinated version, and depends only on other public packages through the workspace", async () => {
    const platformVersion = (await readJson("package.json")).version;
    const publicNames = new Set(PUBLIC_PACKAGES.map((entry) => entry.name));
    for (const entry of PUBLIC_PACKAGES) {
      const manifest = await readJson(`${entry.directory}/package.json`);
      expect(manifest.version, entry.name).toBe(platformVersion);
      expect(manifest.license, entry.name).toBe("AGPL-3.0-or-later");
      for (const field of ["dependencies", "peerDependencies", "optionalDependencies"] as const) {
        for (const [name, range] of Object.entries(manifest[field] ?? {})) {
          if (!name.startsWith("@ekklesia/")) continue;
          expect(publicNames.has(name), `${entry.name} ${field} ${name}`).toBe(true);
          // `pnpm pack` turns this into the exact coordinated version.
          expect(range, `${entry.name} ${field} ${name}`).toBe("workspace:*");
        }
      }
    }
  });

  it("runs no monorepo-root command, or any other script, when a consumer installs or packs it", async () => {
    for (const entry of PUBLIC_PACKAGES) {
      const manifest = await readJson(`${entry.directory}/package.json`);
      for (const script of ["preinstall", "install", "postinstall", "prepare", "prepack"]) {
        expect(manifest.scripts?.[script], `${entry.name} ${script}`).toBeUndefined();
      }
      expect(JSON.stringify(manifest.scripts ?? {}), entry.name).not.toContain("--workspace-root");
    }
  });

  it("keeps module-pack's own LICENSE identical to the repository's", async () => {
    // pnpm adds the workspace LICENSE to a tarball only when no packed path looks like a licence, and
    // module-pack ships `licenses/` and `license-supplements/`, so it carries its own copy.
    expect(await readFile(path.join(repositoryRoot, "packages/module-pack/LICENSE"))).toEqual(
      await readFile(path.join(repositoryRoot, "LICENSE")),
    );
  });
});

describe("the curated Module SDK", () => {
  async function sdkExports(): Promise<string[]> {
    const source = await readFile(
      path.join(repositoryRoot, "packages/module-sdk/src/index.ts"),
      "utf8",
    );
    expect(source).not.toMatch(/export\s*\*/u);
    const names: string[] = [];
    for (const block of source.matchAll(/export\s+(?:type\s+)?\{([^}]*)\}/gu)) {
      for (const item of (block[1] ?? "").split(",")) {
        const name = item
          .replace(/^\s*type\s+/u, "")
          .split(/\s+as\s+/u)
          .pop()
          ?.trim();
        if (name) names.push(name);
      }
    }
    return names.sort();
  }

  it("exposes the author API only", async () => {
    const names = await sdkExports();
    expect(names).toContain("defineModuleRuntime");
    expect(names).toContain("ModuleRouteHandlerContext");
    expect(names).toContain("parseModuleManifest");
    for (const name of names) {
      // No identity or authorization internals, no Drizzle, and no legacy database facade.
      expect(name).not.toMatch(
        /Authoriz|Permission(?:Grant|Decision)|Identity|Session|Credential|Drizzle(?!MigrationJournal)|^ModuleDatabase$|^ModuleSchemaDefinition$|defineModuleSchema|createModuleTable|^parseEkklesia/u,
      );
    }
  });

  it("does not make Drizzle a dependency of a module that does not use it", async () => {
    const sdk = await readJson("packages/module-sdk/package.json");
    expect(Object.keys(sdk.dependencies ?? {})).toEqual(["@ekklesia/contracts"]);
    expect(sdk.peerDependencies ?? {}).toEqual({});
    // Everything the SDK installs: Drizzle is at most an optional peer, and no runtime path reaches it.
    for (const name of ["contracts", "module-database"]) {
      const manifest = await readJson(`packages/${name}/package.json`);
      expect(manifest.dependencies?.["drizzle-orm"], name).toBeUndefined();
      expect(manifest.optionalDependencies?.["drizzle-orm"], name).toBeUndefined();
      if (manifest.peerDependencies?.["drizzle-orm"]) {
        expect(manifest.peerDependenciesMeta?.["drizzle-orm"]?.optional, name).toBe(true);
      }
    }
    const contractsSource = path.join(repositoryRoot, "packages/contracts/src");
    for (const file of await readdir(contractsSource)) {
      // Not even a type: the legacy facade's Drizzle type and schema validator are Core's own, so no
      // declaration a consumer type-checks names Drizzle.
      const source = await readFile(path.join(contractsSource, file), "utf8");
      expect(source, file).not.toMatch(/from\s+"drizzle-orm|import\(\s*"drizzle-orm/u);
    }
    const contracts = await readJson("packages/contracts/package.json");
    expect(Object.keys(contracts.exports as object)).toEqual([".", "./module-package"]);
    for (const field of [
      "dependencies",
      "peerDependencies",
      "optionalDependencies",
      "devDependencies",
    ] as const) {
      expect(contracts[field]?.["drizzle-orm"], field).toBeUndefined();
    }
  });
});

describe("module authors' dependencies", () => {
  it("never name @ekklesia/contracts directly", async () => {
    const template = await readJson("templates/module/package.json");
    const fixture = await readJson("tests/fixtures/standalone-module/package.json");
    for (const manifest of [template, fixture]) {
      expect(JSON.stringify(manifest), manifest.name).not.toContain("@ekklesia/contracts");
    }
    const guide = await readFile(
      path.join(repositoryRoot, "docs/module-development/README.md"),
      "utf8",
    );
    // Never shown as a dependency to add, and stated not to be one.
    expect(guide).not.toMatch(/"@ekklesia\/contracts"\s*:/u);
    expect(guide).toContain("`@ekklesia/contracts` is not a direct dependency.");
  });

  it("type-check every published declaration in the standalone fixture", async () => {
    // skipLibCheck would hide a declaration naming a package the module never installed.
    for (const project of ["tsconfig.json", "tsconfig.ui.json"]) {
      const config = await readJson<{ compilerOptions: { skipLibCheck?: boolean } }>(
        `tests/fixtures/standalone-module/${project}`,
      );
      expect(config.compilerOptions.skipLibCheck, project).toBe(false);
    }
  });

  it("pin module-pack exactly and declare engines.node in the standalone fixture", async () => {
    const fixture = await readJson("tests/fixtures/standalone-module/package.json");
    const devDependencies = fixture.devDependencies as Record<string, string>;
    expect(devDependencies["@ekklesia/module-pack"]).toMatch(/^\d+\.\d+\.\d+$/u);
    expect((fixture.engines as Record<string, string>).node).toBeTruthy();
  });
});

describe("@ekklesia/typescript-config", () => {
  it("ships only its configurations, which extend each other by relative path", async () => {
    const manifest = await readJson("packages/typescript-config/package.json");
    expect(manifest.files?.every((file) => /^[a-z-]+\.json$/u.test(file))).toBe(true);
    for (const file of manifest.files ?? []) {
      const config = await readJson<{ extends?: string }>(`packages/typescript-config/${file}`);
      if (config.extends !== undefined)
        expect(config.extends, file).toMatch(/^\.\/[a-z-]+\.json$/u);
    }
  });
});

describe("the tarball inspection", () => {
  const good = {
    dependencies: { "@ekklesia/contracts": "0.1.2", zod: "4.4.3" },
    devDependencies: { "@ekklesia/core": "0.1.2" },
    ekklesia: { distribution: PUBLIC_PACKAGE_DISTRIBUTION, layer: "module-sdk" },
    files: ["dist"],
    license: "AGPL-3.0-or-later",
    name: "@ekklesia/module-sdk",
    scripts: { build: "tsc" },
    version: "0.1.2",
  };
  const expected = { name: "@ekklesia/module-sdk", version: "0.1.2" };

  it("accepts a packed manifest that names only the coordinated train", () => {
    expect(packedManifestProblems(good, expected)).toEqual([]);
  });

  it("refuses workspace ranges, privacy, missing markers, lifecycle scripts, and mixed trains", () => {
    const cases: Record<string, unknown>[] = [
      { ...good, dependencies: { "@ekklesia/contracts": "workspace:*" } },
      { ...good, private: true },
      { ...good, ekklesia: { layer: "module-sdk" } },
      { ...good, scripts: { prepack: "pnpm --workspace-root exec turbo run build" } },
      { ...good, scripts: { postinstall: "node setup.js" } },
      { ...good, dependencies: { "@ekklesia/contracts": "0.1.1" } },
      { ...good, peerDependencies: { "@ekklesia/core": "0.1.2" } },
      { ...good, version: "0.1.3" },
    ];
    for (const manifest of cases) {
      expect(packedManifestProblems(manifest, expected), JSON.stringify(manifest)).not.toEqual([]);
    }
  });

  it("accepts only declared built files with sources, the manifest, and a LICENSE", () => {
    const hasSource = (file: string) => ["index", "http"].includes(file);
    expect(
      tarballFileProblems(
        ["LICENSE", "package.json", "dist/index.js", "dist/index.d.ts", "dist/http.js.map"],
        good,
        hasSource,
      ),
    ).toEqual([]);
    for (const files of [
      ["package.json", "dist/index.js"],
      ["LICENSE", "package.json", "dist/removed.js"],
      ["LICENSE", "package.json", "src/index.ts"],
      ["LICENSE", "package.json", "tsconfig.json"],
      ["LICENSE", "package.json", "dist/index.test.js"],
    ]) {
      expect(tarballFileProblems(files, good, hasSource), files.join(" ")).not.toEqual([]);
    }
  });
});