@warpgogol/werkstatt-shared 0.2.0

package/src/share/check-hints.ts

@@ -0,0 +1,38 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Warpgogol check hints schema and parser: defines the hint configuration shape for check-warpgogol runs.</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>Initial implementation for check-warpgogol hints support.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const warpgogolCheckHintsSchema = z.object({
+  schemaVersion: z.literal(1),
+  siteId: z.string().min(1),
+  baseUrl: z.string().url().optional(),
+  languages: z.object({
+    default: z.string().min(1),
+    supported: z.array(z.string().min(1)).min(1),
+  }),
+  preferredStartPaths: z.array(z.string().startsWith("/")),
+  sectionAnchors: z.array(
+    z.object({
+      path: z.string().startsWith("/"),
+      sectionId: z.string().min(1),
+      label: z.string().optional(),
+    }),
+  ),
+  audienceProfiles: z.array(z.string().min(1)),
+});
+
+export type WarpgogolCheckHints = z.infer<typeof warpgogolCheckHintsSchema>;
+
+export function parseWarpgogolCheckHints(value: unknown): WarpgogolCheckHints {
+  return warpgogolCheckHintsSchema.parse(value);
+}

package/src/share/content/entity-id.ts

@@ -0,0 +1,65 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+App-agnostic utility functions for normalizing Astro content entry IDs and extracting
+language codes from them. Shared across all apps in apps/*; no app-specific imports allowed.
+</purpose>
+<non-goals>
+  <item>Do not import from apps/* or astro:content.</item>
+  <item>Do not perform schema validation or runtime data fetching.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Merged createDispatcherResolver from dispatch.ts (micro-module consolidation).</item>
+  <item>Tightened createDispatcherResolver typing: replaced any with generic T parameter.</item>
+  <item>Fixed JSDoc: removed references to non-existent callers (components-dispatcher, layouts-dispatcher, pages-dispatcher).</item>
+</CHANGE_SUMMARY>
+*/
+
+// Shared entity-ID normalization for all schema dispatchers.
+// Source: app content schemas/entity-id (migrated to packages/share).
+
+export function toDataEntryId(entry: string): string {
+  return entry.replace(/\\/g, "/").replace(/\.md$/i, "");
+}
+
+export function getEntryLanguage(id: string): string | null {
+  const [firstSegment] = toDataEntryId(id).split("/");
+
+  if (!firstSegment || !/^[a-z]{2}$/i.test(firstSegment)) {
+    return null;
+  }
+
+  return firstSegment;
+}
+
+export function stripEntryLanguage(id: string): string {
+  const normalizedId = toDataEntryId(id);
+  const entryLanguage = getEntryLanguage(normalizedId);
+
+  if (!entryLanguage) {
+    return normalizedId;
+  }
+
+  return normalizedId.slice(entryLanguage.length + 1);
+}
+
+export function pageIdToContentFileSlug(pageId: string): string {
+  return pageId
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase();
+}
+
+/**
+ * Creates a schema lookup function keyed by normalized entry ID.
+ */
+export function createDispatcherResolver<T = unknown>(schemaMap: Record<string, T>) {
+  return (entryId: string): T | undefined => {
+    const schemaId = stripEntryLanguage(toDataEntryId(entryId));
+    if (!(schemaId in schemaMap)) {
+      return undefined;
+    }
+    return schemaMap[schemaId];
+  };
+}

package/src/share/content/index.ts

@@ -0,0 +1,16 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/content/index.ts as an authored share content 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>
+  <item>Removed dispatch.ts re-export (merged into entity-id.ts).</item>
+</CHANGE_SUMMARY>
+*/
+
+export * from "./entity-id.ts";
+export * from "./merge.ts";
+export * from "./resolve-field-path.ts";

package/src/share/content/merge.ts

@@ -0,0 +1,86 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/content/merge.ts as an authored share content 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>
+  <item>Deepening: unified deepMergeEntryData and mergeComponentContent into one configurable deepMerge; old names kept as thin wrappers.</item>
+</CHANGE_SUMMARY>
+*/
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export interface DeepMergeOptions {
+  /** When true, keep the default array if the override array is empty. Default: false. */
+  keepDefaultOnEmptyArray?: boolean;
+}
+
+/**
+ * Unified deep merge: override wins at each key, recursing into objects.
+ * Arrays are replaced wholesale (no per-element merge). When
+ * `keepDefaultOnEmptyArray` is true, an empty override array falls back to the
+ * default array instead of replacing it.
+ */
+export function deepMerge(
+  defaultValue: Record<string, unknown>,
+  overrideValue: Record<string, unknown>,
+  options?: DeepMergeOptions,
+): Record<string, unknown> {
+  const keepDefaultOnEmptyArray = options?.keepDefaultOnEmptyArray ?? false;
+  const result: Record<string, unknown> = {};
+  const keys = new Set([...Object.keys(defaultValue), ...Object.keys(overrideValue)]);
+  for (const key of keys) {
+    const dv = defaultValue[key];
+    const ov = overrideValue[key];
+    if (ov === undefined) {
+      result[key] = dv;
+    } else if (Array.isArray(dv) && Array.isArray(ov)) {
+      if (ov.length > 0) {
+        result[key] = ov;
+      } else if (keepDefaultOnEmptyArray) {
+        result[key] = dv;
+      } else {
+        result[key] = ov;
+      }
+    } else if (isRecord(dv) && isRecord(ov)) {
+      result[key] = deepMerge(dv, ov, options);
+    } else {
+      result[key] = ov;
+    }
+  }
+  return result;
+}
+
+/**
+ * Deep merge for content entry data: override wins, non-empty arrays replace
+ * wholesale, empty override arrays keep the default. Thin wrapper over deepMerge.
+ */
+export function deepMergeEntryData(
+  defaultValue: Record<string, unknown>,
+  overrideValue: Record<string, unknown>,
+): Record<string, unknown> {
+  return deepMerge(defaultValue, overrideValue, { keepDefaultOnEmptyArray: true });
+}
+
+/**
+ * Deep merge for component content: override wins, arrays always replace.
+ * Handles undefined override and non-record inputs. Thin wrapper over deepMerge.
+ */
+export function mergeComponentContent<TContent>(
+  defaultContent: TContent,
+  overrideContent?: Partial<TContent>,
+): TContent {
+  if (overrideContent == null) return defaultContent;
+  if (!isRecord(defaultContent) || !isRecord(overrideContent)) {
+    return overrideContent as TContent;
+  }
+  return deepMerge(
+    defaultContent as Record<string, unknown>,
+    overrideContent as Record<string, unknown>,
+  ) as TContent;
+}

package/src/share/content/resolve-field-path.ts

@@ -0,0 +1,39 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Resolve a dotted field path through a data object, reporting the first missing segment — the shared primitive behind content-reference substitution (RFC-0045 / RFC-0138).</purpose>
+<non-goals>
+  <item>Do not perform substitution or formatting — only path resolution.</item>
+  <item>Do not throw on a missing field; report it in the result.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0155: add Compass scaffolding markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+export interface FieldResolution {
+  value: unknown;
+  missingField: string | null;
+}
+
+/**
+ * Walks a field path through a data object. Returns the value and the first
+ * missing field name, or null if the entire path resolves.
+ */
+export function resolveFieldPath(data: unknown, fieldPath: string[]): FieldResolution {
+  let value: unknown = data;
+  for (let i = 0; i < fieldPath.length; i++) {
+    const field = fieldPath[i];
+    if (value === null || value === undefined) {
+      return { value: undefined, missingField: field };
+    }
+    if (typeof value !== "object") {
+      return { value: undefined, missingField: field };
+    }
+    if (!(field in value)) {
+      const nextField = i + 1 < fieldPath.length ? fieldPath[i + 1] : null;
+      return { value: undefined, missingField: nextField };
+    }
+    value = (value as Record<string, unknown>)[field];
+  }
+  return { value, missingField: null };
+}

package/src/share/content/substitute-deep.ts

@@ -0,0 +1,47 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Framework-agnostic deep walk that applies a string-substitution function to every
+string leaf of an arbitrary data structure, leaving non-string values unchanged (RFC-0138).</purpose>
+<non-goals>
+  <item>Do not parse or resolve {collection.file.field} references — that is the caller's
+        substitute function (RFC-0045 / RFC-0050 resolvers).</item>
+  <item>Do not mutate the input — return a new structure.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0138: extracted the recursive prop-walk so block-prop reference substitution is
+        shared by the astro resolver and the page handler, and unit-testable without astro.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * Recursively substitutes string leaves of a data structure using `substituteString`.
+ *
+ * - strings → `await substituteString(value)`
+ * - arrays / plain objects → recurse
+ * - everything else (number, boolean, null, undefined) → identity
+ *
+ * The input is not mutated; a new structure is returned.
+ */
+export async function substituteRefsDeep(
+  data: unknown,
+  substituteString: (value: string) => Promise<string>,
+): Promise<unknown> {
+  if (typeof data === "string") {
+    return substituteString(data);
+  }
+
+  if (Array.isArray(data)) {
+    return Promise.all(data.map((item) => substituteRefsDeep(item, substituteString)));
+  }
+
+  if (data !== null && typeof data === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+      result[key] = await substituteRefsDeep(value, substituteString);
+    }
+    return result;
+  }
+
+  return data;
+}

package/src/share/content-discipline/index.ts

@@ -0,0 +1,14 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/content-discipline/index.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not define validation logic here.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Added barrel exports for content-discipline submodules.</item>
+</CHANGE_SUMMARY>
+*/
+
+export * from "./types.ts";
+export * from "./parsers.ts";

package/src/share/content-discipline/parsers.ts

@@ -0,0 +1,66 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Parses RFC-0073 content-discipline artifacts and exposes reusable normalization helpers for validators.</purpose>
+<non-goals>
+  <item>Do not read files from disk.</item>
+  <item>Do not resolve Astro content references here.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0073: Add shared parsers and normalization helpers for content-discipline validators.</item>
+  <item>RFC-0082: Delegate YAML reading to @warpgogol/werkstatt-shared/share/onboarding-yaml so single-doc and two-doc RFC-0076-headed files both parse correctly.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { parseOnboardingArtifactPayload } from "../onboarding-yaml/index.ts";
+import {
+  contentAtomsFileSchema,
+  coverageLedgerEntrySchema,
+  voiceProfileSchema,
+  type ContentAtomsFile,
+  type CoverageLedgerEntry,
+  type VoiceProfile,
+} from "./types.ts";
+
+const COVERAGE_LEDGER_LINE = /^-\s+(atom-\d{4,})\s+·\s+reason:\s+([a-z-]+)\s+·\s+note:\s+(.+)$/;
+
+export function parseContentAtomsFile(source: string): ContentAtomsFile {
+  return parseOnboardingArtifactPayload(source, contentAtomsFileSchema);
+}
+
+export function parseVoiceProfileFile(source: string): VoiceProfile {
+  return parseOnboardingArtifactPayload(source, voiceProfileSchema);
+}
+
+export function parseCoverageLedgerMarkdown(source: string): CoverageLedgerEntry[] {
+  const entries: CoverageLedgerEntry[] = [];
+  for (const rawLine of source.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const match = line.match(COVERAGE_LEDGER_LINE);
+    if (!match) {
+      continue;
+    }
+    const [, atomId, reason, note] = match;
+    entries.push(
+      coverageLedgerEntrySchema.parse({
+        atomId,
+        reason,
+        note: note.trim(),
+      }),
+    );
+  }
+  return entries;
+}
+
+export function normalizeComparableText(value: string): string {
+  return value
+    .normalize("NFKC")
+    .replace(/\{\{quote\}\}[\s\S]*?\{\{\/quote\}\}/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLocaleLowerCase();
+}
+
+export function stripAllowedQuoteBlocks(value: string): string {
+  return value.replace(/\{\{quote\}\}[\s\S]*?\{\{\/quote\}\}/g, " ");
+}

package/src/share/content-discipline/types.ts

@@ -0,0 +1,118 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Defines RFC-0073 shared content-discipline contracts for atom coverage, voice profile, and unplaced-atom reasoning.</purpose>
+<non-goals>
+  <item>Do not read files from disk.</item>
+  <item>Do not perform app-specific validation logic.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0073: Introduce shared content-discipline contracts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const contentAtomIntentValues = [
+  "heading",
+  "subheading",
+  "body",
+  "lead",
+  "cta-primary",
+  "cta-secondary",
+  "trust",
+  "proof",
+  "stat-value",
+  "stat-label",
+  "faq-question",
+  "faq-answer",
+  "meta-title",
+  "meta-description",
+  "og-title",
+  "og-description",
+  "legal-prose",
+  "process-step",
+  "comparison-row",
+  "microcopy",
+  "error-message",
+  "confirmation",
+  "placeholder",
+  "consent",
+] as const;
+
+export const unplacedReasonValues = [
+  "legal-deferred",
+  "redundant",
+  "out-of-scope-for-mvp",
+  "client-deprecated",
+  "quality-concern",
+] as const;
+
+export const contentAtomIntentSchema = z.enum(contentAtomIntentValues);
+export const unplacedReasonSchema = z.enum(unplacedReasonValues);
+
+export const contentAtomSchema = z
+  .object({
+    id: z.string().regex(/^atom-\d{4,}$/),
+    sourceId: z.string().min(1),
+    sourceLines: z.tuple([z.number().int().positive(), z.number().int().positive()]),
+    intent: contentAtomIntentSchema,
+    pageHint: z.string().min(1),
+    sectionHint: z.string().min(1),
+    faqQuestion: z.string().min(1).optional(),
+    paraphraseOf: z
+      .string()
+      .regex(/^atom-\d{4,}$/)
+      .optional(),
+    text: z.string().min(1),
+  })
+  .strict();
+
+export const contentAtomsFileSchema = z
+  .object({
+    // RFC-0082: payload is read via parseOnboardingArtifactPayload, which strips
+    // RFC-0076 metadata keys before validation, so .strict() is safe again.
+    client: z.string().min(1),
+    language: z.string().regex(/^[a-z]{2}$/),
+    materialsHash: z.string().min(1),
+    generatedAt: z.string().min(1),
+    atoms: z.array(contentAtomSchema),
+  })
+  .strict();
+
+export const preferredPhrasingSchema = z
+  .object({
+    avoid: z.string().min(1),
+    prefer: z.string().min(1),
+  })
+  .strict();
+
+export const voiceProfileSchema = z
+  .object({
+    // RFC-0082: payload is read via parseOnboardingArtifactPayload, which strips
+    // RFC-0076 metadata keys before validation, so .strict() is safe again.
+    client: z.string().min(1),
+    language: z.string().regex(/^[a-z]{2}$/),
+    register: z.enum(["Sie", "Du", "you", "informal"]),
+    forbiddenPhrases: z.array(z.string().min(1)).default([]),
+    preferredPhrasings: z.array(preferredPhrasingSchema).default([]),
+    mandatoryPhrases: z.array(z.string().min(1)).default([]),
+    allowedQuotes: z.array(z.string().min(1)).default([]),
+  })
+  .strict();
+
+export const coverageLedgerEntrySchema = z
+  .object({
+    atomId: z.string().regex(/^atom-\d{4,}$/),
+    reason: unplacedReasonSchema,
+    note: z.string().min(1),
+  })
+  .strict();
+
+export type ContentAtomIntent = z.infer<typeof contentAtomIntentSchema>;
+export type ContentAtom = z.infer<typeof contentAtomSchema>;
+export type ContentAtomsFile = z.infer<typeof contentAtomsFileSchema>;
+export type UnplacedReason = z.infer<typeof unplacedReasonSchema>;
+export type PreferredPhrasing = z.infer<typeof preferredPhrasingSchema>;
+export type VoiceProfile = z.infer<typeof voiceProfileSchema>;
+export type CoverageLedgerEntry = z.infer<typeof coverageLedgerEntrySchema>;