@kudzujs/core 0.8.15 → 0.8.17

package/framework/compiler/route-capability-planner.mjs

@@ -0,0 +1,118 @@
+export function usesRouteDependencyRuntime({ plan, navigable, hasBindings, hasLists }) {
+  const hasDependencies = plan.effects.some(effect => effect.dependencies?.length)
+  return !navigable && hasDependencies && !plan.effects.some(effect => effect.owner) && !hasBindings && !hasLists && !plan.events.some(event => event.native)
+}
+
+export function planRouteCapabilities(plans, { routes = new Map(), navigationRouteCount = 0 } = {}) {
+  const commandEvents = new Set()
+  const nativeEvents = new Set()
+  const bindings = { count: 0, text: false, svgConditions: false }
+  const lists = {
+    count: 0,
+    styleCount: 0,
+    conditions: false,
+    svg: false,
+    deepConditions: false,
+    textRanges: false,
+    attributes: false,
+    events: false,
+    expressions: false,
+    expressionAttributes: false,
+    seeds: false,
+    effects: false,
+    rowHooks: false,
+    rowRefs: false,
+    complexRowState: false,
+    nested: false,
+    selectors: false,
+    calculated: false,
+    static: false,
+    indexes: false,
+    stableFastPaths: false,
+    generalRowHooks: false,
+    asyncParts: false,
+    mounts: false
+  }
+  const effects = { any: false, derivedDependencies: false, itemDependencies: false, captures: false, navigable: false, navigableOwners: false }
+
+  for (let index = 0; index < plans.length; index++) {
+    const plan = plans[index]
+    const route = routes.get(plan.route)
+    for (const event of plan.events) {
+      if (event.commands) commandEvents.add(event.event)
+      if (event.native) nativeEvents.add(event.event)
+    }
+    bindings.text ||= plan.bindings.some(binding => binding.target === "text")
+    bindings.svgConditions ||= plan.conditions.some(condition => condition.svg)
+    effects.any ||= plan.effects.length > 0
+    effects.derivedDependencies ||= plan.effects.some(effect => effect.dependencyExpressions?.length)
+    effects.itemDependencies ||= plan.effects.some(effect => effect.itemDependencies?.length)
+    effects.captures ||= plan.effects.some(effect => Object.keys(effect.scope).length)
+    effects.navigable ||= Boolean(route?.navigable && plan.effects.length)
+    effects.navigableOwners ||= Boolean(route?.navigable && plan.effects.some(effect => effect.owner))
+    for (const list of plan.lists) {
+      lists.conditions ||= Boolean(list.conditions)
+      lists.svg ||= Boolean(list.svg)
+      lists.deepConditions ||= Boolean(list.conditionHandlers)
+      lists.textRanges ||= Boolean(list.textRanges)
+      lists.attributes ||= Boolean(list.attributes)
+      lists.events ||= Boolean(list.events)
+      lists.expressions ||= Boolean(list.expressions)
+      lists.expressionAttributes ||= Boolean(list.expressionAttributes)
+      lists.seeds ||= Boolean(list.seed || list.valueSeed)
+      lists.effects ||= Boolean(list.effects)
+      lists.rowHooks ||= Boolean(list.rowStates?.length || list.rowRefs?.length)
+      lists.rowRefs ||= Boolean(list.rowRefs?.length)
+      lists.complexRowState ||= Boolean(list.rowStates?.some(state => state.initialValue !== null && typeof state.initialValue === "object"))
+      lists.nested ||= Boolean(list.ownerField)
+      lists.selectors ||= Boolean(list.selector)
+      lists.calculated ||= Boolean(list.source)
+      lists.static ||= Boolean(list.static)
+      lists.indexes ||= Boolean(list.indexed)
+      lists.stableFastPaths ||= !list.children && !list.ownerField && list.key !== null && !list.indexed && !list.reducer && !list.selector
+      lists.generalRowHooks ||= Boolean(list.ownerField && (list.rowStates?.length || list.rowRefs?.length))
+      lists.mounts ||= Boolean(list.mount)
+    }
+  }
+
+  const routeEntries = [...routes.values()]
+  const routeCounts = {
+    behaviors: routeEntries.filter(route => route.hasBehaviors).length,
+    regularBehaviors: routeEntries.filter(route => route.hasBehaviors && !route.usesDependencyRuntime).length,
+    regularStateSeeds: routeEntries.filter(route => route.hasStateSeed && !route.usesDependencyRuntime).length,
+    dependencyStateSeeds: routeEntries.filter(route => route.hasStateSeed && route.usesDependencyRuntime).length
+  }
+  bindings.count = routeEntries.filter(route => route.hasBindings).length
+  lists.count = routeEntries.filter(route => route.hasLists).length
+  lists.styleCount = routeEntries.filter(route => route.hasListStyles).length
+  lists.generalRowHooks ||= lists.rowRefs || lists.complexRowState
+  lists.asyncParts = lists.expressions || lists.expressionAttributes || lists.conditions
+  lists.mounts ||= lists.conditions || lists.nested
+
+  return {
+    routes: routeCounts,
+    events: { command: [...commandEvents].sort(), native: [...nativeEvents].sort(), hasNativeHandlers: nativeEvents.size > 0 },
+    bindings,
+    lists,
+    effects,
+    captures: { nestedState: hasNestedCaptureState(plans), setter: hasCaptureType(plans, "setter") },
+    runtime: {
+      shared: Boolean(bindings.count || lists.count || nativeEvents.size || navigationRouteCount),
+      dependency: routeEntries.some(route => route.usesDependencyRuntime)
+    }
+  }
+}
+
+function hasCaptureType(value, type) {
+  if (!value || typeof value !== "object") return false
+  if (value.type === type) return true
+  return (Array.isArray(value) ? value : Object.values(value)).some(entry => hasCaptureType(entry, type))
+}
+
+function hasNestedCaptureState(value, insideCapture = false) {
+  if (!value || typeof value !== "object") return false
+  if (value.type === "state") return insideCapture
+  if (value.type === "array") return value.value.some(entry => hasNestedCaptureState(entry, true))
+  if (value.type === "object") return value.value.some(([, entry]) => hasNestedCaptureState(entry, true))
+  return (Array.isArray(value) ? value : Object.values(value)).some(entry => hasNestedCaptureState(entry, false))
+}

package/framework/compiler/zustand-pass.mjs

@@ -0,0 +1,95 @@
+import { relative, sep } from "node:path"
+import ts from "typescript"
+import { isReferenceIdentifier, isShadowedIdentifier, nearestFunction, sourceNodeError, unwrapExpression } from "./ast-helpers.mjs"
+
+export function createZustandPass({ isSerializableStateLiteral, nativeCaptureNames, sourceDirectory }) {
+  function analyzeZustandStores(sourceFile) {
+    const createNames = new Set()
+    for (const statement of sourceFile.statements) {
+      if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== "zustand") continue
+      const bindings = statement.importClause?.namedBindings
+      if (statement.importClause?.name || !bindings || !ts.isNamedImports(bindings)) throw sourceNodeError(statement, sourceFile, "Zustand migration input requires a named create import")
+      for (const entry of bindings.elements) {
+        if (entry.isTypeOnly) continue
+        if ((entry.propertyName ?? entry.name).text !== "create") throw sourceNodeError(entry, sourceFile, "Only Zustand create is supported")
+        createNames.add(entry.name.text)
+      }
+    }
+    const stores = new Map()
+    if (!createNames.size) return stores
+    for (const statement of sourceFile.statements) {
+      if (!ts.isVariableStatement(statement) || !statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name) || !declaration.initializer || !ts.isCallExpression(declaration.initializer) || !ts.isIdentifier(declaration.initializer.expression) || !createNames.has(declaration.initializer.expression.text)) continue
+        const callback = declaration.initializer.arguments[0]
+        if (declaration.initializer.arguments.length !== 1 || !callback || (!ts.isArrowFunction(callback) && !ts.isFunctionExpression(callback)) || callback.parameters.length !== 1 || !ts.isIdentifier(callback.parameters[0].name) || callback.asteriskToken || callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) throw sourceNodeError(declaration.initializer, sourceFile, "Zustand create() requires one synchronous initializer with one set parameter")
+        const body = unwrapExpression(callback.body)
+        if (!ts.isObjectLiteralExpression(body)) throw sourceNodeError(callback.body, sourceFile, "Zustand create() initializer must return one object literal")
+        const data = []
+        const actions = new Map()
+        for (const property of body.properties) {
+          if (!ts.isPropertyAssignment(property) || !property.name || !(ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))) throw sourceNodeError(property, sourceFile, "Zustand store entries must be ordinary properties")
+          const name = property.name.text
+          const value = unwrapExpression(property.initializer)
+          if (ts.isArrowFunction(value) || ts.isFunctionExpression(value)) actions.set(name, value)
+          else data.push({ name, value })
+        }
+        if (data.length !== 1 || !isSerializableStateLiteral(data[0].value)) throw sourceNodeError(body, sourceFile, "Zustand migration stores require exactly one directly serializable data property")
+        if (!actions.size) throw sourceNodeError(body, sourceFile, "Zustand migration stores require at least one action")
+        for (const [name, action] of actions) {
+          if (action.asteriskToken || action.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) throw sourceNodeError(action, sourceFile, `Zustand action ${JSON.stringify(name)} must be synchronous`)
+          const capture = [...nativeCaptureNames(action, new Map())].find(entry => entry !== callback.parameters[0].name.text)
+          if (capture) throw sourceNodeError(action, sourceFile, `Zustand action ${JSON.stringify(name)} cannot capture ${JSON.stringify(capture)}`)
+          const validateAction = node => {
+            if (ts.isAwaitExpression(node) || ts.isYieldExpression(node) || ts.isNewExpression(node)) throw sourceNodeError(node, sourceFile, `Zustand action ${JSON.stringify(name)} must be synchronous`)
+            if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ["then", "catch", "finally"].includes(node.expression.name.text)) throw sourceNodeError(node, sourceFile, `Zustand action ${JSON.stringify(name)} cannot schedule asynchronous updates`)
+            if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === callback.parameters[0].name.text && !isShadowedIdentifier(node.expression, action)) {
+              if (nearestFunction(node) !== action) throw sourceNodeError(node, sourceFile, `Zustand action ${JSON.stringify(name)} must call set directly`)
+              if (node.arguments.length !== 1) throw sourceNodeError(node, sourceFile, `Zustand action ${JSON.stringify(name)} set() requires exactly one partial update`)
+            }
+            ts.forEachChild(node, validateAction)
+          }
+          validateAction(action.body)
+        }
+        stores.set(declaration.name.text, { name: declaration.name.text, setName: callback.parameters[0].name.text, field: data[0].name, initialValue: data[0].value, actions, declaration })
+      }
+    }
+    const visit = node => {
+      const recognized = ts.isIdentifier(node) && ts.isCallExpression(node.parent) && node.parent.expression === node && [...stores.values()].some(store => store.declaration.initializer === node.parent)
+      if (ts.isIdentifier(node) && createNames.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile) && !recognized) throw sourceNodeError(node, sourceFile, "Zustand create must directly initialize an exported const store")
+      ts.forEachChild(node, visit)
+    }
+    visit(sourceFile)
+    return stores
+  }
+
+  function normalizeZustandMigrationSyntax(sourceFile, factory, context) {
+    const stores = analyzeZustandStores(sourceFile)
+    if (!stores.size) {
+      const declaration = sourceFile.statements.find(statement => ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "zustand" && !statement.importClause?.isTypeOnly)
+      if (declaration) throw sourceNodeError(declaration, sourceFile, "Zustand create must directly initialize an exported const store")
+      return sourceFile
+    }
+    const identity = name => `${relative(sourceDirectory, sourceFile.fileName).replaceAll(sep, "/")}#${name}`
+    const visitor = node => {
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && stores.has(node.name.text)) {
+        const store = stores.get(node.name.text)
+        return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, factory.createCallExpression(factory.createIdentifier("__kCreateStore"), undefined, [
+          factory.createStringLiteral(identity(store.name)),
+          factory.createStringLiteral(store.field),
+          store.initialValue,
+          factory.createArrayLiteralExpression([...store.actions.keys()].map(name => factory.createStringLiteral(name)))
+        ]))
+      }
+      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "zustand") return undefined
+      return ts.visitEachChild(node, visitor, context)
+    }
+    const normalized = ts.visitNode(sourceFile, visitor)
+    const declaration = factory.createImportDeclaration(undefined, factory.createImportClause(false, undefined, factory.createNamedImports([factory.createImportSpecifier(false, undefined, factory.createIdentifier("__kCreateStore"))])), factory.createStringLiteral("@kudzujs/core"))
+    const statements = [...normalized.statements]
+    statements.splice(statements.findLastIndex(statement => ts.isImportDeclaration(statement)) + 1, 0, declaration)
+    return factory.updateSourceFile(normalized, statements)
+  }
+
+  return { analyzeZustandStores, normalizeZustandMigrationSyntax }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.8.15",
+  "version": "0.8.17",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -23,9 +23,12 @@
   },
   "files": [
     "bin/",
+    "docs/next-architecture/",
     "framework/",
     "GOAL_A.md",
     "GOAL_B.md",
+    "MIGRATION_ROADMAP.md",
+    "PERFORMANCE.md",
     "RELEASES.md",
     "README.md",
     "LICENSE"