@c9up/ream 0.2.25 → 0.2.26

package/src/console/make/generators.ts

@@ -0,0 +1,176 @@
+/**
+ * What each `make:` command generates.
+ *
+ * One table rather than ten near-identical commands: every generator is a
+ * name, a stub and the variables that stub reads. The differences that matter
+ * — which suffix a class carries, whether the name is snake_cased for the file
+ * — live here, in one place, instead of being spread across ten files that
+ * drift.
+ *
+ * The DESTINATION is not here. It is in the stub's own front matter, so an
+ * application that publishes `stubs/make/controller.stub` can move the file as
+ * well as change its contents.
+ */
+
+import type { StubState } from '../../stubs/template.js'
+import { ensureSuffix, stripSuffixInsensitive, toPascalCase, toSnakeCase } from './naming.js'
+
+/** Extra input a generator takes beyond the name. */
+export interface GeneratorInput {
+  /** `app/<module>/…` — where a module-scoped file lands. */
+  module?: string
+  /** `make:middleware --stack server|router|named`. */
+  stack?: string
+  /** `make:listener --event OrderShipped`. */
+  event?: string
+}
+
+export interface Generator {
+  /** The stub, under `stubs/make/`. */
+  kind: string
+  commandName: string
+  description: string
+  /** Does it take `--module`? */
+  moduleScoped: boolean
+  /** The variables its stub reads. */
+  state(name: string, input: GeneratorInput): StubState
+}
+
+/** The shared trio every stub may read. */
+function base(name: string, className: string, module: string): StubState {
+  return { className, module, name }
+}
+
+export const GENERATORS: readonly Generator[] = [
+  {
+    kind: 'controller',
+    commandName: 'make:controller',
+    description: 'Generate an HTTP controller',
+    moduleScoped: true,
+    state: (name, input) =>
+      base(name, ensureSuffix(name, 'Controller'), input.module ?? 'controllers'),
+  },
+  {
+    kind: 'service',
+    commandName: 'make:service',
+    description: 'Generate a service class',
+    moduleScoped: true,
+    state: (name, input) => base(name, ensureSuffix(name, 'Service'), input.module ?? 'services'),
+  },
+  {
+    kind: 'entity',
+    commandName: 'make:entity',
+    description: 'Generate an Atlas entity',
+    moduleScoped: true,
+    state: (name, input) => ({
+      // No suffix: an entity is `User`, not `UserEntity`.
+      ...base(name, toPascalCase(name), input.module ?? 'entities'),
+      tableName: `${toSnakeCase(name)}s`,
+    }),
+  },
+  {
+    kind: 'validator',
+    commandName: 'make:validator',
+    description: 'Generate a Rune validator',
+    moduleScoped: true,
+    state: (name, input) =>
+      base(name, ensureSuffix(name, 'Validator'), input.module ?? 'validators'),
+  },
+  {
+    kind: 'provider',
+    commandName: 'make:provider',
+    description: 'Generate a service provider',
+    moduleScoped: false,
+    state: (name) => base(name, ensureSuffix(name, 'Provider'), ''),
+  },
+  {
+    kind: 'command',
+    commandName: 'make:command',
+    description: 'Generate a console command',
+    moduleScoped: false,
+    state: (name) => {
+      // `app:provision` is the command NAME; the class and the file come from
+      // its last segment, or the published stub would generate a command
+      // unreachable under the name it was asked for.
+      const segments = name.split(':')
+      const last = segments[segments.length - 1] ?? name
+      return {
+        className: toPascalCase(toSnakeCase(last)),
+        fileName: toSnakeCase(last),
+        name,
+      }
+    },
+  },
+  {
+    kind: 'middleware',
+    commandName: 'make:middleware',
+    description: 'Generate an HTTP middleware',
+    moduleScoped: false,
+    state: (name, input) => {
+      const fileName = toSnakeCase(stripSuffixInsensitive(name, 'middleware'))
+      const stack = input.stack ?? 'router'
+      const importer = `() => import('#middleware/${fileName}_middleware.js')`
+      // The line the user pastes into their kernel — different per stack, and
+      // wrong in a way that is hard to spot if it is guessed.
+      const registration =
+        stack === 'server'
+          ? `server.use([${importer}])`
+          : stack === 'named'
+            ? `router.named({ ${fileName}: ${importer} })`
+            : `router.use([${importer}])`
+      return {
+        className: `${toPascalCase(fileName)}Middleware`,
+        fileName,
+        name,
+        registration,
+        stack,
+      }
+    },
+  },
+  {
+    kind: 'event',
+    commandName: 'make:event',
+    description: 'Generate an event class',
+    moduleScoped: false,
+    state: (name) => {
+      const fileName = toSnakeCase(name)
+      return { className: toPascalCase(fileName), fileName, name }
+    },
+  },
+  {
+    kind: 'listener',
+    commandName: 'make:listener',
+    description: 'Generate an event listener',
+    moduleScoped: false,
+    state: (name, input) => {
+      const fileName = toSnakeCase(name)
+      const className = toPascalCase(fileName)
+      if (input.event === undefined) {
+        // Without `--event` there is nothing to type the handler with, and
+        // inventing an import would point at a file that does not exist.
+        return {
+          className,
+          fileName,
+          name,
+          importLine: '',
+          eventType: 'unknown',
+          registration: `emitter.on(SomeEvent, ${className})`,
+        }
+      }
+      const eventFile = toSnakeCase(input.event)
+      const eventClass = toPascalCase(eventFile)
+      return {
+        className,
+        fileName,
+        name,
+        importLine: `import type ${eventClass} from '#app/events/${eventFile}.js'\n\n`,
+        eventType: eventClass,
+        registration: `emitter.on(${eventClass}, ${className})`,
+      }
+    },
+  },
+]
+
+export function generatorFor(kind: string): Generator | undefined {
+  return GENERATORS.find((generator) => generator.kind === kind)
+}

package/src/console/make/naming.ts

@@ -0,0 +1,85 @@
+/**
+ * The naming conventions the generators follow.
+ *
+ * Ported from the Rust generator they replace, case for case: a rename here
+ * changes what `make:controller user` produces, so the rules are written out
+ * rather than approximated.
+ */
+
+/** Add the suffix unless the name already carries it. */
+export function ensureSuffix(name: string, suffix: string): string {
+  return name.endsWith(suffix) ? name : `${name}${suffix}`
+}
+
+/** `user_profile` / `user-profile` / `user profile` → `UserProfile`. */
+export function toPascalCase(name: string): string {
+  return name
+    .split(/[_\-\s]/)
+    .filter((part) => part !== '')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+/**
+ * `UserProfile` → `user_profile`, `HTTPServer` → `http_server`.
+ *
+ * The acronym case is why this is not a one-line regex: an underscore goes
+ * before a capital that FOLLOWS a lowercase, or that follows a capital and is
+ * followed by a lowercase — which is where `HTTPServer` splits.
+ */
+export function toSnakeCase(name: string): string {
+  const chars = [...name]
+  let out = ''
+  for (const [index, char] of chars.entries()) {
+    if (char.toUpperCase() === char && char.toLowerCase() !== char) {
+      const previous = chars[index - 1]
+      const next = chars[index + 1]
+      const previousLower =
+        previous !== undefined &&
+        previous === previous.toLowerCase() &&
+        previous !== previous.toUpperCase()
+      const nextLower =
+        next !== undefined && next === next.toLowerCase() && next !== next.toUpperCase()
+      const previousUpper =
+        previous !== undefined &&
+        previous === previous.toUpperCase() &&
+        previous !== previous.toLowerCase()
+      if (index > 0 && (previousLower || (nextLower && previousUpper))) out += '_'
+      out += char.toLowerCase()
+      continue
+    }
+    out += char
+  }
+  return out
+}
+
+/** Drop a trailing `Middleware` / `middleware` / `_middleware`, whatever the case. */
+export function stripSuffixInsensitive(name: string, suffix: string): string {
+  const lower = name.toLowerCase()
+  const suffixLower = suffix.toLowerCase()
+  if (lower.length > suffixLower.length && lower.endsWith(suffixLower)) {
+    return name.slice(0, name.length - suffix.length).replace(/[_-]+$/, '')
+  }
+  return name
+}
+
+/** Longer than this is not a name, it is a paste accident. */
+export const MAX_NAME_LENGTH = 128
+
+/**
+ * Is this a name a generator may build a path from?
+ *
+ * Refused rather than sanitised: a name with a separator in it is either a
+ * mistake or an attempt to write outside the project, and quietly rewriting it
+ * would produce a file somewhere the user did not ask for.
+ */
+export function nameProblem(name: string): string | undefined {
+  if (name.trim() === '') return 'the name is empty'
+  if (name.length > MAX_NAME_LENGTH) return `the name is longer than ${MAX_NAME_LENGTH} characters`
+  if (/[/\\]/.test(name)) return 'a name may not contain a path separator'
+  if (name.includes('..')) return 'a name may not contain ".."'
+  if (!/^[A-Za-z][A-Za-z0-9_\-:]*$/.test(name)) {
+    return 'a name starts with a letter and holds letters, digits, "_", "-" or ":"'
+  }
+  return undefined
+}

package/src/console/make/resolve.ts

@@ -0,0 +1,134 @@
+/**
+ * Finding a stub, rendering it, and knowing where it goes.
+ *
+ * A stub is addressed the way `codemods.makeUsingStub` addresses one — a
+ * package's `stubsRoot` plus a path inside it, `make/controller.stub` — so a
+ * generator and a package's `configure()` hook read the same file through the
+ * same rule. The application's own copy under `stubs/` wins over the shipped
+ * one, which is what `ream eject` is for.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { render, type StubState } from '../../stubs/template.js'
+
+/** Where an application keeps its own copies — Adonis' `stubs/` root. */
+export const PUBLISHED_ROOT = 'stubs'
+
+/** The stubs this package ships. */
+export const REAM_STUBS_ROOT = path.join(import.meta.dirname, '..', '..', '..', 'stubs')
+
+export interface RenderedStub {
+  /** Relative to the project root, as the stub's front matter declares it. */
+  path: string
+  contents: string
+  /** Did the application's own copy win? */
+  published: boolean
+}
+
+/**
+ * A stub path that could escape its root never reaches the filesystem.
+ *
+ * `eject` takes one from the command line, so this is the boundary: no
+ * absolute path, no `..`, and a `.stub` file at the end of it.
+ */
+export function isSafeStubPath(stubPath: string): boolean {
+  if (stubPath === '' || stubPath.length > 256) return false
+  if (path.isAbsolute(stubPath)) return false
+  const segments = stubPath.split(/[/\\]/)
+  if (segments.includes('..') || segments.includes('')) return false
+  return segments.every((segment) => /^[\w.-]+$/.test(segment))
+}
+
+/** Where the application's copy of `stubPath` would live. */
+export function publishedPath(stubPath: string, cwd: string): string | undefined {
+  if (!isSafeStubPath(stubPath)) return undefined
+  return path.join(cwd, PUBLISHED_ROOT, stubPath)
+}
+
+/** Read `stubPath` — the application's copy when there is one. */
+export function readStub(
+  stubsRoot: string,
+  stubPath: string,
+  cwd: string,
+): { source: string; published: boolean } {
+  const published = publishedPath(stubPath, cwd)
+  if (published !== undefined && fs.existsSync(published)) {
+    return { source: fs.readFileSync(published, 'utf8'), published: true }
+  }
+  if (!isSafeStubPath(stubPath)) {
+    throw new Error(`[make] unusable stub path: ${stubPath}`)
+  }
+  const shipped = path.join(stubsRoot, stubPath)
+  if (!fs.existsSync(shipped)) {
+    throw new Error(`[make] no stub at "${stubPath}" (looked in ${stubsRoot})`)
+  }
+  return { source: fs.readFileSync(shipped, 'utf8'), published: false }
+}
+
+/** Split `---\nto: …\n---\n<body>`; the front matter names the destination. */
+export function splitFrontMatter(template: string): { to?: string; body: string } {
+  const trimmed = template.replace(/^[\r\n]+/, '')
+  if (!trimmed.startsWith('---')) return { body: template }
+  const after = trimmed.slice(3).replace(/^\r?\n/, '')
+  const end = after.indexOf('\n---')
+  if (end === -1) {
+    throw new Error('[make] a stub opened its front matter with `---` and never closed it')
+  }
+  const block = after.slice(0, end)
+  const body = after.slice(end + 4).replace(/^\r?\n/, '')
+  let to: string | undefined
+  for (const rawLine of block.split('\n')) {
+    const line = rawLine.trim()
+    if (line === '' || line.startsWith('#')) continue
+    const at = line.indexOf(':')
+    if (at === -1) throw new Error(`[make] unreadable stub front-matter line: \`${line}\``)
+    if (line.slice(0, at).trim() === 'to') to = line.slice(at + 1).trim()
+  }
+  return to === undefined ? { body } : { to, body }
+}
+
+/**
+ * The destination a stub declares, checked.
+ *
+ * Absolute paths and `..` are refused rather than normalised: a published stub
+ * is a file in the project, and a generator is not a way to write outside it.
+ */
+function assertInsideProject(destination: string): void {
+  if (destination === '') throw new Error('[make] the stub declares an empty destination')
+  if (path.isAbsolute(destination)) {
+    throw new Error(`[make] a stub may not write to an absolute path: ${destination}`)
+  }
+  if (destination.split(/[/\\]/).includes('..')) {
+    throw new Error(`[make] a stub may not write outside the project: ${destination}`)
+  }
+}
+
+export function renderStub(
+  stubsRoot: string,
+  stubPath: string,
+  state: StubState,
+  cwd: string,
+  fallbackPath?: string,
+): RenderedStub {
+  const { source, published } = readStub(stubsRoot, stubPath, cwd)
+  const { to, body } = splitFrontMatter(source)
+  const destination = to === undefined ? fallbackPath : render(to, state)
+  if (destination === undefined) {
+    throw new Error(
+      `[make] the stub at "${stubPath}" declares no destination — add a \`to:\` front-matter line.`,
+    )
+  }
+  assertInsideProject(destination)
+  return { path: destination, contents: render(body, state), published }
+}
+
+/** `make/controller.stub` — the stub a generator of that kind reads. */
+export function stubPathFor(kind: string): string {
+  return `make/${kind}.stub`
+}
+
+/** Render one of this package's own generator stubs. */
+export function renderStubFor(kind: string, state: StubState, cwd: string): RenderedStub {
+  return renderStub(REAM_STUBS_ROOT, stubPathFor(kind), state, cwd)
+}

package/src/console/ui.ts

@@ -1,37 +1,25 @@
 /**
- * Console UI — `this.logger` and `this.prompt` on every command (Console parity).
+ * The one colour helper the Kernel's help and the prompts use.
  *
- * Kept dependency-free: the framework ships no colour or prompt library, and
- * pulling one in for the CLI surface alone is not worth the install weight.
+ * It is a thin call into `@c9up/lumen` rather than a second palette: two
+ * tables of escape codes in one package is how `[ warn ]` ends up yellow in
+ * one command and plain in another.
+ *
+ * The environment is read on EVERY call, not cached, because a command can be
+ * run in-process with the environment changed around it — which is exactly
+ * what the tests covering `FORCE_COLOR` do.
  */
 
 import { stdout } from 'node:process'
+import { ansiColors, type Colors, silentColors, supportsColor } from '@c9up/lumen'
 
-/** Colour is opt-out via NO_COLOR and skipped when piped to a file. */
-function supportsColour(stream: NodeJS.WriteStream): boolean {
-  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') return false
-  if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== '') return true
-  return Boolean(stream.isTTY)
-}
-
-const CODES = {
-  reset: '\u001B[0m',
-  dim: '\u001B[2m',
-  red: '\u001B[31m',
-  green: '\u001B[32m',
-  yellow: '\u001B[33m',
-  blue: '\u001B[34m',
-  magenta: '\u001B[35m',
-  cyan: '\u001B[36m',
-} as const
-
-export type Colour = keyof Omit<typeof CODES, 'reset'>
+export type Colour = 'dim' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan'
 
 export function colourise(
   text: string,
   colour: Colour,
   stream: NodeJS.WriteStream = stdout,
 ): string {
-  if (!supportsColour(stream)) return text
-  return `${CODES[colour]}${text}${CODES.reset}`
+  const colors: Colors = supportsColor(stream) ? ansiColors() : silentColors()
+  return colors[colour](text)
 }

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.25'
+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')