@kudzujs/core 0.8.14 → 0.8.15

package/framework/compiler/router-pass.mjs

@@ -0,0 +1,245 @@
+import ts from "typescript"
+import { bindingNames, functionVarDeclaresName, isFunctionLike, isLocalConst, isReferenceIdentifier, isShadowedIdentifier, loopDeclaresName, nearestFunction, sourceNodeError, statementDeclaresName, unwrapExpression } from "./ast-helpers.mjs"
+
+export function createRouterPass({ withBase }) {
+  return function normalizeReactRouterSyntax(sourceFile, factory, context, base) {
+    const links = new Set()
+    const params = new Set()
+    const searchHooks = new Set()
+    const navigateHooks = new Set()
+    for (const statement of sourceFile.statements) {
+      if ((ts.isExportDeclaration(statement) || ts.isImportDeclaration(statement)) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "react-router-dom") {
+        if (ts.isExportDeclaration(statement)) throw sourceNodeError(statement, sourceFile, "React Router exports are not supported; import Link directly where it renders")
+        const clause = statement.importClause
+        if (clause?.isTypeOnly) continue
+        if (!clause) throw sourceNodeError(statement, sourceFile, "Side-effect React Router imports are not supported")
+        if (clause.name) throw sourceNodeError(clause.name, sourceFile, "React Router default imports are not supported; use named Link, useParams, useSearchParams, or useNavigate imports")
+        const bindings = clause.namedBindings
+        if (!bindings || ts.isNamespaceImport(bindings)) throw sourceNodeError(bindings ?? statement, sourceFile, "React Router namespace imports are not supported; use named Link, useParams, useSearchParams, or useNavigate imports")
+        for (const entry of bindings.elements) {
+          if (entry.isTypeOnly) continue
+          const imported = (entry.propertyName ?? entry.name).text
+          if (imported === "NavLink") throw sourceNodeError(entry, sourceFile, "React Router NavLink active-route semantics cannot be erased to a native anchor")
+          if (imported === "Link") links.add(entry.name.text)
+          else if (imported === "useParams") params.add(entry.name.text)
+          else if (imported === "useSearchParams") searchHooks.add(entry.name.text)
+          else if (imported === "useNavigate") navigateHooks.add(entry.name.text)
+          else throw sourceNodeError(entry, sourceFile, `React Router ${imported} is not supported; only named Link, useParams, useSearchParams, and useNavigate imports can be lowered`)
+        }
+      }
+    }
+    if (!links.size && !params.size && !searchHooks.size && !navigateHooks.size) return sourceFile
+
+    let searchHelper = "__kUseSearchParam"
+    while (sourceFile.text.includes(searchHelper)) searchHelper += "_"
+    let searchWriterHelper = "__kUseSearchParamsWriter"
+    while (sourceFile.text.includes(searchWriterHelper)) searchWriterHelper += "_"
+    const searchDeclarations = new Set()
+    const searchReads = new Map()
+    const searchWrites = new Map()
+    const searchObjects = []
+    const collectSearchHooks = node => {
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && searchHooks.has(node.expression.text) && !isShadowedIdentifier(node.expression, sourceFile)) {
+        const declaration = node.parent
+        const statement = declaration?.parent?.parent
+        const owner = nearestFunction(node)
+        const first = ts.isVariableDeclaration(declaration) && ts.isArrayBindingPattern(declaration.name) ? declaration.name.elements[0] : undefined
+        const second = ts.isVariableDeclaration(declaration) && ts.isArrayBindingPattern(declaration.name) ? declaration.name.elements[1] : undefined
+        if (node.questionDotToken || node.arguments.length || node.typeArguments?.length || !ts.isVariableDeclaration(declaration) || declaration.initializer !== node || !isLocalConst(declaration) || !owner || statement?.parent !== owner.body || !ts.isBindingElement(first) || !ts.isIdentifier(first.name) || declaration.name.elements.length > 2 || second && (!ts.isBindingElement(second) || !ts.isIdentifier(second.name))) {
+          throw sourceNodeError(node, sourceFile, "React Router useSearchParams must initialize one top-level const [params] or [params, setParams] binding")
+        }
+        const entry = { name: first.name.text, setter: second?.name.text, declaration, statement, owner }
+        searchDeclarations.add(declaration)
+        searchObjects.push(entry)
+      }
+      ts.forEachChild(node, collectSearchHooks)
+    }
+    collectSearchHooks(sourceFile)
+    const localBindingShadowed = (node, entry, name = entry.name) => {
+      for (let current = node.parent; current && current !== entry.owner; current = current.parent) {
+        if (isFunctionLike(current) && (current.parameters.some(parameter => bindingNames(parameter.name).includes(name)) || functionVarDeclaresName(current, name))) return true
+        if (ts.isBlock(current) && current.statements.some(statement => statement !== entry.statement && statementDeclaresName(statement, name))) return true
+        if (ts.isCaseBlock(current) && current.clauses.some(clause => clause.statements.some(statement => statement !== entry.statement && statementDeclaresName(statement, name)))) return true
+        if (ts.isCatchClause(current) && current.variableDeclaration && bindingNames(current.variableDeclaration.name).includes(name)) return true
+        if ((ts.isForStatement(current) || ts.isForInStatement(current) || ts.isForOfStatement(current)) && loopDeclaresName(current, name)) return true
+      }
+      return false
+    }
+    for (const entry of searchObjects) {
+      const collectReads = node => {
+        if (ts.isIdentifier(node) && node.text === entry.name && isReferenceIdentifier(node) && !localBindingShadowed(node, entry)) {
+          if (entry.setter && ts.isCallExpression(node.parent) && node.parent.arguments.includes(node) && ts.isIdentifier(node.parent.expression) && node.parent.expression.text === entry.setter) return
+          const property = node.parent
+          const call = property?.parent
+          const declaration = call?.parent
+          const statement = declaration?.parent?.parent
+          if (!ts.isPropertyAccessExpression(property) || property.expression !== node || property.name.text !== "get" || !ts.isCallExpression(call) || call.expression !== property || call.questionDotToken || call.typeArguments?.length || call.arguments.length !== 1 || !ts.isStringLiteral(call.arguments[0])) {
+            throw sourceNodeError(node, sourceFile, 'React Router search parameters only support direct get("static-name") reads')
+          }
+          if (!ts.isVariableDeclaration(declaration) || declaration.initializer !== call || !ts.isIdentifier(declaration.name) || !isLocalConst(declaration) || statement?.parent !== entry.owner.body) {
+            throw sourceNodeError(call, sourceFile, "React Router search parameter get() must directly initialize one top-level const identifier")
+          }
+          searchReads.set(call, call.arguments[0])
+          return
+        }
+        ts.forEachChild(node, collectReads)
+      }
+      collectReads(entry.owner.body)
+      if (!entry.setter) continue
+      const collectWrites = node => {
+        if (ts.isIdentifier(node) && node.text === entry.setter && isReferenceIdentifier(node) && !localBindingShadowed(node, entry, entry.setter)) {
+          const call = node.parent
+          if (!ts.isCallExpression(call) || call.expression !== node || call.questionDotToken || call.typeArguments?.length || nearestFunction(call) === entry.owner) throw sourceNodeError(node, sourceFile, "React Router search parameter setters may only be called directly from a nested browser callback")
+          if (call.arguments.length < 1 || call.arguments.length > 2) throw sourceNodeError(call, sourceFile, "React Router search parameter setters require one inline updater and optional { replace: true }")
+          const updater = unwrapExpression(call.arguments[0])
+          if ((!ts.isArrowFunction(updater) && !ts.isFunctionExpression(updater)) || updater.asteriskToken || updater.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword) || updater.parameters.length !== 1 || !ts.isIdentifier(updater.parameters[0].name)) throw sourceNodeError(call.arguments[0], sourceFile, "React Router search parameter setters require one synchronous inline updater with one identifier parameter")
+          let replace = false
+          if (call.arguments.length === 2) {
+            const options = unwrapExpression(call.arguments[1])
+            const property = ts.isObjectLiteralExpression(options) && options.properties.length === 1 ? options.properties[0] : undefined
+            const name = property && ts.isPropertyAssignment(property) && !ts.isComputedPropertyName(property.name) && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ? property.name.text : undefined
+            if (name !== "replace" || property.initializer.kind !== ts.SyntaxKind.TrueKeyword) throw sourceNodeError(call.arguments[1], sourceFile, "React Router search parameter setters only support exactly { replace: true } as a second argument")
+            replace = true
+          }
+          searchWrites.set(call, { updater, replace })
+          return
+        }
+        ts.forEachChild(node, collectWrites)
+      }
+      collectWrites(entry.owner.body)
+    }
+
+    const navigateDeclarations = new Set()
+    const navigateCalls = new Map()
+    const navigateFunctions = []
+    const collectNavigateHooks = node => {
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && navigateHooks.has(node.expression.text) && !isShadowedIdentifier(node.expression, sourceFile)) {
+        const declaration = node.parent
+        const statement = declaration?.parent?.parent
+        const owner = nearestFunction(node)
+        if (node.questionDotToken || node.arguments.length || node.typeArguments?.length || !ts.isVariableDeclaration(declaration) || declaration.initializer !== node || !ts.isIdentifier(declaration.name) || !isLocalConst(declaration) || !owner || statement?.parent !== owner.body) {
+          throw sourceNodeError(node, sourceFile, "React Router useNavigate must initialize one top-level const identifier in a component")
+        }
+        const entry = { name: declaration.name.text, declaration, statement, owner }
+        navigateDeclarations.add(declaration)
+        navigateFunctions.push(entry)
+      }
+      ts.forEachChild(node, collectNavigateHooks)
+    }
+    collectNavigateHooks(sourceFile)
+    for (const entry of navigateFunctions) {
+      const collectCalls = node => {
+        if (ts.isIdentifier(node) && node.text === entry.name && isReferenceIdentifier(node) && !localBindingShadowed(node, entry)) {
+          const call = node.parent
+          if (!ts.isCallExpression(call) || call.expression !== node || call.questionDotToken || call.typeArguments?.length || nearestFunction(call) === entry.owner) {
+            throw sourceNodeError(node, sourceFile, "React Router navigate bindings may only be called directly from a nested browser callback")
+          }
+          if (call.arguments.length < 1 || call.arguments.length > 2 || !ts.isStringLiteral(call.arguments[0])) {
+            throw sourceNodeError(call, sourceFile, 'React Router useNavigate requires a static root-relative navigate("/path") destination')
+          }
+          const destination = call.arguments[0].text
+          const pathname = destination.match(/^[^?#]*/)[0]
+          let decoded
+          try { decoded = decodeURIComponent(pathname) } catch { throw sourceNodeError(call.arguments[0], sourceFile, 'React Router useNavigate requires a safe static root-relative navigate("/path") destination') }
+          if (!destination.startsWith("/") || destination.startsWith("//") || /%(?:2f|5c)/i.test(pathname) || /[\\\0]/.test(decoded) || decoded.split("/").includes("..") || [...decoded].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) >= 127 && character.charCodeAt(0) <= 159)) throw sourceNodeError(call.arguments[0], sourceFile, 'React Router useNavigate requires a safe static root-relative navigate("/path") destination')
+          let method = "assign"
+          if (call.arguments.length === 2) {
+            const options = unwrapExpression(call.arguments[1])
+            const property = ts.isObjectLiteralExpression(options) && options.properties.length === 1 ? options.properties[0] : undefined
+            const name = property && ts.isPropertyAssignment(property) && !ts.isComputedPropertyName(property.name) && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ? property.name.text : undefined
+            if (name !== "replace" || property.initializer.kind !== ts.SyntaxKind.TrueKeyword) throw sourceNodeError(call.arguments[1], sourceFile, 'React Router useNavigate only supports exactly { replace: true } as a second argument')
+            method = "replace"
+          }
+          navigateCalls.set(call, { method, destination: withBase(base, destination) })
+          return
+        }
+        ts.forEachChild(node, collectCalls)
+      }
+      collectCalls(entry.owner.body)
+    }
+
+    const routerProps = new Set(["discover", "end", "prefetch", "preventScrollReset", "relative", "reloadDocument", "replace", "state", "viewTransition"])
+    const attributes = attributesNode => {
+      const output = []
+      let destination
+      for (const property of attributesNode.properties) {
+        if (ts.isJsxSpreadAttribute(property)) throw sourceNodeError(property, sourceFile, "React Router Link does not support spread attributes during native anchor lowering")
+        const name = property.name.text
+        if (name === "href") throw sourceNodeError(property, sourceFile, "React Router Link must not declare href; Kudzu derives it from to")
+        if (routerProps.has(name)) throw sourceNodeError(property, sourceFile, `React Router Link prop ${JSON.stringify(name)} cannot be erased to a native anchor`)
+        if (name !== "to") {
+          output.push(ts.visitEachChild(property, visitor, context))
+          continue
+        }
+        if (destination !== undefined) throw sourceNodeError(property, sourceFile, "React Router Link requires exactly one to attribute")
+        if (!property.initializer || !ts.isStringLiteral(property.initializer)) throw sourceNodeError(property, sourceFile, 'React Router Link requires a static root-relative to="/path"')
+        destination = property.initializer.text
+        const pathname = destination.match(/^[^?#]*/)[0]
+        let decoded
+        try { decoded = decodeURIComponent(pathname) } catch { throw sourceNodeError(property.initializer, sourceFile, 'React Router Link requires a safe static root-relative to="/path"') }
+        if (!destination.startsWith("/") || destination.startsWith("//") || /%(?:2f|5c)/i.test(pathname) || /[\\\0]/.test(decoded) || decoded.split("/").includes("..") || [...decoded].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) >= 127 && character.charCodeAt(0) <= 159)) throw sourceNodeError(property.initializer, sourceFile, 'React Router Link requires a safe static root-relative to="/path"')
+        output.push(factory.createJsxAttribute(factory.createIdentifier("href"), factory.createStringLiteral(withBase(base, destination))))
+      }
+      if (destination === undefined) throw sourceNodeError(attributesNode.parent, sourceFile, "React Router Link requires exactly one static root-relative to attribute")
+      return factory.updateJsxAttributes(attributesNode, output)
+    }
+    const importedLink = tag => ts.isIdentifier(tag) && links.has(tag.text) && !isShadowedIdentifier(tag, sourceFile)
+    const visitor = node => {
+      if (ts.isVariableStatement(node) && node.declarationList.declarations.some(declaration => searchDeclarations.has(declaration) || navigateDeclarations.has(declaration))) {
+        const declarations = node.declarationList.declarations.flatMap(declaration => {
+          if (navigateDeclarations.has(declaration)) return []
+          if (!searchDeclarations.has(declaration)) return [ts.visitEachChild(declaration, visitor, context)]
+          const entry = searchObjects.find(candidate => candidate.declaration === declaration)
+          if (!entry?.setter) return []
+          return [factory.updateVariableDeclaration(declaration, declaration.name, declaration.exclamationToken, declaration.type, factory.createCallExpression(factory.createIdentifier(searchWriterHelper), undefined, []))]
+        })
+        if (!declarations.length) return undefined
+        return factory.updateVariableStatement(node, node.modifiers, factory.updateVariableDeclarationList(node.declarationList, declarations))
+      }
+      if (ts.isCallExpression(node) && searchReads.has(node)) return factory.createCallExpression(factory.createIdentifier(searchHelper), undefined, [searchReads.get(node)])
+      if (ts.isCallExpression(node) && searchWrites.has(node)) {
+        const { updater, replace } = searchWrites.get(node)
+        return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("globalThis"), "__kSetSearchParams"), undefined, [ts.visitNode(updater, visitor), replace ? factory.createTrue() : factory.createFalse()])
+      }
+      if (ts.isCallExpression(node) && navigateCalls.has(node)) {
+        const { method, destination } = navigateCalls.get(node)
+        return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createPropertyAccessExpression(factory.createIdentifier("globalThis"), "location"), method), undefined, [factory.createStringLiteral(destination)])
+      }
+      if (ts.isJsxElement(node) && importedLink(node.openingElement.tagName)) {
+        const opening = factory.updateJsxOpeningElement(node.openingElement, factory.createIdentifier("a"), node.openingElement.typeArguments, attributes(node.openingElement.attributes))
+        const closing = factory.updateJsxClosingElement(node.closingElement, factory.createIdentifier("a"))
+        return factory.updateJsxElement(node, opening, ts.visitNodes(node.children, visitor), closing)
+      }
+      if (ts.isJsxSelfClosingElement(node) && importedLink(node.tagName)) return factory.updateJsxSelfClosingElement(node, factory.createIdentifier("a"), node.typeArguments, attributes(node.attributes))
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && params.has(node.expression.text) && !isShadowedIdentifier(node.expression, sourceFile)) {
+        if (node.questionDotToken || node.arguments.length || (node.typeArguments?.length ?? 0) > 1) throw sourceNodeError(node, sourceFile, "React Router useParams must be called directly without runtime arguments and with at most one type argument")
+        return node
+      }
+      if (ts.isIdentifier(node) && links.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router Link imports may only be used as direct JSX elements")
+      if (ts.isIdentifier(node) && params.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router useParams imports may only be called directly")
+      if (ts.isIdentifier(node) && searchHooks.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router useSearchParams imports may only initialize the supported top-level tuple binding")
+      if (ts.isIdentifier(node) && navigateHooks.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router useNavigate imports may only initialize the supported top-level navigate binding")
+      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "react-router-dom") {
+        const clause = node.importClause
+        if (!clause || clause.isTypeOnly) return node
+        const bindings = clause.namedBindings
+        if (!bindings || !ts.isNamedImports(bindings)) return node
+        const elements = bindings.elements.filter(entry => entry.isTypeOnly || !["Link", "useParams", "useSearchParams", "useNavigate"].includes((entry.propertyName ?? entry.name).text))
+        if (!elements.length) return undefined
+        return factory.updateImportDeclaration(node, node.modifiers, factory.updateImportClause(clause, clause.isTypeOnly, undefined, factory.updateNamedImports(bindings, elements)), node.moduleSpecifier, node.attributes)
+      }
+      return ts.visitEachChild(node, visitor, context)
+    }
+    const normalized = ts.visitNode(sourceFile, visitor)
+    if (!params.size && !searchHooks.size) return normalized
+    const imports = [
+      ...[...params].map(name => factory.createImportSpecifier(false, name === "useParams" ? undefined : factory.createIdentifier("useParams"), factory.createIdentifier(name))),
+      ...(searchReads.size ? [factory.createImportSpecifier(false, factory.createIdentifier("useSearchParam"), factory.createIdentifier(searchHelper))] : []),
+      ...(searchObjects.some(entry => entry.setter) ? [factory.createImportSpecifier(false, factory.createIdentifier("useSearchParamsWriter"), factory.createIdentifier(searchWriterHelper))] : [])
+    ]
+    const declaration = factory.createImportDeclaration(undefined, factory.createImportClause(false, undefined, factory.createNamedImports(imports)), factory.createStringLiteral("@kudzujs/core"))
+    const statements = [...normalized.statements]
+    statements.splice(statements.findLastIndex(statement => ts.isImportDeclaration(statement)) + 1, 0, declaration)
+    return factory.updateSourceFile(normalized, statements)
+  }
+}

package/framework/compiler/worker-compiler.mjs

@@ -0,0 +1,163 @@
+import { createHash } from "node:crypto"
+import { mkdir, readFile } from "node:fs/promises"
+import { dirname, relative, resolve, sep } from "node:path"
+import { build as bundle } from "esbuild"
+import ts from "typescript"
+import { containsJsx, isUnshadowedGlobal, nearestFunction, sourceNodeError } from "./ast-helpers.mjs"
+
+export function createWorkerCompiler({
+  root,
+  sourceDirectory,
+  outputDirectory,
+  assetPath,
+  parseSourceFile,
+  resolveSourceImport,
+  runtimeModuleReference
+}) {
+  const isImportMetaUrl = node => ts.isPropertyAccessExpression(node) && node.name.text === "url" && ts.isMetaProperty(node.expression) && node.expression.keywordToken === ts.SyntaxKind.ImportKeyword && node.expression.name.text === "meta"
+
+  const candidate = (node, sourceFile) => {
+    if (!ts.isNewExpression(node) || !ts.isIdentifier(node.expression) || node.expression.text !== "Worker") return undefined
+    const first = node.arguments?.[0]
+    if (!first || !ts.isNewExpression(first) || !ts.isIdentifier(first.expression) || first.expression.text !== "URL") return undefined
+    const specifier = first.arguments?.[0]
+    const base = first.arguments?.[1]
+    const relativeLiteral = ts.isStringLiteral(specifier) && (specifier.text.startsWith("./") || specifier.text.startsWith("../"))
+    if (!relativeLiteral && !(specifier && !ts.isStringLiteral(specifier) && base && isImportMetaUrl(base))) return undefined
+    return { worker: node, url: first, sourceFile }
+  }
+
+  const validateCandidate = (value, sourceFile) => {
+    const { worker, url } = value
+    if (!isUnshadowedGlobal(worker.expression, sourceFile)) throw sourceNodeError(worker.expression, sourceFile, "Relative TypeScript Workers require the unshadowed global Worker constructor")
+    if (!isUnshadowedGlobal(url.expression, sourceFile)) throw sourceNodeError(url.expression, sourceFile, "Relative TypeScript Workers require the unshadowed global URL constructor")
+    if (url.arguments?.length !== 2 || !isImportMetaUrl(url.arguments[1])) throw sourceNodeError(url, sourceFile, "Relative TypeScript Workers require new URL(relativeLiteral, import.meta.url)")
+    const specifierNode = url.arguments[0]
+    if (!ts.isStringLiteral(specifierNode) || !(specifierNode.text.startsWith("./") || specifierNode.text.startsWith("../"))) throw sourceNodeError(specifierNode, sourceFile, "Relative TypeScript Worker paths must be relative string literals")
+    if (/[\\?#]/.test(specifierNode.text) || !specifierNode.text.endsWith(".worker.ts")) throw sourceNodeError(specifierNode, sourceFile, "Relative TypeScript Worker paths must end in .worker.ts")
+    if (worker.arguments?.length !== 2) throw sourceNodeError(worker, sourceFile, 'Relative TypeScript Workers require exactly { type: "module" } as the second argument')
+    const options = worker.arguments[1]
+    if (!ts.isObjectLiteralExpression(options) || options.properties.length !== 1) throw sourceNodeError(options, sourceFile, 'Relative TypeScript Workers require exactly { type: "module" } as the second argument')
+    const property = options.properties[0]
+    const name = ts.isPropertyAssignment(property) && !ts.isComputedPropertyName(property.name) && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ? property.name.text : undefined
+    if (name !== "type" || !ts.isStringLiteral(property.initializer) || property.initializer.text !== "module") throw sourceNodeError(property, sourceFile, 'Relative TypeScript Workers require exactly { type: "module" } as the second argument')
+    return { worker, url, specifier: specifierNode.text, options }
+  }
+
+  const rewriteEffect = (callback, file, sourceFile, sourceFiles, workerReferences, factory, context) => {
+    const visit = node => {
+      const value = candidate(node, sourceFile)
+      if (value) {
+        if (nearestFunction(node) !== callback) throw sourceNodeError(node, sourceFile, "Relative TypeScript Worker construction must be directly inside the inline useEffect() callback, not a nested function")
+        const { worker, url, specifier, options } = validateCandidate(value, sourceFile)
+        const target = resolve(dirname(file), specifier)
+        const sourceRelative = relative(sourceDirectory, target)
+        if (sourceRelative.startsWith(`..${sep}`) || sourceRelative === ".." || resolve(sourceDirectory, sourceRelative) !== target) throw sourceNodeError(url.arguments[0], sourceFile, "Relative TypeScript Worker source must remain under src/")
+        if (!sourceFiles.has(target)) throw sourceNodeError(url.arguments[0], sourceFile, `Relative TypeScript Worker ${JSON.stringify(specifier)} must resolve to an existing .worker.ts file under src/`)
+        const identity = `${sourceRelative.replaceAll(sep, "/")}:${ts.getOriginalNode(node).getStart(sourceFile)}`
+        const placeholder = `/__kudzu_worker_${createHash("sha256").update(identity).digest("hex").slice(0, 16)}__.js`
+        workerReferences.push({ root: target, placeholder })
+        return factory.updateNewExpression(worker, worker.expression, worker.typeArguments, [factory.createStringLiteral(placeholder), options])
+      }
+      return ts.visitEachChild(node, visit, context)
+    }
+    return ts.visitEachChild(callback, visit, context)
+  }
+
+  const rejectConstructions = (expression, sourceFile, message) => {
+    const visit = node => {
+      if (candidate(node, sourceFile)) throw sourceNodeError(node, sourceFile, message)
+      ts.forEachChild(node, visit)
+    }
+    visit(expression.body ?? expression)
+  }
+
+  const rejectOrdinaryImports = (sourceFile, file, sourceFiles) => {
+    for (const node of sourceFile.statements) {
+      let specifier
+      let runtime = false
+      if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+        specifier = node.moduleSpecifier
+        runtime = runtimeModuleReference(node)
+      } else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference) && ts.isStringLiteral(node.moduleReference.expression)) {
+        specifier = node.moduleReference.expression
+        runtime = !node.isTypeOnly
+      }
+      if (!runtime || !specifier?.text.startsWith(".")) continue
+      let target
+      try {
+        target = resolveSourceImport(file, specifier.text, sourceFiles)
+      } catch {
+        continue
+      }
+      if (target.endsWith(".worker.ts")) throw sourceNodeError(specifier, sourceFile, "Worker source modules cannot be imported or re-exported as ordinary runtime modules; use new Worker(new URL(relative.worker.ts, import.meta.url), { type: \"module\" }) inside an inline useEffect() callback")
+    }
+  }
+
+  const validateGraphs = async (roots, sourceFiles) => {
+    const visited = new Set()
+    const queue = [...roots]
+    while (queue.length) {
+      const file = queue.shift()
+      if (visited.has(file)) continue
+      visited.add(file)
+      const sourceFile = parseSourceFile(file, await readFile(file, "utf8"))
+      if (containsJsx(sourceFile)) throw sourceNodeError(sourceFile, sourceFile, "Worker modules must not contain JSX")
+      const visit = node => {
+        if (ts.isImportEqualsDeclaration(node)) throw sourceNodeError(node, sourceFile, "TypeScript import-equals declarations are not supported in Worker modules; use a relative ESM import")
+        if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) throw sourceNodeError(node, sourceFile, "Dynamic imports are not supported in Worker modules")
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "require") throw sourceNodeError(node, sourceFile, "require() is not supported in Worker modules")
+        ts.forEachChild(node, visit)
+      }
+      visit(sourceFile)
+      for (const node of sourceFile.statements) {
+        if ((!ts.isImportDeclaration(node) && !ts.isExportDeclaration(node)) || !node.moduleSpecifier || !ts.isStringLiteral(node.moduleSpecifier) || !runtimeModuleReference(node)) continue
+        if (!node.moduleSpecifier.text.startsWith(".")) throw sourceNodeError(node.moduleSpecifier, sourceFile, "Worker modules may only use relative runtime imports")
+        try {
+          queue.push(resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles))
+        } catch (error) {
+          const message = error.message.slice(error.message.indexOf("Relative import"))
+          throw sourceNodeError(node.moduleSpecifier, sourceFile, message)
+        }
+      }
+    }
+  }
+
+  const emit = async (references, sourceFiles, assetsDirectory, base, minify) => {
+    const roots = [...new Set(references.map(reference => reference.root))].sort()
+    if (!roots.length) return new Map()
+    await validateGraphs(roots, sourceFiles)
+    const workerDirectory = resolve(assetsDirectory, "workers")
+    await mkdir(workerDirectory, { recursive: true })
+    const result = await bundle({
+      absWorkingDir: root,
+      entryPoints: roots,
+      outbase: sourceDirectory,
+      outdir: workerDirectory,
+      entryNames: "[dir]/[name]-[hash]",
+      chunkNames: "chunks/[name]-[hash]",
+      bundle: true,
+      splitting: true,
+      format: "esm",
+      platform: "browser",
+      target: "es2022",
+      minify,
+      legalComments: "none",
+      metafile: true,
+      logLevel: "silent"
+    })
+    const emitted = new Map()
+    for (const [output, metadata] of Object.entries(result.metafile.outputs)) {
+      if (!metadata.entryPoint) continue
+      const entry = resolve(root, metadata.entryPoint)
+      const rootReferences = references.filter(reference => reference.root === entry)
+      const outputFile = resolve(root, output)
+      const url = assetPath(base, relative(outputDirectory, outputFile).replaceAll(sep, "/"))
+      for (const reference of rootReferences) emitted.set(reference.placeholder, url)
+    }
+    for (const reference of references) if (!emitted.has(reference.placeholder)) throw new Error(`Worker entry was not emitted: ${relative(root, reference.root)}`)
+    return emitted
+  }
+
+  return { candidate, emit, rejectConstructions, rejectOrdinaryImports, rewriteEffect }
+}