create-kywi-app 0.18.0 → 0.20.0

package/lib/config-scan.mjs

@@ -0,0 +1,385 @@
+/**
+ * Reads the SITES and THEMES out of a project's `kywi.config.ts` — as text.
+ *
+ * WHY NOT PARSE IT PROPERLY. `create-kywi-app` is dependency-free (Node
+ * builtins only, `engines.node >= 20`): it is run through `npx` before the
+ * project it scaffolds exists, so it cannot pull in TypeScript or an AST
+ * library, and it cannot `import()` the config either — that file imports
+ * `@kywi-software/core/config` and calls `assertProductionAuthSecret`. The
+ * precedent is already in the CLI: `detectMode` reads the same file with one
+ * regex. This is that trade taken one level up, and it stays honest about it —
+ * anything it cannot understand comes back in `problems` rather than as a
+ * confident wrong answer.
+ *
+ * WHY IT EXISTS AT ALL. `upgrade` regenerates `kywi.layers.ts`, and that
+ * registry must enumerate exactly the sites the config declares and, for each,
+ * its theme: core's `assertLayerContracts` (plan E2) throws at boot when a
+ * configured site or theme has no layer. Regenerating from the scaffold's
+ * hard-wired single `default` site would break every project that has grown a
+ * second one (kywi-marketing-v3 carries a demo site alongside its own).
+ *
+ * HOW IT READS. One tokenizer pass masks out what must not be read as
+ * structure — `//` and block comments, and the CONTENTS of `'…'`, `"…"` and
+ * `` `…` `` literals — keeping every character position, so a second pass can
+ * track `{`/`[` depth over the masked text and single-line regexes can find
+ * properties at a KNOWN depth. That is what stops a comment's stray `{`, a
+ * string's `}`, or a nested `tokens: { name: … }` from being read as config
+ * structure. String VALUES are then taken from the original text, using the
+ * literal bounds the mask recorded.
+ *
+ * WHAT IT DOES NOT HANDLE (and reports rather than guesses): quoted property
+ * keys (`'id': 'x'`), computed or spread properties, a site object built
+ * outside the array and referenced by name, and regex literals containing
+ * quotes or braces.
+ */
+
+/** @typedef {'coupled'|'headless'|'decoupled'} KywiMode */
+/** @typedef {{ mode: KywiMode|null, sites: Array<{ id: string, theme: string|null }>, themes: Array<{ name: string }>, problems: string[] }} ConfigScan */
+
+/** The same pattern `bin/create-kywi-app.mjs`'s `detectMode` uses, made global. */
+const MODE_RE = /mode:\s*['"](coupled|headless|decoupled)['"]/g
+
+/**
+ * Blank every comment, and the inside of every string literal, to spaces —
+ * newlines kept, so positions and line numbers survive. Returns the masked text
+ * plus the bounds of each string literal, which is how a caller reads a VALUE
+ * back out of the original text without re-implementing quote handling.
+ * @param {string} text
+ * @returns {{ masked: string, strings: Map<number, number> }} strings: opening quote index → closing quote index
+ */
+function maskText(text) {
+  const chars = text.split('')
+  /** @type {Map<number, number>} */
+  const strings = new Map()
+  const n = text.length
+  const blank = (from, to) => {
+    for (let k = from; k < to && k < n; k++) if (chars[k] !== '\n') chars[k] = ' '
+  }
+
+  let i = 0
+  while (i < n) {
+    const ch = text[i]
+
+    if (ch === '/' && text[i + 1] === '/') {
+      const nl = text.indexOf('\n', i)
+      const end = nl === -1 ? n : nl
+      blank(i, end)
+      i = end
+      continue
+    }
+
+    if (ch === '/' && text[i + 1] === '*') {
+      const close = text.indexOf('*/', i + 2)
+      const end = close === -1 ? n : close + 2
+      blank(i, end)
+      i = end
+      continue
+    }
+
+    if (ch === "'" || ch === '"' || ch === '`') {
+      // A template literal may contain `${…}`; the whole literal is opaque, so
+      // the interpolation is masked with everything else and its braces never
+      // reach the depth pass. Nesting a literal inside `${}` is not supported
+      // (nor does any config need it).
+      let j = i + 1
+      while (j < n) {
+        if (text[j] === '\\') {
+          j += 2
+          continue
+        }
+        if (text[j] === ch) break
+        if (ch !== '`' && text[j] === '\n') break // unterminated — do not swallow the file
+        j++
+      }
+      if (j < n && text[j] === ch) {
+        blank(i + 1, j)
+        strings.set(i, j)
+        i = j + 1
+      } else {
+        blank(i + 1, j)
+        i = Math.min(j, n) // j > i always, so this terminates
+      }
+      continue
+    }
+
+    i++
+  }
+
+  return { masked: chars.join(''), strings }
+}
+
+/**
+ * Nesting depth at every character of the masked text. An opening brace carries
+ * the depth OUTSIDE it and its closer the same, so everything strictly between
+ * a `{…}` reads one deeper — which is what "a property at depth 1 of the
+ * outermost object" means concretely.
+ * @param {string} masked
+ * @returns {Int32Array}
+ */
+function depthMap(masked) {
+  const depth = new Int32Array(masked.length)
+  let cur = 0
+  for (let i = 0; i < masked.length; i++) {
+    const ch = masked[i]
+    if (ch === '}' || ch === ']') cur--
+    depth[i] = cur
+    if (ch === '{' || ch === '[') cur++
+  }
+  return depth
+}
+
+/** Index of the `}`/`]` closing the opener at `open`, or -1. */
+function matchingClose(masked, depth, open) {
+  const closer = masked[open] === '{' ? '}' : ']'
+  const d = depth[open]
+  for (let i = open + 1; i < masked.length; i++) {
+    if (masked[i] === closer && depth[i] === d) return i
+  }
+  return -1
+}
+
+/** Index of the first non-whitespace character in `[from, to)`, or -1. */
+function firstNonSpace(masked, from, to) {
+  for (let i = from; i < to; i++) if (!/\s/.test(masked[i])) return i
+  return -1
+}
+
+/**
+ * Locate the config object literal's opening `{`. Three accepted shapes, all in
+ * the wild: `export default { … }`, `export default defineKywiConfig({ … })`
+ * (what the scaffold emits) and `const config = { … }` + `export default config`.
+ * @returns {number} index of the `{`, or -1
+ */
+function findConfigObject(masked) {
+  const ed = /export\s+default\s+/.exec(masked)
+  if (!ed) return -1
+  const after = ed.index + ed[0].length
+  if (masked[after] === '{') return after
+
+  const ident = /^([A-Za-z_$][\w$]*)\s*/.exec(masked.slice(after))
+  if (!ident) return -1
+  const afterIdent = after + ident[0].length
+
+  if (masked[afterIdent] === '(') {
+    // `defineKywiConfig({ … })` — the call's first object argument.
+    const brace = firstNonSpace(masked, afterIdent + 1, masked.length)
+    return brace !== -1 && masked[brace] === '{' ? brace : -1
+  }
+
+  // `export default config` — follow the binding back to its initialiser.
+  const decl = new RegExp(`(?:const|let|var)\\s+${ident[1]}\\s*(?::[^=\\n]*)?=\\s*`).exec(masked)
+  if (!decl) return -1
+  const start = decl.index + decl[0].length
+  return masked[start] === '{' ? start : -1
+}
+
+/**
+ * The value position of a property `name:` found at exactly `wantDepth` inside
+ * `(from, to)`. Depth is what makes this safe: `tokens: { name: 'x' }` sits one
+ * level deeper than the theme's own `name`.
+ * @returns {number} index just past `name:` and its whitespace, or -1
+ */
+function propertyValueAt(masked, depth, name, from, to, wantDepth) {
+  const re = new RegExp(`\\b${name}\\s*:\\s*`, 'g')
+  const region = masked.slice(from, to)
+  let m
+  while ((m = re.exec(region)) !== null) {
+    const at = from + m.index
+    if (depth[at] !== wantDepth) continue
+    return at + m[0].length
+  }
+  return -1
+}
+
+/** JS string escapes, enough for the values a config puts in an id or a theme name. */
+function unescapeString(s) {
+  return s.replace(/\\(u\{[0-9a-fA-F]+\}|u[0-9a-fA-F]{4}|x[0-9a-fA-F]{2}|[\s\S])/g, (_, g) => {
+    if (g[0] === 'u') {
+      const hex = g[1] === '{' ? g.slice(2, -1) : g.slice(1)
+      return String.fromCodePoint(parseInt(hex, 16))
+    }
+    if (g[0] === 'x') return String.fromCharCode(parseInt(g.slice(1), 16))
+    const simple = { n: '\n', t: '\t', r: '\r', b: '\b', f: '\f', v: '\v', '0': '\0' }
+    return simple[g] ?? g
+  })
+}
+
+/**
+ * Read a STRING property of the object literal opening at `objOpen`.
+ * @returns {{ found: boolean, value: string|null }} `found` false = no such
+ * property; `found` true with a null value = present but not a string literal.
+ */
+function readStringProp(text, masked, depth, strings, objOpen, objClose, name) {
+  const at = propertyValueAt(masked, depth, name, objOpen + 1, objClose, depth[objOpen] + 1)
+  if (at === -1) return { found: false, value: null }
+  const end = strings.get(at)
+  if (end === undefined) return { found: true, value: null }
+  return { found: true, value: unescapeString(text.slice(at + 1, end)) }
+}
+
+/**
+ * Split an array literal into its elements at the array's own depth, so a
+ * comma inside a nested object — or inside a string — never splits.
+ * @returns {Array<[number, number]>} half-open `[start, end)` spans
+ */
+function arrayElements(masked, depth, open, close) {
+  const inner = depth[open] + 1
+  /** @type {Array<[number, number]>} */
+  const spans = []
+  let start = open + 1
+  for (let i = start; i < close; i++) {
+    if (masked[i] === ',' && depth[i] === inner) {
+      spans.push([start, i])
+      start = i + 1
+    }
+  }
+  spans.push([start, close])
+  return spans.filter(([a, b]) => masked.slice(a, b).trim() !== '')
+}
+
+/**
+ * The object literal an array element IS, or that it wraps:
+ * `{ id: 'a' }` and `defineSite({ id: 'a' })` both resolve to the same `{`.
+ * @returns {number} index of the `{`, or -1 when the element is not an object
+ */
+function elementObject(masked, from, to) {
+  const start = firstNonSpace(masked, from, to)
+  if (start === -1) return -1
+  if (masked[start] === '{') return start
+  const call = /^[A-Za-z_$][\w$]*\s*\(\s*/.exec(masked.slice(start, to))
+  if (!call) return -1
+  const brace = start + call[0].length
+  return masked[brace] === '{' ? brace : -1
+}
+
+/**
+ * Find a top-level array property of the config object and hand back its
+ * element spans.
+ * @returns {{ open: number, close: number, elements: Array<[number, number]> }|null}
+ */
+function arrayProperty(masked, depth, name, objOpen, objClose) {
+  const at = propertyValueAt(masked, depth, name, objOpen + 1, objClose, depth[objOpen] + 1)
+  if (at === -1 || masked[at] !== '[') return null
+  const close = matchingClose(masked, depth, at)
+  if (close === -1) return null
+  return { open: at, close, elements: arrayElements(masked, depth, at, close) }
+}
+
+/**
+ * Scan a `kywi.config.ts` for the deployment mode, the sites and their themes,
+ * and the declared theme names. Never throws: anything unreadable is described
+ * in `problems`, which the caller (`upgrade`) surfaces instead of writing a
+ * registry it cannot stand behind.
+ * @param {string} text  the contents of kywi.config.ts
+ * @returns {ConfigScan}
+ */
+export function scanKywiConfig(text) {
+  /** @type {ConfigScan} */
+  const result = { mode: null, sites: [], themes: [], problems: [] }
+  if (typeof text !== 'string' || text.trim() === '') {
+    result.problems.push('kywi.config.ts is empty — no config object to read.')
+    return result
+  }
+
+  try {
+    const { masked, strings } = maskText(text)
+    const depth = depthMap(masked)
+
+    const objOpen = findConfigObject(masked)
+    if (objOpen === -1) {
+      result.problems.push(
+        'could not find the exported config object — expected `export default { … }`, `export default defineKywiConfig({ … })` or `const config = { … }` with `export default config`.',
+      )
+      return result
+    }
+    const objClose = matchingClose(masked, depth, objOpen)
+    if (objClose === -1) {
+      result.problems.push('the config object literal is never closed — unbalanced `{` in kywi.config.ts.')
+      return result
+    }
+    const topDepth = depth[objOpen] + 1
+
+    // ── mode ──
+    MODE_RE.lastIndex = 0
+    let m
+    while ((m = MODE_RE.exec(text)) !== null) {
+      const at = m.index
+      // Real code, not a comment or a string: the mask blanked both, so only a
+      // live `mode:` still reads as itself.
+      if (masked.slice(at, at + 5) !== 'mode:') continue
+      if (at < objOpen || at > objClose || depth[at] !== topDepth) continue
+      result.mode = /** @type {KywiMode} */ (m[1])
+      break
+    }
+
+    // ── sites ──
+    const sites = arrayProperty(masked, depth, 'sites', objOpen, objClose)
+    if (!sites) {
+      result.problems.push(
+        'no top-level `sites:` array found in kywi.config.ts — every Kywi project declares at least one site.',
+      )
+    } else {
+      sites.elements.forEach(([from, to], index) => {
+        const open = elementObject(masked, from, to)
+        if (open === -1) {
+          result.problems.push(
+            `sites[${index}] is not an object literal or a \`defineSite({ … })\` call — it reads \`${masked.slice(from, to).trim()}\`, which this scanner cannot follow.`,
+          )
+          return
+        }
+        const close = matchingClose(masked, depth, open)
+        if (close === -1) {
+          result.problems.push(`sites[${index}] is never closed — unbalanced \`{\` in kywi.config.ts.`)
+          return
+        }
+        const id = readStringProp(text, masked, depth, strings, open, close, 'id')
+        if (!id.value) {
+          result.problems.push(
+            `sites[${index}] has no \`id:\` string property — a site cannot be placed in the layer registry without one.`,
+          )
+          return
+        }
+        const theme = readStringProp(text, masked, depth, strings, open, close, 'theme')
+        if (!theme.value) {
+          result.problems.push(
+            `site '${id.value}' has no \`theme:\` string property — its theme layer cannot be generated.`,
+          )
+        }
+        result.sites.push({ id: id.value, theme: theme.value })
+      })
+    }
+
+    // ── themes ──
+    const themes = arrayProperty(masked, depth, 'themes', objOpen, objClose)
+    if (!themes) {
+      result.problems.push('no top-level `themes:` array found in kywi.config.ts.')
+    } else {
+      themes.elements.forEach(([from, to], index) => {
+        const open = elementObject(masked, from, to)
+        if (open === -1) {
+          result.problems.push(
+            `themes[${index}] is not an object literal or a \`defineTheme({ … })\` call — it reads \`${masked.slice(from, to).trim()}\`, which this scanner cannot follow.`,
+          )
+          return
+        }
+        const close = matchingClose(masked, depth, open)
+        if (close === -1) {
+          result.problems.push(`themes[${index}] is never closed — unbalanced \`{\` in kywi.config.ts.`)
+          return
+        }
+        const name = readStringProp(text, masked, depth, strings, open, close, 'name')
+        if (!name.value) {
+          result.problems.push(`themes[${index}] has no \`name:\` string property.`)
+          return
+        }
+        result.themes.push({ name: name.value })
+      })
+    }
+  } catch (err) {
+    // A scanner that throws on a file it does not own would take `upgrade` down
+    // with it. Whatever went wrong is a problem to report, not a crash.
+    result.problems.push(`kywi.config.ts could not be scanned: ${err && err.message ? err.message : String(err)}`)
+  }
+
+  return result
+}