@warpgogol/werkstatt-shared 0.14.0 → 0.15.0

package/src/semantic/tests/image-sitemap.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import {
+  generateImageSitemapXml,
+  harvestContentImage,
+  isHtmlRedirectPage,
+  isSyntheticPreviewUrl,
+} from "../image-sitemap.ts";
+
+describe("isHtmlRedirectPage", () => {
+  it("detects meta-refresh redirect", () => {
+    expect(isHtmlRedirectPage('<meta http-equiv="refresh" content="0;url=/de/">')).toBe(true);
+  });
+
+  it("returns false for normal pages", () => {
+    expect(isHtmlRedirectPage("<html><body>Hello</body></html>")).toBe(false);
+  });
+});
+
+describe("isSyntheticPreviewUrl", () => {
+  it("detects preview screenshots", () => {
+    expect(isSyntheticPreviewUrl("https://example.com/preview/page.png")).toBe(true);
+  });
+
+  it("detects og-image fallback", () => {
+    expect(isSyntheticPreviewUrl("https://example.com/og-image.png")).toBe(true);
+  });
+
+  it("returns false for content images", () => {
+    expect(isSyntheticPreviewUrl("https://example.com/_astro/img.jpg")).toBe(false);
+  });
+});
+
+describe("harvestContentImage", () => {
+  it("extracts canonical URL from link tag", () => {
+    const html = '<link rel="canonical" href="https://example.com/de/page" />';
+    const result = harvestContentImage(html, "https://example.com");
+    expect(result.loc).toBe("https://example.com/de/page");
+  });
+
+  it("returns null loc when no canonical", () => {
+    const result = harvestContentImage("<html></html>", "https://example.com");
+    expect(result.loc).toBeNull();
+  });
+
+  it("harvests img with data-content-image attribute", () => {
+    const html = '<img src="/_astro/hero.jpg" data-content-image alt="Hero" />';
+    const result = harvestContentImage(html, "https://example.com");
+    expect(result.imageUrls).toContain("https://example.com/_astro/hero.jpg");
+    expect(result.title).toBe("Hero");
+  });
+
+  it("harvests meta x-content-image", () => {
+    const html = '<meta name="x-content-image" content="https://example.com/img.jpg" />';
+    const result = harvestContentImage(html, "https://example.com");
+    expect(result.imageUrls).toContain("https://example.com/img.jpg");
+  });
+
+  it("excludes synthetic preview URLs", () => {
+    const html = '<img src="/og-image.png" data-content-image alt="OG" />';
+    const result = harvestContentImage(html, "https://example.com");
+    expect(result.imageUrls).toHaveLength(0);
+  });
+
+  it("deduplicates identical URLs", () => {
+    const html = `
+      <img src="/img.jpg" data-content-image alt="A" />
+      <meta name="x-content-image" content="/img.jpg" />
+    `;
+    const result = harvestContentImage(html, "https://example.com");
+    expect(result.imageUrls).toHaveLength(1);
+  });
+
+  it("falls back to og:image:alt for title", () => {
+    const html = `
+      <img src="/img.jpg" data-content-image />
+      <meta property="og:image:alt" content="OG Alt" />
+    `;
+    const result = harvestContentImage(html, "https://example.com");
+    expect(result.title).toBe("OG Alt");
+  });
+});
+
+describe("generateImageSitemapXml", () => {
+  it("produces valid image sitemap XML", () => {
+    const result = generateImageSitemapXml([
+      { loc: "https://example.com/page", imageUrl: "https://example.com/img.jpg", title: "Test" },
+    ]);
+    expect(result).toContain('<?xml version="1.0"');
+    expect(result).toContain("<urlset");
+    expect(result).toContain("xmlns:image=");
+    expect(result).toContain("<loc>https://example.com/page</loc>");
+    expect(result).toContain("<image:loc>https://example.com/img.jpg</image:loc>");
+    expect(result).toContain("<image:title>Test</image:title>");
+  });
+
+  it("produces empty urlset for no entries", () => {
+    const result = generateImageSitemapXml([]);
+    expect(result).toContain("<urlset");
+    expect(result).not.toContain("<url>");
+  });
+
+  it("escapes XML in URLs", () => {
+    const result = generateImageSitemapXml([
+      { loc: "https://example.com/a&b", imageUrl: "https://example.com/<img>" },
+    ]);
+    expect(result).toContain("a&amp;b");
+    expect(result).toContain("&lt;img&gt;");
+  });
+});

package/src/{share → semantic}/tests/jsonld-service.test.ts

@@ -12,8 +12,8 @@
 */
 
 import { describe, expect, it } from "vitest";
-import { buildJsonLd } from "../semantic/jsonld.ts";
-import type { SemanticPageModel, SemanticOrganization } from "../semantic/models.ts";
+import { buildJsonLd } from "../jsonld.ts";
+import type { SemanticPageModel, SemanticOrganization } from "../models.ts";
 
 function makeOrg(): SemanticOrganization {
   return {

package/src/{share → semantic}/tests/jsonld-video.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "vitest";
-import { buildVideoObjectNodes } from "../semantic/jsonld/video.ts";
-import { createJsonLdContext } from "../semantic/jsonld/context.ts";
-import type { SemanticPageModel, VideoSeoData } from "../semantic/models.ts";
+import { buildVideoObjectNodes } from "../jsonld/video.ts";
+import { createJsonLdContext } from "../jsonld/context.ts";
+import type { SemanticPageModel, VideoSeoData } from "../models.ts";
 
 /*
 <MODULE_CONTRACT>

package/src/{share → semantic}/tests/jsonld-webpage.test.ts

@@ -8,9 +8,9 @@
 */
 
 import { describe, expect, it } from "vitest";
-import { buildWebPageNode } from "../semantic/jsonld/webpage.ts";
-import { createJsonLdContext } from "../semantic/jsonld/context.ts";
-import type { SemanticPageModel, SemanticOrganization } from "../semantic/models.ts";
+import { buildWebPageNode } from "../jsonld/webpage.ts";
+import { createJsonLdContext } from "../jsonld/context.ts";
+import type { SemanticPageModel, SemanticOrganization } from "../models.ts";
 
 function makeModel(overrides: Partial<SemanticPageModel> = {}): SemanticPageModel {
   const org: SemanticOrganization = {

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

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { buildJsonLd } from "../jsonld.ts";
+import { makePage } from "./helpers.ts";
+
+describe("buildJsonLd", () => {
+  it("produces a valid JSON-LD document with @context and @graph", () => {
+    const page = makePage();
+    const doc = buildJsonLd(page);
+    expect(doc["@context"]).toBe("https://schema.org");
+    expect(Array.isArray(doc["@graph"])).toBe(true);
+    expect(doc["@graph"].length).toBeGreaterThan(0);
+  });
+
+  it("includes Organization and WebSite nodes in graph", () => {
+    const page = makePage();
+    const doc = buildJsonLd(page);
+    const types = doc["@graph"].map((n) => n["@type"]);
+    expect(types.some((t) => Array.isArray(t) && t.includes("Organization"))).toBe(true);
+    expect(types.some((t) => t === "WebSite" || (Array.isArray(t) && t.includes("WebSite")))).toBe(
+      true,
+    );
+  });
+
+  it("includes WebPage node in graph", () => {
+    const page = makePage();
+    const doc = buildJsonLd(page);
+    const types = doc["@graph"].map((n) => n["@type"]);
+    expect(types.some((t) => Array.isArray(t) && t.includes("WebPage"))).toBe(true);
+  });
+
+  it("deduplicates graph nodes by @id", () => {
+    const page = makePage();
+    const doc = buildJsonLd(page);
+    const ids = doc["@graph"].map((n) => n["@id"]).filter(Boolean);
+    const uniqueIds = new Set(ids);
+    expect(ids.length).toBe(uniqueIds.size);
+  });
+
+  it("includes BreadcrumbList when breadcrumbs > 1", () => {
+    const page = makePage({
+      breadcrumbs: [
+        { name: "Home", url: "https://example.com/de/" },
+        { name: "About", url: "https://example.com/de/about/" },
+      ],
+    });
+    const doc = buildJsonLd(page);
+    const types = doc["@graph"].map((n) => n["@type"]);
+    expect(types).toContain("BreadcrumbList");
+  });
+
+  it("includes extraGraphNodes when provided", () => {
+    const page = makePage({
+      extraGraphNodes: [
+        { "@type": "SoftwareApplication", "@id": "https://example.com/#/schema/app", name: "App" },
+      ],
+    });
+    const doc = buildJsonLd(page);
+    const ids = doc["@graph"].map((n) => n["@id"]);
+    expect(ids).toContain("https://example.com/#/schema/app");
+  });
+});

package/src/{share → semantic}/tests/llms-0789.test.ts

@@ -12,8 +12,8 @@
 */
 
 import { test, expect } from "vitest";
-import { buildLlmsIndex } from "../semantic/llms.ts";
-import type { SemanticSiteModel } from "../semantic/models.ts";
+import { buildLlmsIndex } from "../llms.ts";
+import type { SemanticSiteModel } from "../models.ts";
 
 function makeSite(overrides: Partial<SemanticSiteModel> = {}): SemanticSiteModel {
   return {

package/src/semantic/tests/llms-policy.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { LLMS_DEPTH_BY_SEMANTIC_TYPE, resolveLlmsPolicy } from "../llms-policy.ts";
+
+describe("resolveLlmsPolicy", () => {
+  it("returns full depth by default", () => {
+    expect(resolveLlmsPolicy(undefined, "content")).toEqual({ depth: "full" });
+  });
+
+  it("uses type default for openSource", () => {
+    expect(resolveLlmsPolicy(undefined, "openSource")).toEqual({ depth: "index-only" });
+  });
+
+  it("uses type default for legal", () => {
+    expect(resolveLlmsPolicy(undefined, "legal")).toEqual({ depth: "exclude" });
+  });
+
+  it("accepts string shorthand", () => {
+    expect(resolveLlmsPolicy("summary", "content")).toEqual({ depth: "summary" });
+  });
+
+  it("falls back to type default for invalid string depth", () => {
+    expect(resolveLlmsPolicy("invalid" as never, "openSource")).toEqual({ depth: "index-only" });
+  });
+
+  it("accepts object form with valid depth", () => {
+    expect(resolveLlmsPolicy({ depth: "exclude" }, "content")).toEqual({ depth: "exclude" });
+  });
+
+  it("includes section excludes when provided", () => {
+    const result = resolveLlmsPolicy(
+      { depth: "summary", sections: { exclude: ["s1", "s2"] } },
+      "content",
+    );
+    expect(result.depth).toBe("summary");
+    expect(result.sections?.exclude).toEqual(["s1", "s2"]);
+  });
+
+  it("filters empty section exclude ids", () => {
+    const result = resolveLlmsPolicy(
+      { depth: "summary", sections: { exclude: ["s1", ""] } },
+      "content",
+    );
+    expect(result.sections?.exclude).toEqual(["s1"]);
+  });
+
+  it("omits sections when no valid excludes", () => {
+    const result = resolveLlmsPolicy({ depth: "summary", sections: { exclude: [] } }, "content");
+    expect(result.sections).toBeUndefined();
+  });
+});
+
+describe("LLMS_DEPTH_BY_SEMANTIC_TYPE", () => {
+  it("maps openSource to index-only", () => {
+    expect(LLMS_DEPTH_BY_SEMANTIC_TYPE.openSource).toBe("index-only");
+  });
+
+  it("maps legal to exclude", () => {
+    expect(LLMS_DEPTH_BY_SEMANTIC_TYPE.legal).toBe("exclude");
+  });
+});

package/src/semantic/tests/llms.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from "vitest";
+import { buildLlmsFull, buildLlmsIndex } from "../llms.ts";
+import { makePage } from "./helpers.ts";
+import type { SemanticSiteModel } from "../models.ts";
+import type { SemanticClaimProvenance } from "../business-projection.ts";
+
+function makeSite(overrides: Partial<SemanticSiteModel> = {}): SemanticSiteModel {
+  const page = makePage();
+  return {
+    organization: page.organization,
+    baseUrl: "https://example.com",
+    defaultLanguage: "de",
+    lang: "de",
+    pages: [page],
+    ...overrides,
+  };
+}
+
+describe("buildLlmsIndex", () => {
+  it("produces llms.txt with site name and description", () => {
+    const site = makeSite();
+    const result = buildLlmsIndex(site);
+    expect(result).toContain("# Warpgogol");
+    expect(result).toContain("Digital infrastructure for nonprofits");
+    expect(result).toContain("## Primary sources");
+  });
+
+  it("includes llms-full.txt reference", () => {
+    const site = makeSite();
+    const result = buildLlmsIndex(site);
+    expect(result).toContain("llms-full.txt");
+  });
+
+  it("includes page links with absolute URLs", () => {
+    const site = makeSite();
+    const result = buildLlmsIndex(site);
+    expect(result).toContain("https://example.com");
+  });
+
+  it("filters out excluded pages from index", () => {
+    const page = makePage({
+      output: {
+        sitemap: { include: true, category: "content", includeLastmod: true },
+        llms: { depth: "exclude" },
+        robots: { index: true, follow: true },
+      },
+    });
+    const site = makeSite({ pages: [page] });
+    const result = buildLlmsIndex(site);
+    expect(result).not.toContain("Test Page");
+  });
+
+  it("includes agent discovery links when agent.enabled is not false", () => {
+    const site = makeSite();
+    const result = buildLlmsIndex(site);
+    expect(result).toContain("agent.json");
+  });
+
+  it("omits agent discovery links when agent.enabled is false", () => {
+    const site = makeSite({ agent: { enabled: false } } as never);
+    const result = buildLlmsIndex(site);
+    expect(result).not.toContain("agent.json");
+  });
+
+  it("includes organization facts section", () => {
+    const site = makeSite();
+    const result = buildLlmsIndex(site);
+    expect(result).toContain("## Organization");
+  });
+});
+
+describe("buildLlmsFull", () => {
+  it("produces llms-full.txt with site name and description", () => {
+    const site = makeSite();
+    const result = buildLlmsFull(site);
+    expect(result).toContain("# Warpgogol");
+    expect(result).toContain("Digital infrastructure for nonprofits");
+  });
+
+  it("includes page sections for full depth pages", () => {
+    const site = makeSite();
+    const result = buildLlmsFull(site);
+    expect(result).toContain("## Test Heading");
+  });
+
+  it("includes page header but not body for summary depth", () => {
+    const page = makePage({
+      output: {
+        sitemap: { include: true, category: "content", includeLastmod: true },
+        llms: { depth: "summary" },
+        robots: { index: true, follow: true },
+      },
+    });
+    const site = makeSite({ pages: [page] });
+    const result = buildLlmsFull(site);
+    expect(result).toContain("## Test Heading");
+    expect(result).toContain("URL:");
+    expect(result).toContain("Description:");
+  });
+
+  it("filters out excluded pages", () => {
+    const page = makePage({
+      output: {
+        sitemap: { include: true, category: "content", includeLastmod: true },
+        llms: { depth: "exclude" },
+        robots: { index: true, follow: true },
+      },
+    });
+    const site = makeSite({ pages: [page] });
+    const result = buildLlmsFull(site);
+    expect(result).not.toContain("## Test Page");
+  });
+
+  it("includes organization facts section", () => {
+    const site = makeSite();
+    const result = buildLlmsFull(site);
+    expect(result).toContain("## Organization facts");
+  });
+
+  it("includes claims section when claims are present", () => {
+    const claims: SemanticClaimProvenance[] = [
+      {
+        id: "c1",
+        claimClass: "factual",
+        claimKind: "fact",
+        statement: "We are certified",
+        verificationLevel: "N2",
+        confidence: "high",
+        evidence: [{ id: "ev1", kind: "certificate", label: "ISO 27001", sha256: "abc123" }],
+      },
+    ];
+    const site = makeSite({ claims });
+    const result = buildLlmsFull(site);
+    expect(result).toContain("## Claims");
+    expect(result).toContain("### We are certified");
+    expect(result).toContain("- Class: factual");
+    expect(result).toContain("- Verification: N2");
+    expect(result).toContain("- Confidence: high");
+    expect(result).toContain("- Evidence:");
+    expect(result).toContain("certificate: ISO 27001");
+    expect(result).toContain("sha256: abc123");
+  });
+
+  it("omits claims section when no claims", () => {
+    const site = makeSite();
+    const result = buildLlmsFull(site);
+    expect(result).not.toContain("## Claims");
+  });
+
+  it("shows Evidence: none when claim has no evidence", () => {
+    const claims: SemanticClaimProvenance[] = [
+      {
+        id: "c1",
+        claimClass: "factual",
+        claimKind: "fact",
+        statement: "Unevidenced claim",
+        evidence: [],
+      },
+    ];
+    const site = makeSite({ claims });
+    const result = buildLlmsFull(site);
+    expect(result).toContain("- Evidence: none");
+  });
+});

package/src/semantic/tests/markdown-hygiene.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import {
+  canonicalizeGeneratedMarkdownText,
+  formatGeneratedMarkdownListItem,
+  normalizeGeneratedMarkdownText,
+} from "../markdown-hygiene.ts";
+
+describe("normalizeGeneratedMarkdownText", () => {
+  it("returns empty string for undefined", () => {
+    expect(normalizeGeneratedMarkdownText(undefined)).toBe("");
+  });
+
+  it("normalizes CRLF to LF", () => {
+    expect(normalizeGeneratedMarkdownText("a\r\nb")).toBe("a\nb");
+  });
+
+  it("converts <br> tags to newlines", () => {
+    expect(normalizeGeneratedMarkdownText("a<br>b")).toBe("a\nb");
+    expect(normalizeGeneratedMarkdownText("a<br/>b")).toBe("a\nb");
+  });
+
+  it("converts date slashes to ISO format", () => {
+    expect(normalizeGeneratedMarkdownText("2024/1/5")).toBe("2024-01-05");
+    expect(normalizeGeneratedMarkdownText("2024/12/15")).toBe("2024-12-15");
+  });
+
+  it("fixes - --- to ---", () => {
+    expect(normalizeGeneratedMarkdownText("- ---\n")).toBe("---");
+  });
+
+  it("fixes - - to - ", () => {
+    expect(normalizeGeneratedMarkdownText("- - item")).toBe("- item");
+  });
+
+  it("fixes - # to #", () => {
+    expect(normalizeGeneratedMarkdownText("- ## Heading")).toBe("## Heading");
+  });
+
+  it("trims trailing whitespace", () => {
+    expect(normalizeGeneratedMarkdownText("text   \n")).toBe("text");
+  });
+});
+
+describe("canonicalizeGeneratedMarkdownText", () => {
+  it("strips default language prefix from URLs", () => {
+    const result = canonicalizeGeneratedMarkdownText("Link to [page](https://example.com/de/page)", {
+      baseUrl: "https://example.com",
+      defaultLanguage: "de",
+    });
+    expect(result).toBe("Link to [page](https://example.com/page)");
+  });
+
+  it("does not strip when no baseUrl/defaultLanguage", () => {
+    const result = canonicalizeGeneratedMarkdownText("https://example.com/de/page");
+    expect(result).toBe("https://example.com/de/page");
+  });
+});
+
+describe("formatGeneratedMarkdownListItem", () => {
+  it("wraps plain text as list item", () => {
+    expect(formatGeneratedMarkdownListItem("Simple text")).toEqual(["- Simple text"]);
+  });
+
+  it("returns empty array for empty text", () => {
+    expect(formatGeneratedMarkdownListItem("")).toEqual([]);
+  });
+
+  it("splits markdown blocks into lines", () => {
+    const result = formatGeneratedMarkdownListItem("## Heading\n\nParagraph");
+    expect(result).toEqual(["## Heading", "", "Paragraph"]);
+  });
+});

package/src/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/organization-jsonld.test.ts

@@ -8,9 +8,9 @@
 */
 
 import { describe, expect, it } from "vitest";
-import { buildOrganizationNode } from "../semantic/jsonld/organization.ts";
-import { createJsonLdContext } from "../semantic/jsonld/context.ts";
-import type { SemanticPageModel, SemanticOrganization } from "../semantic/models.ts";
+import { buildOrganizationNode } from "../jsonld/organization.ts";
+import { createJsonLdContext } from "../jsonld/context.ts";
+import type { SemanticPageModel, SemanticOrganization } from "../models.ts";
 
 function makeOrgWithPrices(
   prices: Array<{ id: string; label: string; amount: string; currency?: string }>,