@c9up/ream 0.2.24 → 0.2.26

package/src/hot.ts

@@ -27,7 +27,7 @@ import { existsSync, writeSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { registerHooks } from 'node:module'
 import { dirname, relative, resolve as resolvePath } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import { fullReloadNotice } from './dev/fullReload.js'
 import { hotReloadHappened } from './dev/hmr.js'
 import { readHotHookConfig } from './dev/hotConfig.js'
@@ -66,9 +66,60 @@ const restartFiles = new Set(
     .filter((file) => existsSync(file)),
 )
 
+/**
+ * `metaFiles` entries that asked for a restart.
+ *
+ * Non-module files the application owns — translations, view templates — live
+ * in `reamrc.ts` because the BUILD has to copy them. A change to one is
+ * invisible to the import graph, so the only way it can do anything in
+ * development is by being named here.
+ *
+ * `reloadServer: false` is the interesting default, and the one upstream picks
+ * for translations: the entry exists so the file ships, and an edit does NOT
+ * restart. NAMED DEVIATION — upstream still logs such a change, because its
+ * watcher covers the whole project anyway. This one watches a fixed list of
+ * directories on purpose (`resources/` belongs to the asset watcher, and a
+ * stylesheet edit must not restart the server), so a `false` entry is simply
+ * not watched. The observable behaviour is the same: nothing happens.
+ */
+async function readReloadPatterns(): Promise<string[]> {
+  try {
+    const rc = (await import(pathToFileURL(resolvePath(root, 'reamrc.ts')).href)) as {
+      default?: { metaFiles?: Array<{ pattern?: unknown; reloadServer?: unknown }> }
+    }
+    return (rc.default?.metaFiles ?? [])
+      .filter((entry) => entry.reloadServer === true && typeof entry.pattern === 'string')
+      .map((entry) => String(entry.pattern))
+  } catch {
+    // No rc file, or one that does not load. The server itself reports a broken
+    // rc far more clearly than the loader could, and a dev server that refuses
+    // to start because of a watch list helps nobody.
+    return []
+  }
+}
+
+const reloadPatterns = await readReloadPatterns()
+
+/**
+ * The directory a pattern lives under — everything before its first wildcard.
+ *
+ * `resources/lang/**\/*.json` is watched as `resources/lang`. Watching the
+ * project root instead would pull in `node_modules` and the build output.
+ */
+function watchRootOf(pattern: string): string {
+  const segments = pattern.replace(/^\.\//, '').split('/')
+  const fixed: string[] = []
+  for (const segment of segments) {
+    if (/[*?{[]/.test(segment)) break
+    fixed.push(segment)
+  }
+  // A pattern that is a bare glob has no directory to narrow to.
+  return fixed.slice(0, -1).join('/') || fixed.join('/')
+}
+
 const relativeToRoot = (file: string): string => relative(root, file).replace(/\\/g, '/')
 const matchesBoundary = globMatcher(boundaries)
-const matchesRestartGlob = globMatcher(restart)
+const matchesRestartGlob = globMatcher([...restart, ...reloadPatterns])
 
 const graph = new HotGraph({
   isBoundary: (file) => matchesBoundary(relativeToRoot(file)),
@@ -126,7 +177,12 @@ function sayNow(line: string): void {
 
 watchProject({
   root,
-  directories: WATCH_DIRS,
+  directories: [
+    ...WATCH_DIRS,
+    // Whatever a `reloadServer: true` entry named, and nothing else: the
+    // directories above are the ones the graph can reason about.
+    ...reloadPatterns.map(watchRootOf).filter((dir) => dir !== ''),
+  ],
   files: [...restartFiles].map((file) => relative(root, file)),
   onChange: (file) => {
     const decision = graph.decide(file)

package/src/index.ts

@@ -272,8 +272,22 @@ export type {
 
 // ─── Codemods ───────────────────────────────────────────────
 
-export type { Codemods } from './Codemods.js'
-export { createCodemods } from './Codemods.js'
+export {
+  type Codemods,
+  createCodemods,
+  type GeneratedStub,
+  type StubState,
+} from './Codemods.js'
+export {
+  compile as compileStub,
+  escapeHtml,
+  generate as generateStub,
+  render as renderStub,
+  type StubBlock,
+  StubSyntaxError,
+  type StubValue,
+  type TemplateOptions,
+} from './stubs/template.js'
 
 // ─── Errors ─────────────────────────────────────────────────
 
@@ -385,4 +399,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.24'
+export const VERSION = '0.2.26'

package/src/stubs/index.ts

@@ -0,0 +1,14 @@
+/**
+ * `@c9up/ream/stubs` — the stub engine, and where this package keeps its own.
+ *
+ * Every Ream package exports a `stubsRoot` from this subpath: it is what
+ * `codemods.makeUsingStub(stubsRoot, 'make/controller.stub')` takes, and what
+ * `ream eject --pkg` reads to copy a template into the application.
+ */
+
+import * as path from 'node:path'
+
+export * from './template.js'
+
+/** `<package>/stubs` — resolved from this file, so it survives the build. */
+export const stubsRoot = path.join(import.meta.dirname, '..', '..', 'stubs')

package/src/stubs/template.ts

@@ -0,0 +1,262 @@
+/**
+ * The stub template engine.
+ *
+ * A port of the one upstream uses (tempura), grammar for grammar: comments,
+ * declared props, inline variables, conditionals, loops, custom blocks, and
+ * the two interpolation forms. A template is compiled into a JavaScript
+ * function once and then called — the same design, for the same reason: a
+ * tree-walking interpreter re-reads the template on every render, and a stub
+ * is rendered in a loop by the generators.
+ *
+ *     {{! a comment }}
+ *     {{#expect name, entity }}
+ *     {{#var plural = name + 's' }}
+ *     {{#if entity.isModel }}…{{#elif entity.isView }}…{{#else}}…{{/if}}
+ *     {{#each items as item, index }}…{{/each}}
+ *     {{ name }}      the value
+ *     {{{ name }}}    the value, unescaped
+ *
+ * NAMED DEVIATION — upstream escapes HTML in `{{ }}` and leaves `{{{ }}}`
+ * raw, because its templates are web pages. Ours are SOURCE FILES: escaping
+ * `"` into `"` there produces code that does not parse, and the mistake
+ * is silent. So `{{ }}` does not escape by default, `{{{ }}}` is accepted as
+ * the same thing (a stub written for upstream keeps working), and an `escape`
+ * option turns it back on for anyone templating markup.
+ *
+ * `new Function` compiles the result. That is how upstream does it too, and
+ * the trust boundary is the same: a stub ships inside a package whose
+ * `configure` hook is already executing.
+ */
+
+/** What a template may read. Scalars, lists and nested records. */
+export type StubValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | StubValue[]
+  | { [key: string]: StubValue }
+
+export type StubState = Record<string, StubValue>
+
+/** A custom block — `{{#myBlock key=value }}` calls it with those arguments. */
+export type StubBlock = (args: Record<string, StubValue>) => string
+
+export interface TemplateOptions {
+  /** Names the template may read even when the state does not carry them. */
+  props?: string[]
+  /** Custom `{{#name}}` blocks. */
+  blocks?: Record<string, StubBlock>
+  /** Applied to every `{{ }}`. Identity by default — see the header. */
+  escape?: (value: unknown) => string
+}
+
+/** Raised when a template cannot be read, naming what is wrong with it. */
+export class StubSyntaxError extends Error {
+  readonly code = 'E_REAM_STUB_SYNTAX'
+  constructor(message: string) {
+    super(message)
+    this.name = 'StubSyntaxError'
+  }
+}
+
+/** HTML escaping, for a stub that does template markup. */
+export function escapeHtml(value: unknown): string {
+  const text = value === null || value === undefined ? '' : String(value)
+  return text.replace(/[&"<>]/g, (char) => {
+    if (char === '&') return '&amp;'
+    if (char === '"') return '&quot;'
+    if (char === '<') return '&lt;'
+    return '&gt;'
+  })
+}
+
+/** The default: a source file wants its quotes and its angle brackets back. */
+function asIs(value: unknown): string {
+  return value === null || value === undefined ? '' : String(value)
+}
+
+const CURLY = /{{{?\s*([\s\S]*?)\s*}}}?/g
+const BLOCK = /^#\s*(\w[\w\d]*)\s*([\s\S]*)/
+const ARGS = /([a-zA-Z$_][^\s=]*)\s*=\s*((["`'])(?:(?=(\\?))\4.)*?\3|{[^}]*}|\[[^\]]*]|\S+)/g
+
+/**
+ * Compile a template into the body of a function.
+ *
+ * Kept separate from `compile` so a test can read what a template became —
+ * the generated source is the only place a subtle mistake shows itself.
+ */
+export function generate(input: string, options: TemplateOptions = {}): string {
+  const blocks = options.blocks ?? {}
+  const declared = new Set<string>(options.props ?? [])
+  const stack: string[] = []
+
+  let body = ''
+  let literal = ''
+  let last = 0
+  CURLY.lastIndex = 0
+
+  /** Flush the literal text collected since the last tag. */
+  const flush = (): void => {
+    if (literal.length > 0) {
+      body += `${body ? 'x+=' : '='}\`${literal}\`;`
+    } else if (body.length === 0) {
+      body = '="";'
+    }
+    literal = ''
+  }
+
+  let match: RegExpExecArray | null = CURLY.exec(input)
+  while (match !== null) {
+    literal += escapeForTemplate(input.slice(last, match.index))
+    last = match.index + match[0].length
+
+    const inner = (match[1] ?? '').trim()
+    const first = inner.charAt(0)
+
+    if (first === '!') {
+      // A comment. It leaves no trace in the output.
+    } else if (first === '#') {
+      flush()
+      const parsed = BLOCK.exec(inner)
+      if (parsed === null) {
+        throw new StubSyntaxError(`Unreadable block: {{${inner}}}`)
+      }
+      const action = parsed[1] ?? ''
+      const rest = (parsed[2] ?? '').trim()
+      body += openBlock(action, rest, stack, declared, blocks)
+    } else if (first === '/') {
+      const closing = inner.slice(1).trim()
+      const opened = stack.pop()
+      flush()
+      if (opened === undefined) {
+        throw new StubSyntaxError(`Closed "${closing}" with nothing open.`)
+      }
+      if (opened !== closing) {
+        throw new StubSyntaxError(`Expected to close "${opened}"; closed "${closing}" instead.`)
+      }
+      body += '}'
+    } else {
+      // Both forms interpolate the same way — see the header.
+      literal += `\${$$e(${inner})}`
+    }
+
+    match = CURLY.exec(input)
+  }
+
+  if (stack.length > 0) {
+    throw new StubSyntaxError(`Unterminated "${stack.pop()}" block.`)
+  }
+  if (last < input.length) {
+    literal += escapeForTemplate(input.slice(last))
+  }
+  flush()
+
+  const bindings = declared.size > 0 ? `{${[...declared].join()}}=$$s,x` : ' x'
+  return `var${bindings}${body}return x`
+}
+
+function openBlock(
+  action: string,
+  rest: string,
+  stack: string[],
+  declared: Set<string>,
+  blocks: Record<string, StubBlock>,
+): string {
+  if (action === 'expect') {
+    // Names the template reads. Declaring them is what lets an unknown one
+    // fail as `x is not defined` rather than as `undefined` in the output.
+    for (const key of rest.split(/[\n\r\s\t]*,[\n\r\s\t]*/g)) {
+      if (key !== '') declared.add(key)
+    }
+    return ''
+  }
+
+  if (action === 'var') {
+    const at = rest.indexOf('=')
+    if (at === -1) {
+      throw new StubSyntaxError(`{{#var}} needs an assignment: {{#var ${rest}}}`)
+    }
+    const name = rest.slice(0, at).trim()
+    const value = rest
+      .slice(at + 1)
+      .trim()
+      .replace(/;$/, '')
+    return `var ${name}=${value};`
+  }
+
+  if (action === 'each') {
+    stack.push(action)
+    const at = rest.indexOf(' as ')
+    if (at === -1) {
+      return `for(var i=0,$$a=${rest};i<$$a.length;i++){`
+    }
+    const list = rest.slice(0, at).trim()
+    const [item = 'item', index = 'i'] = rest
+      .slice(at + 4)
+      .trim()
+      .replace(/[()\s]/g, '')
+      .split(',')
+    return `for(var ${index}=0,${item},$$a=${list};${index}<$$a.length;${index}++){${item}=$$a[${index}];`
+  }
+
+  if (action === 'if') {
+    stack.push(action)
+    return `if(${rest}){`
+  }
+  if (action === 'elif') return `}else if(${rest}){`
+  if (action === 'else') return '}else{'
+
+  if (action in blocks) {
+    // `{{#note tone="warn" }}` — the arguments become one object.
+    const args: string[] = []
+    let found: RegExpExecArray | null = ARGS.exec(rest)
+    while (found !== null) {
+      args.push(`${found[1]}:${found[2]}`)
+      found = ARGS.exec(rest)
+    }
+    ARGS.lastIndex = 0
+    return `x+=$$b.${action}(${args.length > 0 ? `{${args.join()}}` : '{}'});`
+  }
+
+  throw new StubSyntaxError(
+    `Unknown "${action}" block. Known: expect, var, if, elif, else, each${
+      Object.keys(blocks).length > 0 ? `, ${Object.keys(blocks).join(', ')}` : ''
+    }.`,
+  )
+}
+
+/** Protect the literal text from the template literal it is about to live in. */
+function escapeForTemplate(text: string): string {
+  return text.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${')
+}
+
+/** Compile a template into a render function. */
+export function compile(
+  input: string,
+  options: TemplateOptions = {},
+): (state: StubState) => string {
+  const source = generate(input, options)
+  let render: (escaper: (value: unknown) => string, blocks: unknown, state: StubState) => string
+  try {
+    // eslint-disable-next-line no-new-func -- the whole point of a compiler
+    render = new Function('$$e', '$$b', '$$s', source) as typeof render
+  } catch (error) {
+    throw new StubSyntaxError(
+      `This stub does not compile: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+  const escaper = options.escape ?? asIs
+  const blocks = options.blocks ?? {}
+  return (state: StubState) => render(escaper, blocks, state)
+}
+
+/** Compile and render in one go. */
+export function render(
+  input: string,
+  state: StubState = {},
+  options: TemplateOptions = {},
+): string {
+  return compile(input, { props: Object.keys(state), ...options })(state)
+}

package/stubs/make/command.stub

@@ -0,0 +1,29 @@
+---
+to: commands/{{ fileName }}.ts
+---
+import { BaseCommand, flags } from '@c9up/ream/console'
+import type { CommandOptions } from '@c9up/ream/console'
+
+export default class {{ className }} extends BaseCommand {
+  static commandName = '{{ name }}'
+  static description = 'TODO describe what this command does'
+
+  /**
+   * `startApp` boots providers and the container before `run()`. Off by
+   * default: a command that only touches the filesystem has no
+   * reason to open a database connection. Turn it on to reach `this.app`.
+   */
+  static options: CommandOptions = { startApp: false }
+
+  @flags.boolean({ description: 'Report what would happen without doing it' })
+  declare dryRun: boolean
+
+  async run(): Promise<void> {
+    if (this.dryRun) {
+      this.logger.info('Dry run — nothing was changed.')
+      return
+    }
+
+    this.logger.success('{{ name }} ran.')
+  }
+}

package/stubs/make/controller.stub

@@ -0,0 +1,30 @@
+---
+to: app/{{ module }}/{{ className }}.ts
+---
+import type { HttpContext } from '@c9up/ream'
+
+export class {{ className }} {
+  async index({ response }: HttpContext) {
+    response.status(200).json([])
+  }
+
+  async show({ params, response }: HttpContext) {
+    const { id } = params
+    response.status(200).json({ id })
+  }
+
+  async store({ request, response }: HttpContext) {
+    const data = request.body()
+    response.status(201).json({ created: true })
+  }
+
+  async update({ params, response }: HttpContext) {
+    const { id } = params
+    response.status(200).json({ id, updated: true })
+  }
+
+  async destroy({ params, response }: HttpContext) {
+    const { id } = params
+    response.status(204).send('')
+  }
+}

package/stubs/make/entity.stub

@@ -0,0 +1,11 @@
+---
+to: app/{{ module }}/{{ name }}.ts
+---
+import { Entity, Column, PrimaryKey, BaseEntity } from '@c9up/atlas'
+
+@Entity('{{ tableName }}')
+export class {{ className }} extends BaseEntity {
+  @PrimaryKey() id!: string
+  @Column() createdAt!: string
+  @Column() updatedAt!: string
+}

package/stubs/make/event.stub

@@ -0,0 +1,13 @@
+---
+to: app/events/{{ fileName }}.ts
+---
+import { BaseEvent } from '@c9up/ream/events'
+
+export default class {{ className }} extends BaseEvent {
+  /** Name listeners subscribe to. Defaults to the class name when omitted. */
+  static eventName = '{{ fileName }}'
+
+  constructor(public payload: Record<string, unknown>) {
+    super()
+  }
+}

package/stubs/make/listener.stub

@@ -0,0 +1,13 @@
+---
+to: app/listeners/{{ fileName }}.ts
+---
+{{ importLine }}/**
+ * Register it with the emitter:
+ *   {{ registration }}
+ */
+export default class {{ className }} {
+  async handle(event: {{ eventType }}): Promise<void> {
+    // React to the event.
+    void event
+  }
+}

package/stubs/make/middleware.stub

@@ -0,0 +1,16 @@
+---
+to: app/middleware/{{ fileName }}_middleware.ts
+---
+import type { HttpContext } from '@c9up/ream'
+
+/**
+ * Register it in `start/kernel.ts`:
+ *   {{ registration }}
+ */
+export default class {{ className }} {
+  async handle(ctx: HttpContext, next: () => Promise<void>) {
+    // Runs before the route handler.
+    await next()
+    // Runs after it — the response is available here.
+  }
+}

package/stubs/make/provider.stub

@@ -0,0 +1,26 @@
+---
+to: providers/{{ className }}.ts
+---
+import { Provider } from '@c9up/ream'
+
+export default class {{ className }} extends Provider {
+  register() {
+    // Register bindings in the container
+  }
+
+  async boot() {
+    // Connect and verify
+  }
+
+  async start() {
+    // Runs before HTTP server starts
+  }
+
+  async ready() {
+    // Application operational
+  }
+
+  async shutdown() {
+    // Cleanup
+  }
+}

package/stubs/make/service.stub

@@ -0,0 +1,27 @@
+---
+to: app/{{ module }}/{{ className }}.ts
+---
+import { Service } from '@c9up/ream'
+
+@Service()
+export class {{ className }} {
+  async findAll() {
+    return []
+  }
+
+  async findById(id: string) {
+    return null
+  }
+
+  async create(data: Record<string, unknown>) {
+    return data
+  }
+
+  async update(id: string, data: Record<string, unknown>) {
+    return { id, ...data }
+  }
+
+  async delete(id: string) {
+    return { id }
+  }
+}

package/stubs/make/validator.stub

@@ -0,0 +1,10 @@
+---
+to: app/{{ module }}/{{ className }}.ts
+---
+import { rules, schema } from '@c9up/rune'
+
+export const {{ className }} = schema({
+  // Define validation rules
+  // name: rules.string().min(1).max(255),
+  // email: rules.string().email(),
+})