Ekklesia/tests/public-packages.test.ts

import { spawnSync } from "node:child_process";
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 {
  artifactDigests,
  PACKAGE_TRAIN_MANIFEST,
  type PackageTrainManifest,
  PUBLIC_PACKAGE_DISTRIBUTION,
  PUBLIC_PACKAGES,
  packedManifestProblems,
  releaseDirectoryProblems,
  releaseSetProblems,
  serializeManifest,
  tarballFileProblems,
  tarballName,
  workspacePackages as releaseWorkspacePackages,
} from "../scripts/package-release.js";

/**
 * The public module-development package boundary and its release train (ADR 0053): which packages
 * may be published, what their manifests may say, what the author-facing SDK exposes, and what a
 * release directory must hold. The tarballs themselves are built and inspected by
 * `pnpm packages:release` (`scripts/package-release.ts`), and proven by `pnpm test:package-release`.
 */

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("is what the release builder itself accepts, read without a YAML parser", async () => {
    const platformVersion = (await readJson("package.json")).version;
    const read = await releaseWorkspacePackages(repositoryRoot);
    expect(read.map((entry) => entry.name).sort()).toEqual(
      [...(await workspacePackages()).keys()].sort(),
    );
    expect(releaseSetProblems(read, platformVersion)).toEqual([]);
  });

  it("refuses a missing, mis-versioned, or private public package, and anything else publishable", async () => {
    const read = await releaseWorkspacePackages(repositoryRoot);
    const without = read.filter((entry) => entry.name !== "@ekklesia/ui");
    expect(releaseSetProblems(without, "0.1.2").join(" ")).toContain("@ekklesia/ui is missing");
    const changed = read.map((entry) =>
      entry.name === "@ekklesia/module-sdk"
        ? { ...entry, manifest: { ...entry.manifest, private: true, version: "0.2.0" } }
        : entry.name === "@ekklesia/core"
          ? { ...entry, manifest: { ...entry.manifest, private: undefined } }
          : entry.name === "@ekklesia/module-ui-host"
            ? {
                ...entry,
                manifest: {
                  ...entry.manifest,
                  ekklesia: { distribution: PUBLIC_PACKAGE_DISTRIBUTION },
                },
              }
            : entry,
    );
    const problems = releaseSetProblems(changed, "0.1.2").join(" ");
    expect(problems).toContain("@ekklesia/module-sdk is version 0.2.0");
    expect(problems).toContain("@ekklesia/module-sdk is private");
    expect(problems).toContain("@ekklesia/core is publishable but not in the release set");
    expect(problems).toContain("@ekklesia/module-ui-host carries the distribution marker");
  });

  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, at this release, 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>;
    // Part of setting a release version: the fixture consumes exactly this release's module-pack.
    expect(devDependencies["@ekklesia/module-pack"]).toBe((await readJson("package.json")).version);
    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" },
    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" },
      // Development dependencies never ship: they name private packages outside the train.
      { ...good, devDependencies: { "@ekklesia/core": "0.1.2" } },
      // A registry is the publication step's configuration, never part of an artifact.
      { ...good, publishConfig: { registry: "https://registry.example/" } },
    ];
    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([]);
    }
  });

  it("refuses a dependency map whose order differs from its source", () => {
    const source = { dependencies: { "@ekklesia/contracts": "workspace:*", zod: "4.4.3" } };
    expect(packedManifestProblems(good, expected, source)).toEqual([]);
    const reordered = { ...good, dependencies: { zod: "4.4.3", "@ekklesia/contracts": "0.1.2" } };
    expect(packedManifestProblems(reordered, expected, source)).toEqual([
      "orders dependencies differently from its source",
    ]);
  });
});

describe("the pack hook", () => {
  it("drops devDependencies and restores the source's key order, changing nothing else", async () => {
    const { hooks } = await import("../scripts/lib/pack-hooks.cjs");
    const directory = path.join(repositoryRoot, "packages", "module-pack");
    const source = await readJson("packages/module-pack/package.json");
    const dependencies = Object.fromEntries(
      Object.keys(source.dependencies ?? {})
        .reverse()
        .map((name) => [name, name.startsWith("@ekklesia/") ? "0.1.2" : "1.0.0"]),
    );
    const packed = hooks.beforePacking(
      { ...source, dependencies, devDependencies: { "@ekklesia/core": "0.1.2" } },
      directory,
    );
    expect(packed.devDependencies).toBeUndefined();
    expect(Object.keys(packed.dependencies as object)).toEqual(
      Object.keys(source.dependencies ?? {}),
    );
    expect(packed.dependencies).toEqual(dependencies);
    expect(packed.name).toBe(source.name);
  });
});

describe("a clean source tree", () => {
  it("ignores pnpm's package store, which pnpm creates in a checkout that is its own mount", () => {
    // In CI the checkout is a workspace volume, so `pnpm install` puts `.pnpm-store/` at its root:
    // a package cache, never source, which must not make the release builder's clean tree dirty.
    const ignored = spawnSync("git", ["check-ignore", "--quiet", ".pnpm-store/v11/index.db"], {
      cwd: repositoryRoot,
    });
    expect(ignored.status).toBe(0);
  });
});

describe("the release directory", () => {
  const version = "0.1.2";
  function release(mutate?: (files: Map<string, Uint8Array>) => void) {
    const files = new Map<string, Uint8Array>();
    for (const entry of PUBLIC_PACKAGES) {
      files.set(tarballName(entry.name, version), Buffer.from(`tarball of ${entry.name}`));
    }
    const manifest: PackageTrainManifest = {
      packageTrain: 1,
      packages: PUBLIC_PACKAGES.map((entry) => {
        const file = tarballName(entry.name, version);
        const data = files.get(file) ?? new Uint8Array();
        return {
          file,
          name: entry.name,
          role: entry.role,
          size: data.length,
          version,
          ...artifactDigests(data),
        };
      }),
      source: { modified: false, revision: "86ae907f59458508e3277666cdd214f5bd7c1078" },
      version,
    };
    mutate?.(files);
    files.set(PACKAGE_TRAIN_MANIFEST, Buffer.from(serializeManifest(manifest)));
    return { files, manifest };
  }

  it("names each tarball as pnpm pack does", () => {
    expect(tarballName("@ekklesia/module-sdk", "0.1.2")).toBe("ekklesia-module-sdk-0.1.2.tgz");
  });

  it("records npm-compatible integrity and SHA-256 for each artifact", () => {
    const digests = artifactDigests(Buffer.from("abc"));
    expect(digests.sha256).toBe("ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad");
    expect(digests.integrity).toMatch(/^sha512-[A-Za-z0-9+/]{86}==$/u);
  });

  it("accepts exactly the expected train, matching its manifest", () => {
    const { files, manifest } = release();
    expect(releaseDirectoryProblems(manifest, files)).toEqual([]);
  });

  it("refuses a missing, extra, or altered artifact", () => {
    const missing = release((files) => files.delete(tarballName("@ekklesia/ui", version)));
    expect(releaseDirectoryProblems(missing.manifest, missing.files).join(" ")).toContain(
      "ekklesia-ui-0.1.2.tgz is missing",
    );
    const extra = release((files) =>
      files.set("ekklesia-module-ui-host-0.1.2.tgz", Buffer.from("x")),
    );
    expect(releaseDirectoryProblems(extra.manifest, extra.files).join(" ")).toContain(
      "ekklesia-module-ui-host-0.1.2.tgz is not part of the release",
    );
    const altered = release((files) =>
      files.set(tarballName("@ekklesia/module-pack", version), Buffer.from("changed")),
    );
    expect(releaseDirectoryProblems(altered.manifest, altered.files).join(" ")).toContain(
      "does not match its size, SHA-256, or integrity",
    );
  });

  it("serializes the manifest the same way every time, packages sorted by name", () => {
    const { manifest } = release();
    const reversed = { ...manifest, packages: [...manifest.packages].reverse() };
    expect(serializeManifest(reversed)).toBe(serializeManifest(manifest));
    const parsed = JSON.parse(serializeManifest(manifest)) as PackageTrainManifest;
    expect(parsed.packages.map((entry) => entry.name)).toEqual(
      [...PUBLIC_PACKAGES.map((entry) => entry.name)].sort(),
    );
    expect(Object.keys(parsed)).toEqual(["packageTrain", "version", "source", "packages"]);
  });
});