@warpgogol/werkstatt-shared 0.14.0 → 0.14.1

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

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { buildMarkdownPageSemantic } from "../page-builders/markdown-page.ts";
+
+const baseInput = {
+  type: "content" as const,
+  lang: "de",
+  url: "https://example.com/de/page/",
+  title: "Test Page",
+  description: "A test page",
+  heading: "Test Heading",
+  blocks: [],
+};
+
+describe("buildMarkdownPageSemantic", () => {
+  it("builds a SemanticPageModel with canonical URL", () => {
+    const result = buildMarkdownPageSemantic(baseInput);
+    expect(result.type).toBe("content");
+    expect(result.lang).toBe("de");
+    expect(result.url).toBe("https://example.com/de/page/");
+    expect(result.title).toBe("Test Page");
+    expect(result.description).toBe("A test page");
+    expect(result.heading).toBe("Test Heading");
+  });
+
+  it("builds flat breadcrumb fallback when no breadcrumbs provided", () => {
+    const result = buildMarkdownPageSemantic({
+      ...baseInput,
+      breadcrumbsContent: { homeLabel: "Start" },
+    });
+    expect(result.breadcrumbs).toHaveLength(2);
+    expect(result.breadcrumbs[0]).toEqual({ name: "Start", url: "https://example.com/de/" });
+    expect(result.breadcrumbs[1]).toEqual({ name: "Test Heading", url: "https://example.com/de/page/" });
+  });
+
+  it("uses provided breadcrumbs when available", () => {
+    const result = buildMarkdownPageSemantic({
+      ...baseInput,
+      breadcrumbs: [
+        { name: "Home", url: "https://example.com/de/" },
+        { name: "Section", url: "https://example.com/de/section/" },
+        { name: "Page", url: "https://example.com/de/section/page/" },
+      ],
+    });
+    expect(result.breadcrumbs).toHaveLength(3);
+    expect(result.breadcrumbs[1]).toEqual({ name: "Section", url: "https://example.com/de/section/" });
+  });
+
+  it("passes through blocks", () => {
+    const blocks = [{ id: "b1", blockType: "prose", heading: "Block 1" }];
+    const result = buildMarkdownPageSemantic({ ...baseInput, blocks });
+    expect(result.blocks).toBe(blocks);
+  });
+
+  it("passes through people and initiatives", () => {
+    const result = buildMarkdownPageSemantic({
+      ...baseInput,
+      people: [{ name: "Jane", role: "CEO" }],
+      initiatives: [{ id: "i1", name: "Project", summary: "A project" }],
+    });
+    expect(result.people).toEqual([{ name: "Jane", role: "CEO" }]);
+    expect(result.initiatives).toEqual([{ id: "i1", name: "Project", summary: "A project" }]);
+  });
+
+  it("passes through faqEntries when provided", () => {
+    const result = buildMarkdownPageSemantic({
+      ...baseInput,
+      faqEntries: [{ id: "q1", question: "Q?", answer: "A." }],
+    });
+    expect(result.faqEntries).toEqual([{ id: "q1", question: "Q?", answer: "A." }]);
+  });
+
+  it("sets faqEntries to undefined when empty", () => {
+    const result = buildMarkdownPageSemantic({
+      ...baseInput,
+      faqEntries: [],
+    });
+    expect(result.faqEntries).toBeUndefined();
+  });
+
+  it("includes audience when provided", () => {
+    const result = buildMarkdownPageSemantic({
+      ...baseInput,
+      audience: "developer",
+    });
+    expect(result.audience).toBe("developer");
+  });
+
+  it("omits audience when not provided", () => {
+    const result = buildMarkdownPageSemantic(baseInput);
+    expect(result.audience).toBeUndefined();
+  });
+
+  it("uses default Home label when no breadcrumbsContent", () => {
+    const result = buildMarkdownPageSemantic(baseInput);
+    expect(result.breadcrumbs[0].name).toBe("Home");
+  });
+});

package/src/share/semantic/tests/markdown-twin-provenance.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from "vitest";
+import {
+  AUDIENCE_BY_PAGE_TYPE,
+  buildMarkdownTwin,
+  buildMarkdownTwinFrontmatter,
+  computeContentHash,
+  parseMarkdownTwinFrontmatter,
+  verifyMarkdownTwinHash,
+  type MarkdownTwinProvenance,
+} from "../markdown-twin-provenance.ts";
+
+const baseProvenance: MarkdownTwinProvenance = {
+  canonical: "https://example.com/de/page",
+  language: "de",
+  lastModified: "2024-01-15",
+  license: "CC-BY-4.0",
+  generator: "test",
+  sourceKind: "authored",
+};
+
+describe("computeContentHash", () => {
+  it("produces sha256: prefix", () => {
+    expect(computeContentHash("body text").startsWith("sha256:")).toBe(true);
+  });
+
+  it("is deterministic for same input", () => {
+    expect(computeContentHash("body")).toBe(computeContentHash("body"));
+  });
+
+  it("normalizes trailing whitespace", () => {
+    expect(computeContentHash("body\n\n")).toBe(computeContentHash("body"));
+  });
+
+  it("normalizes CRLF to LF", () => {
+    expect(computeContentHash("a\r\nb")).toBe(computeContentHash("a\nb"));
+  });
+});
+
+describe("buildMarkdownTwinFrontmatter", () => {
+  it("includes all core provenance fields", () => {
+    const fm = buildMarkdownTwinFrontmatter(baseProvenance, "sha256:abc");
+    expect(fm).toContain('canonical: "https://example.com/de/page"');
+    expect(fm).toContain('language: "de"');
+    expect(fm).toContain('lastModified: "2024-01-15"');
+    expect(fm).toContain('contentHash: "sha256:abc"');
+    expect(fm).toContain('license: "CC-BY-4.0"');
+    expect(fm).toContain('generator: "test"');
+    expect(fm).toContain('sourceKind: "authored"');
+    expect(fm).toContain('schema: "gogol.markdown-twin@2"');
+  });
+
+  it("emits null for lastModified when null", () => {
+    const fm = buildMarkdownTwinFrontmatter(
+      { ...baseProvenance, lastModified: null },
+      "sha256:abc",
+    );
+    expect(fm).toContain("lastModified: null");
+  });
+
+  it("includes pageId when provided", () => {
+    const fm = buildMarkdownTwinFrontmatter(
+      { ...baseProvenance, pageId: "about" },
+      "sha256:abc",
+    );
+    expect(fm).toContain('pageId: "about"');
+  });
+
+  it("includes sourceInputs when provided", () => {
+    const fm = buildMarkdownTwinFrontmatter(
+      { ...baseProvenance, sourceInputs: ["file1.md", "file2.md"] },
+      "sha256:abc",
+    );
+    expect(fm).toContain('sourceInputs:');
+    expect(fm).toContain('"file1.md"');
+  });
+
+  it("includes semantic meta when provided", () => {
+    const fm = buildMarkdownTwinFrontmatter(
+      {
+        ...baseProvenance,
+        semantic: {
+          id: "page-1",
+          route: "/de/page",
+          title: "Page",
+          type: "content",
+          domain: "content",
+          audience: "general",
+          lang: "de",
+          metaDescription: "A page",
+          priority: 0.7,
+          tags: ["tag1"],
+        },
+      },
+      "sha256:abc",
+    );
+    expect(fm).toContain('id: "page-1"');
+    expect(fm).toContain('type: "content"');
+    expect(fm).toContain("priority: 0.7");
+  });
+});
+
+describe("buildMarkdownTwin", () => {
+  it("produces frontmatter + body", () => {
+    const twin = buildMarkdownTwin("# Hello\n\nWorld", baseProvenance);
+    expect(twin.startsWith("---\n")).toBe(true);
+    expect(twin).toContain("# Hello");
+    expect(twin).toContain("World");
+  });
+});
+
+describe("parseMarkdownTwinFrontmatter", () => {
+  it("round-trips buildMarkdownTwin output", () => {
+    const body = "# Hello\n\nWorld";
+    const twin = buildMarkdownTwin(body, baseProvenance);
+    const parsed = parseMarkdownTwinFrontmatter(twin);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.frontmatter.canonical).toBe("https://example.com/de/page");
+    expect(parsed!.frontmatter.language).toBe("de");
+    expect(parsed!.body).toBe("# Hello\n\nWorld\n");
+  });
+
+  it("returns null for no frontmatter", () => {
+    expect(parseMarkdownTwinFrontmatter("just text")).toBeNull();
+  });
+});
+
+describe("verifyMarkdownTwinHash", () => {
+  it("verifies correct hash", () => {
+    const twin = buildMarkdownTwin("# Hello", baseProvenance);
+    expect(verifyMarkdownTwinHash(twin)).toBe(true);
+  });
+
+  it("fails for tampered body", () => {
+    const twin = buildMarkdownTwin("# Hello", baseProvenance);
+    const tampered = twin.replace("# Hello", "# Tampered");
+    expect(verifyMarkdownTwinHash(tampered)).toBe(false);
+  });
+});
+
+describe("AUDIENCE_BY_PAGE_TYPE", () => {
+  it("maps home to general", () => {
+    expect(AUDIENCE_BY_PAGE_TYPE.home).toBe("general");
+  });
+
+  it("maps projects to developer", () => {
+    expect(AUDIENCE_BY_PAGE_TYPE.projects).toBe("developer");
+  });
+
+  it("maps legal to business_owner", () => {
+    expect(AUDIENCE_BY_PAGE_TYPE.legal).toBe("business_owner");
+  });
+});

package/src/share/semantic/tests/organization-profile.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+import { buildOrganizationProfile } from "../organization-profile.ts";
+
+const baseInput = {
+  lang: "de",
+  siteUrl: "https://example.com",
+  brandName: "Warpgogol",
+  description: "Digital infrastructure",
+  founders: [],
+  boardMembers: [],
+};
+
+describe("buildOrganizationProfile", () => {
+  it("builds organization with canonical root URL", () => {
+    const result = buildOrganizationProfile(baseInput);
+    expect(result.organization.name).toBe("Warpgogol");
+    expect(result.organization.url).toBe("https://example.com/");
+    expect(result.organization.description).toBe("Digital infrastructure");
+  });
+
+  it("emits image as og-image.png absolute URL", () => {
+    const result = buildOrganizationProfile(baseInput);
+    expect(result.organization.image).toBe("https://example.com/og-image.png");
+  });
+
+  it("deduplicates people by name", () => {
+    const result = buildOrganizationProfile({
+      ...baseInput,
+      founders: [{ name: "Jane" }, { name: "John" }],
+      boardMembers: [{ name: "Jane" }, { name: "Bob" }],
+    });
+    expect(result.people.map((p) => p.name).sort()).toEqual(["Bob", "Jane", "John"]);
+  });
+
+  it("prefers team over founders+board when available", () => {
+    const result = buildOrganizationProfile({
+      ...baseInput,
+      founders: [{ name: "Founder" }],
+      boardMembers: [{ name: "Board" }],
+      team: [{ name: "Team Member" }],
+    });
+    expect(result.people).toHaveLength(1);
+    expect(result.people[0].name).toBe("Team Member");
+  });
+
+  it("builds address from primitives", () => {
+    const result = buildOrganizationProfile({
+      ...baseInput,
+      address: { street: "Test St", streetNumber: "1", zip: "12345", city: "Berlin", country: "DE" },
+    });
+    expect(result.organization.address).toEqual({
+      streetAddress: "Test St 1",
+      postalCode: "12345",
+      addressLocality: "Berlin",
+      addressCountry: "DE",
+    });
+  });
+
+  it("emits contactPoints when email or contactType provided", () => {
+    const result = buildOrganizationProfile({
+      ...baseInput,
+      email: "info@example.com",
+      contactType: "support",
+    });
+    expect(result.organization.contactPoints).toEqual([
+      { contactType: "support", email: "info@example.com" },
+    ]);
+  });
+
+  it("emits donationAccount from bank primitives", () => {
+    const result = buildOrganizationProfile({
+      ...baseInput,
+      bank: { accountHolder: "Org", iban: "DE00", bic: "BIC", bankName: "Bank", konto: "1", blz: "2" },
+    });
+    expect(result.organization.donationAccount).toEqual({
+      accountHolder: "Org",
+      iban: "DE00",
+      bic: "BIC",
+      bankName: "Bank",
+      accountNumber: "1",
+      bankCode: "2",
+    });
+  });
+
+  it("emits sameAs and logo when provided", () => {
+    const result = buildOrganizationProfile({
+      ...baseInput,
+      sameAs: ["https://twitter.com/example"],
+      logoUrl: "https://example.com/logo.png",
+    });
+    expect(result.organization.sameAs).toEqual(["https://twitter.com/example"]);
+    expect(result.organization.logo).toBe("https://example.com/logo.png");
+  });
+
+  it("emits schemaType override", () => {
+    const result = buildOrganizationProfile({
+      ...baseInput,
+      schemaType: ["Organization", "ProfessionalService"],
+    });
+    expect(result.organization.schemaType).toEqual(["Organization", "ProfessionalService"]);
+  });
+
+  it("returns empty initiatives array", () => {
+    const result = buildOrganizationProfile(baseInput);
+    expect(result.initiatives).toEqual([]);
+  });
+});

package/src/share/semantic/tests/output-projection.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { resolvePageOutput } from "../output-projection.ts";
+
+describe("resolvePageOutput", () => {
+  it("returns defaults for undefined input", () => {
+    const result = resolvePageOutput(undefined);
+    expect(result.sitemap.include).toBe(true);
+    expect(result.sitemap.category).toBe("content");
+    expect(result.sitemap.includeLastmod).toBe(true);
+    expect(result.robots.index).toBe(true);
+    expect(result.robots.follow).toBe(true);
+    expect(result.llms.depth).toBe("full");
+  });
+
+  it("handles sitemap: false boolean shorthand", () => {
+    const result = resolvePageOutput({ sitemap: false });
+    expect(result.sitemap.include).toBe(false);
+  });
+
+  it("handles sitemap object form", () => {
+    const result = resolvePageOutput({
+      sitemap: { include: false, category: "custom", lastmod: "2024-01-01", includeLastmod: false },
+    });
+    expect(result.sitemap.include).toBe(false);
+    expect(result.sitemap.category).toBe("custom");
+    expect(result.sitemap.lastmod).toBe("2024-01-01");
+    expect(result.sitemap.includeLastmod).toBe(false);
+  });
+
+  it("uses legal category for legal semanticType", () => {
+    const result = resolvePageOutput({}, { semanticType: "legal" });
+    expect(result.sitemap.category).toBe("legal");
+  });
+
+  it("handles robots: false boolean shorthand", () => {
+    const result = resolvePageOutput({ robots: false });
+    expect(result.robots.index).toBe(false);
+    expect(result.robots.follow).toBe(false);
+  });
+
+  it("handles robots object form", () => {
+    const result = resolvePageOutput({ robots: { index: false, follow: true } });
+    expect(result.robots.index).toBe(false);
+    expect(result.robots.follow).toBe(true);
+  });
+
+  it("handles llms string shorthand", () => {
+    const result = resolvePageOutput({ llms: "index-only" });
+    expect(result.llms.depth).toBe("index-only");
+  });
+
+  it("handles llms object form with sections", () => {
+    const result = resolvePageOutput({
+      llms: { depth: "summary", sections: { exclude: ["section-1", "section-2"] } },
+    });
+    expect(result.llms.depth).toBe("summary");
+    expect(result.llms.sections?.exclude).toEqual(["section-1", "section-2"]);
+  });
+
+  it("resolves content image", () => {
+    const result = resolvePageOutput({
+      image: { url: "https://example.com/img.jpg", alt: "Test", width: 800, height: 600 },
+    });
+    expect(result.image).toEqual({
+      url: "https://example.com/img.jpg",
+      alt: "Test",
+      width: 800,
+      height: 600,
+      contentImage: true,
+    });
+  });
+
+  it("omits image when url is empty", () => {
+    const result = resolvePageOutput({ image: { url: "" } });
+    expect(result.image).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { buildPageMarkdown } from "../page-markdown.ts";
+import { makePage } from "./helpers.ts";
+
+describe("buildPageMarkdown", () => {
+  it("produces markdown with page title as h1", () => {
+    const page = makePage({ title: "Test Page" });
+    const result = buildPageMarkdown(page);
+    expect(result).toContain("# Test Page");
+  });
+
+  it("includes Summary section from lead", () => {
+    const page = makePage({ lead: "This is the lead text." });
+    const result = buildPageMarkdown(page);
+    expect(result).toContain("## Summary");
+    expect(result).toContain("This is the lead text.");
+  });
+
+  it("falls back to description for summary", () => {
+    const page = makePage({ description: "A test page description" });
+    const result = buildPageMarkdown(page);
+    expect(result).toContain("## Summary");
+    expect(result).toContain("A test page description");
+  });
+
+  it("includes Business context section for generic blocks", () => {
+    const page = makePage({
+      blocks: [
+        {
+          id: "block-1",
+          blockType: "prose",
+          heading: "About Us",
+          summary: "We are great.",
+        },
+      ],
+    });
+    const result = buildPageMarkdown(page);
+    expect(result).toContain("## Business context");
+    expect(result).toContain("### About Us");
+    expect(result).toContain("We are great.");
+  });
+
+  it("classifies legal blocks as Constraints", () => {
+    const page = makePage({
+      blocks: [
+        {
+          id: "block-1",
+          blockType: "prose",
+          heading: "Legal Notice",
+          summary: "Legal info.",
+        },
+      ],
+    });
+    const result = buildPageMarkdown(page);
+    expect(result).toContain("## Constraints");
+    expect(result).toContain("### Legal Notice");
+  });
+
+  it("includes People section when page has people", () => {
+    const page = makePage({
+      people: [{ name: "Jane Doe", role: "CEO", description: "Leader" }],
+    });
+    const result = buildPageMarkdown(page);
+    expect(result).toContain("## People");
+    expect(result).toContain("### Jane Doe");
+    expect(result).toContain("**CEO**");
+  });
+
+  it("includes Initiatives section when page has initiatives", () => {
+    const page = makePage({
+      initiatives: [{ id: "init-1", name: "Project Alpha", summary: "A project" }],
+    });
+    const result = buildPageMarkdown(page);
+    expect(result).toContain("## Initiatives");
+    expect(result).toContain("Project Alpha");
+  });
+
+  it("includes FAQ section when page has faqEntries", () => {
+    const page = makePage({
+      faqEntries: [{ id: "q1", question: "What is this?", answer: "A test." }],
+    });
+    const result = buildPageMarkdown(page);
+    expect(result).toContain("## FAQ");
+    expect(result).toContain("### What is this?");
+    expect(result).toContain("A test.");
+  });
+
+  it("collapses excessive blank lines", () => {
+    const page = makePage({
+      blocks: [
+        { id: "b1", blockType: "prose", heading: "Block 1", summary: "S1" },
+        { id: "b2", blockType: "prose", heading: "Block 2", summary: "S2" },
+      ],
+    });
+    const result = buildPageMarkdown(page);
+    expect(result).not.toMatch(/\n{3,}/);
+  });
+});

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

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import {
+  blocksToMarkdown,
+  extractAnswerBlocksFromMarkdown,
+  toPageEntryId,
+  toSemanticAnswerBlocks,
+} from "../page-utils.ts";
+
+describe("extractAnswerBlocksFromMarkdown", () => {
+  it("extracts h2 sections with content", () => {
+    const md = "## Section 1\n\nContent 1\n\n## Section 2\n\nContent 2";
+    const blocks = extractAnswerBlocksFromMarkdown(md);
+    expect(blocks).toHaveLength(2);
+    expect(blocks[0]).toEqual({ heading: "Section 1", content: "Content 1" });
+    expect(blocks[1]).toEqual({ heading: "Section 2", content: "Content 2" });
+  });
+
+  it("ignores content before first h2", () => {
+    const md = "Intro text\n\n## Section\n\nContent";
+    const blocks = extractAnswerBlocksFromMarkdown(md);
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0].heading).toBe("Section");
+  });
+
+  it("returns empty for no h2", () => {
+    expect(extractAnswerBlocksFromMarkdown("Just text")).toEqual([]);
+  });
+});
+
+describe("blocksToMarkdown", () => {
+  it("converts blocks back to markdown", () => {
+    const blocks = [
+      { heading: "Section 1", content: "Content 1" },
+      { heading: "Section 2", content: "Content 2" },
+    ];
+    expect(blocksToMarkdown(blocks)).toBe("## Section 1\n\nContent 1\n\n## Section 2\n\nContent 2");
+  });
+});
+
+describe("toPageEntryId", () => {
+  it("strips language prefix and .html", () => {
+    expect(toPageEntryId(new URL("https://example.com/de/about.html"))).toBe("about");
+  });
+
+  it("handles nested paths", () => {
+    expect(toPageEntryId(new URL("https://example.com/de/section/page"))).toBe("section-page");
+  });
+
+  it("returns index for root", () => {
+    expect(toPageEntryId(new URL("https://example.com/de/"))).toBe("index");
+  });
+});
+
+describe("toSemanticAnswerBlocks", () => {
+  it("produces SemanticBlock with blockType prose", () => {
+    const blocks = [{ heading: "Section", content: "Summary line\n- fact 1\n- fact 2" }];
+    const result = toSemanticAnswerBlocks(blocks);
+    expect(result).toHaveLength(1);
+    expect(result[0].blockType).toBe("prose");
+    expect(result[0].heading).toBe("Section");
+    expect(result[0].summary).toBe("Summary line");
+    expect(result[0].facts).toEqual(["- fact 1", "- fact 2"]);
+  });
+
+  it("preserves table content as summary", () => {
+    const blocks = [
+      {
+        heading: "Pricing",
+        content: "| Col1 | Col2 |\n| --- | --- |\n| a | b |",
+      },
+    ];
+    const result = toSemanticAnswerBlocks(blocks);
+    expect(result[0].summary).toContain("| Col1 | Col2 |");
+    expect(result[0].facts).toBeUndefined();
+  });
+
+  it("preserves multi-paragraph content as summary", () => {
+    const blocks = [
+      {
+        heading: "Section",
+        content: "First paragraph.\n\nSecond paragraph.",
+      },
+    ];
+    const result = toSemanticAnswerBlocks(blocks);
+    expect(result[0].summary).toBe("First paragraph.\n\nSecond paragraph.");
+    expect(result[0].facts).toBeUndefined();
+  });
+});