@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/scripts/section-compat.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+// Deterministic normalization and persisted legacy-id migration for a view's
+// ordered `views[].sections` composition (E3 task 1.5, CU-15/CU-16).
+//
+// The pure entry point maps a declared section list — possibly missing, empty,
+// or in the pre-E3 legacy `{ name, variant }` shape — to the ordered
+// `{ id, type, variant? }` model:
+//   * a registered presentation slot is `{ id: "slot:<slot>", type: "<slot>" }`
+//     and is mandatory: the normalized list always contains every registered
+//     slot exactly once, in registry order unless the declared list reorders it;
+//   * a legacy entry migrates to `{ id: "<name>-<n>", type: "<name>",
+//     variant? }`, where `n` is the 1-based position among the view's legacy
+//     entries in declared order, appended after the slots;
+//   * anything that cannot be adapted safely (a held/disallowed legacy type, a
+//     reserved-prefixed id, a duplicate) is refused with a diagnostic and no
+//     output, so the caller writes nothing.
+//
+// It is a pure function over its arguments (same input -> identical output) and
+// depends only on the Node standard library. Wiring it into the manifest
+// load/validation and CLI paths is owned by the later migration/operation tasks
+// (§3/§5); this module does not touch the filesystem beyond reading the registry
+// for the optional convenience wrapper.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0
+}
+
+function slotEntry(slot) {
+  return { id: `slot:${slot}`, type: slot }
+}
+
+// Copy only the declared fields, so an entry carrying an unknown property never
+// leaks into the normalized output and the input object is never mutated.
+function copyEntry(entry) {
+  return {
+    id: entry.id,
+    type: entry.type,
+    ...(isNonEmptyString(entry.variant) ? { variant: entry.variant } : {}),
+  }
+}
+
+// A legacy `{ name, variant? }` entry (or its bare-string shorthand) — the
+// pre-E3 shape that has no id/type yet.
+export function isLegacySectionEntry(entry) {
+  const value = typeof entry === 'string' ? { name: entry } : entry
+  if (!isPlainObject(value)) return false
+  if (isNonEmptyString(value.id) || isNonEmptyString(value.type)) return false
+  return isNonEmptyString(value.name)
+}
+
+// A registered-slot entry: the reserved `id === "slot:" + type` form.
+export function isSlotSectionEntry(entry) {
+  return (
+    isPlainObject(entry) &&
+    isNonEmptyString(entry.id) &&
+    isNonEmptyString(entry.type) &&
+    entry.id === `slot:${entry.type}`
+  )
+}
+
+// An editorial instance: a persisted id that must not start with `slot:`.
+export function isEditorialSectionEntry(entry) {
+  return (
+    isPlainObject(entry) &&
+    isNonEmptyString(entry.id) &&
+    isNonEmptyString(entry.type) &&
+    !entry.id.startsWith('slot:')
+  )
+}
+
+// Discriminate a declared entry: 'slot' (reserved id form), 'editorial'
+// (persisted non-reserved id), 'legacy' (`{ name }`), or 'invalid'.
+export function classifySectionEntry(entry) {
+  const value = typeof entry === 'string' ? { name: entry } : entry
+  if (!isPlainObject(value)) return 'invalid'
+  const hasId = isNonEmptyString(value.id)
+  const hasType = isNonEmptyString(value.type)
+  const hasName = isNonEmptyString(value.name)
+  if (hasId && hasType && !hasName) {
+    return value.id.startsWith('slot:') ? 'slot' : 'editorial'
+  }
+  if (hasName && !hasId && !hasType) return 'legacy'
+  return 'invalid'
+}
+
+/**
+ * Normalize one view's declared sections to the ordered composition model.
+ *
+ * @param {string} viewName
+ * @param {unknown[]} declaredSections the manifest `views[].sections` (may be
+ *   missing/empty, legacy, new-form, or a mix)
+ * @param {string[]} registeredSlots the view's ordered core slots
+ * @param {{ allowedSections?: string[], maxSections?: number }} [options]
+ * @returns {{ ok: boolean, sections: object[] | null, diagnostics: object[] }}
+ *   On failure `sections` is null (no output) and `diagnostics` is non-empty.
+ */
+export function normalizeViewSections(viewName, declaredSections, registeredSlots, options = {}) {
+  const slots = Array.isArray(registeredSlots) ? registeredSlots.filter(isNonEmptyString) : []
+  const allowedSections = Array.isArray(options.allowedSections) ? options.allowedSections : null
+  const maxSections = typeof options.maxSections === 'number' ? options.maxSections : null
+  const declared = Array.isArray(declaredSections) ? declaredSections : []
+
+  const diagnostics = []
+  const push = (code, message, path) =>
+    diagnostics.push({ code, severity: 'error', message, ...(path ? { path } : {}) })
+
+  // Missing/empty composition: the registered slots in current render order and
+  // no editorial instance.
+  if (declared.length === 0) {
+    return { ok: true, sections: slots.map(slotEntry), diagnostics: [] }
+  }
+
+  const emitted = []
+  const seenIds = new Set()
+  const emittedSlots = new Set()
+  const legacy = []
+
+  declared.forEach((raw, index) => {
+    const path = `views["${viewName}"].sections[${index}]`
+    const entry = typeof raw === 'string' ? { name: raw } : raw
+    const kind = classifySectionEntry(entry)
+
+    if (kind === 'slot') {
+      if (entry.id !== `slot:${entry.type}`) {
+        push(
+          'E_RESERVED_ID',
+          `${path} reserved slot id "${entry.id}" must equal "slot:${entry.type}".`,
+          path,
+        )
+        return
+      }
+      if (!slots.includes(entry.type)) {
+        push('E_UNKNOWN_HOST', `${path} names unregistered slot "${entry.type}".`, path)
+        return
+      }
+      if (emittedSlots.has(entry.type) || seenIds.has(entry.id)) {
+        push('E_DUPLICATE_ID', `${path} duplicate section id "${entry.id}".`, path)
+        return
+      }
+      emitted.push(copyEntry(entry))
+      emittedSlots.add(entry.type)
+      seenIds.add(entry.id)
+      return
+    }
+
+    if (kind === 'editorial') {
+      if (seenIds.has(entry.id)) {
+        push('E_DUPLICATE_ID', `${path} duplicate section id "${entry.id}".`, path)
+        return
+      }
+      if (allowedSections && !allowedSections.includes(entry.type)) {
+        push(
+          'E_DISALLOWED_TYPE',
+          `${path} section type "${entry.type}" is not an allowed section for view "${viewName}".`,
+          path,
+        )
+        return
+      }
+      emitted.push(copyEntry(entry))
+      seenIds.add(entry.id)
+      return
+    }
+
+    if (kind === 'legacy') {
+      legacy.push({ entry, path })
+      return
+    }
+
+    push(
+      'E_UNKNOWN_SECTION_SHAPE',
+      `${path} is neither a legacy { name } entry nor an { id, type } entry.`,
+      path,
+    )
+  })
+
+  // Every registered slot is mandatory: append any the declared list omitted, in
+  // registry order, so the normalized composition always contains each slot
+  // exactly once.
+  for (const slot of slots) {
+    if (!emittedSlots.has(slot)) {
+      const entry = slotEntry(slot)
+      emitted.push(entry)
+      emittedSlots.add(slot)
+      seenIds.add(entry.id)
+    }
+  }
+
+  // Persisted legacy migration: a concrete `<name>-<n>` id derived once from the
+  // 1-based position among the view's legacy entries, appended after the slots.
+  legacy.forEach(({ entry, path }, index) => {
+    const id = `${entry.name}-${index + 1}`
+    if (id.startsWith('slot:')) {
+      push(
+        'E_RESERVED_ID',
+        `${path} legacy name "${entry.name}" would mint a reserved id "${id}".`,
+        path,
+      )
+      return
+    }
+    if (allowedSections && !allowedSections.includes(entry.name)) {
+      push(
+        'E_DISALLOWED_TYPE',
+        `${path} legacy section "${entry.name}" is not an allowed section for view "${viewName}" (held or missing a verified bridge/provenance or data source); it cannot be adapted.`,
+        path,
+      )
+      return
+    }
+    if (seenIds.has(id)) {
+      push(
+        'E_DUPLICATE_ID',
+        `${path} legacy section "${entry.name}" would mint duplicate id "${id}".`,
+        path,
+      )
+      return
+    }
+    emitted.push({
+      id,
+      type: entry.name,
+      ...(isNonEmptyString(entry.variant) ? { variant: entry.variant } : {}),
+    })
+    seenIds.add(id)
+  })
+
+  if (diagnostics.length > 0) {
+    return { ok: false, sections: null, diagnostics }
+  }
+
+  const editorialCount = emitted.filter((entry) => isEditorialSectionEntry(entry)).length
+  if (maxSections !== null && editorialCount > maxSections) {
+    return {
+      ok: false,
+      sections: null,
+      diagnostics: [
+        {
+          code: 'E_SECTION_LIMIT',
+          severity: 'error',
+          message: `View "${viewName}" normalized to ${editorialCount} editorial instances, exceeding maxSections ${maxSections}.`,
+        },
+      ],
+    }
+  }
+
+  return { ok: true, sections: emitted, diagnostics: [] }
+}
+
+// Package-side seam over the view registry: resolve a view's `registeredSlots`,
+// `allowedSections`, and `maxSections` and normalize its declared sections. The
+// registry is read from the package (`recipes/`) or the installed-skill assets,
+// so the caller passes only the view name and its declared list.
+function resolveRegistryPath() {
+  const candidates = [
+    join(here, '..', 'recipes', 'recipes.json'),
+    join(here, 'recipes.json'),
+    join(here, '..', 'assets', 'recipes', 'recipes.json'),
+  ]
+  return candidates.find((candidate) => existsSync(candidate)) ?? null
+}
+
+let cachedRecipes = null
+
+function loadRecipes() {
+  if (!cachedRecipes) {
+    const path = resolveRegistryPath()
+    if (!path) throw new Error('section-compat: could not locate the view recipe registry.')
+    cachedRecipes = JSON.parse(readFileSync(path, 'utf8'))
+  }
+  return cachedRecipes
+}
+
+
+export function normalizeViewSectionsForView(viewName, declaredSections) {
+  const recipe = loadRecipes().views.find((view) => view.name === viewName) ?? null
+  if (!recipe) {
+    return {
+      ok: false,
+      sections: null,
+      diagnostics: [
+        {
+          code: 'E_UNKNOWN_VIEW',
+          severity: 'error',
+          message: `Unknown view "${viewName}".`,
+        },
+      ],
+    }
+  }
+  return normalizeViewSections(viewName, declaredSections, recipe.registeredSlots ?? [], {
+    allowedSections: recipe.allowedSections ?? [],
+    maxSections: recipe.maxSections,
+  })
+}