@warpgogol/werkstatt-shared 0.2.0

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

@@ -0,0 +1,49 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/semantic/jsonld/faq.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not validate FAQ input data.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Added FAQPage JSON-LD support.</item>
+  <item>Moved from app semantic/jsonld/faq to packages/share.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { JsonLdContext } from "./context.ts";
+import type { JsonLdNode } from "./types.ts";
+import type { SemanticFaqEntry } from "../models.ts";
+
+function buildQuestionNode(entry: SemanticFaqEntry): JsonLdNode {
+  return {
+    "@type": "Question",
+    name: entry.question,
+    acceptedAnswer: {
+      "@type": "Answer",
+      text: entry.answer,
+    },
+  };
+}
+
+export function buildFaqPageNode(context: JsonLdContext): JsonLdNode | null {
+  const entries = context.page.faqEntries;
+  if (!entries || entries.length === 0) {
+    return null;
+  }
+
+  return {
+    "@type": "FAQPage",
+    "@id": context.faqPageId,
+    mainEntity: entries.map((entry) => buildQuestionNode(entry)),
+  };
+}
+
+export function buildFaqNodes(context: JsonLdContext): JsonLdNode[] {
+  // RFC-0506: suppress FAQPage on ratgeber depth-1 article pages.
+  if (context.page.surfaceId === "ratgeber" && context.page.depth === 1) {
+    return [];
+  }
+  const faqPage = buildFaqPageNode(context);
+  return faqPage ? [faqPage] : [];
+}

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

@@ -0,0 +1,53 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/semantic/jsonld/initiative.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not validate initiative input data.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Added initiatives list node plus initiative item-position wiring.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { JsonLdContext } from "./context.ts";
+import type { JsonLdNode } from "./types.ts";
+
+function buildInitiativeNode(
+  context: JsonLdContext,
+  initiative: { name: string; summary: string },
+): JsonLdNode {
+  const { ids } = context;
+
+  return {
+    "@type": ["Thing", "Project"],
+    "@id": ids.initiative(initiative.name),
+    name: initiative.name,
+    description: initiative.summary,
+  };
+}
+
+export function buildInitiativeNodes(context: JsonLdContext): JsonLdNode[] {
+  return (context.page.initiatives ?? []).map((initiative) =>
+    buildInitiativeNode(context, initiative),
+  );
+}
+
+export function buildInitiativesListNode(context: JsonLdContext): JsonLdNode | null {
+  const { page, ids, initiativesListId } = context;
+
+  if (!page.initiatives?.length) {
+    return null;
+  }
+
+  return {
+    "@type": "ItemList",
+    "@id": initiativesListId,
+    itemListElement: page.initiatives.map((initiative, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      item: { "@id": ids.initiative(initiative.name) },
+      name: initiative.name,
+    })),
+  };
+}

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

@@ -0,0 +1,101 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/semantic/jsonld/organization.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not validate input context.</item>
+  <item>Do not fetch external data.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Added Organization JSON-LD generation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { JsonLdContext } from "./context.ts";
+import type { JsonLdNode } from "./types.ts";
+
+export function buildOrganizationNode(context: JsonLdContext): JsonLdNode {
+  const { page, ids } = context;
+
+  return {
+    // RFC-0242: a Bodenstation studio deployment overrides this to ["Organization", "ProfessionalService"].
+    "@type": page.organization.schemaType ?? ["Organization", "NGO"],
+    "@id": ids.organization,
+    name: page.organization.name,
+    legalName: page.organization.legalName,
+    description: page.organization.description,
+    url: page.organization.url,
+    email: page.organization.email,
+    ...(page.organization.foundingYear ? { foundingDate: page.organization.foundingYear } : {}),
+    ...(page.organization.registration ? { identifier: page.organization.registration } : {}),
+    ...(page.organization.founders?.length
+      ? {
+          founder: page.organization.founders.map((person) => ({
+            "@id": ids.person(person.name),
+          })),
+        }
+      : {}),
+    ...(page.organization.boardMembers?.length
+      ? {
+          member: page.organization.boardMembers.map((person) => ({
+            "@id": ids.person(person.name),
+          })),
+        }
+      : {}),
+    ...(page.organization.contactPoints?.length
+      ? {
+          contactPoint: page.organization.contactPoints.map((contactPoint) => ({
+            "@type": "ContactPoint",
+            contactType: contactPoint.contactType,
+            email: contactPoint.email,
+          })),
+        }
+      : {}),
+    ...(page.organization.address
+      ? {
+          address: {
+            "@type": "PostalAddress",
+            streetAddress: page.organization.address.streetAddress,
+            postalCode: page.organization.address.postalCode,
+            addressLocality: page.organization.address.addressLocality,
+            addressCountry: page.organization.address.addressCountry,
+          },
+        }
+      : {}),
+    ...(page.organization.areaServed?.length ? { areaServed: page.organization.areaServed } : {}),
+    ...(page.organization.location?.serviceArea?.length && !page.organization.areaServed?.length
+      ? { areaServed: page.organization.location.serviceArea }
+      : {}),
+    ...(page.organization.team?.length
+      ? {
+          // RFC-0148: public team members as schema.org employees.
+          employee: page.organization.team.map((member) => ({
+            "@type": "Person",
+            name: member.name,
+            ...(member.description ? { description: member.description } : {}),
+          })),
+        }
+      : {}),
+    ...(page.organization.offer?.prices?.length
+      ? {
+          // RFC-0147: project the canonical offer as schema.org Offer nodes.
+          // RFC-0745: emit priceCurrency from canonical source currency when available.
+          makesOffer: page.organization.offer.prices.map((price) => ({
+            "@type": "Offer",
+            name: price.label,
+            priceSpecification: {
+              "@type": "PriceSpecification",
+              price: price.amount,
+            },
+            ...(price.currency ? { priceCurrency: price.currency } : {}),
+          })),
+        }
+      : {}),
+    // RFC-0163: entity-grounding signals for Google Knowledge Graph + LLM disambiguation.
+    ...(page.organization.sameAs?.length ? { sameAs: page.organization.sameAs } : {}),
+    ...(page.organization.logo
+      ? { logo: { "@type": "ImageObject", url: page.organization.logo } }
+      : {}),
+    ...(page.organization.image ? { image: page.organization.image } : {}),
+  };
+}

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

@@ -0,0 +1,71 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/semantic/jsonld/person.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not validate person attributes.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Added Person JSON-LD generation for organization members.</item>
+  <item>Moved from app semantic/jsonld/person to packages/share.</item>
+  <item>RFC-0512: emit address, knowsAbout, affiliation when present on SemanticPerson.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { JsonLdContext } from "./context.ts";
+import type { SemanticPerson } from "../models.ts";
+import type { JsonLdNode } from "./types.ts";
+
+function buildPersonNode(context: JsonLdContext, person: SemanticPerson): JsonLdNode {
+  const { ids } = context;
+
+  return {
+    "@type": "Person",
+    "@id": ids.person(person.name),
+    name: person.name,
+    ...(person.role ? { jobTitle: person.role } : {}),
+    ...(person.description ? { description: person.description } : {}),
+    // RFC-0200: lifespan, portrait, social grounding, and the profile-page URL.
+    ...(person.birthDate ? { birthDate: person.birthDate } : {}),
+    ...(person.deathDate ? { deathDate: person.deathDate } : {}),
+    ...(person.image ? { image: person.image } : {}),
+    ...(person.sameAs?.length ? { sameAs: person.sameAs } : {}),
+    ...(person.profileUrl ? { url: person.profileUrl } : {}),
+    // RFC-0512: extended Person fields for team profile pages.
+    ...(person.address
+      ? {
+          address: {
+            "@type": "PostalAddress",
+            addressLocality: person.address.addressLocality,
+            ...(person.address.addressRegion
+              ? { addressRegion: person.address.addressRegion }
+              : {}),
+            addressCountry: person.address.addressCountry,
+          },
+        }
+      : {}),
+    ...(person.knowsAbout?.length ? { knowsAbout: person.knowsAbout } : {}),
+    ...(person.affiliation
+      ? {
+          affiliation: {
+            "@type": "Organization",
+            name: person.affiliation.name,
+            ...(person.affiliation.url ? { url: person.affiliation.url } : {}),
+          },
+        }
+      : {}),
+    worksFor: { "@id": ids.organization },
+  };
+}
+
+export function buildPersonNodes(context: JsonLdContext): JsonLdNode[] {
+  const people = [
+    ...(context.page.organization.founders ?? []),
+    ...(context.page.organization.boardMembers ?? []),
+    ...(context.page.people ?? []),
+  ];
+
+  const uniquePeople = Array.from(new Map(people.map((person) => [person.name, person])).values());
+
+  return uniquePeople.map((person) => buildPersonNode(context, person));
+}

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

@@ -0,0 +1,80 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/semantic/jsonld/service.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not validate service input data.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Added Service JSON-LD generation.</item>
+  <item>Moved from app semantic/jsonld/service to packages/share.</item>
+  <item>RFC-0498: extend buildServiceNodes to gate Service emission by per-depth policy for all surface depths (website-local depth-1, website-service depth-1, website-local depth-5).</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { JsonLdContext } from "./context.ts";
+import type { JsonLdNode } from "./types.ts";
+import type { SemanticService } from "../models.ts";
+
+function buildServiceNode(context: JsonLdContext, service: SemanticService): JsonLdNode {
+  const { ids } = context;
+
+  return {
+    "@type": "Service",
+    "@id": ids.service(service.name),
+    name: service.name,
+    ...(service.description ? { description: service.description } : {}),
+    provider: { "@id": ids.organization },
+  };
+}
+
+/**
+ * RFC-0492: build the industry-specific Service node for depth-1 `website-local` pages.
+ * Replaces the organization-level Service nodes with a single node carrying
+ * `serviceType`, `audience`, and `provider`.
+ */
+function buildIndustryServiceNode(context: JsonLdContext): JsonLdNode | null {
+  const { page, ids } = context;
+  if (!page.industryService) return null;
+
+  return {
+    "@type": "Service",
+    "@id": `${ids.organization}/service-industry`,
+    name: page.industryService.serviceType,
+    serviceType: page.industryService.serviceType,
+    provider: { "@id": ids.organization },
+    ...(page.industryService.audience
+      ? { audience: { "@type": "Audience", name: page.industryService.audience } }
+      : {}),
+    ...(page.industryService.description ? { description: page.industryService.description } : {}),
+    ...(page.industryService.areaServed
+      ? { areaServed: { "@type": "City", name: page.industryService.areaServed } }
+      : {}),
+  };
+}
+
+/**
+ * RFC-0492/RFC-0498: for surface pages where Service is required (website-local depth-1,
+ * website-service depth-1, website-local depth-5), suppress organization-level Service nodes
+ * and emit a single industry-specific Service node instead.
+ * For surface pages where Service is prohibited (depth-0, 2, 3, 4), emit no Service nodes.
+ * For non-surface pages, emit organization-level Service nodes as before.
+ */
+export function buildServiceNodes(context: JsonLdContext): JsonLdNode[] {
+  const { page } = context;
+
+  // RFC-0498: surface pages with industryService get the industry-specific Service node.
+  // This covers website-local depth-1, website-service depth-1, and website-local depth-5.
+  if (page.industryService) {
+    const industryNode = buildIndustryServiceNode(context);
+    return industryNode ? [industryNode] : [];
+  }
+
+  // RFC-0498: surface pages without industryService and where Service is prohibited emit no Service nodes.
+  // Depth-0, 2, 3, 4 in website-local have Service in prohibitedTypes.
+  if (page.surfaceId && page.depth !== undefined && page.depth !== 1 && page.depth !== 5) {
+    return [];
+  }
+
+  return (page.organization.services ?? []).map((service) => buildServiceNode(context, service));
+}

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

@@ -0,0 +1,31 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/semantic/jsonld/shared.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not modify node structure.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Added graph deduplication utility keyed by @id.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { JsonLdNode } from "./types.ts";
+
+export function dedupeGraph(nodes: JsonLdNode[]): JsonLdNode[] {
+  const seenIds = new Set<string>();
+
+  return nodes.filter((node) => {
+    const nodeId = typeof node["@id"] === "string" ? node["@id"] : null;
+    if (!nodeId) {
+      return true;
+    }
+
+    if (seenIds.has(nodeId)) {
+      return false;
+    }
+
+    seenIds.add(nodeId);
+    return true;
+  });
+}

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

@@ -0,0 +1,18 @@
+/*
+<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>
+<non-goals>
+  <item>Do not implement JSON-LD processing logic.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Moved from app semantic/jsonld/types to packages/share.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type JsonLdNode = Record<string, unknown>;
+
+export type JsonLdDocument = {
+  "@context": "https://schema.org";
+  "@graph": JsonLdNode[];
+};

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

@@ -0,0 +1,98 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/semantic/jsonld/webpage.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 type expansion for donate/faq/news page variants.</item>
+  <item>RFC-0372: speakable reads from unified page.blocks instead of answerBlocks.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { JsonLdContext } from "./context.ts";
+import type { SemanticPageModel } from "../models.ts";
+import type { JsonLdNode } from "./types.ts";
+
+function getWebPageTypes(page: SemanticPageModel): string[] {
+  switch (page.type) {
+    case "about":
+      return ["WebPage", "AboutPage"];
+    case "projects":
+      return ["WebPage", "CollectionPage"];
+    case "openSource":
+      return ["WebPage", "CollectionPage"];
+    case "donationContact":
+      return ["WebPage", "ContactPage"];
+    case "person":
+      // RFC-0200: a per-member profile page is a schema.org ProfilePage.
+      return ["WebPage", "ProfilePage"];
+    case "collection":
+      // RFC-0490: a pillar hub page is a schema.org CollectionPage.
+      return ["WebPage", "CollectionPage"];
+    default:
+      return ["WebPage"];
+  }
+}
+
+export function buildWebPageNode(context: JsonLdContext): JsonLdNode {
+  const { page, ids, webpageId, breadcrumbId, initiativesListId, servicesListId } = context;
+
+  return {
+    "@type": getWebPageTypes(page),
+    "@id": webpageId,
+    url: page.url,
+    name: page.title,
+    headline: page.heading ?? page.title,
+    description: page.description,
+    inLanguage: page.lang,
+    isPartOf: { "@id": ids.website },
+    about: { "@id": ids.organization },
+    publisher: { "@id": ids.organization },
+    ...(page.type === "about" ? { mainEntity: { "@id": ids.organization } } : {}),
+    ...(page.type === "projects" && page.initiatives?.length
+      ? { mainEntity: { "@id": initiativesListId } }
+      : {}),
+    // RFC-0200: a profile page's subject is the profiled Person (attached to page.people).
+    // RFC-0512: for team profile pages, prefer the extended Person/SoftwareApplication node
+    // from extraGraphNodes as mainEntity — this covers AI-agent profiles (where page.people
+    // is empty) and human profiles (where the extended Person node has a different @id).
+    ...(page.type === "person" && page.extraGraphNodes?.[0]
+      ? { mainEntity: { "@id": page.extraGraphNodes[0]["@id"] } }
+      : page.type === "person" && page.people?.[0]
+        ? { mainEntity: { "@id": ids.person(page.people[0].name) } }
+        : {}),
+    ...(page.organization.services?.length && servicesListId
+      ? { mentions: { "@id": servicesListId } }
+      : {}),
+    ...(page.breadcrumbs.length > 1 ? { breadcrumb: { "@id": breadcrumbId } } : {}),
+    ...(page.lead ? { abstract: page.lead } : {}),
+    // RFC-0163: primary image of the page (consumed from RFC-0162 primaryImage).
+    ...(page.primaryImage
+      ? {
+          primaryImageOfPage: {
+            "@type": "ImageObject",
+            url: page.primaryImage.url,
+            ...(page.primaryImage.width ? { width: page.primaryImage.width } : {}),
+            ...(page.primaryImage.height ? { height: page.primaryImage.height } : {}),
+          },
+        }
+      : {}),
+    // RFC-0227: link credited materials from the page entity for licensable-images treatment.
+    ...(page.materialCreditAtIds?.length
+      ? { associatedMedia: page.materialCreditAtIds.map((id) => ({ "@id": id })) }
+      : {}),
+    // RFC-0163: speakable answer surface for voice assistants / AI Overviews. The
+    // page heading and lead are always-present, extractable answer anchors.
+    // RFC-0372: reads from unified page.blocks (any block with a heading counts as speakable).
+    ...(page.blocks.some((b) => b.heading)
+      ? {
+          speakable: {
+            "@type": "SpeakableSpecification",
+            cssSelector: page.lead ? ["h1", ".section-header__lead"] : ["h1"],
+          },
+        }
+      : {}),
+  };
+}

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

@@ -0,0 +1,27 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/semantic/jsonld/website.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 WebSite JSON-LD generation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { JsonLdContext } from "./context.ts";
+import type { JsonLdNode } from "./types.ts";
+
+export function buildWebSiteNode(context: JsonLdContext): JsonLdNode {
+  const { page, ids } = context;
+
+  return {
+    "@type": "WebSite",
+    "@id": ids.website,
+    url: page.organization.url,
+    name: page.organization.name,
+    inLanguage: page.lang,
+    publisher: { "@id": ids.organization },
+  };
+}

package/src/share/semantic/jsonld.ts

@@ -0,0 +1,75 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Assembles a complete JSON-LD document from a SemanticPageModel by composing all entity-specific nodes.</purpose>
+<non-goals>
+  <item>Do not handle raw content parsing.</item>
+  <item>Do not manage external API interactions.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Added initiative list graph node, breadcrumb fallback, and shared dedupe utility.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { buildArticleNode } from "./jsonld/article.ts";
+import { buildBreadcrumbNode } from "./jsonld/breadcrumb.ts";
+import { buildCollectionListNode } from "./jsonld/collection-list.ts";
+import { createJsonLdContext } from "./jsonld/context.ts";
+import { buildFaqNodes } from "./jsonld/faq.ts";
+import { buildInitiativesListNode, buildInitiativeNodes } from "./jsonld/initiative.ts";
+import { buildOrganizationNode } from "./jsonld/organization.ts";
+import { buildPersonNodes } from "./jsonld/person.ts";
+import { buildServiceNodes } from "./jsonld/service.ts";
+import { dedupeGraph } from "./jsonld/shared.ts";
+import type { JsonLdDocument } from "./jsonld/types.ts";
+import { buildWebPageNode } from "./jsonld/webpage.ts";
+import { buildWebSiteNode } from "./jsonld/website.ts";
+import type { SemanticPageModel } from "./models.ts";
+
+export type { JsonLdDocument } from "./jsonld/types.ts";
+export type { JsonLdContext } from "./jsonld/context.ts";
+
+export function buildJsonLd(page: SemanticPageModel): JsonLdDocument {
+  const context = createJsonLdContext(page);
+  const articleNode = buildArticleNode(context);
+  const breadcrumbNode = buildBreadcrumbNode(context);
+  const collectionListNode = buildCollectionListNode(context);
+  const initiativesListNode = buildInitiativesListNode(context);
+  // RFC-0498: suppress the org-level services ItemList for all surface pages.
+  // Surface pages emit industry-specific Service nodes (depth-1, website-service, depth-5)
+  // or no Service nodes at all (depth-0, 2, 3, 4) — never org-level services.
+  const suppressOrgServices = page.surfaceId !== undefined;
+  const servicesListNode =
+    !suppressOrgServices && context.servicesListId
+      ? {
+          "@type": "ItemList" as const,
+          "@id": context.servicesListId,
+          itemListElement: (context.page.organization.services ?? []).map((service, index) => ({
+            "@type": "ListItem",
+            position: index + 1,
+            item: { "@id": context.ids.service(service.name) },
+            name: service.name,
+          })),
+        }
+      : null;
+
+  return {
+    "@context": "https://schema.org",
+    "@graph": dedupeGraph([
+      buildOrganizationNode(context),
+      buildWebSiteNode(context),
+      buildWebPageNode(context),
+      ...buildPersonNodes(context),
+      ...buildServiceNodes(context),
+      ...buildFaqNodes(context),
+      ...buildInitiativeNodes(context),
+      ...(initiativesListNode ? [initiativesListNode] : []),
+      ...(servicesListNode ? [servicesListNode] : []),
+      ...(collectionListNode ? [collectionListNode] : []),
+      ...(articleNode ? [articleNode] : []),
+      ...(breadcrumbNode ? [breadcrumbNode] : []),
+      // RFC-0512: extra nodes from team profile pages (SoftwareApplication, CollectionPage).
+      ...(page.extraGraphNodes ?? []),
+    ]),
+  };
+}