@warpgogol/werkstatt-shared 0.14.0 → 0.14.1

package/src/share/semantic/jsonld/tests/organization.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { buildOrganizationNode } from "../organization.ts";
+import { createJsonLdContext } from "../context.ts";
+import { makePage } from "../../tests/helpers.ts";
+
+describe("buildOrganizationNode", () => {
+  it("builds Organization node with default schemaType", () => {
+    const page = makePage();
+    const ctx = createJsonLdContext(page);
+    const node = buildOrganizationNode(ctx);
+    expect(node["@type"]).toEqual(["Organization", "NGO"]);
+    expect(node["@id"]).toBe(ctx.ids.organization);
+    expect(node.name).toBe("Warpgogol");
+    expect(node.description).toBe("Digital infrastructure for nonprofits");
+    expect(node.url).toBe("https://example.com");
+  });
+
+  it("uses custom schemaType when provided", () => {
+    const page = makePage({
+      organization: makePage().organization,
+    });
+    page.organization.schemaType = ["Organization", "ProfessionalService"];
+    const ctx = createJsonLdContext(page);
+    const node = buildOrganizationNode(ctx);
+    expect(node["@type"]).toEqual(["Organization", "ProfessionalService"]);
+  });
+
+  it("emits legalName, email, foundingYear, registration when present", () => {
+    const page = makePage({
+      organization: makePage().organization,
+    });
+    page.organization.legalName = "Warpgogol GmbH";
+    page.organization.email = "info@example.com";
+    page.organization.foundingYear = "2020";
+    page.organization.registration = "HRB 12345";
+    const ctx = createJsonLdContext(page);
+    const node = buildOrganizationNode(ctx);
+    expect(node.legalName).toBe("Warpgogol GmbH");
+    expect(node.email).toBe("info@example.com");
+    expect(node.foundingDate).toBe("2020");
+    expect(node.identifier).toBe("HRB 12345");
+  });
+
+  it("emits address when present", () => {
+    const page = makePage({
+      organization: makePage().organization,
+    });
+    page.organization.address = {
+      streetAddress: "Test Str. 1",
+      postalCode: "12345",
+      addressLocality: "Berlin",
+      addressCountry: "DE",
+    };
+    const ctx = createJsonLdContext(page);
+    const node = buildOrganizationNode(ctx);
+    expect(node.address).toEqual({
+      "@type": "PostalAddress",
+      streetAddress: "Test Str. 1",
+      postalCode: "12345",
+      addressLocality: "Berlin",
+      addressCountry: "DE",
+    });
+  });
+
+  it("emits contactPoints when present", () => {
+    const page = makePage({
+      organization: makePage().organization,
+    });
+    page.organization.contactPoints = [
+      { contactType: "customer service", email: "support@example.com" },
+    ];
+    const ctx = createJsonLdContext(page);
+    const node = buildOrganizationNode(ctx);
+    expect(node.contactPoint).toHaveLength(1);
+    expect((node.contactPoint as unknown[])[0]).toMatchObject({
+      "@type": "ContactPoint",
+      contactType: "customer service",
+      email: "support@example.com",
+    });
+  });
+
+  it("emits sameAs links", () => {
+    const page = makePage({
+      organization: makePage().organization,
+    });
+    page.organization.sameAs = ["https://twitter.com/example", "https://github.com/example"];
+    const ctx = createJsonLdContext(page);
+    const node = buildOrganizationNode(ctx);
+    expect(node.sameAs).toEqual(["https://twitter.com/example", "https://github.com/example"]);
+  });
+
+  it("emits logo and image", () => {
+    const page = makePage({
+      organization: makePage().organization,
+    });
+    page.organization.logo = "https://example.com/logo.png";
+    page.organization.image = "https://example.com/image.png";
+    const ctx = createJsonLdContext(page);
+    const node = buildOrganizationNode(ctx);
+    expect(node.logo).toEqual({ "@type": "ImageObject", url: "https://example.com/logo.png" });
+    expect(node.image).toBe("https://example.com/image.png");
+  });
+
+  it("emits founders as Person references", () => {
+    const page = makePage({
+      organization: makePage().organization,
+    });
+    page.organization.founders = [{ name: "Jane Doe" }];
+    const ctx = createJsonLdContext(page);
+    const node = buildOrganizationNode(ctx);
+    expect(node.founder).toEqual([{ "@id": ctx.ids.person("Jane Doe") }]);
+  });
+
+  it("emits areaServed when present", () => {
+    const page = makePage({
+      organization: makePage().organization,
+    });
+    page.organization.areaServed = ["Berlin", "Brandenburg"];
+    const ctx = createJsonLdContext(page);
+    const node = buildOrganizationNode(ctx);
+    expect(node.areaServed).toEqual(["Berlin", "Brandenburg"]);
+  });
+});

package/src/share/semantic/jsonld/tests/person.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import { buildPersonNodes } from "../person.ts";
+import { createJsonLdContext } from "../context.ts";
+import { makePage } from "../../tests/helpers.ts";
+
+describe("buildPersonNodes", () => {
+  it("returns empty array when no people, founders, or boardMembers", () => {
+    const page = makePage();
+    const ctx = createJsonLdContext(page);
+    expect(buildPersonNodes(ctx)).toEqual([]);
+  });
+
+  it("builds Person nodes from page.people", () => {
+    const page = makePage({
+      people: [{ name: "Jane Doe", role: "CEO", description: "A leader" }],
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildPersonNodes(ctx);
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]["@type"]).toBe("Person");
+    expect(nodes[0].name).toBe("Jane Doe");
+    expect(nodes[0].jobTitle).toBe("CEO");
+    expect(nodes[0].description).toBe("A leader");
+    expect(nodes[0].worksFor).toEqual({ "@id": ctx.ids.organization });
+  });
+
+  it("merges founders, boardMembers, and people with deduplication by name", () => {
+    const page = makePage({
+      organization: makePage().organization,
+      people: [{ name: "Jane Doe", role: "CEO" }],
+    });
+    page.organization.founders = [{ name: "Jane Doe", role: "Founder" }];
+    page.organization.boardMembers = [{ name: "John Smith", role: "Board Member" }];
+    const ctx = createJsonLdContext(page);
+    const nodes = buildPersonNodes(ctx);
+    expect(nodes).toHaveLength(2);
+    const names = nodes.map((n) => n.name);
+    expect(names).toContain("Jane Doe");
+    expect(names).toContain("John Smith");
+  });
+
+  it("emits extended fields (address, knowsAbout, affiliation)", () => {
+    const page = makePage({
+      people: [
+        {
+          name: "Jane Doe",
+          address: { addressLocality: "Berlin", addressCountry: "DE" },
+          knowsAbout: ["AI", "Cloud"],
+          affiliation: { name: "Warpgogol", url: "https://example.com" },
+        },
+      ],
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildPersonNodes(ctx);
+    expect(nodes[0].address).toEqual({
+      "@type": "PostalAddress",
+      addressLocality: "Berlin",
+      addressCountry: "DE",
+    });
+    expect(nodes[0].knowsAbout).toEqual(["AI", "Cloud"]);
+    expect(nodes[0].affiliation).toEqual({
+      "@type": "Organization",
+      name: "Warpgogol",
+      url: "https://example.com",
+    });
+  });
+
+  it("emits birthDate, deathDate, image, sameAs, profileUrl", () => {
+    const page = makePage({
+      people: [
+        {
+          name: "Jane Doe",
+          birthDate: "1980",
+          deathDate: "2024",
+          image: "https://example.com/jane.jpg",
+          sameAs: ["https://linkedin.com/in/jane"],
+          profileUrl: "https://example.com/de/team/jane/",
+        },
+      ],
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildPersonNodes(ctx);
+    expect(nodes[0].birthDate).toBe("1980");
+    expect(nodes[0].deathDate).toBe("2024");
+    expect(nodes[0].image).toBe("https://example.com/jane.jpg");
+    expect(nodes[0].sameAs).toEqual(["https://linkedin.com/in/jane"]);
+    expect(nodes[0].url).toBe("https://example.com/de/team/jane/");
+  });
+});

package/src/share/semantic/jsonld/tests/service.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { buildServiceNodes } from "../service.ts";
+import { createJsonLdContext } from "../context.ts";
+import { makePage } from "../../tests/helpers.ts";
+
+describe("buildServiceNodes", () => {
+  it("returns org-level Service nodes for non-surface pages", () => {
+    const page = makePage({
+      organization: makePage().organization,
+    });
+    page.organization.services = [
+      { id: "s1", name: "Hosting", description: "Managed hosting" },
+      { id: "s2", name: "Security" },
+    ];
+    const ctx = createJsonLdContext(page);
+    const nodes = buildServiceNodes(ctx);
+    expect(nodes).toHaveLength(2);
+    expect(nodes[0]["@type"]).toBe("Service");
+    expect(nodes[0].name).toBe("Hosting");
+    expect(nodes[0].description).toBe("Managed hosting");
+    expect(nodes[0].provider).toEqual({ "@id": ctx.ids.organization });
+  });
+
+  it("emits industry-specific Service node when industryService is present", () => {
+    const page = makePage({
+      surfaceId: "website-local",
+      depth: 1,
+      industryService: {
+        serviceType: "Web Development",
+        audience: "Nonprofits",
+        description: "Custom web development",
+        areaServed: "Berlin",
+      },
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildServiceNodes(ctx);
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]["@type"]).toBe("Service");
+    expect(nodes[0].serviceType).toBe("Web Development");
+    expect(nodes[0].audience).toEqual({ "@type": "Audience", name: "Nonprofits" });
+    expect(nodes[0].areaServed).toEqual({ "@type": "City", name: "Berlin" });
+  });
+
+  it("suppresses Service nodes for surface pages without industryService at prohibited depths", () => {
+    const page = makePage({
+      surfaceId: "website-local",
+      depth: 0,
+    });
+    const ctx = createJsonLdContext(page);
+    expect(buildServiceNodes(ctx)).toEqual([]);
+  });
+
+  it("emits org-level Service nodes for surface depth-1 without industryService", () => {
+    const page = makePage({
+      surfaceId: "website-local",
+      depth: 1,
+      organization: makePage().organization,
+    });
+    page.organization.services = [{ id: "s1", name: "Consulting" }];
+    const ctx = createJsonLdContext(page);
+    const nodes = buildServiceNodes(ctx);
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0].name).toBe("Consulting");
+  });
+});

package/src/share/semantic/jsonld/tests/shared.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { dedupeGraph } from "../shared.ts";
+import type { JsonLdNode } from "../types.ts";
+
+describe("dedupeGraph", () => {
+  it("returns empty array for empty input", () => {
+    expect(dedupeGraph([])).toEqual([]);
+  });
+
+  it("removes duplicate nodes by @id", () => {
+    const nodes: JsonLdNode[] = [
+      { "@id": "org-1", "@type": "Organization", name: "Org" },
+      { "@id": "org-1", "@type": "Organization", name: "Duplicate" },
+      { "@id": "org-2", "@type": "Organization", name: "Other" },
+    ];
+    const result = dedupeGraph(nodes);
+    expect(result).toHaveLength(2);
+    expect(result[0]["@id"]).toBe("org-1");
+    expect(result[0].name).toBe("Org");
+    expect(result[1]["@id"]).toBe("org-2");
+  });
+
+  it("preserves first occurrence of duplicates", () => {
+    const nodes: JsonLdNode[] = [
+      { "@id": "a", value: "first" },
+      { "@id": "a", value: "second" },
+    ];
+    const result = dedupeGraph(nodes);
+    expect(result).toHaveLength(1);
+    expect(result[0].value).toBe("first");
+  });
+
+  it("keeps nodes without @id", () => {
+    const nodes: JsonLdNode[] = [
+      { "@type": "Thing", name: "No ID" },
+      { "@type": "Thing", name: "Also No ID" },
+    ];
+    const result = dedupeGraph(nodes);
+    expect(result).toHaveLength(2);
+  });
+});

package/src/share/semantic/jsonld/tests/video.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import { buildVideoObjectNodes } from "../video.ts";
+import { createJsonLdContext } from "../context.ts";
+import { makePage } from "../../tests/helpers.ts";
+
+describe("buildVideoObjectNodes", () => {
+  it("returns empty array when no blocks have video data", () => {
+    const page = makePage({ blocks: [{ id: "b1", heading: "Test" }] });
+    const ctx = createJsonLdContext(page);
+    expect(buildVideoObjectNodes(ctx)).toEqual([]);
+  });
+
+  it("builds VideoObject nodes for blocks with video data", () => {
+    const page = makePage({
+      blocks: [
+        {
+          id: "vid-1",
+          heading: "Video Section",
+          video: {
+            seo: { name: "Intro Video", description: "An intro", uploadDate: "2024-01-15" },
+            manifest: {
+              posterUrl: "https://example.com/poster.jpg",
+              contentUrl: "https://example.com/video.mp4",
+              durationSec: 90,
+            },
+          },
+        },
+      ],
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildVideoObjectNodes(ctx);
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]["@type"]).toBe("VideoObject");
+    expect(nodes[0].name).toBe("Intro Video");
+    expect(nodes[0].description).toBe("An intro");
+    expect(nodes[0].uploadDate).toBe("2024-01-15");
+    expect(nodes[0].thumbnailUrl).toBe("https://example.com/poster.jpg");
+    expect(nodes[0].contentUrl).toBe("https://example.com/video.mp4");
+    expect(nodes[0].duration).toBe("PT1M30S");
+  });
+
+  it("formats duration correctly for hours, minutes, seconds", () => {
+    const page = makePage({
+      blocks: [
+        {
+          id: "vid-2",
+          heading: "Long Video",
+          video: {
+            seo: { name: "Long", description: "Long", uploadDate: "2024-01-15" },
+            manifest: {
+              posterUrl: "https://example.com/p.jpg",
+              contentUrl: "https://example.com/v.mp4",
+              durationSec: 3661,
+            },
+          },
+        },
+      ],
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildVideoObjectNodes(ctx);
+    expect(nodes[0].duration).toBe("PT1H1M1S");
+  });
+
+  it("omits duration when durationSec is not provided", () => {
+    const page = makePage({
+      blocks: [
+        {
+          id: "vid-3",
+          heading: "No Duration",
+          video: {
+            seo: { name: "NoDur", description: "No dur", uploadDate: "2024-01-15" },
+            manifest: {
+              posterUrl: "https://example.com/p.jpg",
+              contentUrl: "https://example.com/v.mp4",
+            },
+          },
+        },
+      ],
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildVideoObjectNodes(ctx);
+    expect(nodes[0].duration).toBeUndefined();
+  });
+});

package/src/share/semantic/jsonld/tests/webpage.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { buildWebPageNode } from "../webpage.ts";
+import { createJsonLdContext } from "../context.ts";
+import { makePage } from "../../tests/helpers.ts";
+
+describe("buildWebPageNode", () => {
+  it("builds WebPage node for content type", () => {
+    const page = makePage({ type: "content" });
+    const ctx = createJsonLdContext(page);
+    const node = buildWebPageNode(ctx);
+    expect(node["@type"]).toEqual(["WebPage"]);
+    expect(node["@id"]).toBe(ctx.webpageId);
+    expect(node.url).toBe(page.url);
+    expect(node.name).toBe("Test Page");
+    expect(node.description).toBe("A test page description");
+    expect(node.inLanguage).toBe("de");
+  });
+
+  it("uses heading for name when available", () => {
+    const page = makePage({ heading: "Custom Heading" });
+    const ctx = createJsonLdContext(page);
+    const node = buildWebPageNode(ctx);
+    expect(node.headline).toBe("Custom Heading");
+  });
+
+  it("uses title for headline", () => {
+    const page = makePage({ title: "Page Title" });
+    const ctx = createJsonLdContext(page);
+    const node = buildWebPageNode(ctx);
+    expect(node.name).toBe("Page Title");
+  });
+
+  it("emits CollectionPage for collection type", () => {
+    const page = makePage({ type: "collection" });
+    const ctx = createJsonLdContext(page);
+    const node = buildWebPageNode(ctx);
+    expect(node["@type"]).toEqual(["WebPage", "CollectionPage"]);
+  });
+
+  it("emits AboutPage for about type", () => {
+    const page = makePage({ type: "about" });
+    const ctx = createJsonLdContext(page);
+    const node = buildWebPageNode(ctx);
+    expect(node["@type"]).toEqual(["WebPage", "AboutPage"]);
+  });
+
+  it("emits ProfilePage for person type", () => {
+    const page = makePage({ type: "person" });
+    const ctx = createJsonLdContext(page);
+    const node = buildWebPageNode(ctx);
+    expect(node["@type"]).toEqual(["WebPage", "ProfilePage"]);
+  });
+
+  it("links to organization via publisher", () => {
+    const page = makePage();
+    const ctx = createJsonLdContext(page);
+    const node = buildWebPageNode(ctx);
+    expect(node.publisher).toEqual({ "@id": ctx.ids.organization });
+  });
+
+  it("links to breadcrumb when breadcrumbs > 1", () => {
+    const page = makePage({
+      breadcrumbs: [
+        { name: "Home", url: "https://example.com/de/" },
+        { name: "Page", url: "https://example.com/de/page/" },
+      ],
+    });
+    const ctx = createJsonLdContext(page);
+    const node = buildWebPageNode(ctx);
+    expect(node.breadcrumb).toEqual({ "@id": ctx.breadcrumbId });
+  });
+
+  it("omits breadcrumb when only one crumb", () => {
+    const page = makePage({
+      breadcrumbs: [{ name: "Home", url: "https://example.com/de/" }],
+    });
+    const ctx = createJsonLdContext(page);
+    const node = buildWebPageNode(ctx);
+    expect(node.breadcrumb).toBeUndefined();
+  });
+
+  it("emits primaryImage when present", () => {
+    const page = makePage({
+      primaryImage: { url: "https://example.com/img.jpg" },
+    });
+    const ctx = createJsonLdContext(page);
+    const node = buildWebPageNode(ctx);
+    expect(node.primaryImageOfPage).toEqual({
+      "@type": "ImageObject",
+      url: "https://example.com/img.jpg",
+    });
+  });
+});

package/src/share/semantic/jsonld/tests/website.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { buildWebSiteNode } from "../website.ts";
+import { createJsonLdContext } from "../context.ts";
+import { makePage } from "../../tests/helpers.ts";
+
+describe("buildWebSiteNode", () => {
+  it("builds WebSite node with organization URL and language", () => {
+    const page = makePage({ lang: "de" });
+    const ctx = createJsonLdContext(page);
+    const node = buildWebSiteNode(ctx);
+    expect(node["@type"]).toBe("WebSite");
+    expect(node["@id"]).toBe(ctx.ids.website);
+    expect(node.url).toBe(page.organization.url);
+    expect(node.inLanguage).toBe("de");
+    expect(node.publisher).toEqual({ "@id": ctx.ids.organization });
+  });
+
+  it("uses organization name for WebSite name", () => {
+    const page = makePage({
+      organization: makePage().organization,
+    });
+    page.organization.name = "Test Org";
+    const ctx = createJsonLdContext(page);
+    const node = buildWebSiteNode(ctx);
+    expect(node.name).toBe("Test Org");
+  });
+});

package/src/share/semantic/jsonld/types.ts

@@ -1,3 +1,4 @@
+// test-adjacency: exempt — pure type definitions
 /*
 <MODULE_CONTRACT>
 <purpose>Maintains packages/share/src/semantic/jsonld/types.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>

package/src/share/semantic/models.ts

@@ -1,3 +1,4 @@
+// test-adjacency: exempt — pure type definitions
 /*
 <MODULE_CONTRACT>
 <purpose>Defines types for semantic data structures used throughout the Warpgogol ecosystem.</purpose>

package/src/share/semantic/tests/ai.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { buildAiTxt } from "../ai.ts";
+
+describe("buildAiTxt", () => {
+  it("generates header from siteUrl", () => {
+    const result = buildAiTxt({ policy: "allow" }, "https://example.com");
+    expect(result).toContain("# ai.txt for example.com");
+    expect(result).toContain("policy: allow");
+  });
+
+  it("includes version and updated", () => {
+    const result = buildAiTxt({ policy: "allow", version: "1.0", updated: "2024-01-01" }, "https://example.com");
+    expect(result).toContain("version: 1.0");
+    expect(result).toContain("updated: 2024-01-01");
+  });
+
+  it("includes optional fields when provided", () => {
+    const result = buildAiTxt({
+      policy: "limited",
+      training: "disallow",
+      usage: ["search", "summarization"],
+      commercial: "no",
+      attribution: "required",
+      license: "CC-BY-4.0",
+    }, "https://example.com");
+    expect(result).toContain("training: disallow");
+    expect(result).toContain("usage: search, summarization");
+    expect(result).toContain("commercial: no");
+    expect(result).toContain("attribution: required");
+    expect(result).toContain("license: CC-BY-4.0");
+  });
+
+  it("emits provider sections", () => {
+    const result = buildAiTxt({
+      policy: "allow",
+      providers: [
+        { name: "OpenAI", policy: "disallow", training: "disallow" },
+        { name: "Anthropic", policy: "allow", url: "https://anthropic.com" },
+      ],
+    }, "https://example.com");
+    expect(result).toContain("[OpenAI]");
+    expect(result).toContain("[Anthropic]");
+    expect(result).toContain("url: https://anthropic.com");
+  });
+
+  it("includes url and contact in header comments", () => {
+    const result = buildAiTxt({
+      policy: "allow",
+      url: "https://example.com/policy",
+      contact: "info@example.com",
+    }, "https://example.com");
+    expect(result).toContain("# See: https://example.com/policy");
+    expect(result).toContain("# Contact: info@example.com");
+  });
+});

package/src/share/semantic/tests/block-extraction.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { BlockExtractorRegistry, BLOCK_EXTRACTORS } from "../block-extraction.ts";
+import "../block-extractors/index.ts";
+
+describe("BlockExtractorRegistry", () => {
+  it("registers and retrieves extractors", () => {
+    const registry = new BlockExtractorRegistry();
+    registry.register({
+      blockType: "test-block",
+      extract: () => ({ heading: "Test" }),
+    });
+    expect(registry.has("test-block")).toBe(true);
+    expect(registry.get("test-block")?.blockType).toBe("test-block");
+  });
+
+  it("returns undefined for unregistered type", () => {
+    const registry = new BlockExtractorRegistry();
+    expect(registry.get("nonexistent")).toBeUndefined();
+  });
+
+  it("lists registered types", () => {
+    const registry = new BlockExtractorRegistry();
+    registry.register({ blockType: "a", extract: () => ({}) });
+    registry.register({ blockType: "b", extract: () => ({}) });
+    expect(registry.listTypes().sort()).toEqual(["a", "b"]);
+  });
+});
+
+describe("BLOCK_EXTRACTORS", () => {
+  it("is a registry instance with pre-registered extractors", () => {
+    expect(BLOCK_EXTRACTORS).toBeInstanceOf(BlockExtractorRegistry);
+    expect(BLOCK_EXTRACTORS.listTypes().length).toBeGreaterThan(0);
+  });
+});