@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

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,
+  })
+}

package/scripts/section-config.mjs

@@ -0,0 +1,253 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+// User-owned source configuration audit.
+//
+// Data-bound section instances (for example the `products` type) resolve their
+// content from a canonical query the user declares in a user-owned `data.ts`
+// export named `sectionSources`. The manifest records only the structural
+// instance (`{ id, type, variant }`); the query lives in the user file. `sync`
+// never patches user files, so a freshly added instance is intentionally
+// unconfigured until the user supplies its entry. `doctor` reports those gaps
+// with the file and instance id so the repair is actionable.
+//
+// The audit is a conservative static read of the object literal: it extracts
+// the top-level keys of `sectionSources` and whether each value is an object.
+// It never executes the user file and never rewrites it. Deep validity (the
+// canonical query fields) is enforced at build/runtime by the runtime
+// `sectionSourceSchema`, which surfaces an `unconfigured` state for the
+// instance rather than failing the page.
+
+/** Locate the `sectionSources` declaration and return the index of its name. */
+function findSectionSourcesIndex(source) {
+  const match = /\bsectionSources\b/.exec(source)
+  return match ? match.index : -1
+}
+
+/**
+ * Match the brace that opens at `open` and return the index of its closer,
+ * ignoring braces inside string literals and comments. Returns -1 when
+ * unbalanced.
+ */
+function matchBrace(source, open) {
+  let depth = 0
+  let i = open
+  while (i < source.length) {
+    const ch = source[i]
+    if (ch === '/' && source[i + 1] === '/') {
+      i = source.indexOf('\n', i)
+      if (i < 0) return -1
+      continue
+    }
+    if (ch === '/' && source[i + 1] === '*') {
+      const end = source.indexOf('*/', i + 2)
+      if (end < 0) return -1
+      i = end + 2
+      continue
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      i = skipString(source, i)
+      if (i < 0) return -1
+      continue
+    }
+    if (ch === '{') depth++
+    else if (ch === '}') {
+      depth--
+      if (depth === 0) return i
+    }
+    i++
+  }
+  return -1
+}
+
+/** Advance past a string literal starting at `start`; returns the index after it. */
+function skipString(source, start) {
+  const quote = source[start]
+  let i = start + 1
+  while (i < source.length) {
+    if (source[i] === '\\') {
+      i += 2
+      continue
+    }
+    if (source[i] === quote) return i + 1
+    i++
+  }
+  return -1
+}
+
+/** Advance past a value starting at `start`, returning the index at depth 0 after it. */
+function skipValue(source, start) {
+  let depth = 0
+  let i = start
+  while (i < source.length) {
+    const ch = source[i]
+    if (ch === '/' && source[i + 1] === '/') {
+      const nl = source.indexOf('\n', i)
+      if (nl < 0) return source.length
+      i = nl + 1
+      continue
+    }
+    if (ch === '/' && source[i + 1] === '*') {
+      const end = source.indexOf('*/', i + 2)
+      if (end < 0) return source.length
+      i = end + 2
+      continue
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const next = skipString(source, i)
+      if (next < 0) return source.length
+      i = next
+      continue
+    }
+    if (ch === '{' || ch === '[' || ch === '(') depth++
+    else if (ch === '}' || ch === ']' || ch === ')') {
+      if (depth === 0) return i
+      depth--
+    } else if (ch === ',' && depth === 0) return i
+    i++
+  }
+  return source.length
+}
+
+/** Read an object key at `start` (quoted string or bare identifier). */
+function readKey(source, start) {
+  const ch = source[start]
+  if (ch === '"' || ch === "'" || ch === '`') {
+    const end = skipString(source, start)
+    if (end < 0) return null
+    return { key: source.slice(start + 1, end - 1), next: end }
+  }
+  let i = start
+  while (i < source.length && /[A-Za-z0-9_$]/.test(source[i])) i++
+  if (i === start) return null
+  return { key: source.slice(start, i), next: i }
+}
+
+function skipWhitespaceAndComments(source, start) {
+  let i = start
+  while (i < source.length) {
+    const ch = source[i]
+    if (/\s/.test(ch)) {
+      i++
+      continue
+    }
+    if (ch === '/' && source[i + 1] === '/') {
+      const nl = source.indexOf('\n', i)
+      if (nl < 0) return source.length
+      i = nl + 1
+      continue
+    }
+    if (ch === '/' && source[i + 1] === '*') {
+      const end = source.indexOf('*/', i + 2)
+      if (end < 0) return source.length
+      i = end + 2
+      continue
+    }
+    break
+  }
+  return i
+}
+
+/**
+ * Extract the top-level entries of the `sectionSources` object literal in a
+ * `data.ts` source. Returns a Map of key -> `{ objectValue }` (whether the
+ * declared value is an object literal). An absent or unparsable declaration
+ * yields an empty Map.
+ */
+export function extractSectionSourceEntries(source) {
+  const entries = new Map()
+  if (typeof source !== 'string') return entries
+  const declIndex = findSectionSourcesIndex(source)
+  if (declIndex < 0) return entries
+  const bodyStart = source.indexOf('{', declIndex)
+  if (bodyStart < 0) return entries
+  const bodyEnd = matchBrace(source, bodyStart)
+  if (bodyEnd < 0) return entries
+  const body = source.slice(bodyStart + 1, bodyEnd)
+  let i = 0
+  while (i < body.length) {
+    i = skipWhitespaceAndComments(body, i)
+    if (i >= body.length) break
+    const key = readKey(body, i)
+    if (!key) break
+    const colon = skipWhitespaceAndComments(body, key.next)
+    if (body[colon] !== ':') break
+    const valueStart = skipWhitespaceAndComments(body, colon + 1)
+    entries.set(key.key, { objectValue: body[valueStart] === '{' })
+    i = skipValue(body, valueStart)
+    if (body[i] === ',') i++
+  }
+  return entries
+}
+
+/**
+ * The data-bound section instances declared across a manifest's views, in
+ * order. `isDataBound` is the predicate that identifies a data-bound type
+ * (typically `sectionIsDataBound` from `recipes/validate.mjs`).
+ */
+export function collectDataBoundInstances(manifest, isDataBound) {
+  const instances = []
+  const views = Array.isArray(manifest?.views) ? manifest.views : []
+  for (const view of views) {
+    const sections = Array.isArray(view?.sections) ? view.sections : []
+    for (const section of sections) {
+      if (!section || typeof section.type !== 'string') continue
+      if (!isDataBound(section.type)) continue
+      instances.push({
+        view: view.name,
+        id: section.id,
+        type: section.type,
+        variant: typeof section.variant === 'string' ? section.variant : null,
+      })
+    }
+  }
+  return instances
+}
+
+/**
+ * Audit a project's user-owned source configuration against its data-bound
+ * section instances. Returns `{ diagnostics }` where each diagnostic carries
+ * the owning view, the instance id/type, the user-owned file, and a repair
+ * message. Missing declarations and non-object declarations are both reported;
+ * deep query validity is enforced at build/runtime, not here.
+ */
+export function auditSectionConfig({ dir, manifest, isDataBound }) {
+  const diagnostics = []
+  const name = typeof manifest?.name === 'string' && manifest.name.length > 0 ? manifest.name : 'storefront'
+  const instances = collectDataBoundInstances(manifest, isDataBound)
+  const byView = new Map()
+  for (const instance of instances) {
+    if (!byView.has(instance.view)) byView.set(instance.view, [])
+    byView.get(instance.view).push(instance)
+  }
+  for (const [view, viewInstances] of byView) {
+    const relPath = `lib/${name}/views/${view}/data.ts`
+    const absPath = join(dir, relPath)
+    const entries = existsSync(absPath)
+      ? extractSectionSourceEntries(readFileSync(absPath, 'utf8'))
+      : null
+    for (const instance of viewInstances) {
+      const entry = entries?.get(instance.id)
+      if (!entry) {
+        diagnostics.push({
+          code: 'E_SECTION_CONFIG_MISSING',
+          view,
+          id: instance.id,
+          type: instance.type,
+          path: relPath,
+          message: `section "${instance.id}" (${instance.type}) is not configured; add a sectionSources["${instance.id}"] entry in ${relPath}`,
+        })
+      } else if (!entry.objectValue) {
+        diagnostics.push({
+          code: 'E_SECTION_CONFIG_INVALID',
+          view,
+          id: instance.id,
+          type: instance.type,
+          path: relPath,
+          message: `sectionSources["${instance.id}"] in ${relPath} must be an object literal (kind/query/maxItems)`,
+        })
+      }
+    }
+  }
+  return { diagnostics }
+}