@synap-core/workspace-templates 0.12.0 → 0.24.0

package/src/template-documents.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Templates carry documents (`documents[]` + sidebar items
+ * `{kind: "document", documentSlug}`, plan 9ad4b2fc §5 lane 12). The pod
+ * installs them with the views (synap-backend `utils/template-documents.ts`);
+ * this file pins the authoring half:
+ *
+ *  (1) the catalog schema accepts `documents[]` and refuses an unknown key in one;
+ *  (2) both converters carry the documents verbatim, and a template WITHOUT
+ *      documents compiles to a definition with no `documents` key (so every
+ *      shipped template's body and content hash stay what they were);
+ *  (3) `validateTemplate` refuses a bad slug, a duplicate slug, a missing
+ *      title, an unknown scope, and a document sidebar item naming a document
+ *      neither the template nor a base it COMPOSES onto declares (a `require`
+ *      base keeps its own space, so its documents are not reachable);
+ *  (4) no shipped template declares documents while the control plane's
+ *      publish door cannot carry them (it strips `documents` and refuses a
+ *      `kind: "document"` sidebar item): the set is derived from `src/*.yaml`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { workspaceSpecSchema } from "../schema/workspace.ts";
+import { toPackageDefinition, toWorkspaceDefinition } from "./define.ts";
+import { readYamlTemplates } from "./generate.mjs";
+import type { WorkspaceYaml } from "./types.ts";
+import { validateTemplate } from "./validate.ts";
+
+const base = (overrides: Partial<WorkspaceYaml> = {}): WorkspaceYaml =>
+  ({
+    meta: {
+      slug: "docs-demo",
+      name: "Docs demo",
+      description: "d",
+      icon: "x",
+      color: "violet",
+    },
+    workspace: { name: "Docs demo", description: "d" },
+    profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
+    ...overrides,
+  }) as WorkspaceYaml;
+
+const DOCS = [
+  {
+    slug: "space-home",
+    title: "Space home",
+    content: 'Welcome.\n\n::synap-cell{cellKey="lens-section"}',
+    scope: "space" as const,
+  },
+  { slug: "notes", title: "Notes", content: "" },
+];
+
+const withDocs = base({
+  documents: DOCS,
+  layout: {
+    sidebarItems: [{ kind: "document", documentSlug: "space-home", label: "Home" }],
+  },
+});
+
+const rules = (tpl: WorkspaceYaml, opts = {}) =>
+  validateTemplate(tpl, opts).errors.map((e) => e.rule);
+
+describe("templates carry documents", () => {
+  it("(1) the catalog schema accepts documents[] and refuses an unknown key in one", () => {
+    const { meta: _meta, ...spec } = withDocs;
+    expect(workspaceSpecSchema.safeParse(spec).success).toBe(true);
+    const bad = { ...spec, documents: [{ ...DOCS[1], body: "typo" }] };
+    expect(workspaceSpecSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it("(2) both converters carry the documents; a template without any emits no key", () => {
+    expect(toPackageDefinition(withDocs).documents).toEqual(DOCS);
+    expect(toWorkspaceDefinition(withDocs).definition.documents).toEqual(DOCS);
+    expect(toPackageDefinition(withDocs).layoutConfig?.sidebarItems).toEqual([
+      { kind: "document", documentSlug: "space-home", label: "Home" },
+    ]);
+    expect("documents" in toPackageDefinition(base())).toBe(false);
+    expect("documents" in toWorkspaceDefinition(base()).definition).toBe(false);
+  });
+
+  it("(3a) a clean template with documents validates", () => {
+    const r = validateTemplate(withDocs, {});
+    expect(r, JSON.stringify(r.errors)).toEqual({ ok: true, errors: [] });
+  });
+
+  it("(3b) each document rule fires", () => {
+    expect(rules(base({ documents: [{ ...DOCS[1], slug: "Not Kebab" }] }))).toContain(
+      "document-slug-invalid"
+    );
+    expect(rules(base({ documents: [DOCS[1], { ...DOCS[1], title: "Again" }] }))).toContain(
+      "document-slug-duplicate"
+    );
+    expect(rules(base({ documents: [{ ...DOCS[1], title: " " }] }))).toContain(
+      "document-title-required"
+    );
+    expect(
+      rules(base({ documents: [{ ...DOCS[1], scope: "project" as never }] }))
+    ).toContain("document-scope-unknown");
+    expect(
+      rules(
+        base({
+          documents: DOCS,
+          layout: { sidebarItems: [{ kind: "document", documentSlug: "missing" }] },
+        })
+      )
+    ).toContain("sidebar-document-unknown");
+    expect(
+      rules(base({ layout: { sidebarItems: [{ kind: "document" }] } }))
+    ).toContain("sidebar-document-unknown");
+  });
+
+  it("(3c) an overlay may name a document of a base it composes onto, not of one it requires", () => {
+    const baseTpl = base({ documents: DOCS });
+    const overlay = (relation: "compose" | "require") =>
+      base({
+        meta: { ...base().meta, slug: "docs-overlay" },
+        dependencies: [{ slug: "docs-demo", relation }],
+        layout: { sidebarItems: [{ kind: "document", documentSlug: "notes" }] },
+      });
+    const resolveDep = (slug: string) => (slug === "docs-demo" ? baseTpl : undefined);
+    expect(rules(overlay("compose"), { resolveDep })).not.toContain(
+      "sidebar-document-unknown"
+    );
+    expect(rules(overlay("require"), { resolveDep })).toContain(
+      "sidebar-document-unknown"
+    );
+  });
+
+  it("(4) no shipped template declares documents while the CP publish door cannot carry them", () => {
+    const yamls = readYamlTemplates() as Array<{ file: string; data: WorkspaceYaml }>;
+    expect(yamls.length).toBeGreaterThanOrEqual(25);
+    const declaring = yamls
+      .filter(
+        ({ data }) =>
+          (data.documents?.length ?? 0) > 0 ||
+          (data.layout?.sidebarItems ?? []).some((i) => i.kind === "document")
+      )
+      .map(({ file }) => file);
+    if (declaring.length === 0) return;
+    // A template uses them: the CP's packageDefinitionSchema must slot both.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const cpPackages = join(here, "../../../../synap-control-plane-api/src/routes/packages.ts");
+    expect(existsSync(cpPackages), `${declaring.join(", ")} declare documents; ${cpPackages} is needed to check the CP carries them`).toBe(true);
+    const src = readFileSync(cpPackages, "utf8");
+    const start = src.indexOf("export const packageDefinitionSchema = z.object(");
+    expect(start).toBeGreaterThan(-1);
+    const body = src.slice(start, src.indexOf("\n});", start));
+    expect(body, `${declaring.join(", ")} declare documents, which the CP publish door strips`).toMatch(/\n  documents:/);
+    // The sidebar ITEM's kind enum is the one listing "profile" (the nested
+    // `surface` enum already lists "document"; it is not the item's kind).
+    const itemKinds = [...body.matchAll(/kind: z\.enum\(\[([^\]]*)\]\)/g)]
+      .map((m) => m[1]!)
+      .filter((list) => list.includes('"profile"'));
+    expect(itemKinds.length, "the CP sidebar item kind enum was not found").toBeGreaterThan(0);
+    for (const list of itemKinds)
+      expect(list, `${declaring.join(", ")} name a document sidebar item, which the CP publish door refuses`).toContain('"document"');
+  });
+});