@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/scripts/ownership-conflict.mjs

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+// Ownership-conflict detection (E1 task 5.1 / CU-08).
+//
+// A view slot renders from the selected variant's assembly fragment, which
+// consumes two user-owned contract files:
+//
+//   views/<view>/schema.ts  — Zod mirrors of the block / data-shape contracts
+//   views/<view>/props.ts   — the element props objects
+//
+// Those files are user-owned: a developer may customize them and they survive
+// `sync`. When an operation selects a variant, the engine verifies that the
+// customized contract still provides every field the variant's fragment
+// requires. A customized file that dropped or renamed a required field is an
+// actionable ownership conflict: the operation reports the file and the
+// differing fields and writes nothing.
+//
+// The required field set is the *pristine template render* of the same file —
+// the canonical provider of the slot's data shape (design Decision 9) — reduced
+// to the schema/props identifiers the selected variant's fragments actually
+// reference, transitively. This is a bounded, deterministic text inspection: no
+// user code is imported or executed, and the customized file is only ever read.
+// Customization that changes values, adds fields, or relaxes fields to optional
+// keeps the required set satisfied and is never flagged.
+//
+// The detector is read-only by construction (it opens files only for reading),
+// so a rejected plan/apply/alias leaves every file byte-unchanged.
+
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { getCatalogVariant } from '../recipes/validate.mjs'
+import { DEFAULT_THEME_MODE } from './manifest.mjs'
+import { replacePlaceholders } from './render-templates.mjs'
+import { viewTemplateDir } from './reconcile.mjs'
+import { assemblyDir, hasViewAssembly } from './view-assembly.mjs'
+import {
+  resolveFeatureMountOverrides,
+  resolveViewGenerationSelection,
+} from './view-selection.mjs'
+
+export const OWNERSHIP_CONFLICT_CODE = 'E_OWNERSHIP_CONFLICT'
+
+// The user-owned contract files checked, in a stable order.
+const CONTRACT_FILES = Object.freeze([
+  { rel: 'schema.ts', kind: 'schema' },
+  { rel: 'props.ts', kind: 'props' },
+])
+
+// An identifier the selected fragment consumes from a contract file. The
+// templates name block prop schemas (`...Schema`) and element props objects
+// (`...Props`); nothing else is a data-shape contract.
+const CONTRACT_IDENTIFIER_RE = /[A-Za-z_$][\w$]*(?:Schema|Props)/g
+const IDENTIFIER_RE = /[A-Za-z_$][\w$]*/g
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function diagnostic(message, extra = {}) {
+  return { code: OWNERSHIP_CONFLICT_CODE, severity: 'error', message, ...extra }
+}
+
+function toPosix(rel) {
+  return rel.split(path.sep).join('/')
+}
+
+// Return the text inside the bracket pair starting at `openIndex`, honoring
+// strings and comments so a `}` inside a string/comment does not close early.
+// Only the matching open/close pair is counted, which is sufficient for the
+// balanced object literals these templates declare.
+function sliceBalanced(text, openIndex) {
+  const open = text[openIndex]
+  const close = open === '{' ? '}' : open === '(' ? ')' : open === '[' ? ']' : null
+  if (!close) return ''
+  let depth = 0
+  let quote = null
+  for (let i = openIndex; i < text.length; i++) {
+    const ch = text[i]
+    const next = text[i + 1]
+    if (quote) {
+      if (ch === '\\') {
+        i++
+        continue
+      }
+      if (ch === quote) quote = null
+      continue
+    }
+    if (ch === '/' && next === '/') {
+      const nl = text.indexOf('\n', i)
+      i = nl === -1 ? text.length : nl
+      continue
+    }
+    if (ch === '/' && next === '*') {
+      const end = text.indexOf('*/', i + 2)
+      i = end === -1 ? text.length : end + 1
+      continue
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      quote = ch
+      continue
+    }
+    if (ch === open) depth++
+    else if (ch === close) {
+      depth--
+      if (depth === 0) return text.slice(openIndex + 1, i)
+    }
+  }
+  return text.slice(openIndex + 1)
+}
+
+// Split an object body into its top-level entries, respecting nested
+// brackets/strings/comments so a comma inside a nested value never splits.
+function topLevelEntries(body) {
+  const entries = []
+  let depth = 0
+  let quote = null
+  let start = 0
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i]
+    const next = body[i + 1]
+    if (quote) {
+      if (ch === '\\') {
+        i++
+        continue
+      }
+      if (ch === quote) quote = null
+      continue
+    }
+    if (ch === '/' && next === '/') {
+      const nl = body.indexOf('\n', i)
+      i = nl === -1 ? body.length : nl
+      continue
+    }
+    if (ch === '/' && next === '*') {
+      const end = body.indexOf('*/', i + 2)
+      i = end === -1 ? body.length : end + 1
+      continue
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      quote = ch
+      continue
+    }
+    if (ch === '{' || ch === '(' || ch === '[') depth++
+    else if (ch === '}' || ch === ')' || ch === ']') depth--
+    else if (ch === ',' && depth === 0) {
+      entries.push(body.slice(start, i))
+      start = i + 1
+    }
+  }
+  entries.push(body.slice(start))
+  return entries.map((entry) => entry.trim()).filter(Boolean)
+}
+
+const ENTRY_RE = /^(?:\.\.\.\s*)?(?:"([^"]+)"|'([^']+)'|([A-Za-z_$][\w$]*))\s*(?::([\s\S]*))?$/
+
+function parseEntry(entry) {
+  const spread = /^\.\.\./.test(entry)
+  const match = entry.match(ENTRY_RE)
+  if (!match) return null
+  const key = match[1] ?? match[2] ?? match[3]
+  return { key, value: (match[4] ?? '').trim(), spread }
+}
+
+// Map each `const <id> = z.object({ ... })` to its top-level field names. A
+// spread-free object literal is what these mirrors declare; anonymous nested
+// objects are not named and are reached through their referencing schema.
+function extractSchemaFields(text) {
+  const out = new Map()
+  const re = /(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*z\s*\.\s*object\s*\(/g
+  let match
+  while ((match = re.exec(text))) {
+    const id = match[1]
+    const paren = match.index + match[0].length - 1
+    const brace = text.indexOf('{', paren)
+    if (brace === -1) continue
+    const fields = new Map()
+    for (const entry of topLevelEntries(sliceBalanced(text, brace))) {
+      const parsed = parseEntry(entry)
+      if (parsed && !parsed.spread) fields.set(parsed.key, parsed.value)
+    }
+    out.set(id, fields)
+  }
+  return out
+}
+
+// Map each `const <id> = { ... }` object literal to its top-level field names.
+// A spread entry (`...content`) is not a field, so it is not recorded.
+function extractObjectFields(text) {
+  const out = new Map()
+  const re = /(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*\{/g
+  let match
+  while ((match = re.exec(text))) {
+    const id = match[1]
+    const brace = match.index + match[0].length - 1
+    const fields = new Map()
+    for (const entry of topLevelEntries(sliceBalanced(text, brace))) {
+      const parsed = parseEntry(entry)
+      if (parsed && !parsed.spread) fields.set(parsed.key, parsed.value)
+    }
+    out.set(id, fields)
+  }
+  return out
+}
+
+// The transitive field set reachable from a root schema identifier: the root's
+// own fields plus, for every field value that references another declared
+// schema (e.g. `z.array(featureItemSchema)`), that schema's fields. This is what
+// lets a removed item field inside `featureItemSchema` surface through the
+// `featurePropsSchema` the fragment references.
+function transitiveFields(fieldSets, rootId, seen = new Set()) {
+  const out = new Map()
+  const direct = fieldSets.get(rootId)
+  if (!direct || seen.has(rootId)) return out
+  seen.add(rootId)
+  for (const [key, value] of direct) {
+    out.set(key, value)
+    for (const ref of value.match(IDENTIFIER_RE) ?? []) {
+      if (ref === rootId || !fieldSets.has(ref)) continue
+      for (const [nestedKey, nestedValue] of transitiveFields(fieldSets, ref, seen)) {
+        out.set(nestedKey, nestedValue)
+      }
+    }
+  }
+  return out
+}
+
+// Collect the contract identifiers a selected variant's fragments consume.
+function referencedIdentifiers(templateDir, slot, variant) {
+  const dir = path.join(assemblyDir(templateDir), 'slots', slot, variant)
+  const ids = new Set()
+  for (const name of ['catalog.part', 'registry.part', 'element.part']) {
+    const file = path.join(dir, name)
+    if (!existsSync(file)) continue
+    for (const id of readFileSync(file, 'utf8').match(CONTRACT_IDENTIFIER_RE) ?? []) {
+      ids.add(id)
+    }
+  }
+  return ids
+}
+
+function compareContract({ relPath, kind, pristineText, customizedText, rootIds }) {
+  const pristineSets = kind === 'schema' ? extractSchemaFields(pristineText) : extractObjectFields(pristineText)
+  const customizedSets =
+    kind === 'schema' ? extractSchemaFields(customizedText) : extractObjectFields(customizedText)
+  const required = new Map()
+  const provided = new Map()
+  for (const id of rootIds) {
+    if (kind === 'schema') {
+      if (!pristineSets.has(id)) continue
+      for (const [key, value] of transitiveFields(pristineSets, id)) required.set(key, value)
+      for (const [key, value] of transitiveFields(customizedSets, id)) provided.set(key, value)
+    } else {
+      // Element props are flat: a spread (`...content`) is not a field, so a
+      // root with only spreads requires nothing and can never conflict.
+      const pristineFields = pristineSets.get(id)
+      if (!pristineFields) continue
+      for (const [key, value] of pristineFields) required.set(key, value)
+      for (const [key, value] of customizedSets.get(id) ?? []) provided.set(key, value)
+    }
+  }
+  const missing = [...required.keys()].filter((key) => !provided.has(key)).sort()
+  if (missing.length === 0) return null
+  return {
+    path: relPath,
+    fields: missing,
+    expected: [...required.keys()].sort(),
+    actual: [...provided.keys()].sort(),
+  }
+}
+
+/**
+ * Detect ownership conflicts for the composition described by `manifest`.
+ *
+ * Returns `{ ok, diagnostics }`. A conflict is reported for every customized
+ * user-owned `views/<view>/schema.ts` / `props.ts` that no longer provides a
+ * field required by a variant the manifest selects (directly or through a
+ * feature mount). Nothing is written. `options.viewTemplateDir` is the hermetic
+ * injection seam a test uses without touching the template tree; it defaults to
+ * the package resolver.
+ */
+export function detectOwnershipConflicts(projectDir, manifest, options = {}) {
+  const name = isPlainObject(manifest) && typeof manifest.name === 'string' ? manifest.name : null
+  if (!name) return { ok: true, diagnostics: [] }
+  const resolveTemplateDir =
+    typeof options.viewTemplateDir === 'function' ? options.viewTemplateDir : viewTemplateDir
+
+  const mountOverrides = resolveFeatureMountOverrides(manifest)
+  if (!mountOverrides.ok) return { ok: true, diagnostics: [] }
+
+  const subs = {
+    name,
+    siteName: manifest.siteName ?? name,
+    mode: manifest.theme?.mode ?? DEFAULT_THEME_MODE,
+  }
+  const diagnostics = []
+  const views = Array.isArray(manifest.views) ? manifest.views : []
+  for (const view of views) {
+    const viewName = typeof view === 'string' ? view : view?.name
+    if (typeof viewName !== 'string') continue
+    const templateDir = resolveTemplateDir(viewName)
+    if (!templateDir || !hasViewAssembly(templateDir)) continue
+    const resolved = resolveViewGenerationSelection(view, mountOverrides.byView)
+    if (!resolved.ok) continue
+    const selectedSlots = Object.keys(resolved.selection)
+    if (selectedSlots.length === 0) continue
+
+    const viewDir = path.join(projectDir, 'lib', name, 'views', viewName)
+    for (const { rel, kind } of CONTRACT_FILES) {
+      const abs = path.join(viewDir, rel)
+      const templateFile = path.join(templateDir, rel)
+      if (!existsSync(abs) || !existsSync(templateFile)) continue
+      const customizedText = readFileSync(abs, 'utf8')
+      const pristineText = replacePlaceholders(readFileSync(templateFile, 'utf8'), subs)
+      // A pristine file is the canonical contract; only a customized file can
+      // conflict with the selected variant.
+      if (customizedText === pristineText) continue
+      const projectRel = toPosix(path.relative(projectDir, abs))
+
+      for (const slot of selectedSlots) {
+        const variant = resolved.selection[slot]
+        const rootIds = [...referencedIdentifiers(templateDir, slot, variant)].filter((id) =>
+          kind === 'schema' ? /Schema$/.test(id) : /Props$/.test(id),
+        )
+        if (rootIds.length === 0) continue
+        const conflict = compareContract({
+          relPath: projectRel,
+          kind,
+          pristineText,
+          customizedText,
+          rootIds,
+        })
+        if (!conflict) continue
+        const dataShape = getCatalogVariant(viewName, slot, variant)?.dataShape ?? variant
+        diagnostics.push(
+          diagnostic(
+            `The customized user-owned file "${projectRel}" no longer provides the data shape required by ${viewName}.${slot} variant "${variant}". Missing field(s): ${conflict.fields.join(', ')}. Add the missing field(s) to the user-owned contract (or select a compatible variant), then re-plan.`,
+            {
+              path: projectRel,
+              detail: {
+                file: projectRel,
+                view: viewName,
+                slot,
+                variant,
+                dataShape,
+                fields: conflict.fields,
+                expected: conflict.expected,
+                actual: conflict.actual,
+                recovery: 'adapt-the-user-owned-contract-and-replan',
+              },
+            },
+          ),
+        )
+      }
+    }
+  }
+  return { ok: diagnostics.length === 0, diagnostics }
+}