@pikku/core 0.12.107 → 0.12.112

package/src/dev/hot-reload.ts

@@ -1,225 +0,0 @@
-import { watch, type FSWatcher } from 'node:fs'
-import { stat } from 'node:fs/promises'
-import { basename, join, resolve, relative } from 'node:path'
-
-import { pikkuState } from '../pikku-state.js'
-import { clearMiddlewareCache } from '../middleware-runner.js'
-import { clearPermissionsCache } from '../permissions.js'
-import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middleware-runner.js'
-import { httpRouter } from '../wirings/http/routers/http-router.js'
-import type { Logger } from '../services/logger.js'
-import type { CorePikkuFunctionConfig } from '../function/functions.types.js'
-import {
-  createModuleRunner,
-  isTopLevelAwaitLimitation,
-} from './module-runner.js'
-
-export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js'
-
-interface PikkuDevReloaderOptions {
-  srcDirectories: string[]
-  logger: Logger
-  pikkuDir?: string
-}
-
-const isFunctionConfig = (
-  value: unknown
-): value is CorePikkuFunctionConfig<any, any> => {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'func' in value &&
-    typeof (value as { func?: unknown }).func === 'function'
-  )
-}
-
-const findCompiledFile = async (
-  tsFile: string,
-  srcDir: string,
-  pikkuDir: string
-): Promise<string | null> => {
-  const rel = relative(srcDir, tsFile).replace(/\.ts$/, '.js')
-  const candidates = [
-    join(pikkuDir, 'dist', rel),
-    join(srcDir, rel),
-    tsFile.replace(/\.ts$/, '.js'),
-  ]
-  for (const candidate of candidates) {
-    try {
-      await stat(candidate)
-      return candidate
-    } catch {
-      // not found, try next
-    }
-  }
-  return null
-}
-
-const isWatchedTsFile = (filename: string): boolean => {
-  return (
-    filename.endsWith('.ts') &&
-    !filename.endsWith('.test.ts') &&
-    !filename.endsWith('.d.ts') &&
-    !filename.endsWith('.gen.ts') &&
-    // Hidden files: editor/sed atomic-write temps must never trigger a reload.
-    !basename(filename).startsWith('.')
-  )
-}
-
-/** Not every reload failure is a mistake in the file: pikku's reloader emits
- *  `cjs`, which has no way to express top-level `await`, so a perfectly valid
- *  module can fail here forever. Saying so outright saves the reader from
- *  hunting a bug that is not in their code. The stack is dropped in that case
- *  because it points into esbuild rather than at anything actionable. */
-const reloadFailureReason = (error: Error): string => {
-  if (isTopLevelAwaitLimitation(error)) {
-    return (
-      `  ${error.message}\n` +
-      '  This is a pikku limitation, not a mistake in your file: the hot-reloader compiles to `cjs`, ' +
-      'which cannot express top-level `await`. Move the awaited work into a function, or restart the ' +
-      'dev server to pick the file up.'
-    )
-  }
-  return `  ${error.stack ?? error.message}`
-}
-
-export interface PikkuDevReloaderHandle {
-  close: () => void
-  /** Re-import every file changed since the last drain (post-codegen, once
-   *  fresh meta is in state). */
-  reimportPending: () => Promise<void>
-}
-
-export async function pikkuDevReloader(
-  options: PikkuDevReloaderOptions
-): Promise<PikkuDevReloaderHandle> {
-  const { srcDirectories, logger, pikkuDir = '.pikku' } = options
-  const absSrcDirs = srcDirectories.map((d) => resolve(d))
-  const absPikkuDir = resolve(pikkuDir)
-  const watchers: FSWatcher[] = []
-
-  const functionsMap = pikkuState(null, 'function', 'functions')
-  const moduleRunner = createModuleRunner()
-
-  const handleFileChange = async (changedTsFile: string) => {
-    const start = Date.now()
-    const reloadedNames: string[] = []
-    const addedNames: string[] = []
-
-    const srcDir = absSrcDirs.find((d) => changedTsFile.startsWith(d))
-    if (!srcDir) return
-
-    const compiledFile = await findCompiledFile(
-      changedTsFile,
-      srcDir,
-      absPikkuDir
-    )
-    const importPath = compiledFile ?? changedTsFile
-
-    const result = await moduleRunner.run(importPath)
-    if (!result.ok) {
-      // Keeping the old code leaves the process disagreeing with the file on
-      // disk, and the only symptom is stale output from a function that looks
-      // correct in the editor — so the reason has to be printed here, where it
-      // is still known, rather than left for the developer to reconstruct.
-      logger.error(
-        `Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)\n` +
-          reloadFailureReason(result.error)
-      )
-      return
-    }
-    const mod = result.exports
-
-    // knowledge: decisions/internals/hot-reload-writes-into-the-function-map-captured-at-startup.md
-    for (const [exportName, exportValue] of Object.entries(mod)) {
-      if (!isFunctionConfig(exportValue)) continue
-      const isNew = !functionsMap.has(exportName)
-      functionsMap.set(exportName, exportValue)
-      if (isNew) addedNames.push(exportName)
-      else reloadedNames.push(exportName)
-    }
-
-    // Re-importing re-ran the module’s wire* side effects, so reset the router
-    // and caches even when no function export changed — a wiring-only edit has
-    // to rebuild the route matchers too.
-    clearMiddlewareCache()
-    clearPermissionsCache()
-    clearChannelMiddlewareCache()
-    httpRouter.reset()
-
-    if (reloadedNames.length > 0 || addedNames.length > 0) {
-      const elapsed = Date.now() - start
-      const parts: string[] = []
-      if (reloadedNames.length > 0) parts.push(reloadedNames.join(', '))
-      if (addedNames.length > 0) parts.push(`new: ${addedNames.join(', ')}`)
-      logger.info(`Hot-reloaded: ${parts.join('; ')} (${elapsed}ms)`)
-    }
-  }
-
-  let debounceTimer: ReturnType<typeof setTimeout> | undefined
-  const pendingChanges = new Set<string>()
-  // Files re-imported since the last reimportPending() drain, re-run after the
-  // dev server's codegen pass so registrations skipped for missing meta retry.
-  const postCodegenQueue = new Set<string>()
-
-  const safeHandleFileChange = async (file: string) => {
-    try {
-      await handleFileChange(file)
-    } catch (err) {
-      logger.error(
-        `Hot-reload error for ${relative(process.cwd(), file)}: ${err instanceof Error ? err.message : String(err)}`
-      )
-    }
-  }
-
-  const scheduleReload = (filePath: string) => {
-    pendingChanges.add(filePath)
-    if (debounceTimer) clearTimeout(debounceTimer)
-    debounceTimer = setTimeout(async () => {
-      const files = [...pendingChanges]
-      pendingChanges.clear()
-      for (const file of files) {
-        postCodegenQueue.add(file)
-        await safeHandleFileChange(file)
-      }
-    }, 50)
-  }
-
-  for (const srcDir of absSrcDirs) {
-    try {
-      const watcher = watch(
-        srcDir,
-        { recursive: true },
-        (eventType, filename) => {
-          if (filename && isWatchedTsFile(filename)) {
-            scheduleReload(join(srcDir, filename))
-          }
-        }
-      )
-      watchers.push(watcher)
-    } catch (err: any) {
-      logger.error(
-        `Failed to watch directory ${srcDir}: ${err?.message || err}`
-      )
-    }
-  }
-
-  logger.info(`Hot-reload active for: ${srcDirectories.join(', ')}`)
-
-  return {
-    close: () => {
-      if (debounceTimer) clearTimeout(debounceTimer)
-      for (const watcher of watchers) {
-        watcher.close()
-      }
-      moduleRunner.clear()
-    },
-    reimportPending: async () => {
-      const files = [...postCodegenQueue]
-      postCodegenQueue.clear()
-      for (const file of files) {
-        await safeHandleFileChange(file)
-      }
-    },
-  }
-}

package/src/dev/module-runner.test.ts

@@ -1,235 +0,0 @@
-import { describe, test, beforeEach, afterEach } from 'node:test'
-import assert from 'node:assert/strict'
-import v8 from 'node:v8'
-import vm from 'node:vm'
-import { mkdtemp, writeFile, rm } from 'node:fs/promises'
-import { createRequire } from 'node:module'
-import { join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { tmpdir } from 'node:os'
-
-import {
-  createModuleRunner,
-  isTopLevelAwaitLimitation,
-} from './module-runner.js'
-
-// A forced-GC hook without launching the process with a flag: on Bun use the
-// native collector; on Node flip --expose-gc on just long enough to grab `gc`.
-const getGc = (): (() => void) => {
-  const bun = (globalThis as any).Bun
-  if (bun) return () => bun.gc(true)
-  v8.setFlagsFromString('--expose-gc')
-  const gc = vm.runInNewContext('gc') as () => void
-  v8.setFlagsFromString('--no-expose-gc')
-  return () => gc()
-}
-
-const heapUsedMb = () => process.memoryUsage().heapUsed / 1048576
-
-// V8's --experimental-test-coverage retains coverage data for every compiled
-// script for the life of the run, which pins the runner's per-reload compiled
-// functions (and would equally pin the old leaky mechanism), so a heap-growth
-// measurement can't discriminate a leak from a non-leak while it's on. run-tests.sh
-// exports this marker in --coverage mode (the flag itself is not visible to the
-// isolated test child). The single-slot registry guarantee below still runs
-// unconditionally.
-const UNDER_COVERAGE = process.env.PIKKU_TEST_COVERAGE === '1'
-
-describe('createModuleRunner', { concurrency: false }, () => {
-  let tmpDir: string
-
-  beforeEach(async () => {
-    tmpDir = await mkdtemp(join(tmpdir(), 'pikku-module-runner-'))
-    await writeFile(
-      join(tmpDir, 'package.json'),
-      JSON.stringify({ type: 'module' })
-    )
-  })
-
-  afterEach(async () => {
-    await rm(tmpDir, { recursive: true, force: true })
-  })
-
-  test('runs a TS module and returns its exports', async () => {
-    const runner = createModuleRunner()
-    const file = join(tmpDir, 'todo.ts')
-    await writeFile(
-      file,
-      `interface Todo { id: string }
-       export const createTodo = { func: async (_s: any, d: Todo) => ({ id: d.id }) }`
-    )
-
-    const result = await runner.run(file)
-    assert.equal(result.ok, true)
-    const createTodo = (result as { exports: Record<string, unknown> }).exports
-      .createTodo as {
-      func: (...a: any[]) => Promise<any>
-    }
-    assert.equal(typeof createTodo.func, 'function')
-    assert.deepEqual(await createTodo.func({}, { id: 'abc' }), { id: 'abc' })
-  })
-
-  test('top-level import side effects hit the live singleton dependency', async () => {
-    // Delegated imports must resolve to the SAME module instance the rest of
-    // the process holds, so a user file's wire* side effect mutates live state.
-    await writeFile(
-      join(tmpDir, 'registry.js'),
-      `export const registry = new Map()
-       export const wire = (name, cfg) => registry.set(name, cfg)`
-    )
-
-    const runner = createModuleRunner()
-    const userFile = join(tmpDir, 'wired.ts')
-    await writeFile(
-      userFile,
-      `import { wire } from './registry.js'
-       export const createTodo = { func: async () => ({ ok: true }) }
-       wire('createTodo', createTodo)`
-    )
-
-    const result = await runner.run(userFile)
-    assert.equal(result.ok, true)
-    const mod = (result as { exports: Record<string, unknown> }).exports
-
-    // Read the dependency through the same resolver the runner uses, so we
-    // observe the exact instance the user module's `import` bound to (using a
-    // separate `import()` would resolve a distinct copy under the tsx test
-    // loader and prove nothing about live-singleton delegation).
-    const dep = createRequire(pathToFileURL(userFile))('./registry.js') as {
-      registry: Map<string, unknown>
-    }
-    assert.equal(dep.registry.has('createTodo'), true)
-    assert.strictEqual(dep.registry.get('createTodo'), mod!.createTodo)
-  })
-
-  test('re-running the same path overwrites a single registry slot', async () => {
-    const runner = createModuleRunner()
-    const file = join(tmpDir, 'value.ts')
-
-    await writeFile(file, `export const value = { func: async () => 'v1' }`)
-    const first = await runner.run(file)
-    assert.equal(first.ok, true)
-    assert.equal(await ((first as any).exports.value as any).func(), 'v1')
-
-    await writeFile(file, `export const value = { func: async () => 'v2' }`)
-    const second = await runner.run(file)
-    assert.equal(second.ok, true)
-    assert.equal(await ((second as any).exports.value as any).func(), 'v2')
-
-    // Stable key: many reloads of one path never grow the registry.
-    for (let i = 0; i < 20; i++) await runner.run(file)
-    assert.equal(runner.size, 1)
-  })
-
-  test('reports a bad edit with its reason so the caller can say why', async () => {
-    const runner = createModuleRunner()
-    const file = join(tmpDir, 'broken.ts')
-    await writeFile(
-      file,
-      `export const oops = { func: async () => ( } ] syntax`
-    )
-    const result = await runner.run(file)
-    assert.equal(result.ok, false)
-    // The caller keeps serving the old code, so this error is the only thing
-    // standing between the developer and an unexplained stale response.
-    const { error } = result as { error: Error }
-    assert.ok(error instanceof Error)
-    assert.match(error.message, /broken\.ts/)
-    assert.equal(isTopLevelAwaitLimitation(error), false)
-  })
-
-  test('names the top-level await limitation as such', async () => {
-    const runner = createModuleRunner()
-    const file = join(tmpDir, 'tla.ts')
-    await writeFile(
-      file,
-      `const config = await Promise.resolve({ ok: true })
-       export const load = { func: async () => config }`
-    )
-    const result = await runner.run(file)
-    assert.equal(result.ok, false)
-    // Nothing is wrong with this file — the `cjs` emit is what cannot take it,
-    // and the caller has to be able to tell the developer that.
-    assert.equal(
-      isTopLevelAwaitLimitation((result as { error: Error }).error),
-      true
-    )
-  })
-
-  test('a thrown non-Error still arrives as an Error carrying its value', async () => {
-    const runner = createModuleRunner()
-    const file = join(tmpDir, 'throws-a-string.ts')
-    await writeFile(file, `throw 'boom'`)
-    const result = await runner.run(file)
-    assert.equal(result.ok, false)
-    const { error } = result as { error: Error }
-    assert.ok(error instanceof Error)
-    assert.equal(error.message, 'boom')
-    assert.equal((error as { cause?: unknown }).cause, 'boom')
-  })
-
-  test('editing and reimporting a module 200x does not leak memory', async () => {
-    const gc = getGc()
-    const runner = createModuleRunner()
-    const file = join(tmpDir, 'big.ts')
-    // A sizeable module edited on every reload (the real dev pattern). The old
-    // fresh-URL reimport left one of these in the native ESM loader map per
-    // edit (~0.3-1.3 MB each) — ~84 MB (Node) / ~222 MB (Bun) over 200 edits —
-    // and OOMed. The evictable runner overwrites a single stable slot, so the
-    // previous module is collected and heap stays bounded.
-    const payload = JSON.stringify(
-      Array.from({ length: 2000 }, (_, i) => ({ i, s: 'field_' + i }))
-    )
-    const write = (marker: number) =>
-      writeFile(
-        file,
-        `export const data = ${payload}
-         export const handler = { func: async () => data.length }
-         // edit ${marker}`
-      )
-
-    // Warm up (first compile allocates esbuild + shared caches), then baseline.
-    await write(0)
-    await runner.run(file)
-    gc()
-    const baseline = heapUsedMb()
-
-    for (let i = 1; i <= 200; i++) {
-      await write(i)
-      const result = await runner.run(file)
-      assert.equal(result.ok, true)
-    }
-    gc()
-    const growth = heapUsedMb() - baseline
-
-    assert.equal(runner.size, 1)
-    if (UNDER_COVERAGE) return
-    assert.ok(
-      growth < 15,
-      `heap grew ${growth.toFixed(1)} MB over 200 edits (expected < 15 MB)`
-    )
-  })
-
-  test('a .js specifier resolves to the .ts file that actually exists', async () => {
-    // How every TypeScript source in a pikku app refers to a sibling: the
-    // import is written `.js` and only the `.ts` is on disk. Nothing else here
-    // covers it — the delegated-import test writes a real `.js` — and it is the
-    // shape that breaks under Bun once `pikku dev` has been running, where the
-    // reload fails and the process quietly keeps serving the previous code.
-    await writeFile(join(tmpDir, 'dep.ts'), `export const value = 'from-dep'`)
-
-    const runner = createModuleRunner()
-    const userFile = join(tmpDir, 'importer.ts')
-    await writeFile(
-      userFile,
-      `import { value } from './dep.js'
-       export const fn = { func: async () => value }`
-    )
-
-    const result = await runner.run(userFile)
-    assert.equal(result.ok, true)
-    const mod = (result as { exports: Record<string, unknown> }).exports
-    assert.equal(await (mod.fn as { func: () => Promise<string> }).func(), 'from-dep')
-  })
-
-})

package/src/dev/module-runner.ts

@@ -1,138 +0,0 @@
-import { readFile } from 'node:fs/promises'
-import { createRequire } from 'node:module'
-import { dirname, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { compileFunction } from 'node:vm'
-import type { transformSync as EsbuildTransformSync } from 'esbuild'
-
-type EsbuildTransform = typeof EsbuildTransformSync
-
-let transformSync: EsbuildTransform | undefined
-
-const loadTransform = async (): Promise<EsbuildTransform> => {
-  if (transformSync) return transformSync
-  // esbuild is a dev-only dependency hoisted from @pikku/cli at runtime; the
-  // `./dev` export is dev-only so it is never loaded in production runtimes.
-  const esbuild = await import('esbuild')
-  transformSync = esbuild.transformSync
-  return transformSync
-}
-
-/** The outcome of one run. A failure carries its error rather than collapsing
- *  to `null`: the caller keeps serving the previously-loaded code, so unless the
- *  reason travels with the failure the running process silently disagrees with
- *  the file on disk and nothing anywhere says why. */
-export type PikkuModuleRunResult =
-  { ok: true; exports: Record<string, unknown> } | { ok: false; error: Error }
-
-export interface PikkuModuleRunner {
-  /** Run a user module by absolute path. Repeated runs of one path overwrite a
-   *  single registry slot. Failure is returned, not thrown, so the caller can
-   *  keep the previously-loaded code — and the discriminant makes that case
-   *  impossible to read past by accident. */
-  run: (absPath: string) => Promise<PikkuModuleRunResult>
-  evict: (absPath: string) => void
-  clear: () => void
-  readonly size: number
-}
-
-/** esbuild states pikku's one documented reload limitation only in the text of
- *  its transform error. Matching it is worth the fragility: the developer's file
- *  is correct, and no amount of re-reading it will reveal that the reloader —
- *  not the file — is what cannot cope. */
-export const isTopLevelAwaitLimitation = (error: Error): boolean =>
-  /top-level await/i.test(error.message)
-
-interface BunResolver {
-  resolveSync: (specifier: string, parent: string) => string
-}
-
-/** The `require` a reloaded module is run with.
- *
- *  On Bun, `createRequire`'s referrer stops being honoured somewhere in a
- *  long-running process: the same relative specifier that resolves in a fresh
- *  script fails inside a `pikku dev` that has been up for a while, so a file
- *  importing `./sibling.js` reloads as `Cannot find module` and the developer
- *  is left serving the previous code from an edit that looked applied. Bun's
- *  own resolver still answers correctly when handed the importer's directory
- *  outright, so the specifier is resolved to an absolute path first and the
- *  referrer never has to survive the trip. Anything Bun's resolver declines —
- *  builtins among them — falls through to `require` unchanged.
- */
-const createRequireForFile = (absPath: string): NodeRequire => {
-  const base = createRequire(pathToFileURL(absPath))
-  const bun = (globalThis as { Bun?: BunResolver }).Bun
-  if (!bun) return base
-
-  const importerDir = dirname(absPath)
-  const resolveThroughBun = (specifier: string): string => {
-    try {
-      return bun.resolveSync(specifier, importerDir)
-    } catch {
-      return specifier
-    }
-  }
-
-  // Only resolution is delegated; the require itself stays outside the guard so
-  // a module that throws while evaluating reports its own error rather than
-  // being retried under a second specifier.
-  const bunRequire = ((specifier: string) =>
-    base(resolveThroughBun(specifier))) as NodeRequire
-  return Object.assign(bunRequire, base)
-}
-
-export const createModuleRunner = (): PikkuModuleRunner => {
-  const registry = new Map<string, Record<string, unknown>>()
-
-  const run = async (filePath: string): Promise<PikkuModuleRunResult> => {
-    const absPath = resolve(filePath)
-    try {
-      const transform = await loadTransform()
-      const source = await readFile(absPath, 'utf-8')
-      const { code } = transform(source, {
-        loader: absPath.endsWith('.ts') ? 'ts' : 'js',
-        format: 'cjs',
-        sourcefile: absPath,
-      })
-
-      const fn = compileFunction(
-        code,
-        ['require', 'exports', 'module', '__filename', '__dirname'],
-        { filename: absPath }
-      )
-
-      const require = createRequireForFile(absPath)
-      const moduleObj: { exports: Record<string, unknown> } = { exports: {} }
-      fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath))
-
-      registry.set(absPath, moduleObj.exports)
-      return { ok: true, exports: moduleObj.exports }
-    } catch (thrown) {
-      // A bad edit, or the one known limitation: a file using top-level
-      // `await`, which cannot be emitted in `cjs` form. Normalised to an
-      // `Error` so the caller always has a message and a stack to print
-      // without re-deriving them; a non-`Error` throw keeps its original value
-      // as the `cause`.
-      return {
-        ok: false,
-        error:
-          thrown instanceof Error
-            ? thrown
-            : new Error(String(thrown), { cause: thrown }),
-      }
-    }
-  }
-
-  return {
-    run,
-    evict: (filePath: string) => {
-      registry.delete(resolve(filePath))
-    },
-    clear: () => {
-      registry.clear()
-    },
-    get size() {
-      return registry.size
-    },
-  }
-}