@warpgogol/werkstatt-shared 0.14.0 → 0.15.0

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

@@ -0,0 +1,209 @@
+import { describe, expect, it } from "vitest";
+import {
+  extractEmail,
+  extractListFacts,
+  extractLists,
+  extractParagraphs,
+  extractPostalAddress,
+  mergePeople,
+  normalizeWhitespace,
+  splitMarkdownSections,
+  splitSentences,
+} from "../extract.ts";
+
+describe("normalizeWhitespace", () => {
+  it("collapses multiple spaces", () => {
+    expect(normalizeWhitespace("a   b\n  c")).toBe("a b c");
+  });
+});
+
+describe("splitMarkdownSections", () => {
+  it("splits by h2 headings", () => {
+    const md = "## Section 1\n\nBody 1\n\n## Section 2\n\nBody 2";
+    const sections = splitMarkdownSections(md);
+    expect(sections).toHaveLength(2);
+    expect(sections[0]).toEqual({ heading: "Section 1", body: "Body 1" });
+    expect(sections[1]).toEqual({ heading: "Section 2", body: "Body 2" });
+  });
+
+  it("splits by h3 when level=3", () => {
+    const md = "### Sub 1\n\nBody 1\n\n### Sub 2\n\nBody 2";
+    const sections = splitMarkdownSections(md, 3);
+    expect(sections).toHaveLength(2);
+    expect(sections[0].heading).toBe("Sub 1");
+  });
+
+  it("returns empty for empty input", () => {
+    expect(splitMarkdownSections("")).toEqual([]);
+  });
+});
+
+describe("extractParagraphs", () => {
+  it("splits on blank lines", () => {
+    expect(extractParagraphs("Para 1\n\nPara 2\n\nPara 3")).toEqual(["Para 1", "Para 2", "Para 3"]);
+  });
+});
+
+describe("splitSentences", () => {
+  it("splits on period + space + capital", () => {
+    expect(splitSentences("Hello world. Next sentence.")).toEqual([
+      "Hello world.",
+      "Next sentence.",
+    ]);
+  });
+
+  it("handles German abbreviations", () => {
+    const result = splitSentences("Das ist z.B. ein Test. Und noch einer.", "de");
+    expect(result).toHaveLength(2);
+    expect(result[0]).toContain("z.B.");
+  });
+
+  it("handles English abbreviations", () => {
+    const result = splitSentences("See e.g. the docs. For more info.", "en");
+    expect(result).toHaveLength(2);
+  });
+
+  it("skips numbered list markers", () => {
+    const result = splitSentences("1. First item 2. Second item", "en");
+    expect(result).toHaveLength(1);
+  });
+
+  it("returns empty for empty input", () => {
+    expect(splitSentences("")).toEqual([]);
+  });
+});
+
+describe("extractListFacts", () => {
+  it("extracts bullet list items", () => {
+    expect(extractListFacts("- Item 1\n- Item 2")).toEqual(["Item 1", "Item 2"]);
+  });
+
+  it("extracts numbered list items", () => {
+    expect(extractListFacts("1. First\n2. Second")).toEqual(["First", "Second"]);
+  });
+});
+
+describe("extractLists", () => {
+  it("extracts a single bullet list with dash marker", () => {
+    const result = extractLists("- Item 1\n- Item 2\n- Item 3");
+    expect(result).toEqual([{ marker: "-", items: ["Item 1", "Item 2", "Item 3"] }]);
+  });
+
+  it("extracts a single bullet list with asterisk marker", () => {
+    const result = extractLists("* Item 1\n* Item 2");
+    expect(result).toEqual([{ marker: "*", items: ["Item 1", "Item 2"] }]);
+  });
+
+  it("extracts a single bullet list with plus marker", () => {
+    const result = extractLists("+ Item 1\n+ Item 2");
+    expect(result).toEqual([{ marker: "+", items: ["Item 1", "Item 2"] }]);
+  });
+
+  it("extracts an ordered list with digit marker", () => {
+    const result = extractLists("1. First\n2. Second\n3. Third");
+    expect(result).toEqual([{ marker: "digit", items: ["First", "Second", "Third"] }]);
+  });
+
+  it("groups consecutive list lines into a single list", () => {
+    const md = "- Alpha\n- Beta\n- Gamma";
+    const result = extractLists(md);
+    expect(result).toHaveLength(1);
+    expect(result[0].items).toHaveLength(3);
+  });
+
+  it("terminates list on blank line", () => {
+    const md = "- Item 1\n- Item 2\n\nProse text";
+    const result = extractLists(md);
+    expect(result).toHaveLength(1);
+    expect(result[0].items).toEqual(["Item 1", "Item 2"]);
+  });
+
+  it("terminates list on non-list line", () => {
+    const md = "- Item 1\n- Item 2\nSome prose line";
+    const result = extractLists(md);
+    expect(result).toHaveLength(1);
+    expect(result[0].items).toEqual(["Item 1", "Item 2"]);
+  });
+
+  it("separates lists broken by prose", () => {
+    const md = "- List 1 item\n\nSome prose\n\n- List 2 item";
+    const result = extractLists(md);
+    expect(result).toHaveLength(2);
+    expect(result[0].items).toEqual(["List 1 item"]);
+    expect(result[1].items).toEqual(["List 2 item"]);
+  });
+
+  it("skips lines inside fenced code blocks", () => {
+    const md = "- Real item\n\n```text\n- Not a list item\n- Also not\n```\n\n- Another real item";
+    const result = extractLists(md);
+    expect(result).toHaveLength(2);
+    expect(result[0].items).toEqual(["Real item"]);
+    expect(result[1].items).toEqual(["Another real item"]);
+  });
+
+  it("skips indented (nested) list lines — they do not start a new list", () => {
+    const md = "- Top level\n  - Nested item\n  - Another nested\n- Top level 2";
+    const result = extractLists(md);
+    expect(result).toHaveLength(1);
+    expect(result[0].items).toEqual(["Top level", "Top level 2"]);
+  });
+
+  it("returns empty array for empty input", () => {
+    expect(extractLists("")).toEqual([]);
+  });
+
+  it("returns empty array for prose with no lists", () => {
+    expect(extractLists("Just some prose. No lists here.")).toEqual([]);
+  });
+
+  it("separates lists with different marker types", () => {
+    const md = "- Dash item\n* Star item";
+    const result = extractLists(md);
+    expect(result).toHaveLength(2);
+    expect(result[0].marker).toBe("-");
+    expect(result[1].marker).toBe("*");
+  });
+});
+
+describe("extractEmail", () => {
+  it("extracts email from text", () => {
+    expect(extractEmail("Contact us at info@example.com today")).toBe("info@example.com");
+  });
+
+  it("returns undefined when no email", () => {
+    expect(extractEmail("No email here")).toBeUndefined();
+  });
+});
+
+describe("extractPostalAddress", () => {
+  it("extracts address with ZIP", () => {
+    const result = extractPostalAddress("Test Str. 1, 12345 Berlin");
+    expect(result).toEqual({
+      streetAddress: "Test Str. 1",
+      postalCode: "12345",
+      addressLocality: "Berlin",
+      addressCountry: "DE",
+    });
+  });
+
+  it("returns undefined when no match", () => {
+    expect(extractPostalAddress("No address here")).toBeUndefined();
+  });
+});
+
+describe("mergePeople", () => {
+  it("merges and deduplicates by name", () => {
+    const result = mergePeople(
+      [{ name: "Jane", role: "Founder" }],
+      [{ name: "Jane", description: "Bio" }, { name: "John" }],
+    );
+    expect(result).toHaveLength(2);
+    const jane = result.find((p) => p.name === "Jane");
+    expect(jane?.role).toBe("Founder");
+    expect(jane?.description).toBe("Bio");
+  });
+
+  it("handles undefined groups", () => {
+    expect(mergePeople(undefined, [{ name: "A" }])).toEqual([{ name: "A" }]);
+  });
+});

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

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import { buildJsonFeed, buildRssFeed } from "../feed.ts";
+
+const channel = {
+  title: "Test Feed",
+  url: "https://example.com",
+  description: "A test feed",
+  language: "de",
+  selfUrl: "https://example.com/feed.xml",
+};
+
+const items = [
+  { title: "Item 1", url: "https://example.com/1", summary: "Summary 1", publishedAt: "2024-01-01" },
+  { title: "Item 2", url: "https://example.com/2", summary: "Summary 2", publishedAt: "2024-06-01" },
+];
+
+describe("buildRssFeed", () => {
+  it("produces valid RSS XML", () => {
+    const result = buildRssFeed(channel, items);
+    expect(result).toContain('<?xml version="1.0"');
+    expect(result).toContain("<rss version=\"2.0\"");
+    expect(result).toContain("<channel>");
+    expect(result).toContain("<title>Test Feed</title>");
+    expect(result).toContain("<language>de</language>");
+  });
+
+  it("sorts items by publishedAt descending", () => {
+    const result = buildRssFeed(channel, items);
+    const item1Idx = result.indexOf("Item 1");
+    const item2Idx = result.indexOf("Item 2");
+    expect(item2Idx).toBeLessThan(item1Idx);
+  });
+
+  it("escapes XML special characters", () => {
+    const result = buildRssFeed(channel, [
+      { title: "A & B <C>", url: "https://example.com/x", summary: "S", publishedAt: "2024-01-01" },
+    ]);
+    expect(result).toContain("A &amp; B &lt;C&gt;");
+  });
+
+  it("includes atom self link", () => {
+    const result = buildRssFeed(channel, items);
+    expect(result).toContain('href="https://example.com/feed.xml"');
+    expect(result).toContain('rel="self"');
+  });
+
+  it("derives lastBuildDate from latest item", () => {
+    const result = buildRssFeed(channel, items);
+    expect(result).toContain("<lastBuildDate>");
+  });
+
+  it("omits lastBuildDate for empty feed", () => {
+    const result = buildRssFeed(channel, []);
+    expect(result).not.toContain("<lastBuildDate>");
+  });
+});
+
+describe("buildJsonFeed", () => {
+  it("produces JSON Feed v1.1", () => {
+    const result = buildJsonFeed({
+      title: "Test Feed",
+      home_page_url: "https://example.com",
+      feed_url: "https://example.com/feed.json",
+      description: "A test feed",
+      language: "de",
+      items,
+    });
+    const parsed = JSON.parse(result);
+    expect(parsed.version).toBe("https://jsonfeed.org/version/1.1");
+    expect(parsed.title).toBe("Test Feed");
+    expect(parsed.items).toHaveLength(2);
+  });
+
+  it("sorts items by publishedAt descending", () => {
+    const result = buildJsonFeed({
+      title: "Test",
+      home_page_url: "https://example.com",
+      feed_url: "https://example.com/feed.json",
+      description: "",
+      language: "de",
+      items,
+    });
+    const parsed = JSON.parse(result);
+    expect(parsed.items[0].title).toBe("Item 2");
+    expect(parsed.items[1].title).toBe("Item 1");
+  });
+
+  it("includes date_modified when updatedAt provided", () => {
+    const result = buildJsonFeed({
+      title: "Test",
+      home_page_url: "https://example.com",
+      feed_url: "https://example.com/feed.json",
+      description: "",
+      language: "de",
+      items: [{ title: "T", url: "https://example.com/1", summary: "S", publishedAt: "2024-01-01", updatedAt: "2024-06-01" }],
+    });
+    const parsed = JSON.parse(result);
+    expect(parsed.items[0].date_modified).toBe("2024-06-01");
+  });
+
+  it("omits items array for empty feed", () => {
+    const result = buildJsonFeed({
+      title: "Test",
+      home_page_url: "https://example.com",
+      feed_url: "https://example.com/feed.json",
+      description: "",
+      language: "de",
+      items: [],
+    });
+    const parsed = JSON.parse(result);
+    expect(parsed.items).toBeUndefined();
+  });
+});

package/src/semantic/tests/freshness.pbt.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import fc from "fast-check";
+import {
+  calculateAgeDays,
+  isAssessmentStale,
+  isItemStale,
+  DEFAULT_FRESHNESS_WINDOW_DAYS,
+} from "../freshness.ts";
+
+const validTimestamp = fc.integer({ min: 0, max: Date.now() });
+const validDateFromTs = (ts: number) => new Date(ts);
+
+describe("calculateAgeDays — property-based (AC-7)", () => {
+  it("is pure and deterministic — same input always produces same output", () => {
+    fc.assert(
+      fc.property(validTimestamp, validTimestamp, (observedTs, referenceTs) => {
+        const observed = validDateFromTs(observedTs);
+        const reference = validDateFromTs(referenceTs);
+        const a = calculateAgeDays(observed.toISOString(), reference);
+        const b = calculateAgeDays(observed.toISOString(), reference);
+        expect(a).toBe(b);
+      }),
+      { numRuns: 50 },
+    );
+  });
+
+  it("returns non-negative age when reference >= observed", () => {
+    fc.assert(
+      fc.property(
+        validTimestamp,
+        fc.integer({ min: 0, max: 365 * 10 }),
+        (observedTs, daysAfter) => {
+          const observed = validDateFromTs(observedTs);
+          const reference = new Date(observed.getTime() + daysAfter * 86400000);
+          const age = calculateAgeDays(observed.toISOString(), reference);
+          expect(age).toBeGreaterThanOrEqual(0);
+        },
+      ),
+      { numRuns: 50 },
+    );
+  });
+
+  it("returns negative age when reference < observed", () => {
+    fc.assert(
+      fc.property(
+        validTimestamp.filter((ts) => ts > 365 * 10 * 86400000),
+        fc.integer({ min: 1, max: 365 * 10 }),
+        (observedTs, daysBefore) => {
+          const observed = validDateFromTs(observedTs);
+          const reference = new Date(observed.getTime() - daysBefore * 86400000);
+          const age = calculateAgeDays(observed.toISOString(), reference);
+          expect(age).toBeLessThan(0);
+        },
+      ),
+      { numRuns: 50 },
+    );
+  });
+
+  it("returns Number.MAX_SAFE_INTEGER for invalid date strings", () => {
+    fc.assert(
+      fc.property(
+        fc.string().filter((s) => isNaN(new Date(s).getTime())),
+        (invalid) => {
+          expect(calculateAgeDays(invalid)).toBe(Number.MAX_SAFE_INTEGER);
+        },
+      ),
+      { numRuns: 50 },
+    );
+  });
+});
+
+describe("isAssessmentStale", () => {
+  it("returns true when age exceeds maxAgeDays", () => {
+    const reference = new Date("2026-09-12T00:00:00Z");
+    const assessment = {
+      observedAt: "2026-06-01T00:00:00Z",
+      freshness: { maxAgeDays: 90 },
+    };
+    expect(isAssessmentStale(assessment, reference)).toBe(true);
+  });
+
+  it("returns false when age is within maxAgeDays", () => {
+    const reference = new Date("2026-09-12T00:00:00Z");
+    const assessment = {
+      observedAt: "2026-08-01T00:00:00Z",
+      freshness: { maxAgeDays: 90 },
+    };
+    expect(isAssessmentStale(assessment, reference)).toBe(false);
+  });
+});
+
+describe("isItemStale", () => {
+  it("returns false when retrievedAt is missing", () => {
+    expect(isItemStale({}, DEFAULT_FRESHNESS_WINDOW_DAYS)).toBe(false);
+  });
+
+  it("returns true when age exceeds maxAgeDays", () => {
+    const reference = new Date("2026-09-12T00:00:00Z");
+    const item = { retrievedAt: "2026-01-01T00:00:00Z" };
+    expect(isItemStale(item, 180, reference)).toBe(true);
+  });
+
+  it("returns false when age is within maxAgeDays", () => {
+    const reference = new Date("2026-09-12T00:00:00Z");
+    const item = { retrievedAt: "2026-08-01T00:00:00Z" };
+    expect(isItemStale(item, 180, reference)).toBe(false);
+  });
+});

package/src/semantic/tests/helpers.ts

@@ -0,0 +1,32 @@
+import type { SemanticOrganization, SemanticPageModel, SemanticPageType } from "../models.ts";
+
+export function makeOrganization(
+  overrides: Partial<SemanticOrganization> = {},
+): SemanticOrganization {
+  return {
+    name: "Warpgogol",
+    description: "Digital infrastructure for nonprofits",
+    url: "https://example.com",
+    ...overrides,
+  };
+}
+
+export function makePage(
+  overrides: Partial<SemanticPageModel> & { type?: SemanticPageType } = {},
+): SemanticPageModel {
+  return {
+    type: overrides.type ?? "content",
+    lang: "de",
+    url: "https://example.com/de/page/",
+    title: "Test Page",
+    description: "A test page description",
+    heading: "Test Heading",
+    breadcrumbs: [
+      { name: "Home", url: "https://example.com/de/" },
+      { name: "Test Page", url: "https://example.com/de/page/" },
+    ],
+    blocks: [],
+    organization: makeOrganization(),
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import {
+  canonicalRootUrl,
+  createSemanticIds,
+  getBaseUrl,
+  markdownTwinRelPath,
+  markdownTwinUrlPath,
+  toAbsoluteUrl,
+  toCanonicalUrl,
+  toPathname,
+} from "../ids.ts";
+
+describe("getBaseUrl", () => {
+  it("returns origin from string URL", () => {
+    expect(getBaseUrl("https://example.com/de/page")).toBe("https://example.com");
+  });
+
+  it("returns origin from URL object", () => {
+    expect(getBaseUrl(new URL("https://example.com/de/page?q=1"))).toBe("https://example.com");
+  });
+});
+
+describe("toCanonicalUrl", () => {
+  it("strips search and hash", () => {
+    expect(toCanonicalUrl("https://example.com/de/page?q=1#top")).toBe(
+      "https://example.com/de/page",
+    );
+  });
+});
+
+describe("toAbsoluteUrl", () => {
+  it("resolves relative path against base", () => {
+    expect(toAbsoluteUrl("https://example.com", "/de/page")).toBe("https://example.com/de/page");
+  });
+});
+
+describe("canonicalRootUrl", () => {
+  it("returns unprefixed root URL", () => {
+    expect(canonicalRootUrl("https://example.com")).toBe("https://example.com/");
+  });
+});
+
+describe("toPathname", () => {
+  it("extracts pathname from URL string", () => {
+    expect(toPathname("https://example.com/de/page?q=1")).toBe("/de/page");
+  });
+});
+
+describe("markdownTwinRelPath", () => {
+  const opts = { supportedLangs: ["de", "uk"] };
+
+  it("returns index.md for root path", () => {
+    expect(markdownTwinRelPath("/", opts)).toBe("index.md");
+  });
+
+  it("returns lang-root index for language root", () => {
+    expect(markdownTwinRelPath("/de/", opts)).toBe("de/index.md");
+  });
+
+  it("returns nested path as .md file", () => {
+    expect(markdownTwinRelPath("/de/about/", opts)).toBe("de/about.md");
+  });
+});
+
+describe("markdownTwinUrlPath", () => {
+  it("prefixes rel path with slash", () => {
+    expect(markdownTwinUrlPath("/de/about/", { supportedLangs: ["de"] })).toBe("/de/about.md");
+  });
+});
+
+describe("createSemanticIds", () => {
+  const ids = createSemanticIds("https://example.com");
+
+  it("generates organization id", () => {
+    expect(ids.organization).toBe("https://example.com/#/schema/organization");
+  });
+
+  it("generates website id", () => {
+    expect(ids.website).toBe("https://example.com/#/schema/website");
+  });
+
+  it("generates webpage id from page URL", () => {
+    expect(ids.webpage("https://example.com/de/page")).toBe(
+      "https://example.com/de/page#/schema/webpage",
+    );
+  });
+
+  it("generates breadcrumb id from page URL", () => {
+    expect(ids.breadcrumb("https://example.com/de/page")).toBe(
+      "https://example.com/de/page#/schema/breadcrumb",
+    );
+  });
+
+  it("generates person id with slugified name", () => {
+    expect(ids.person("Jane Doe")).toBe("https://example.com/#/schema/person/jane-doe");
+  });
+
+  it("generates initiative id with slugified name", () => {
+    expect(ids.initiative("Project Alpha")).toBe(
+      "https://example.com/#/schema/initiative/project-alpha",
+    );
+  });
+
+  it("generates service id with slugified name", () => {
+    expect(ids.service("Web Hosting")).toBe("https://example.com/#/schema/service/web-hosting");
+  });
+
+  it("generates faq id from page URL", () => {
+    expect(ids.faq("https://example.com/de/page")).toBe(
+      "https://example.com/de/page#/schema/faq",
+    );
+  });
+
+  it("strips trailing slash from baseUrl", () => {
+    const ids2 = createSemanticIds("https://example.com/");
+    expect(ids2.organization).toBe("https://example.com/#/schema/organization");
+  });
+});

package/src/{share/tests/image-sitemap.test.ts → semantic/tests/image-sitemap-0150.test.ts}

@@ -5,7 +5,7 @@ import {
   isHtmlRedirectPage,
   isSyntheticPreviewUrl,
   type SitemapImageEntry,
-} from "../semantic/image-sitemap.ts";
+} from "../image-sitemap.ts";
 
 const SITE = "https://example.org";