@warpgogol/werkstatt-shared 0.2.0

package/src/share/semantic/extract.ts

@@ -0,0 +1,118 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/semantic/extract.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { SemanticPerson, SemanticPostalAddress } from "./models.ts";
+
+export function normalizeWhitespace(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+export function slugify(value: string): string {
+  return (
+    value
+      .toLowerCase()
+      .normalize("NFKD")
+      .replace(/[\u0300-\u036f]/g, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "entity"
+  );
+}
+
+export type MarkdownSection = {
+  heading: string;
+  body: string;
+};
+
+export function splitMarkdownSections(markdown: string, level: 2 | 3 = 2): MarkdownSection[] {
+  const normalizedMarkdown = markdown.trim();
+  if (!normalizedMarkdown) {
+    return [];
+  }
+
+  const marker = "#".repeat(level);
+  const splitPattern = new RegExp(`\\n(?=${marker}\\s+)`);
+  const headingPattern = new RegExp(`^${marker}\\s+`);
+
+  return normalizedMarkdown
+    .split(splitPattern)
+    .map((section) => section.trim())
+    .filter((section) => headingPattern.test(section))
+    .map((section) => {
+      const [headingLine = "", ...restLines] = section.split("\n");
+      return {
+        heading: headingLine.replace(headingPattern, "").trim(),
+        body: restLines.join("\n").trim(),
+      };
+    });
+}
+
+export function extractParagraphs(markdown: string): string[] {
+  return markdown
+    .split(/\n\s*\n/)
+    .map((part) => normalizeWhitespace(part))
+    .filter(Boolean);
+}
+
+export function extractListFacts(markdown: string): string[] {
+  return markdown
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("- ") || /^\d+\.\s+/.test(line))
+    .map((line) =>
+      line
+        .replace(/^-\s+/, "")
+        .replace(/^\d+\.\s+/, "")
+        .trim(),
+    )
+    .filter(Boolean);
+}
+
+export function extractEmail(markdown: string): string | undefined {
+  const match = markdown.match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i);
+  return match?.[0];
+}
+
+export function extractPostalAddress(
+  markdown: string,
+  country: string = "DE",
+): SemanticPostalAddress | undefined {
+  const match = markdown.match(/([^\n,]+),\s*(\d{5})\s+([^\n]+)/);
+
+  if (!match) {
+    return undefined;
+  }
+
+  return {
+    streetAddress: match[1].trim(),
+    postalCode: match[2].trim(),
+    addressLocality: match[3].trim(),
+    addressCountry: country,
+  };
+}
+
+export function mergePeople(...groups: Array<SemanticPerson[] | undefined>): SemanticPerson[] {
+  const merged = new Map<string, SemanticPerson>();
+
+  for (const group of groups) {
+    for (const person of group ?? []) {
+      const existing = merged.get(person.name);
+      merged.set(person.name, {
+        name: person.name,
+        role: existing?.role ?? person.role,
+        description: existing?.description ?? person.description,
+        isDeceased: existing?.isDeceased || person.isDeceased,
+      });
+    }
+  }
+
+  return Array.from(merged.values());
+}

package/src/share/semantic/feed.ts

@@ -0,0 +1,124 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0165/RFC-0317: pure RSS 2.0 + JSON Feed v1.1 formatters. Framework-agnostic —
+the site-OS feed.generate command supplies the channel + dated items and writes the result.</purpose>
+<non-goals>
+  <item>Do not read files or fetch content — the caller supplies resolved items.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0165: initial implementation.</item>
+  <item>RFC-0317: add JSON Feed v1.1 output from the same item set.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface FeedItem {
+  title: string;
+  /** Absolute URL. */
+  url: string;
+  summary: string;
+  /** ISO date. */
+  publishedAt: string;
+  /** ISO date; defaults to publishedAt. */
+  updatedAt?: string;
+}
+
+export interface FeedChannel {
+  title: string;
+  /** Absolute site URL. */
+  url: string;
+  description: string;
+  language: string;
+  /** Absolute URL of the feed itself (Atom self-link). */
+  selfUrl: string;
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function toRfc822(iso: string): string {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? iso : date.toUTCString();
+}
+
+export function buildRssFeed(channel: FeedChannel, items: FeedItem[]): string {
+  const sorted = [...items].sort(
+    (a, b) => new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime(),
+  );
+  // Deterministic: derive lastBuildDate from item dates (never `now`), and omit it for an
+  // empty feed so a no-article app produces a stable, churn-free file.
+  const lastBuild = sorted[0]?.updatedAt ?? sorted[0]?.publishedAt;
+
+  const itemXml = sorted
+    .map((item) =>
+      [
+        "    <item>",
+        `      <title>${escapeXml(item.title)}</title>`,
+        `      <link>${escapeXml(item.url)}</link>`,
+        `      <guid isPermaLink="true">${escapeXml(item.url)}</guid>`,
+        `      <description>${escapeXml(item.summary)}</description>`,
+        `      <pubDate>${escapeXml(toRfc822(item.publishedAt))}</pubDate>`,
+        "    </item>",
+      ].join("\n"),
+    )
+    .join("\n");
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">',
+    "  <channel>",
+    `    <title>${escapeXml(channel.title)}</title>`,
+    `    <link>${escapeXml(channel.url)}</link>`,
+    `    <description>${escapeXml(channel.description)}</description>`,
+    `    <language>${escapeXml(channel.language)}</language>`,
+    ...(lastBuild ? [`    <lastBuildDate>${escapeXml(toRfc822(lastBuild))}</lastBuildDate>`] : []),
+    `    <atom:link href="${escapeXml(channel.selfUrl)}" rel="self" type="application/rss+xml" />`,
+    ...(itemXml ? [itemXml] : []),
+    "  </channel>",
+    "</rss>",
+    "",
+  ].join("\n");
+}
+
+export interface JsonFeedInput {
+  title: string;
+  home_page_url: string;
+  feed_url: string;
+  description: string;
+  language: string;
+  items: FeedItem[];
+}
+
+/** RFC-0317: JSON Feed v1.1 from the same item set as the RSS feed. */
+export function buildJsonFeed(input: JsonFeedInput): string {
+  const sorted = [...input.items].sort(
+    (a, b) => new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime(),
+  );
+
+  const feed: Record<string, unknown> = {
+    version: "https://jsonfeed.org/version/1.1",
+    title: input.title,
+    description: input.description || undefined,
+    home_page_url: input.home_page_url,
+    feed_url: input.feed_url,
+    language: input.language,
+  };
+  if (sorted.length > 0) {
+    feed.items = sorted.map((item) => ({
+      id: item.url,
+      url: item.url,
+      title: item.title,
+      content_text: item.summary || undefined,
+      date_published: item.publishedAt,
+      ...(item.updatedAt ? { date_modified: item.updatedAt } : {}),
+    }));
+  }
+
+  return `${JSON.stringify(feed, null, 2)}\n`;
+}

package/src/share/semantic/ids.ts

@@ -0,0 +1,76 @@
+/*
+<MODULE_CONTRACT>
+<purpose>URL transformations and semantic ID generation for structured data. Framework-agnostic — used across all Warpgogol apps.</purpose>
+<non-goals>
+  <item>Do not perform raw URL parsing beyond basic structure validation.</item>
+  <item>Do not manage application configuration or external service interactions.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Moved from app semantic/ids to packages/share/src/semantic/ids.ts — framework-agnostic, reusable across all apps.</item>
+</CHANGE_SUMMARY>
+*/
+
+export function getBaseUrl(url: URL | string): string {
+  const resolvedUrl = new URL(typeof url === "string" ? url : url.toString());
+  return resolvedUrl.origin;
+}
+
+export function toCanonicalUrl(url: URL | string): string {
+  const resolvedUrl = new URL(typeof url === "string" ? url : url.toString());
+  resolvedUrl.search = "";
+  resolvedUrl.hash = "";
+  return resolvedUrl.toString();
+}
+
+export function toAbsoluteUrl(baseUrl: string, path: string): string {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+export function toPathname(url: string): string {
+  return new URL(url).pathname;
+}
+
+export function markdownTwinRelPath(
+  pathname: string,
+  opts: { supportedLangs: readonly string[] },
+): string {
+  const p = pathname.replace(/^\/+|\/+$/g, "");
+  if (p === "") return "index.md";
+  const isLangRoot = !p.includes("/") && opts.supportedLangs.includes(p);
+  if (isLangRoot) return `${p}/index.md`;
+  return `${p}.md`;
+}
+
+export function markdownTwinUrlPath(
+  pathname: string,
+  opts: { supportedLangs: readonly string[] },
+): string {
+  return `/${markdownTwinRelPath(pathname, opts)}`;
+}
+
+function toIdSegment(value: string): string {
+  return (
+    value
+      .toLowerCase()
+      .normalize("NFKD")
+      .replace(/[\u0300-\u036f]/g, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "entity"
+  );
+}
+
+export function createSemanticIds(baseUrl: string) {
+  const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
+
+  return {
+    organization: `${normalizedBaseUrl}/#/schema/organization`,
+    website: `${normalizedBaseUrl}/#/schema/website`,
+    webpage: (pageUrl: string) => `${toCanonicalUrl(pageUrl)}#/schema/webpage`,
+    breadcrumb: (pageUrl: string) => `${toCanonicalUrl(pageUrl)}#/schema/breadcrumb`,
+    person: (name: string) => `${normalizedBaseUrl}/#/schema/person/${toIdSegment(name)}`,
+    initiative: (name: string) => `${normalizedBaseUrl}/#/schema/initiative/${toIdSegment(name)}`,
+    service: (name: string) => `${normalizedBaseUrl}/#/schema/service/${toIdSegment(name)}`,
+    faq: (pageUrl: string) => `${toCanonicalUrl(pageUrl)}#/schema/faq`,
+  };
+}

package/src/share/semantic/image-sitemap.ts

@@ -0,0 +1,153 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0172: pure harvester + formatter for the post-build image sitemap. Reads
+rendered HTML (supplied by the caller) and extracts the page's single lead/content image,
+then formats a Google image sitemap. Framework-agnostic — the site-OS dist.sitemap.images.generate
+command walks dist/client and writes the result; this module touches no filesystem.</purpose>
+<non-goals>
+  <item>Do not read files or fetch HTML — the caller supplies the HTML string.</item>
+  <item>Do not construct /_astro or /cdn-cgi/image URLs — only read what the render emitted (RFC-0152).</item>
+  <item>Do not apply policy/severity — the command decides pass/fail from the harvest result.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0172: initial implementation.</item>
+</CHANGE_SUMMARY>
+*/
+
+/** One resolved image entry harvested from rendered HTML. */
+export interface SitemapImageEntry {
+  /** Absolute page URL (canonical, from the document). */
+  loc: string;
+  /** Absolute image URL; provider-emitted (/_astro/<hash> or /cdn-cgi/image/...). */
+  imageUrl: string;
+  /** From the `<img alt>` / `og:image:alt`, when present. */
+  title?: string;
+}
+
+/** Result of harvesting one rendered HTML document. */
+export interface ContentImageHarvest {
+  /** Canonical absolute page URL, or null when no canonical link is present. */
+  loc: string | null;
+  /** All distinct content-image signals found, absolutized. >1 is a uniqueness violation. */
+  imageUrls: string[];
+  /** Best-effort image title (alt text), when discoverable. */
+  title?: string;
+}
+
+/**
+ * True when the HTML is a meta-refresh redirect stub (no real content) — e.g. the
+ * RFC-0160 prefixed-default-language `/de/…` → `/…` stubs.
+ *
+ * Note: we deliberately do NOT treat `window.location` as a stub signal. Full
+ * content pages (the root home, RFC-0159) carry a *soft* client-side language
+ * redirect for non-default browser locales while still serving complete HTML;
+ * those must be harvested, not skipped.
+ */
+export function isHtmlRedirectPage(html: string): boolean {
+  return /<meta[^>]+http-equiv=["']refresh["']/i.test(html);
+}
+
+/** RFC-0150 preview screenshots and the og-image fallback are NOT content images. */
+export function isSyntheticPreviewUrl(url: string): boolean {
+  return /\/preview\/[^"']*\.png(\?|$)/i.test(url) || /\/og-image\.png(\?|$)/i.test(url);
+}
+
+function extractCanonical(html: string, siteUrl: string): string | null {
+  const m = html.match(/<link[^>]+rel=["']canonical["'][^>]*href=["']([^"']+)["']/i);
+  if (!m?.[1]) return null;
+  return absolutize(m[1], siteUrl);
+}
+
+/** Absolutize a possibly-relative URL against the site origin. Returns null if unresolvable. */
+function absolutize(url: string, siteUrl: string): string | null {
+  try {
+    return new URL(url, ensureTrailingSlash(siteUrl)).toString();
+  } catch {
+    return null;
+  }
+}
+
+function ensureTrailingSlash(origin: string): string {
+  return origin.endsWith("/") ? origin : `${origin}/`;
+}
+
+/** Pull the value of a single attribute from an HTML tag string. */
+function attr(tag: string, name: string): string | undefined {
+  const m = tag.match(new RegExp(`${name}=["']([^"']*)["']`, "i"));
+  return m?.[1];
+}
+
+/**
+ * Harvest the page's content image(s) from one rendered HTML document.
+ *
+ * Two signal sources, unified (RFC-0172):
+ *   1. `<img ... data-content-image ...>` — render-resolved hero `leadImage` (hashed URL).
+ *   2. `<meta name="x-content-image" content="...">` — authored `output.image` (absolute).
+ *
+ * Returns every distinct, absolutized URL found so the caller can enforce the
+ * one-per-page contract. Synthetic preview/og-image URLs are excluded here.
+ */
+export function harvestContentImage(html: string, siteUrl: string): ContentImageHarvest {
+  const loc = extractCanonical(html, siteUrl);
+  const urls = new Set<string>();
+  let title: string | undefined;
+
+  // 1. <img data-content-image>
+  const imgRe = /<img\b[^>]*\bdata-content-image\b[^>]*>/gi;
+  let im: RegExpExecArray | null;
+  while ((im = imgRe.exec(html)) !== null) {
+    const tag = im[0];
+    const src = attr(tag, "src");
+    if (!src) continue;
+    const abs = absolutize(src, siteUrl);
+    if (!abs || isSyntheticPreviewUrl(abs)) continue;
+    urls.add(abs);
+    if (!title) title = attr(tag, "alt") || undefined;
+  }
+
+  // 2. <meta name="x-content-image" content="...">
+  const metaRe = /<meta[^>]+name=["']x-content-image["'][^>]*content=["']([^"']+)["'][^>]*>/gi;
+  let mm: RegExpExecArray | null;
+  while ((mm = metaRe.exec(html)) !== null) {
+    const abs = absolutize(mm[1], siteUrl);
+    if (!abs || isSyntheticPreviewUrl(abs)) continue;
+    urls.add(abs);
+  }
+
+  // Fallback title from og:image:alt when an <img> alt was unavailable.
+  if (!title) {
+    const altMeta = html.match(
+      /<meta[^>]+property=["']og:image:alt["'][^>]*content=["']([^"']+)["']/i,
+    );
+    if (altMeta?.[1]) title = altMeta[1];
+  }
+
+  return { loc, imageUrls: [...urls], ...(title ? { title } : {}) };
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Render the image sitemap XML. Each entry becomes one `<url>` with an
+ * `<image:image>` child. An empty entry list yields a valid empty urlset.
+ * The caller is responsible for prepending the GENERATED marker if desired.
+ */
+export function generateImageSitemapXml(entries: SitemapImageEntry[]): string {
+  const urls = entries
+    .map((e) => {
+      const titleXml = e.title ? `\n      <image:title>${escapeXml(e.title)}</image:title>` : "";
+      return `  <url>\n    <loc>${escapeXml(e.loc)}</loc>\n    <image:image>\n      <image:loc>${escapeXml(
+        e.imageUrl,
+      )}</image:loc>${titleXml}\n    </image:image>\n  </url>`;
+    })
+    .join("\n");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset\n  xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"\n  xmlns:image="http://www.google.com/schemas/sitemap-image/1.1"\n>\n${urls}\n</urlset>`;
+}

package/src/share/semantic/index.ts

@@ -0,0 +1,36 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for the entire semantic layer: models, extractors, IDs, JSON-LD, LLMs projections, page builders, and utilities.</purpose>
+<non-goals>
+  <item>Do not contain implementation logic — this is a barrel file only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Expanded barrel to cover the full semantic layer: ids, jsonld, llms, page-utils, page-builders.</item>
+</CHANGE_SUMMARY>
+*/
+
+export * from "./models.ts";
+export * from "./breadcrumbs.ts";
+export * from "./extract.ts";
+export * from "./ids.ts";
+export * from "./jsonld.ts";
+export * from "./markdown-hygiene.ts";
+export * from "./llms.ts";
+export * from "./llms-policy.ts";
+export * from "./output-projection.ts";
+export * from "./business-projection.ts";
+export * from "./organization-profile.ts";
+export * from "./ai.ts";
+export * from "./robots.ts";
+export * from "./page-utils.ts";
+export * from "./page-markdown.ts";
+export * from "./feed.ts";
+export * from "./image-sitemap.ts";
+export * from "./page-builders/markdown-page.ts";
+export * from "./build-page.ts";
+export * from "./block-extraction.ts";
+export * from "./block-extractors/index.ts";
+export * from "./update-stamp.ts";
+export * from "./markdown-twin-provenance.ts";
+export * from "./price-marker-resolver.ts";

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

@@ -0,0 +1,47 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0167: builds the Article/BlogPosting JSON-LD node from a page that carries article
+metadata (datePublished/author/…). Gives Google freshness/Discover signals and LLM recency +
+attribution that a bare WebPage lacks.</purpose>
+<non-goals>
+  <item>Do not emit when the page has no datePublished.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0167: initial implementation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { JsonLdContext } from "./context.ts";
+import type { JsonLdNode } from "./types.ts";
+
+export function buildArticleNode(context: JsonLdContext): JsonLdNode | null {
+  const { page, ids, webpageId } = context;
+  if (!page.datePublished) {
+    return null;
+  }
+  const isRatgeberDepth1 = page.surfaceId === "ratgeber" && page.depth === 1;
+  const author = page.authorRecord
+    ? {
+        "@type": "Person",
+        name: page.authorRecord.name,
+        ...(page.authorRecord.contactUrl ? { url: page.authorRecord.contactUrl } : {}),
+      }
+    : page.author
+      ? { "@type": "Person", name: page.author }
+      : undefined;
+  return {
+    "@type": ["Article", "BlogPosting"],
+    "@id": webpageId.replace("#/schema/webpage", "#/schema/article"),
+    headline: page.heading ?? page.title,
+    description: page.description,
+    datePublished: page.datePublished,
+    dateModified: page.dateModified ?? page.datePublished,
+    ...(author ? { author } : {}),
+    publisher: { "@id": ids.organization },
+    mainEntityOfPage: isRatgeberDepth1 ? page.url : { "@id": webpageId },
+    inLanguage: page.lang,
+    ...(page.primaryImage ? { image: page.primaryImage.url } : {}),
+    ...(page.keywords?.length ? { keywords: page.keywords.join(", ") } : {}),
+  };
+}

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

@@ -0,0 +1,47 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/semantic/jsonld/breadcrumb.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not parse raw content.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Added breadcrumb support for JSON-LD generation.</item>
+  <item>Moved from app semantic/jsonld/breadcrumb to packages/share.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { JsonLdContext } from "./context.ts";
+import type { JsonLdNode } from "./types.ts";
+
+export function buildBreadcrumbNode(context: JsonLdContext): JsonLdNode | null {
+  const { page, breadcrumbId } = context;
+
+  if (page.breadcrumbs.length <= 1) {
+    return null;
+  }
+
+  // RFC-0229: trail crumbs carry root-relative paths so the *rendered* links work in any environment.
+  // The BreadcrumbList `item` must be an absolute canonical URL, so resolve each crumb against the
+  // page's canonical origin (already-absolute crumb URLs pass through unchanged).
+  const toAbsolute = (url: string): string => {
+    try {
+      return new URL(url, page.url).toString();
+    } catch {
+      return url;
+    }
+  };
+
+  return {
+    "@type": "BreadcrumbList",
+    "@id": breadcrumbId,
+    itemListElement: page.breadcrumbs.map((item, index) => ({
+      "@type": "ListItem",
+      // RFC-0229: stable, position-scoped @id so each crumb is an addressable node in the page graph.
+      "@id": `${breadcrumbId}/${index + 1}`,
+      position: index + 1,
+      name: item.name,
+      item: toAbsolute(item.url),
+    })),
+  };
+}

package/src/share/semantic/jsonld/collection-list.ts

@@ -0,0 +1,30 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Builds the JSON-LD ItemList node for "collection"-typed pages (RFC-0490 pillar hub).</purpose>
+<non-goals>
+  <item>Do not build per-item Product or Service nodes — the ItemList references page URLs only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0490: initial — ItemList node for collection-typed pillar hub pages.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { JsonLdContext } from "./context.ts";
+import type { JsonLdNode } from "./types.ts";
+
+export function buildCollectionListNode(context: JsonLdContext): JsonLdNode | null {
+  const { page, collectionListId } = context;
+  if (!collectionListId || !page.collectionItems?.length) return null;
+
+  return {
+    "@type": "ItemList",
+    "@id": collectionListId,
+    itemListElement: page.collectionItems.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      url: item.url,
+      name: item.name,
+    })),
+  };
+}

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

@@ -0,0 +1,46 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Creates a typed context object for JSON-LD node builders from a SemanticPageModel.</purpose>
+<non-goals>
+  <item>Do not parse or transform content.</item>
+  <item>Do not fetch external data.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Added servicesListId and initiativesListId derived IDs.</item>
+  <item>Moved from app semantic/jsonld/context to packages/share.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { createSemanticIds } from "../ids.ts";
+import type { SemanticPageModel } from "../models.ts";
+
+export type JsonLdContext = {
+  page: SemanticPageModel;
+  ids: ReturnType<typeof createSemanticIds>;
+  webpageId: string;
+  breadcrumbId: string;
+  initiativesListId: string;
+  servicesListId?: string;
+  faqPageId?: string;
+  collectionListId?: string;
+};
+
+export function createJsonLdContext(page: SemanticPageModel): JsonLdContext {
+  const ids = createSemanticIds(new URL(page.url).origin);
+  const webpageId = ids.webpage(page.url);
+
+  return {
+    page,
+    ids,
+    webpageId,
+    breadcrumbId: ids.breadcrumb(page.url),
+    initiativesListId: `${webpageId}/initiatives`,
+    servicesListId: page.organization.services?.length ? `${ids.organization}/services` : undefined,
+    faqPageId: page.faqEntries && page.faqEntries.length > 0 ? ids.faq(page.url) : undefined,
+    collectionListId:
+      page.type === "collection" && page.collectionItems?.length
+        ? `${webpageId}/industries`
+        : undefined,
+  };
+}