@warpgogol/werkstatt-shared 0.13.0 → 0.14.1

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);
+  });
+});

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

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildBreadcrumbTrail,
+  stripSiteNameFromTitle,
+  surfaceAncestorPageIds,
+  type BreadcrumbAncestorResolver,
+} from "../breadcrumbs.ts";
+
+describe("stripSiteNameFromTitle", () => {
+  it("strips site name suffix", () => {
+    expect(stripSiteNameFromTitle("About | Warpgogol")).toBe("About");
+  });
+
+  it("returns title unchanged when no separator", () => {
+    expect(stripSiteNameFromTitle("About")).toBe("About");
+  });
+
+  it("trims whitespace", () => {
+    expect(stripSiteNameFromTitle("  About  ")).toBe("About");
+  });
+});
+
+describe("surfaceAncestorPageIds", () => {
+  it("returns empty for non-surface pageId", () => {
+    expect(surfaceAncestorPageIds("some-page")).toEqual([]);
+  });
+
+  it("returns empty for depth-0 root landing", () => {
+    expect(surfaceAncestorPageIds("industry:_root")).toEqual([]);
+  });
+
+  it("returns root + intermediate ancestors for depth-2", () => {
+    expect(surfaceAncestorPageIds("industry:tech:saas")).toEqual([
+      "industry:_root",
+      "industry:tech",
+    ]);
+  });
+});
+
+describe("buildBreadcrumbTrail", () => {
+  const noopResolver: BreadcrumbAncestorResolver = {
+    resolveAncestors: async () => [],
+  };
+
+  it("builds [Home, self] trail with no ancestors", async () => {
+    const trail = await buildBreadcrumbTrail({
+      pageId: "about",
+      pageTitle: "About | Site",
+      selfUrl: "https://example.com/de/about/",
+      homeLabel: "Home",
+      homeUrl: "https://example.com/de/",
+      lang: "de",
+      defaultLang: "de",
+      resolver: noopResolver,
+    });
+    expect(trail).toHaveLength(2);
+    expect(trail[0]).toEqual({ name: "Home", url: "https://example.com/de/" });
+    expect(trail[1]).toEqual({
+      name: "About",
+      url: "https://example.com/de/about/",
+      pageId: "about",
+    });
+  });
+
+  it("inserts ancestors between Home and self", async () => {
+    const resolver: BreadcrumbAncestorResolver = {
+      resolveAncestors: async () => [
+        { name: "Section", url: "https://example.com/de/section/" },
+      ],
+    };
+    const trail = await buildBreadcrumbTrail({
+      pageId: "page",
+      pageTitle: "Page",
+      selfUrl: "https://example.com/de/section/page/",
+      homeLabel: "Home",
+      homeUrl: "https://example.com/de/",
+      lang: "de",
+      defaultLang: "de",
+      resolver,
+    });
+    expect(trail).toHaveLength(3);
+    expect(trail[1]).toEqual({ name: "Section", url: "https://example.com/de/section/" });
+  });
+
+  it("deduplicates ancestors that collapse onto Home or self", async () => {
+    const resolver: BreadcrumbAncestorResolver = {
+      resolveAncestors: async () => [
+        { name: "Home", url: "https://example.com/de/" },
+        { name: "Self", url: "https://example.com/de/page/" },
+        { name: "Real Ancestor", url: "https://example.com/de/real/" },
+      ],
+    };
+    const trail = await buildBreadcrumbTrail({
+      pageId: "page",
+      pageTitle: "Page",
+      selfUrl: "https://example.com/de/page/",
+      homeLabel: "Home",
+      homeUrl: "https://example.com/de/",
+      lang: "de",
+      defaultLang: "de",
+      resolver,
+    });
+    expect(trail).toHaveLength(3);
+    expect(trail[1]).toEqual({ name: "Real Ancestor", url: "https://example.com/de/real/" });
+  });
+
+  it("drops ancestors with empty names", async () => {
+    const resolver: BreadcrumbAncestorResolver = {
+      resolveAncestors: async () => [
+        { name: "  ", url: "https://example.com/de/empty/" },
+        { name: "Valid", url: "https://example.com/de/valid/" },
+      ],
+    };
+    const trail = await buildBreadcrumbTrail({
+      pageId: "page",
+      pageTitle: "Page",
+      selfUrl: "https://example.com/de/page/",
+      homeLabel: "Home",
+      homeUrl: "https://example.com/de/",
+      lang: "de",
+      defaultLang: "de",
+      resolver,
+    });
+    expect(trail).toHaveLength(3);
+    expect(trail[1]).toEqual({ name: "Valid", url: "https://example.com/de/valid/" });
+  });
+});

package/src/share/semantic/tests/build-page.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import { buildSemanticPageModelWith } from "../build-page.ts";
+import type { SemanticContentReader } from "../build-page.ts";
+
+function makeReader(overrides: Partial<SemanticContentReader> = {}): SemanticContentReader {
+  return {
+    getPageFrontmatter: async () => ({
+      title: "Test Page",
+      description: "A test page",
+      blocks: [],
+    }),
+    getProseBody: async () => "",
+    getHomeLabel: async () => "Home",
+    getFaqEntries: async () => [],
+    getDerivedPrices: () => null,
+    ...overrides,
+  };
+}
+
+const baseArgs = {
+  pageId: "test-page",
+  semanticType: "content" as const,
+  lang: "de",
+  url: "https://example.com/de/page/",
+  profile: {
+    organization: { name: "Org", description: "Desc", url: "https://example.com" },
+    people: [],
+    initiatives: [],
+  },
+};
+
+describe("buildSemanticPageModelWith", () => {
+  it("builds a SemanticPageModel from reader frontmatter", async () => {
+    const reader = makeReader();
+    const result = await buildSemanticPageModelWith(reader, baseArgs);
+    expect(result).not.toBeNull();
+    expect(result!.title).toBe("Test Page");
+    expect(result!.description).toBe("A test page");
+    expect(result!.lang).toBe("de");
+  });
+
+  it("returns null when reader returns null frontmatter and no fallback", async () => {
+    const reader = makeReader({ getPageFrontmatter: async () => null });
+    const result = await buildSemanticPageModelWith(reader, baseArgs);
+    expect(result).toBeNull();
+  });
+
+  it("uses fallbackFrontmatter when reader returns null", async () => {
+    const reader = makeReader({ getPageFrontmatter: async () => null });
+    const result = await buildSemanticPageModelWith(reader, {
+      ...baseArgs,
+      fallbackFrontmatter: { title: "Fallback", description: "Fallback desc", blocks: [] },
+    });
+    expect(result).not.toBeNull();
+    expect(result!.title).toBe("Fallback");
+  });
+
+  it("attaches people for about pages", async () => {
+    const reader = makeReader();
+    const result = await buildSemanticPageModelWith(reader, {
+      ...baseArgs,
+      semanticType: "about",
+      profile: {
+        organization: { name: "Org", description: "Desc", url: "https://example.com" },
+        people: [{ name: "Jane", role: "CEO" }],
+        initiatives: [],
+      },
+    });
+    expect(result!.people).toEqual([{ name: "Jane", role: "CEO" }]);
+  });
+
+  it("attaches initiatives for projects pages", async () => {
+    const reader = makeReader();
+    const result = await buildSemanticPageModelWith(reader, {
+      ...baseArgs,
+      semanticType: "projects",
+      profile: {
+        organization: { name: "Org", description: "Desc", url: "https://example.com" },
+        people: [],
+        initiatives: [{ id: "i1", name: "Project", summary: "A project" }],
+      },
+    });
+    expect(result!.initiatives).toEqual([{ id: "i1", name: "Project", summary: "A project" }]);
+  });
+
+  it("attaches FAQ entries for donationContact pages", async () => {
+    const reader = makeReader({
+      getFaqEntries: async () => [{ id: "q1", question: "Q?", answer: "A." }],
+    });
+    const result = await buildSemanticPageModelWith(reader, {
+      ...baseArgs,
+      semanticType: "donationContact",
+    });
+    expect(result!.faqEntries).toEqual([{ id: "q1", question: "Q?", answer: "A." }]);
+  });
+
+  it("uses provided breadcrumbs when supplied", async () => {
+    const reader = makeReader();
+    const result = await buildSemanticPageModelWith(reader, {
+      ...baseArgs,
+      breadcrumbs: [
+        { name: "Home", url: "https://example.com/de/" },
+        { name: "Section", url: "https://example.com/de/section/" },
+        { name: "Page", url: "https://example.com/de/page/" },
+      ],
+    });
+    expect(result!.breadcrumbs).toHaveLength(3);
+  });
+
+  it("resolves price markers in heading and description", async () => {
+    const reader = makeReader({
+      getPageFrontmatter: async () => ({
+        title: "Pricing",
+        description: "Cost: {amount:50}",
+        blocks: [],
+      }),
+    });
+    const result = await buildSemanticPageModelWith(reader, baseArgs);
+    expect(result!.description).toContain("€");
+    expect(result!.description).not.toContain("{amount:");
+  });
+});