@lovrozagar/honey 0.6.5 → 0.7.0

package/src/feature-detect.ts

@@ -0,0 +1,147 @@
+/**
+ * Detects which optional honey features (`openapi`, `i18n`, `serve`) app code uses, so build
+ * tooling can import their entries ahead of the app. A bundle cannot follow the lazy, opaque
+ * feature imports honey uses at run time. Not a package export.
+ */
+
+export type HoneyFeature = "i18n" | "openapi" | "serve"
+
+export const FEATURES: readonly HoneyFeature[] = ["i18n", "openapi", "serve"]
+
+const FEATURE_ENTRY: Record<HoneyFeature, { enable: string; specifier: string }> = {
+	i18n: { enable: "enableI18n", specifier: "@lovrozagar/honey/i18n" },
+	openapi: { enable: "enableOpenApi", specifier: "@lovrozagar/honey/openapi" },
+	serve: { enable: "enableServe", specifier: "@lovrozagar/honey/serve" },
+}
+
+const METHOD_FEATURE: Record<string, HoneyFeature> = {
+	errorI18n: "i18n",
+	manifest: "openapi",
+	openapi: "openapi",
+	serve: "serve",
+}
+
+/** Globals whose `.serve()` is the runtime's own server, not `Honey.serve()`. */
+const RUNTIME_SERVE_OWNERS = new Set(["Bun", "Deno"])
+
+function blank(s: string): string {
+	return s.replace(/[^\n]/g, " ")
+}
+
+/**
+ * Replaces comments and string, template and regex literal contents with spaces, keeping every
+ * newline so offsets and line numbers still line up. A scanner, not a parser; it is only accurate
+ * enough to keep `// app.serve(` in a comment from counting as a call.
+ */
+export function stripCommentsAndStrings(code: string): string {
+	let out = ""
+	let i = 0
+	while (i < code.length) {
+		const ch = code[i] as string
+		const next = code[i + 1]
+		if (ch === "/" && next === "/") {
+			const end = code.indexOf("\n", i)
+			const stop = end === -1 ? code.length : end
+			out += blank(code.slice(i, stop))
+			i = stop
+		} else if (ch === "/" && next === "*") {
+			const end = code.indexOf("*/", i + 2)
+			const stop = end === -1 ? code.length : end + 2
+			out += blank(code.slice(i, stop))
+			i = stop
+		} else if (ch === '"' || ch === "'" || ch === "`") {
+			let j = i + 1
+			while (j < code.length && code[j] !== ch) {
+				if (code[j] === "\\") j++
+				else if (ch !== "`" && code[j] === "\n") break
+				j++
+			}
+			const stop = Math.min(j + 1, code.length)
+			out += ch + blank(code.slice(i + 1, stop - 1)) + (stop - 1 > i ? (code[stop - 1] ?? "") : "")
+			i = stop
+		} else {
+			out += ch
+			i++
+		}
+	}
+	return out
+}
+
+/** Feature calls in source text, ignoring comments and strings. */
+export function detectFeaturesInSource(code: string): Set<HoneyFeature> {
+	const text = stripCommentsAndStrings(code)
+	const found = new Set<HoneyFeature>()
+	const re = /(\b[A-Za-z_$][\w$]*\s*)?\.\s*(openapi|manifest|errorI18n|serve)\s*\(/g
+	for (const m of text.matchAll(re)) {
+		const owner = m[1]?.trim()
+		const method = m[2] as string
+		if (method === "serve" && owner && RUNTIME_SERVE_OWNERS.has(owner)) continue
+		found.add(METHOD_FEATURE[method] as HoneyFeature)
+	}
+	return found
+}
+
+type AstNode = { [key: string]: unknown; type: string }
+
+function isNode(value: unknown): value is AstNode {
+	return value !== null && typeof value === "object" && typeof (value as { type?: unknown }).type === "string"
+}
+
+/** Feature calls and import specifiers of an ESTree program. */
+export function scanProgram(program: unknown): { features: Set<HoneyFeature>; imports: string[] } {
+	const features = new Set<HoneyFeature>()
+	const imports: string[] = []
+	const stack: unknown[] = [program]
+	while (stack.length > 0) {
+		const node = stack.pop()
+		if (Array.isArray(node)) {
+			stack.push(...node)
+			continue
+		}
+		if (!isNode(node)) continue
+		switch (node.type) {
+			case "ImportDeclaration":
+			case "ExportAllDeclaration":
+			case "ExportNamedDeclaration":
+			case "ImportExpression": {
+				const source = node.source as { type?: string; value?: unknown } | null | undefined
+				if (source && typeof source.value === "string") imports.push(source.value)
+				break
+			}
+			case "CallExpression": {
+				const callee = node.callee as AstNode | undefined
+				if (callee?.type === "MemberExpression" && !callee.computed) {
+					const property = callee.property as { name?: unknown }
+					const feature = typeof property.name === "string" ? METHOD_FEATURE[property.name] : undefined
+					const object = callee.object as { name?: unknown; type?: string }
+					const runtimeOwned =
+						property.name === "serve" && object.type === "Identifier" && RUNTIME_SERVE_OWNERS.has(String(object.name))
+					if (feature && !runtimeOwned) features.add(feature)
+				}
+				break
+			}
+		}
+		for (const key in node) {
+			if (key === "type" || key === "start" || key === "end" || key === "loc" || key === "range") continue
+			const value = node[key]
+			if (value !== null && typeof value === "object") stack.push(value)
+		}
+	}
+	return { features, imports }
+}
+
+/** `import { enableX } from "…"; enableX();` for each feature, on one line. */
+export function featurePrelude(features: Iterable<HoneyFeature>): string {
+	const parts: string[] = []
+	for (const feature of FEATURES) {
+		if (![...features].includes(feature)) continue
+		const { enable, specifier } = FEATURE_ENTRY[feature]
+		parts.push(`import { ${enable} } from ${JSON.stringify(specifier)}; ${enable}();`)
+	}
+	return parts.join(" ")
+}
+
+/** True when `code` already imports the entry for `feature`. */
+export function importsFeatureEntry(code: string, feature: HoneyFeature): boolean {
+	return code.includes(FEATURE_ENTRY[feature].specifier)
+}

package/src/feature-slots.ts

@@ -0,0 +1,70 @@
+import type { createProxyHandler } from "./proxy.ts"
+import type { createBus } from "./realtime/bus.ts"
+import type { resolveRealtimeConfig } from "./realtime/route.ts"
+import type { createRealtimePublisher, createRealtimeSession } from "./realtime/server.ts"
+import type { compileTrust } from "./trust.ts"
+import type { originAllowed } from "./ws-origin.ts"
+import type { createWsSession } from "./ws/session.ts"
+
+/**
+ * Runtime features a builder method needs but most apps never call. The core imports none of
+ * them, so a bundle of an app that does not use them leaves them out; each feature's entry
+ * registers itself when imported. A builder method that finds its feature missing throws at
+ * registration, naming the import.
+ */
+export type FeatureSlots = {
+	proxy: { createProxyHandler: typeof createProxyHandler }
+	realtime: {
+		createBus: typeof createBus
+		createRealtimePublisher: typeof createRealtimePublisher
+		createRealtimeSession: typeof createRealtimeSession
+		resolveRealtimeConfig: typeof resolveRealtimeConfig
+	}
+	trust: { compileTrust: typeof compileTrust }
+	ws: { createWsSession: typeof createWsSession; originAllowed: typeof originAllowed }
+}
+
+export type FeatureName = keyof FeatureSlots
+
+const ENTRY: Record<FeatureName, string> = {
+	proxy: "@lovrozagar/honey/proxy",
+	realtime: "@lovrozagar/honey/realtime",
+	trust: "@lovrozagar/honey/trust",
+	ws: "@lovrozagar/honey/ws/session",
+}
+
+const slots: { [K in FeatureName]?: FeatureSlots[K] } = {}
+
+export function registerFeature<K extends FeatureName>(name: K, impl: FeatureSlots[K]): void {
+	slots[name] = impl
+}
+
+/** Tests only: forget a registered feature. */
+export function resetFeature(name: FeatureName): void {
+	delete slots[name]
+}
+
+/** The registered feature, or a throw that names the import `caller` needs. */
+export function requireFeature<K extends FeatureName>(name: K, caller: string): FeatureSlots[K] {
+	const impl = slots[name]
+	if (impl === undefined) {
+		throw new Error(`honey: ${caller} requires \`import "${ENTRY[name]}"\` in the app entry.`)
+	}
+	return impl as FeatureSlots[K]
+}
+
+/**
+ * The registered feature, importing its entry first when nothing registered it yet. Works where
+ * modules load at run time (Node, Bun, Deno from `node_modules`); a bundle cannot follow the
+ * opaque specifier, so there the entry must be imported (honey's WebSocket adapters do).
+ */
+export async function loadFeature<K extends FeatureName>(name: K, caller: string): Promise<FeatureSlots[K]> {
+	const impl = slots[name]
+	if (impl !== undefined) return impl as FeatureSlots[K]
+	try {
+		await import(/* @vite-ignore */ ENTRY[name])
+	} catch {
+		/* reported below, naming the import */
+	}
+	return requireFeature(name, caller)
+}

package/src/fetch-request.ts

@@ -0,0 +1,13 @@
+/** A Request-shaped object (Honey's Node shim) that can hand over the real Fetch `Request` behind it. */
+export const TO_FETCH_REQUEST = Symbol.for("honey.toFetchRequest")
+
+/**
+ * The Fetch `Request` for `req`. On Bun, Deno and Workers that is `req` itself. On Node, `ctx.req`
+ * is a lighter view of the incoming message, so `new Request(ctx.req)`, `fetch(ctx.req)` and
+ * `ctx.req instanceof Request` need this first; it builds the real Request once, and it then owns
+ * the body (read the body through either, not both).
+ */
+export function toFetchRequest(req: Request): Request {
+	const own = (req as unknown as { [TO_FETCH_REQUEST]?: () => Request })[TO_FETCH_REQUEST]
+	return typeof own === "function" ? own.call(req) : req
+}

package/src/gen-process.ts

@@ -0,0 +1,42 @@
+/** Runs `honey generate` in a child process. Not a package export. */
+import { spawn } from "node:child_process"
+import { createRequire } from "node:module"
+import { dirname, extname, join } from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+const isBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined"
+
+/**
+ * argv that starts this package's CLI on the current runtime. Bun and a compiled install run the
+ * CLI directly. Source under Node (this repository's tests) goes through jiti's loader, with the
+ * `honey-source` condition so the app resolves the package to the same source.
+ */
+export function cliInvocation(): string[] {
+	const self = fileURLToPath(import.meta.url)
+	const ext = extname(self)
+	const cli = join(dirname(self), `cli${ext}`)
+	if (ext !== ".ts" || isBun) return [process.execPath, cli]
+	const jitiDir = dirname(createRequire(import.meta.url).resolve("jiti/package.json"))
+	const register = pathToFileURL(join(jitiDir, "lib", "jiti-register.mjs")).href
+	return [process.execPath, "--conditions=honey-source", "--import", register, cli]
+}
+
+/**
+ * Runs `honey <args>` in `cwd` and resolves when it exits 0. Each run gets a fresh module graph,
+ * so edits to any file the app imports are seen, and app side effects die with the child.
+ */
+export function runCli(args: string[], options: { cwd: string; env?: Record<string, string> }): Promise<void> {
+	const [cmd, ...pre] = cliInvocation() as [string, ...string[]]
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn(cmd, [...pre, ...args], {
+			cwd: options.cwd,
+			env: { ...process.env, ...options.env },
+			stdio: ["ignore", "inherit", "inherit"],
+		})
+		child.on("error", reject)
+		child.on("exit", (code, signal) => {
+			if (code === 0) resolvePromise()
+			else reject(new Error(`honey ${args[0] ?? ""} failed (${signal ?? `exit ${code}`})`))
+		})
+	})
+}

package/src/gen-write.ts

@@ -0,0 +1,127 @@
+import { createHash, randomBytes } from "node:crypto"
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync } from "node:fs"
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path"
+import { toYaml } from "./yaml.ts"
+
+/** Lists what one generator run wrote into an output directory, so the next run can delete leftovers. */
+export const OUTPUT_MANIFEST = ".honey-generated.json"
+
+/**
+ * Writes `content` unless the file already holds exactly that. The write goes to a temp file in
+ * the same directory and is renamed over the target, so a crash never leaves a truncated file.
+ * Returns true when the file was written.
+ */
+export function writeFileIfChanged(filePath: string, content: string): boolean {
+	if (existsSync(filePath)) {
+		try {
+			if (readFileSync(filePath, "utf-8") === content) return false
+		} catch {
+			/* unreadable — overwrite */
+		}
+	}
+	mkdirSync(dirname(filePath), { recursive: true })
+	const tmp = `${filePath}.${randomBytes(6).toString("hex")}.tmp`
+	writeFileSync(tmp, content, "utf-8")
+	try {
+		renameSync(tmp, filePath)
+	} catch (err) {
+		rmSync(tmp, { force: true })
+		throw err
+	}
+	return true
+}
+
+function checksum(text: string): string {
+	return createHash("sha256").update(text).digest("hex").slice(0, 12)
+}
+
+/** Source file with a `@generated` header. Compares the full content, not only the header checksum. */
+export function writeGenFile(filePath: string, body: string, generator: string): boolean {
+	const normalized = body.replace(/\n*$/, "\n")
+	const ext = filePath.endsWith(".d.ts") ? ".d.ts" : extname(filePath)
+	const hash = checksum(normalized)
+	const header =
+		ext === ".sql"
+			? `-- @generated by ${generator} — do not edit. checksum: ${hash}`
+			: `/* @generated by ${generator} — do not edit. checksum: ${hash} */`
+	return writeFileIfChanged(filePath, `${header}\n${normalized}`)
+}
+
+/** `x-generated` marker: an extension key, so the document stays valid OpenAPI. */
+function withMarker(data: unknown, generator: string): Record<string, unknown> {
+	const hash = checksum(JSON.stringify(data, null, 2))
+	return { "x-generated": `${generator} checksum:${hash}`, ...(data as Record<string, unknown>) }
+}
+
+export function writeGenJsonFile(filePath: string, data: unknown, generator: string): boolean {
+	return writeFileIfChanged(filePath, `${JSON.stringify(withMarker(data, generator), null, 2)}\n`)
+}
+
+export function writeGenYamlFile(filePath: string, data: unknown, generator: string): boolean {
+	return writeFileIfChanged(filePath, toYaml(withMarker(data, generator)))
+}
+
+/**
+ * Writes a generated directory (an SDK port, the Go CLI) and deletes the files the previous run
+ * wrote that this run no longer produces. Only files listed in the previous manifest are ever
+ * deleted, so hand-written files next to generated ones survive. Paths must stay inside `outDir`.
+ */
+export function writeOutputDir(outDir: string, files: Record<string, string>): void {
+	const root = resolve(outDir)
+	const written = new Set<string>()
+	for (const [rel, content] of Object.entries(files)) {
+		const abs = resolveInside(root, rel)
+		writeFileIfChanged(abs, content)
+		written.add(toPosix(relative(root, abs)))
+	}
+
+	for (const stale of readOutputManifest(root)) {
+		if (written.has(stale)) continue
+		const abs = resolveInside(root, stale)
+		rmSync(abs, { force: true })
+		removeEmptyParents(dirname(abs), root)
+	}
+
+	const manifest = `${JSON.stringify({ files: [...written].sort(compareCodeUnits) }, null, 2)}\n`
+	writeFileIfChanged(join(root, OUTPUT_MANIFEST), manifest)
+}
+
+function readOutputManifest(root: string): string[] {
+	const path = join(root, OUTPUT_MANIFEST)
+	if (!existsSync(path)) return []
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8")) as { files?: unknown }
+		return Array.isArray(parsed.files) ? parsed.files.filter((f): f is string => typeof f === "string") : []
+	} catch {
+		return []
+	}
+}
+
+function resolveInside(root: string, rel: string): string {
+	const abs = resolve(root, rel)
+	if (isAbsolute(rel) || (abs !== root && !abs.startsWith(root + sep))) {
+		throw new Error(`generated file path escapes its output directory: ${rel}`)
+	}
+	if (abs === root) throw new Error(`generated file path is the output directory itself: ${rel}`)
+	return abs
+}
+
+function removeEmptyParents(dir: string, root: string): void {
+	let current = dir
+	while (current !== root && current.startsWith(root + sep)) {
+		/* a directory the user already deleted counts as removed; keep walking up */
+		if (existsSync(current)) {
+			if (readdirSync(current).length > 0) return
+			rmdirSync(current)
+		}
+		current = dirname(current)
+	}
+}
+
+function toPosix(p: string): string {
+	return p.split(sep).join("/")
+}
+
+function compareCodeUnits(a: string, b: string): number {
+	return a < b ? -1 : a > b ? 1 : 0
+}

package/src/glob.ts

@@ -0,0 +1,109 @@
+import { isAbsolute, relative } from "node:path"
+
+/**
+ * Glob → RegExp for `watch` patterns, matched against a path relative to the project root.
+ * Supports `**` (any number of segments), `*` and `?` (within a segment), `{a,b}` alternation and
+ * `[...]` classes (`[!...]` negates). A pattern is anchored at the root, so `src/**` never matches
+ * `node_modules/x/src/a.ts`.
+ */
+export function globToRegExp(pattern: string): RegExp {
+	const normalized = pattern.replaceAll("\\", "/").replace(/^(\.\/)+/, "")
+	const segments = normalized.split("/")
+	let re = "^"
+	segments.forEach((segment, i) => {
+		const last = i === segments.length - 1
+		if (segment === "**") {
+			re += last ? ".*" : "(?:[^/]*/)*"
+			return
+		}
+		re += segmentToRegExp(segment)
+		if (!last) re += "/"
+	})
+	return new RegExp(`${re}$`)
+}
+
+function segmentToRegExp(segment: string): string {
+	let out = ""
+	for (let i = 0; i < segment.length; i++) {
+		const ch = segment[i] as string
+		if (ch === "*") {
+			/* a stray `**` inside a segment means the same as `*` */
+			while (segment[i + 1] === "*") i++
+			out += "[^/]*"
+		} else if (ch === "?") {
+			out += "[^/]"
+		} else if (ch === "[") {
+			const close = segment.indexOf("]", i + 2)
+			if (close === -1) {
+				out += "\\["
+				continue
+			}
+			let body = segment.slice(i + 1, close)
+			if (body.startsWith("!")) body = `^${body.slice(1)}`
+			out += `[${body.replaceAll("\\", "\\\\").replaceAll("/", "")}]`
+			i = close
+		} else if (ch === "{") {
+			const close = matchingBrace(segment, i)
+			if (close === -1) {
+				out += "\\{"
+				continue
+			}
+			const alternatives = splitTopLevel(segment.slice(i + 1, close))
+			out += `(?:${alternatives.map(segmentToRegExp).join("|")})`
+			i = close
+		} else {
+			out += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+		}
+	}
+	return out
+}
+
+function matchingBrace(s: string, open: number): number {
+	let depth = 0
+	for (let i = open; i < s.length; i++) {
+		if (s[i] === "{") depth++
+		else if (s[i] === "}" && --depth === 0) return i
+	}
+	return -1
+}
+
+function splitTopLevel(body: string): string[] {
+	const parts: string[] = []
+	let depth = 0
+	let start = 0
+	for (let i = 0; i < body.length; i++) {
+		if (body[i] === "{") depth++
+		else if (body[i] === "}") depth--
+		else if (body[i] === "," && depth === 0) {
+			parts.push(body.slice(start, i))
+			start = i + 1
+		}
+	}
+	parts.push(body.slice(start))
+	return parts
+}
+
+/**
+ * A matcher for `patterns`, compiled once: true when `file` (absolute, or relative to `root`)
+ * matches any pattern. Files outside `root` never match.
+ */
+export function compileGlobs(patterns: readonly string[]): (file: string, root: string) => boolean {
+	const regexps = patterns.map(globToRegExp)
+	return (file, root) => {
+		const rel = (isAbsolute(file) ? relative(root, file) : file).replaceAll("\\", "/")
+		if (rel === "" || rel.startsWith("../") || rel === ".." || isAbsolute(rel)) return false
+		return regexps.some((re) => re.test(rel))
+	}
+}
+
+/** True when `file` (absolute, or relative to `root`) matches any pattern. Files outside `root` never match. */
+export function matchesGlob(file: string, patterns: readonly string[], root: string): boolean {
+	return compileGlobs(patterns)(file, root)
+}
+
+/**
+ * Paths a watch never regenerates for: generated files (`_gen/` and the `_gen` directory itself,
+ * `*.gen.*`), dependencies, and the `<file>.<hex>.tmp` files an atomic write renames into place. Shared by `honey generate --watch`
+ * and the Vite plugin.
+ */
+export const WATCH_IGNORE_RE = /(^|[/\\])_gen([/\\]|$)|\.gen\.(tsx?|json|ya?ml|d\.ts)$|[/\\]node_modules[/\\]|\.tmp$/