@warpgogol/werkstatt-shared 0.2.0

package/src/share/content-reference.ts

@@ -0,0 +1,333 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Framework-agnostic content reference index resolver — loads a build-time generated index
+and resolves braceless collection.file.field references without astro:content (RFC-0527).</purpose>
+<non-goals>
+  <item>Do not generate the index — that is content.ref-index.generate in @warpgogol/site-kernel-codegen.</item>
+  <item>Do not validate references — that is content.references.validate in @warpgogol/site-kernel-checks.</item>
+  <item>Do not handle brace-delimited {collection.file.field} syntax — legacy, removed by RFC-0529.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0045: Initial implementation of content data references in markdown files.</item>
+  <item>RFC-0527: Rewrite as framework-agnostic index-based resolver. Remove astro:content dependency.
+        Replace parseContentReference, resolveContentReference, substituteContentReferences,
+        substituteContentReferencesInData with loadContentRefIndex, resolveReference,
+        resolveReferencesInString, resolveReferencesDeep.</item>
+  <item>RFC-0602: allow null generatedAt in ContentRefIndex for timestamp determinism.</item>
+  <item>RFC-0731: Add SourceRef type and sourceRef optional parameter for this. self-reference syntax.
+        this. is expanded to collection.file. before pattern matching. REF-12 for missing sourceRef,
+        REF-13 for unresolvable field after expansion.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFileSync } from "node:fs";
+import { parse } from "yaml";
+import { substituteRefsDeep } from "./content/substitute-deep.ts";
+import { resolveFieldPath } from "./content/resolve-field-path.ts";
+import { scanFormulas, resolveFormula } from "./formula-eval.ts";
+
+export interface ContentRefIndex {
+  version: 1;
+  generatedAt: string | null;
+  entries: Record<string, Record<string, Record<string, unknown>>>;
+  collections: string[];
+}
+
+export interface ResolveReferenceResult {
+  value: unknown;
+  resolved: boolean;
+  error?: string;
+}
+
+export interface SourceRef {
+  collection: string;
+  file: string;
+}
+
+const REF_PATTERN = /^([a-z][a-z-]*)\.([a-z0-9-/]+)\.(.+)$/;
+const FIELD_PATH_PATTERN = /[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*/;
+const PURE_REF_PATTERN = new RegExp(`^[a-z][a-z-]*\\.[a-z0-9-/]+\\.${FIELD_PATH_PATTERN.source}$`);
+const BRACELESS_SCAN_PATTERN = new RegExp(
+  `[a-z][a-z-]*\\.[a-z0-9-/]+\\.${FIELD_PATH_PATTERN.source}`,
+  "g",
+);
+const THIS_PREFIX = "this.";
+const THIS_SCAN_PATTERN = new RegExp(`this\\.${FIELD_PATH_PATTERN.source}`, "g");
+const DEFAULT_INDEX_PATH = "src/content-ref-index.generated.yaml";
+
+function expandThisRef(ref: string, sourceRef?: SourceRef): string | null {
+  if (!ref.startsWith(THIS_PREFIX)) return null;
+  if (!sourceRef) return null;
+  const fieldPath = ref.slice(THIS_PREFIX.length);
+  return `${sourceRef.collection}.${sourceRef.file}.${fieldPath}`;
+}
+
+export const EMPTY_CONTENT_REF_INDEX: ContentRefIndex = {
+  version: 1,
+  generatedAt: "",
+  entries: {},
+  collections: [],
+};
+
+let cachedIndex: ContentRefIndex | null | undefined;
+
+export function loadContentRefIndex(indexPath: string): ContentRefIndex | null {
+  try {
+    const raw = readFileSync(indexPath, "utf8");
+    const parsed = parse(raw) as ContentRefIndex;
+    if (parsed && parsed.version === 1 && parsed.entries) {
+      return parsed;
+    }
+    return null;
+  } catch (err: unknown) {
+    if (err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT") {
+      console.warn(
+        `[content-ref-index] ${indexPath} not found — formula references =(...) and braceless content references will not resolve. ` +
+          `Run: pnpm exec werkstatt run content.ref-index.generate --site <siteId>`,
+      );
+    }
+    return null;
+  }
+}
+
+export function getContentRefIndex(indexPath?: string): ContentRefIndex | null {
+  if (cachedIndex === undefined) {
+    cachedIndex = loadContentRefIndex(indexPath ?? DEFAULT_INDEX_PATH);
+  }
+  return cachedIndex;
+}
+
+export function resetContentRefIndexCache(): void {
+  cachedIndex = undefined;
+}
+
+export function resolveReference(
+  index: ContentRefIndex,
+  ref: string,
+  lang: string,
+  defaultLang: string,
+  sourceRef?: SourceRef,
+): ResolveReferenceResult {
+  // RFC-0731: Expand this. prefix before pattern matching
+  let effectiveRef = ref;
+  if (ref.startsWith(THIS_PREFIX)) {
+    if (!sourceRef) {
+      return {
+        value: undefined,
+        resolved: false,
+        error: `REF-12: this. reference used without sourceRef context`,
+      };
+    }
+    const expanded = expandThisRef(ref, sourceRef);
+    if (!expanded) {
+      return {
+        value: undefined,
+        resolved: false,
+        error: `REF-12: this. reference used without sourceRef context`,
+      };
+    }
+    effectiveRef = expanded;
+  }
+
+  const match = effectiveRef.match(REF_PATTERN);
+  if (!match) {
+    return { value: undefined, resolved: false, error: `Invalid reference syntax: ${ref}` };
+  }
+
+  const [, collection, file, fieldPathStr] = match;
+  const fieldPath = fieldPathStr.split(".");
+
+  const collectionEntries = index.entries[collection];
+  if (!collectionEntries) {
+    return {
+      value: undefined,
+      resolved: false,
+      error: `REF-01: Collection "${collection}" not found in index`,
+    };
+  }
+
+  const fileEntries = collectionEntries[file];
+  if (!fileEntries) {
+    return {
+      value: undefined,
+      resolved: false,
+      error: `REF-02: File "${file}" not found in collection "${collection}"`,
+    };
+  }
+
+  let data = fileEntries[lang];
+  if (!data && lang !== defaultLang) {
+    data = fileEntries[defaultLang];
+  }
+  if (!data) {
+    return {
+      value: undefined,
+      resolved: false,
+      error: `REF-02: No entry for language "${lang}" or fallback "${defaultLang}" for ${collection}.${file}`,
+    };
+  }
+
+  const { value, missingField } = resolveFieldPath(data, fieldPath);
+  if (missingField || value === undefined) {
+    // Field-level fallback: if the field path fails in the requested language,
+    // retry with the default language data before reporting REF-03.
+    if (lang !== defaultLang) {
+      const fallbackData = fileEntries[defaultLang];
+      if (fallbackData) {
+        const fallbackResult = resolveFieldPath(fallbackData, fieldPath);
+        if (!fallbackResult.missingField && fallbackResult.value !== undefined) {
+          return { value: fallbackResult.value, resolved: true };
+        }
+      }
+    }
+    // RFC-0731: If this was a this. reference, report REF-13 instead of REF-03
+    if (ref.startsWith(THIS_PREFIX)) {
+      return {
+        value: undefined,
+        resolved: false,
+        error: `REF-13: this.${fieldPathStr} unresolved — field "${missingField ?? fieldPath[fieldPath.length - 1]}" not found in ${sourceRef?.collection}.${sourceRef?.file}`,
+      };
+    }
+    return {
+      value: undefined,
+      resolved: false,
+      error: `REF-03: Field "${missingField ?? fieldPath[fieldPath.length - 1]}" not found in ${collection}.${file}`,
+    };
+  }
+
+  return { value, resolved: true };
+}
+
+export function resolveReferencesInString(
+  index: ContentRefIndex,
+  text: string,
+  lang: string,
+  defaultLang: string,
+  sourceRef?: SourceRef,
+): string {
+  // RFC-0731: Check for this. as a pure reference (entire text is this.field.path)
+  if (
+    sourceRef &&
+    text.startsWith(THIS_PREFIX) &&
+    THIS_SCAN_PATTERN.test(text) &&
+    text.trim() === text.trim()
+  ) {
+    const expanded = expandThisRef(text.trim(), sourceRef);
+    if (expanded) {
+      const result = resolveReference(index, expanded, lang, defaultLang);
+      if (result.resolved) {
+        return formatValue(result.value);
+      }
+    }
+  }
+  THIS_SCAN_PATTERN.lastIndex = 0;
+
+  if (PURE_REF_PATTERN.test(text)) {
+    const result = resolveReference(index, text, lang, defaultLang);
+    if (result.resolved) {
+      return formatValue(result.value);
+    }
+    return text;
+  }
+
+  // RFC-0570: resolve =(...) formula expressions first
+  const formulas = scanFormulas(text);
+  let formulaResult = text;
+  if (formulas.length > 0) {
+    // Process formulas in reverse order to preserve indices
+    for (let i = formulas.length - 1; i >= 0; i--) {
+      const { start, end, expression } = formulas[i];
+      const result = resolveFormula(index, expression, lang, defaultLang, sourceRef);
+      const replacement = result.resolved ? result.value : "";
+      formulaResult = formulaResult.slice(0, start) + replacement + formulaResult.slice(end);
+    }
+  }
+
+  // If the entire string was a formula, return the formula result
+  if (formulas.length > 0 && formulas[0].start === 0 && formulas[0].end === text.length) {
+    return formulaResult;
+  }
+
+  let result = formulaResult;
+  const pattern = new RegExp(BRACELESS_SCAN_PATTERN.source, "g");
+  let match: RegExpExecArray | null;
+  const replacements: Array<{ start: number; end: number; resolved: string }> = [];
+
+  while ((match = pattern.exec(formulaResult)) !== null) {
+    const candidate = match[0];
+    const collectionMatch = candidate.match(/^([a-z][a-z-]*)\./);
+    if (!collectionMatch) continue;
+    const collection = collectionMatch[1];
+    if (!index.entries[collection]) continue;
+
+    const resolved = resolveReference(index, candidate, lang, defaultLang, sourceRef);
+    if (resolved.resolved) {
+      replacements.push({
+        start: match.index,
+        end: match.index + candidate.length,
+        resolved: formatValue(resolved.value),
+      });
+    }
+  }
+
+  // RFC-0731: Scan for this. references in mixed strings
+  if (sourceRef) {
+    const thisPattern = new RegExp(THIS_SCAN_PATTERN.source, "g");
+    let thisMatch: RegExpExecArray | null;
+    while ((thisMatch = thisPattern.exec(formulaResult)) !== null) {
+      const candidate = thisMatch[0];
+      const expanded = expandThisRef(candidate, sourceRef);
+      if (!expanded) continue;
+      const resolved = resolveReference(index, expanded, lang, defaultLang);
+      if (resolved.resolved) {
+        // Check for overlap with existing replacements
+        const thisStart = thisMatch.index;
+        const thisEnd = thisStart + candidate.length;
+        const overlaps = replacements.some((r) => thisStart < r.end && thisEnd > r.start);
+        if (!overlaps) {
+          replacements.push({
+            start: thisStart,
+            end: thisEnd,
+            resolved: formatValue(resolved.value),
+          });
+        }
+      }
+    }
+  }
+
+  for (let i = replacements.length - 1; i >= 0; i--) {
+    const { start, end, resolved } = replacements[i];
+    result = result.slice(0, start) + resolved + result.slice(end);
+  }
+
+  return result;
+}
+
+export async function resolveReferencesDeep(
+  index: ContentRefIndex,
+  data: unknown,
+  lang: string,
+  defaultLang: string,
+  sourceRef?: SourceRef,
+): Promise<unknown> {
+  return substituteRefsDeep(data, (value) =>
+    Promise.resolve(resolveReferencesInString(index, value, lang, defaultLang, sourceRef)),
+  );
+}
+
+function formatValue(value: unknown): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value.join(", ");
+  }
+  return "";
+}

package/src/share/counter-utils.ts

@@ -0,0 +1,75 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/counter-utils.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not depend on GSAP or DOM.</item>
+  <item>Do not handle animation logic.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Created shared counter utilities to eliminate duplication between hero and impact sections.</item>
+  <item>getStartValue now generates "1" in highest digit (e.g., "1,000" instead of "0,000") for better visual feedback during count-up.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface CounterStat {
+  value?: string;
+  label: string;
+  numericValue?: number;
+  prefix?: string;
+  suffix?: string;
+  decimals?: number;
+  duration?: number;
+}
+
+export interface ResolvedCounterStat extends CounterStat {
+  isAnimated: boolean;
+  startValue: string;
+  finalFormatted: string;
+}
+
+export function formatNumber(value: number, locale: string, decimals = 0): string {
+  return new Intl.NumberFormat(locale, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(value);
+}
+
+export function parseNumeric(val: string | undefined): number | undefined {
+  if (!val) return undefined;
+  const cleaned = val.replace(/[^\d.,]/g, "").replace(/,/g, "");
+  const num = parseFloat(cleaned);
+  return isNaN(num) ? undefined : num;
+}
+
+// Create start value with same width as final, starting from "1" in highest digit
+export function getStartValue(formattedFinal: string): string {
+  // Replace digits: first digit becomes "1", rest become "0"
+  // "1,250" → "1,000", "14" → "10"
+  let firstDigit = true;
+  return formattedFinal.replace(/\d/g, () => {
+    if (firstDigit) {
+      firstDigit = false;
+      return "1";
+    }
+    return "0";
+  });
+}
+
+export function resolveCounterStats(
+  stats: CounterStat[],
+  animated: boolean | undefined,
+  locale: string,
+): ResolvedCounterStat[] {
+  return stats.map((stat) => {
+    const numericValue = stat.numericValue ?? parseNumeric(stat.value);
+    const isAnimated: boolean = (animated ?? false) && numericValue !== undefined;
+    const decimals = stat.decimals ?? 0;
+    const finalFormatted =
+      numericValue !== undefined
+        ? formatNumber(numericValue, locale, decimals)
+        : (stat.value ?? "");
+    const startValue = isAnimated ? getStartValue(finalFormatted) : finalFormatted;
+    return { ...stat, numericValue, isAnimated, startValue, finalFormatted };
+  });
+}

package/src/share/css-value-normalize.ts

@@ -0,0 +1,48 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Canonical CSS value normalizer shared by biome.css.generate (codegen) and
+biome.tokens.validate (drift detection). Whitespace collapsing, quote
+normalisation, hex lowercasing, and trailing-zero stripping are applied in a
+single deterministic order so that generated CSS and drift comparisons never
+disagree on equality.
+</purpose>
+<non-goals>
+  <item>Do not format CSS for emission — line-breaking is the caller's job.</item>
+  <item>Do not parse CSS structure — this is a string-level transform only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial: unified normalizeCssValue from site-kernel-codegen and site-kernel-checks.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * Normalize a CSS value string for stable comparison and emission.
+ *
+ * Applies (in order):
+ * 1. Whitespace collapse + trim (multi-line gradients become single-line)
+ * 2. Parenthesis spacing removal
+ * 3. Single → double quote conversion
+ * 4. Hex color lowercasing
+ * 5. Trailing decimal zero stripping
+ */
+export function normalizeCssValue(value: string): string {
+  return (
+    value
+      // Collapse all whitespace runs (handles multi-line gradient formatting)
+      .replace(/\s+/g, " ")
+      .trim()
+      // Remove spaces immediately after ( and before ) so gradient args align
+      .replace(/\(\s+/g, "(")
+      .replace(/\s+\)/g, ")")
+      // CSS strings: double quotes
+      .replace(/'([^']*)'/g, '"$1"')
+      // Hex colors: lowercase
+      .replace(/#([0-9A-Fa-f]+)/g, (_m, hex) => `#${hex.toLowerCase()}`)
+      // Strip trailing decimal zeros (e.g. 20.40px → 20.4px, 1.10 → 1.1)
+      .replace(/(\d+\.\d*[1-9])0+/g, "$1")
+      // Strip redundant .0 suffix (e.g. 1.0 → 1, 0.0 → 0)
+      .replace(/(\d+)\.0+(?!\d)/g, "$1")
+  );
+}

package/src/share/dev-props-validator.ts

@@ -0,0 +1,131 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0262: the dev-only fail-fast prop validator wired into buildPage's
+`validateProps` hook. Resolves each block's manifest propsSchema at runtime
+(packages/ui/src, workspace-relative, resolved by walking up from cwd to
+pnpm-workspace.yaml — this package never ships a hand-rolled path guess) and
+throws PAGE-PROPS-01 on a genuine shape violation. Infrastructure failures
+(workspace root not found, manifest unreadable, schema unresolved) are
+swallowed with a console.warn — this is a dev convenience feature and must
+never crash rendering for a reason unrelated to the author's actual props.
+</purpose>
+<non-goals>
+  <item>Do not replace page.block.validate — that remains the authoritative build.check gate.</item>
+  <item>Do not run in production — callers must gate construction behind a dev check.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0262: initial implementation.</item>
+  <item>Replaced hand-rolled validateShape with ajv standard validator.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getSectionPropsSchema } from "@warpgogol/werkstatt-shared/ontology/schemas/manifest-resolver";
+import Ajv, { type ValidateFunction } from "ajv";
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+
+/**
+ * Block-level props consumed by blocks-renderer.astro (NOT by section components).
+ * These are valid on every block regardless of section archetype, so the
+ * validator strips them before per-section propsSchema validation.
+ *
+ * Must stay in sync with packages/os/site-kernel-checks/src/page-block.ts
+ * UNIVERSAL_BLOCK_PROPS and packages/werkstatt-site/src/domain/ui/blocks-renderer.astro.
+ */
+const UNIVERSAL_BLOCK_PROPS: ReadonlySet<string> = new Set(["hideSectionNumber", "anchorId"]);
+
+let packagesUiRootPromise: Promise<string | null> | undefined;
+
+async function resolvePackagesUiRoot(): Promise<string | null> {
+  if (!packagesUiRootPromise) {
+    packagesUiRootPromise = (async () => {
+      let dir = process.cwd();
+      for (let depth = 0; depth < 12; depth += 1) {
+        try {
+          await stat(join(dir, "pnpm-workspace.yaml"));
+          return join(dir, "packages", "werkstatt-site", "src", "domain", "ui");
+        } catch {
+          const parent = dirname(dir);
+          if (parent === dir) return null;
+          dir = parent;
+        }
+      }
+      return null;
+    })();
+  }
+  return packagesUiRootPromise;
+}
+
+const schemaCache = new Map<string, Record<string, unknown> | null>();
+const validateCache = new Map<string, ValidateFunction | null>();
+
+async function resolveSchema(planetName: string): Promise<Record<string, unknown> | null> {
+  if (schemaCache.has(planetName)) return schemaCache.get(planetName)!;
+  try {
+    const packagesUiRoot = await resolvePackagesUiRoot();
+    if (!packagesUiRoot) {
+      schemaCache.set(planetName, null);
+      return null;
+    }
+    const resolved = await getSectionPropsSchema(planetName, packagesUiRoot);
+    const schema = resolved?.propsSchema ?? null;
+    schemaCache.set(planetName, schema);
+    return schema;
+  } catch (error) {
+    console.warn(
+      `[dev-props-validator] Could not resolve propsSchema for "${planetName}": ${String(error)}`,
+    );
+    schemaCache.set(planetName, null);
+    return null;
+  }
+}
+
+function resolveValidator(planetName: string, schema: Record<string, unknown>): ValidateFunction {
+  const cached = validateCache.get(planetName);
+  if (cached) return cached;
+  const validate = ajv.compile(schema);
+  validateCache.set(planetName, validate);
+  return validate;
+}
+
+/**
+ * RFC-0262: build the `validateProps` callback for `BuildPageOptions`. Callers
+ * MUST only pass this in dev contexts (`import.meta.env.DEV` /
+ * `process.env.NODE_ENV !== "production"`) — it is never active during
+ * `astro build`.
+ */
+export function createDevPropsValidator(): (
+  planetName: string,
+  props: Record<string, unknown>,
+  blockId: string | null,
+) => Promise<void> {
+  return async (planetName, props, blockId) => {
+    const schema = await resolveSchema(planetName);
+    if (!schema) return; // No pinned schema (or resolution failed) — nothing to check.
+
+    // Strip UNIVERSAL_BLOCK_PROPS before validation — these are consumed by
+    // blocks-renderer.astro (not by the section component) and are valid on
+    // every block regardless of section archetype. Must stay in sync with
+    // packages/os/site-kernel-checks/src/page-block.ts.
+    const strippedProps: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(props)) {
+      if (!UNIVERSAL_BLOCK_PROPS.has(k)) strippedProps[k] = v;
+    }
+
+    const validate = resolveValidator(planetName, schema);
+    if (validate(strippedProps)) return;
+
+    const errors = (validate.errors ?? []).map(
+      (e) => `props${e.instancePath}: ${e.message ?? "validation failed"}`,
+    );
+    const blockLabel = blockId ? `block "${blockId}"` : "a shell block";
+    throw new Error(
+      `[PAGE-PROPS-01] ${blockLabel} (${planetName}) violates its pinned propsSchema:\n` +
+        errors.map((e) => `  - ${e}`).join("\n"),
+    );
+  };
+}