@c9up/ream 0.2.23 → 0.2.24

package/src/Ignitor.ts

@@ -63,6 +63,18 @@ import type { AppEnvironment } from './Application.js'
 /**
  * Reamrc config — like AdonisJS adonisrc.ts with defineConfig().
  */
+/** A command the CLI runs on the application's behalf. */
+export interface AssetsCommand {
+  command: string
+  args?: string[]
+}
+
+/** What `assets` declares: a watcher for `dev`, a one-shot for `build`. */
+export interface AssetsConfig {
+  devServer?: AssetsCommand
+  build?: AssetsCommand
+}
+
 export interface ReamrcConfig {
   providers?: Array<
     | (() => Promise<{ default: new (app: AppContext) => ProviderContract }>)
@@ -113,6 +125,18 @@ export interface ReamrcConfig {
   }
   /** Test suites and runner settings — the `tests` block of adonisrc.ts. */
   tests?: TestsConfig
+  /**
+   * The asset pipeline `ream dev` and `ream build` drive alongside the app.
+   *
+   * `devServer` is started beside the development server and killed with it;
+   * `build` runs once, before the TypeScript build, and a non-zero exit stops
+   * the build rather than shipping a bundle nobody rebuilt.
+   *
+   * Declared here because the CLI already reads it: without the type an app
+   * that configures its asset build gets an excess-property error from
+   * `defineConfig`, which is a strange way to learn that the option exists.
+   */
+  assets?: AssetsConfig
 }
 
 /** One test suite, as declared in the rc file (AdonisJS `tests.suites[]`). */

package/src/dev/fullReload.ts

@@ -0,0 +1,34 @@
+/**
+ * Saying why the process is about to restart.
+ *
+ * A change the loader cannot swap in place becomes an exit code the dev server
+ * restarts on. From the terminal the only trace of it was the boot banner
+ * printing itself a second time — which reads as a server rebooting on its own
+ * rather than as a file that fell outside `hotHook.boundaries`. Upstream's dev
+ * server logs the file it reloaded for; this is that line.
+ *
+ * Kept apart from the loader entry so it can be tested: importing that entry
+ * registers module hooks, which a test cannot undo.
+ */
+
+/** Why a change could not be swapped in place. */
+export type ReloadReason = 'outside-boundaries' | 'restart-list'
+
+/**
+ * The line to print before restarting.
+ *
+ * @param file - absolute path of the file that changed.
+ * @param relativise - turns it into the path the editor shows, so the line can
+ *   be read at a glance.
+ */
+export function fullReloadNotice(
+  file: string,
+  reason: ReloadReason,
+  relativise: (file: string) => string,
+): string {
+  const why =
+    reason === 'restart-list'
+      ? ' (it is on `hotHook.restart`, which always restarts)'
+      : ' (nothing importing it is inside a `hotHook.boundaries` entry, so it could not be swapped)'
+  return `[ream] full reload — ${relativise(file)}${why}`
+}

package/src/dev/hotGlob.ts

@@ -0,0 +1,66 @@
+/**
+ * Matching the globs an application declares under `hotHook.boundaries`.
+ *
+ * A dependency for this would be `picomatch` plus `fast-glob`, which is two
+ * packages and their trees for the three wildcards these patterns actually use.
+ * The patterns are written by hand in a `package.json` and read once at boot;
+ * what they need is to be right, not fast.
+ *
+ * The dialect is the one those files already use:
+ *   *   any run of characters inside one path segment
+ *   **  any number of segments, including none
+ *   ?   exactly one character inside a segment
+ *
+ * A leading `./` is optional, and matching is done on POSIX-shaped paths
+ * relative to the project root, so a Windows checkout and a Linux one read the
+ * same pattern the same way.
+ */
+
+/** Turn one glob into an anchored regular expression. */
+export function globToRegExp(pattern: string): RegExp {
+  const cleaned = pattern.replace(/^\.\//, '')
+  let out = ''
+  for (let i = 0; i < cleaned.length; i += 1) {
+    const char = cleaned[i]
+    if (char === '*') {
+      if (cleaned[i + 1] === '*') {
+        // `**/` swallows the separator so that `a/**/b` also matches `a/b`;
+        // a trailing `**` simply matches the rest.
+        i += 1
+        if (cleaned[i + 1] === '/') {
+          i += 1
+          out += '(?:[^/]+/)*'
+        } else {
+          out += '.*'
+        }
+        continue
+      }
+      out += '[^/]*'
+      continue
+    }
+    if (char === '?') {
+      out += '[^/]'
+      continue
+    }
+    // Everything else is literal, including the characters a regular
+    // expression would otherwise read as syntax.
+    out += (char ?? '').replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^${out}$`)
+}
+
+/**
+ * A matcher over several globs.
+ *
+ * Returns a predicate rather than a class: the graph takes a function, and a
+ * project with no boundaries gets one that is honestly always false instead of
+ * an empty object that has to be checked for.
+ */
+export function globMatcher(patterns: readonly string[]): (path: string) => boolean {
+  const expressions = patterns.map(globToRegExp)
+  if (expressions.length === 0) return () => false
+  return (path: string) => {
+    const normalised = path.replace(/\\/g, '/').replace(/^\.\//, '')
+    return expressions.some((expression) => expression.test(normalised))
+  }
+}

package/src/dev/hotGraph.ts

@@ -0,0 +1,109 @@
+/**
+ * The import graph a hot reload reasons over, and what it decides.
+ *
+ * Owned here rather than taken from `hot-hook`, which used to do this job. The
+ * package is 655 lines and four npm dependencies, and it had to be installed by
+ * every application because a dev-only loader has no business in a production
+ * install of the framework — so a project created before that convention simply
+ * lost hot reloading and was told nothing. The part that genuinely needs a
+ * library is the part Node now provides itself: `module.registerHooks` for the
+ * graph, `fs.watch` for the changes.
+ *
+ * NO node_modules dependency, deliberately: everything below is arithmetic on
+ * paths.
+ *
+ * The graph is built by the resolver as the program runs, never by reading
+ * files. A `resolve` hook is handed the importer and the imported, which is
+ * exactly an edge, and it sees dynamic imports as they happen — a static parse
+ * of the source could only guess at those.
+ */
+
+/** A module's place in the graph: who imports it, and which version is live. */
+interface Node {
+  /** Modules that imported this one. The graph is walked upward, so this is the direction stored. */
+  readonly importers: Set<string>
+  /** Bumped on invalidation; appended to the URL so the loader fetches the file again. */
+  version: number
+}
+
+/** What a change to one file means. */
+export type Decision =
+  | { kind: 'swap'; invalidated: string[] }
+  | { kind: 'reload'; file: string; reason: 'outside-boundaries' | 'restart-list' }
+  | { kind: 'ignore' }
+
+export class HotGraph {
+  readonly #nodes = new Map<string, Node>()
+  readonly #isBoundary: (file: string) => boolean
+  readonly #isRestart: (file: string) => boolean
+
+  constructor(options: {
+    isBoundary: (file: string) => boolean
+    isRestart: (file: string) => boolean
+  }) {
+    this.#isBoundary = options.isBoundary
+    this.#isRestart = options.isRestart
+  }
+
+  #node(file: string): Node {
+    let node = this.#nodes.get(file)
+    if (node === undefined) {
+      node = { importers: new Set(), version: 0 }
+      this.#nodes.set(file, node)
+    }
+    return node
+  }
+
+  /** Record that `importer` imported `file`. Called from the resolve hook. */
+  link(file: string, importer: string | undefined): void {
+    const node = this.#node(file)
+    if (importer !== undefined && importer !== file) node.importers.add(importer)
+  }
+
+  /** The version to hang off the URL, or 0 while the module has never been invalidated. */
+  version(file: string): number {
+    return this.#nodes.get(file)?.version ?? 0
+  }
+
+  /** Whether the resolver has ever seen this file. */
+  knows(file: string): boolean {
+    return this.#nodes.has(file)
+  }
+
+  /**
+   * What to do about `file` having changed.
+   *
+   * Walks up from the changed file collecting what has to be re-imported, and
+   * stops at each boundary: a boundary is imported dynamically, so the next
+   * import of it re-resolves, and with it everything below that was collected
+   * on the way. A path that reaches a module nobody imports without crossing a
+   * boundary cannot be re-imported by anyone, and that is a full reload.
+   *
+   * Deciding before invalidating matters: a decision that turns out to be a
+   * full reload must leave no version bumped behind, or a later swap would
+   * hand the caller a URL for a module the process never re-imported.
+   */
+  decide(file: string): Decision {
+    if (this.#isRestart(file)) return { kind: 'reload', file, reason: 'restart-list' }
+    if (!this.#nodes.has(file)) return { kind: 'ignore' }
+
+    const collected = new Set<string>()
+    const queue = [file]
+    while (queue.length > 0) {
+      const current = queue.pop()
+      if (current === undefined || collected.has(current)) continue
+      collected.add(current)
+      // A boundary is where the walk stops: whoever imports it does so
+      // dynamically and will ask for it again.
+      if (this.#isBoundary(current)) continue
+      const importers = this.#nodes.get(current)?.importers
+      if (importers === undefined || importers.size === 0) {
+        return { kind: 'reload', file, reason: 'outside-boundaries' }
+      }
+      for (const importer of importers) queue.push(importer)
+    }
+
+    for (const path of collected) this.#node(path).version += 1
+    return { kind: 'swap', invalidated: [...collected] }
+  }
+}

package/src/dev/hotWatcher.ts

@@ -0,0 +1,89 @@
+/**
+ * Watching the project for the changes a hot reload reacts to.
+ *
+ * `fs.watch` with `recursive: true`, which Node implements on Linux, macOS and
+ * Windows alike — the reason a watcher used to be a dependency here, and is not
+ * any more.
+ *
+ * Two behaviours are worth stating because they are not obvious from the API:
+ *
+ * A save is rarely one event. Editors write, rename and touch, and a single
+ * Ctrl-S can arrive as several notifications for the same file within a few
+ * milliseconds. Each one would walk the graph and bump a version, so they are
+ * coalesced.
+ *
+ * `ream dev` also watches from the outside, in Rust. That is not a duplicate:
+ * this watcher dies with the process it lives in, so a server that crashed on a
+ * syntax error has nothing left to notice the fix. The outer one covers exactly
+ * that window, and hands back over by restarting the process.
+ */
+
+import { type FSWatcher, watch } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+/** How long to wait for a save to finish arriving before acting on it. */
+const SETTLE_MS = 40
+
+export interface WatcherOptions {
+  /** Project root; every reported path is absolute, resolved against it. */
+  root: string
+  /** Directories under the root to watch, when they exist. */
+  directories: readonly string[]
+  /** Individual files to watch — env files sit at the root, so no directory covers them. */
+  files: readonly string[]
+  /** Called once per settled change, with an absolute path. */
+  onChange: (file: string) => void
+}
+
+export interface Watcher {
+  close: () => void
+}
+
+export function watchProject(options: WatcherOptions): Watcher {
+  const watchers: FSWatcher[] = []
+  const pending = new Map<string, NodeJS.Timeout>()
+
+  const report = (file: string): void => {
+    const existing = pending.get(file)
+    if (existing !== undefined) clearTimeout(existing)
+    const timer = setTimeout(() => {
+      pending.delete(file)
+      options.onChange(file)
+    }, SETTLE_MS)
+    // The dev server must still be able to exit while a save is settling.
+    timer.unref?.()
+    pending.set(file, timer)
+  }
+
+  for (const directory of options.directories) {
+    const absolute = resolve(options.root, directory)
+    try {
+      watchers.push(
+        watch(absolute, { recursive: true }, (_event, name) => {
+          if (typeof name !== 'string' || name === '') return
+          report(join(absolute, name))
+        }),
+      )
+    } catch {
+      // A directory this project does not have is not an error: the list is
+      // the framework's conventional layout, not a requirement.
+    }
+  }
+
+  for (const file of options.files) {
+    const absolute = resolve(options.root, file)
+    try {
+      watchers.push(watch(absolute, () => report(absolute)))
+    } catch {
+      // Same: a `.env` that does not exist is simply not watched.
+    }
+  }
+
+  return {
+    close: () => {
+      for (const timer of pending.values()) clearTimeout(timer)
+      pending.clear()
+      for (const watcher of watchers) watcher.close()
+    },
+  }
+}

package/src/env/loadEnvFiles.ts

@@ -1,41 +1,82 @@
 import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import { parseEnv } from 'node:util'
 import { interpolate } from './interpolate.js'
 import { normalizeNodeEnv } from './nodeEnv.js'
 
 /**
- * Load `.env` files into `process.env` — the shared primitive behind both the
- * Ignitor (HTTP/console boot) and `Env.create()` (config/test flow), mirroring
- * AdonisJS which loads env in every flow.
+ * The `.env*` files that will be read, most-specific first.
  *
- * Order is most-specific-first and "already-present wins", so the shell / CI
- * always overrides the files. Missing files are skipped silently. Uses Node's
- * built-in parser — no dependency.
+ * Exported because `@c9up/ream/hot` has to WATCH exactly this list: nothing
+ * imports an env file, so hot-hook's dependency tree never sees one and an
+ * edit to `.env` changed nothing at all. A second copy of the list in the
+ * loader entry would drift from this one the first time the naming changes.
  *
- * @param appRoot Directory URL the `.env*` files are resolved against.
- * @param options.skipEnvLocal Skip `.env.local` (the test flow does, so a
- *   developer's local overrides don't leak into tests).
+ * @param options.skipEnvLocal Skip `.env.local` — see {@link loadEnvFiles}.
  */
-export function loadEnvFiles(appRoot: URL, options: { skipEnvLocal?: boolean } = {}): void {
+export function envFileNames(options: { skipEnvLocal?: boolean } = {}): string[] {
   // Normalised, so `NODE_ENV=prod` loads `.env.production` — the file the
   // deployment actually wrote — instead of looking for `.env.prod`.
   const raw = normalizeNodeEnv(process.env.NODE_ENV)
   const nodeEnv = raw === 'unknown' ? undefined : raw
-  const files = [
+  return [
     nodeEnv ? `.env.${nodeEnv}.local` : null,
     options.skipEnvLocal ? null : '.env.local',
     nodeEnv ? `.env.${nodeEnv}` : null,
     '.env',
   ].filter((name): name is string => name !== null)
+}
+
+/**
+ * Where the `.env*` files are read from.
+ *
+ * Normally beside the application, which is what `appRoot` names. A BUILT
+ * application moves: `start/env.js` sits in `dist/`, so `new URL('../',
+ * import.meta.url)` resolves there and the files at the project root become
+ * invisible — `ream start` died on a `.env` it was standing next to.
+ *
+ * `ENV_PATH` is AdonisJS's own variable for this, named and shaped the same
+ * way: a DIRECTORY to read the files from, as in
+ * `ENV_PATH=/etc/secrets node server.js`. An application moving over keeps
+ * whatever it already sets.
+ *
+ * It is also why the ordering rule stays here rather than in the CLI: node's
+ * `--env-file` applies files last-wins while this loader applies them
+ * most-specific-first, and a second copy of that would be one to keep in step
+ * forever.
+ */
+function envDirectory(appRoot: URL): URL {
+  const override = process.env.ENV_PATH
+  if (override === undefined || override.trim() === '') return appRoot
+  // A directory URL, so `new URL('.env', directory)` lands inside it rather
+  // than beside it.
+  return pathToFileURL(override.endsWith('/') ? override : `${override}/`)
+}
 
-  for (const name of files) {
+/**
+ * Load `.env` files into `process.env` — the shared primitive behind both the
+ * Ignitor (HTTP/console boot) and `Env.create()` (config/test flow), mirroring
+ * AdonisJS which loads env in every flow.
+ *
+ * Order is most-specific-first and "already-present wins", so the shell / CI
+ * always overrides the files. Missing files are skipped silently. Uses Node's
+ * built-in parser — no dependency.
+ *
+ * @param appRoot Directory URL the `.env*` files are resolved against.
+ * @param options.skipEnvLocal Skip `.env.local` (the test flow does, so a
+ *   developer's local overrides don't leak into tests).
+ */
+export function loadEnvFiles(appRoot: URL, options: { skipEnvLocal?: boolean } = {}): void {
+  const directory = envDirectory(appRoot)
+  let found = false
+  for (const name of envFileNames(options)) {
     let contents: string
     try {
-      contents = readFileSync(fileURLToPath(new URL(name, appRoot)), 'utf8')
+      contents = readFileSync(fileURLToPath(new URL(name, directory)), 'utf8')
     } catch {
       continue // file absent — nothing to load
     }
+    found = true
     const parsed = parseEnv(contents)
     for (const [key, value] of Object.entries(parsed)) {
       if (typeof value !== 'string' || process.env[key] !== undefined) continue
@@ -49,4 +90,18 @@ export function loadEnvFiles(appRoot: URL, options: { skipEnvLocal?: boolean } =
       })
     }
   }
+
+  // Upstream raises when `ENV_PATH` names a place with no env file in it, and
+  // for the reason silence would be wrong: the variable is somebody saying
+  // where the file IS. A typo in the path would otherwise start a server on
+  // whatever defaults happened to be around, which is how a deployment reads
+  // its staging config in production and nobody finds out until later.
+  //
+  // Without `ENV_PATH` a missing file stays silent: an application may have
+  // none at all, and every value may come from the environment.
+  if (!found && process.env.ENV_PATH !== undefined && process.env.ENV_PATH.trim() !== '') {
+    throw new Error(
+      `ENV_PATH points at ${process.env.ENV_PATH}, which holds none of ${envFileNames(options).join(', ')}`,
+    )
+  }
 }