mega-framework 0.1.0

package/src/cli/generators/index.js

@@ -0,0 +1,368 @@
+// @ts-check
+/**
+ * 코드 generator 13종 — `mega g <kind> <name>` 의 본체 (ADR-012/142).
+ *
+ * 각 generator 는 **코드 + 테스트를 동시에 생성**한다(ADR-012). 멀티앱 인지(`--app`, 기본 'main',
+ * ADR-012)이며, `templates/<kind>/*.tpl`(ADR-142)을 토큰 치환해 파일로 쓴다. 테스트는 `test/` 아래에
+ * 소스 경로를 미러링한 위치에 두고(예 `apps/main/controllers/x-controller.js` →
+ * `test/apps/main/controllers/x-controller.test.js`, ADR-069 예시 정합), 테스트→소스 import 는 상대경로로
+ * 자동 계산한다.
+ *
+ * **덮어쓰기 금지** — 이미 존재하는 파일은 건너뛰며(`--force` 로만 덮어씀), 결과를 호출자에게 보고한다
+ * (silent 덮어쓰기 방지, P4/P7).
+ *
+ * @module cli/generators
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { nameVariants, renderTemplate } from '../template-engine.js'
+
+/** templates/ 루트(패키지 동봉). src/cli/generators/index.js 기준 3단계 위. */
+const TEMPLATES_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../../templates')
+
+/** 지원 generator 종류(roadmap §337 — 13종). */
+export const GENERATOR_KINDS = /** @type {const} */ ([
+  'app',
+  'controller',
+  'channel',
+  'service',
+  'model',
+  'middleware',
+  'route',
+  'schedule',
+  'job',
+  'worker',
+  'locale',
+  'adapter',
+  'migration',
+])
+
+/** adapter `--kind` → 베이스 클래스(mega-framework export 명). */
+const ADAPTER_BASES = /** @type {Record<string, string>} */ ({
+  db: 'MegaDbAdapter',
+  cache: 'MegaCacheAdapter',
+  bus: 'MegaBusAdapter',
+  session: 'MegaSessionAdapter',
+  log: 'MegaLogSinkAdapter',
+})
+
+/**
+ * 템플릿 파일을 읽는다.
+ * @param {string} kind @param {string} file - 예 'code.tpl'. @returns {string}
+ */
+function readTpl(kind, file) {
+  return readFileSync(join(TEMPLATES_ROOT, kind, file), 'utf8')
+}
+
+/**
+ * `from` 파일에서 `to` 파일로의 `./`-접두 상대 import 경로(POSIX 슬래시).
+ * @param {string} fromAbs @param {string} toAbs @returns {string}
+ */
+function relImport(fromAbs, toAbs) {
+  let rel = relative(dirname(fromAbs), toAbs).split(sep).join('/')
+  if (!rel.startsWith('.')) rel = `./${rel}`
+  return rel
+}
+
+/** 소스 상대경로 → 테스트 상대경로(test/ 미러 + .test.js). @param {string} codeRel @param {string} ext */
+function mirrorTestRel(codeRel, ext = '.js') {
+  return join('test', codeRel.slice(0, -ext.length) + '.test.js')
+}
+
+/** 마이그레이션 타임스탬프(YYYYMMDDHHmmss). CLI 런타임이므로 Date 사용 가능. @returns {string} */
+function migrationTimestamp() {
+  const d = new Date()
+  const p = (/** @type {number} */ n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
+}
+
+/**
+ * @typedef {object} Artifact
+ * @property {string} outAbs - 쓸 파일 절대경로.
+ * @property {string} content - 렌더된 내용.
+ * @property {'code'|'test'|'task'|'route'} role
+ */
+
+/**
+ * kind 별로 생성할 artifact 목록을 계획한다(아직 디스크에 쓰지 않음).
+ * @param {string} kind
+ * @param {string} rawName
+ * @param {Record<string, any>} opts - { app, version, kind(adapter), lng, ns }
+ * @param {string} projectRoot
+ * @returns {Artifact[]}
+ */
+export function planArtifacts(kind, rawName, opts, projectRoot) {
+  const app = typeof opts.app === 'string' && opts.app.length > 0 ? opts.app : 'main'
+  const v = nameVariants(rawName)
+  /** 공통 토큰. */
+  const base = { Name: v.pascal, name: v.kebab, camelName: v.camel, app }
+
+  /**
+   * 코드+테스트 표준 쌍을 만든다.
+   * @param {object} a
+   * @param {string} a.codeRel - 소스 상대경로.
+   * @param {Record<string,string>} a.vars - 추가 토큰.
+   * @param {string} [a.codeTpl] @param {string} [a.testTpl]
+   * @returns {Artifact[]}
+   */
+  const pair = ({ codeRel, vars, codeTpl = 'code.tpl', testTpl = 'test.tpl' }) => {
+    const codeAbs = join(projectRoot, codeRel)
+    const testAbs = join(projectRoot, mirrorTestRel(codeRel))
+    const allVars = { ...base, ...vars }
+    return [
+      { outAbs: codeAbs, role: 'code', content: renderTemplate(readTpl(kind, codeTpl), allVars) },
+      {
+        outAbs: testAbs,
+        role: 'test',
+        content: renderTemplate(readTpl(kind, testTpl), { ...allVars, importPath: relImport(testAbs, codeAbs) }),
+      },
+    ]
+  }
+
+  switch (kind) {
+    case 'model':
+      return pair({ codeRel: `apps/${app}/models/${v.kebab}.js`, vars: { table: v.snake } })
+
+    case 'service':
+      return pair({ codeRel: `apps/${app}/services/${v.kebab}-service.js`, vars: {} })
+
+    case 'channel':
+      return pair({ codeRel: `apps/${app}/channels/${v.kebab}-channel.js`, vars: {} })
+
+    case 'middleware':
+      return pair({ codeRel: `apps/${app}/middlewares/${v.kebab}.js`, vars: {} })
+
+    case 'route':
+      return pair({ codeRel: `apps/${app}/routes/${v.kebab}.js`, vars: {} })
+
+    case 'schedule':
+      return pair({ codeRel: `apps/${app}/schedules/${v.kebab}.js`, vars: { cron: '0 3 * * *' } })
+
+    case 'job':
+      return pair({ codeRel: `apps/${app}/jobs/${v.kebab}.js`, vars: { subject: v.kebab } })
+
+    case 'controller':
+      return planController(v, app, opts, projectRoot, base)
+
+    case 'worker':
+      return planWorker(v, app, projectRoot, base)
+
+    case 'adapter':
+      return planAdapter(v, opts, projectRoot, base)
+
+    case 'migration':
+      return planMigration(v, app, projectRoot, base)
+
+    case 'locale':
+      return planLocale(v, app, opts, projectRoot, base)
+
+    case 'app':
+      return planApp(v, projectRoot, base)
+
+    default:
+      throw new Error(`Unknown generator kind '${kind}'. Supported: ${GENERATOR_KINDS.join(', ')}.`)
+  }
+}
+
+/**
+ * @typedef {{ kebab: string, pascal: string, camel: string, snake: string, words: string[] }} Variants
+ * @typedef {Record<string, string>} BaseVars
+ */
+
+/**
+ * controller — 기본은 클래스+테스트. `--version=vN` 이면 controllers/vN/ + routes/vN/ wiring(없으면 생성)
+ * + 테스트(ADR-069).
+ * @param {Variants} v @param {string} app @param {Record<string, any>} opts @param {string} projectRoot @param {BaseVars} base
+ * @returns {Artifact[]}
+ */
+function planController(v, app, opts, projectRoot, base) {
+  const version = normalizeVersion(opts.version)
+  const seg = version ? `${version}/` : ''
+  const codeRel = `apps/${app}/controllers/${seg}${v.kebab}-controller.js`
+  const codeAbs = join(projectRoot, codeRel)
+  const testAbs = join(projectRoot, mirrorTestRel(codeRel))
+  /** @type {Artifact[]} */
+  const out = [
+    { outAbs: codeAbs, role: 'code', content: renderTemplate(readTpl('controller', 'code.tpl'), base) },
+    {
+      outAbs: testAbs,
+      role: 'test',
+      content: renderTemplate(readTpl('controller', 'test.tpl'), { ...base, importPath: relImport(testAbs, codeAbs) }),
+    },
+  ]
+  if (version) {
+    const routeAbs = join(projectRoot, `apps/${app}/routes/${version}/${v.kebab}.js`)
+    if (!existsSync(routeAbs)) {
+      out.push({
+        outAbs: routeAbs,
+        role: 'route',
+        content: renderTemplate(readTpl('controller', 'route.tpl'), {
+          ...base,
+          version,
+          controllerImport: relImport(routeAbs, codeAbs),
+        }),
+      })
+    }
+  }
+  return out
+}
+
+/** worker — 클래스 파일 + taskFile + 테스트(ADR-124).
+ * @param {Variants} v @param {string} app @param {string} projectRoot @param {BaseVars} base
+ * @returns {Artifact[]} */
+function planWorker(v, app, projectRoot, base) {
+  const codeRel = `apps/${app}/workers/${v.kebab}.js`
+  const taskRel = `apps/${app}/workers/${v.kebab}.task.js`
+  const codeAbs = join(projectRoot, codeRel)
+  const taskAbs = join(projectRoot, taskRel)
+  const testAbs = join(projectRoot, mirrorTestRel(codeRel))
+  const taskFile = taskRel.split(sep).join('/') // projectRoot 기준 상대(POSIX) — MegaWorker static taskFile.
+  return [
+    { outAbs: codeAbs, role: 'code', content: renderTemplate(readTpl('worker', 'code.tpl'), { ...base, taskFile }) },
+    { outAbs: taskAbs, role: 'task', content: renderTemplate(readTpl('worker', 'task.tpl'), base) },
+    {
+      outAbs: testAbs,
+      role: 'test',
+      content: renderTemplate(readTpl('worker', 'test.tpl'), {
+        ...base,
+        importPath: relImport(testAbs, codeAbs),
+        taskImportPath: relImport(testAbs, taskAbs),
+      }),
+    },
+  ]
+}
+
+/** adapter — shared/adapters/ 에 베이스 상속 골격 + 테스트(ADR-045).
+ * @param {Variants} v @param {Record<string, any>} opts @param {string} projectRoot @param {BaseVars} base
+ * @returns {Artifact[]} */
+function planAdapter(v, opts, projectRoot, base) {
+  const akind = typeof opts.kind === 'string' ? opts.kind : 'db'
+  const Base = ADAPTER_BASES[akind]
+  if (!Base) {
+    throw new Error(`mega g adapter: --kind must be one of [${Object.keys(ADAPTER_BASES).join(', ')}]. Got '${akind}'.`)
+  }
+  const codeRel = `shared/adapters/mega-${v.kebab}-adapter.js`
+  const codeAbs = join(projectRoot, codeRel)
+  const testAbs = join(projectRoot, mirrorTestRel(codeRel))
+  const vars = { ...base, Base, kind: akind, driver: v.kebab }
+  return [
+    { outAbs: codeAbs, role: 'code', content: renderTemplate(readTpl('adapter', 'code.tpl'), vars) },
+    {
+      outAbs: testAbs,
+      role: 'test',
+      content: renderTemplate(readTpl('adapter', 'test.tpl'), { ...vars, importPath: relImport(testAbs, codeAbs) }),
+    },
+  ]
+}
+
+/** migration — 타임스탬프 up/down + 테스트.
+ * @param {Variants} v @param {string} app @param {string} projectRoot @param {BaseVars} base
+ * @returns {Artifact[]} */
+function planMigration(v, app, projectRoot, base) {
+  const ts = migrationTimestamp()
+  const codeRel = `apps/${app}/migrations/${ts}-${v.kebab}.js`
+  const codeAbs = join(projectRoot, codeRel)
+  const testAbs = join(projectRoot, mirrorTestRel(codeRel))
+  const vars = { ...base, timestamp: ts }
+  return [
+    { outAbs: codeAbs, role: 'code', content: renderTemplate(readTpl('migration', 'code.tpl'), vars) },
+    {
+      outAbs: testAbs,
+      role: 'test',
+      content: renderTemplate(readTpl('migration', 'test.tpl'), { ...vars, importPath: relImport(testAbs, codeAbs) }),
+    },
+  ]
+}
+
+/** locale — apps/<app>/locales/<lng>/<ns>.json + JSON 검증 테스트(ADR-039).
+ * @param {Variants} v @param {string} app @param {Record<string, any>} opts @param {string} projectRoot @param {BaseVars} base
+ * @returns {Artifact[]} */
+function planLocale(v, app, opts, projectRoot, base) {
+  const lng = typeof opts.lng === 'string' && opts.lng.length > 0 ? opts.lng : 'en'
+  const ns = v.kebab
+  const codeRel = `apps/${app}/locales/${lng}/${ns}.json`
+  const codeAbs = join(projectRoot, codeRel)
+  const testAbs = join(projectRoot, mirrorTestRel(codeRel, '.json'))
+  const vars = { ...base, lng, ns }
+  return [
+    { outAbs: codeAbs, role: 'code', content: renderTemplate(readTpl('locale', 'code.tpl'), vars) },
+    {
+      outAbs: testAbs,
+      role: 'test',
+      content: renderTemplate(readTpl('locale', 'test.tpl'), { ...vars, importPath: relImport(testAbs, codeAbs) }),
+    },
+  ]
+}
+
+/** app — apps/<name>/{app.config.js, routes/index.js} + 라우트 테스트.
+ * @param {Variants} v @param {string} projectRoot @param {BaseVars} base
+ * @returns {Artifact[]} */
+function planApp(v, projectRoot, base) {
+  const name = v.kebab
+  const configAbs = join(projectRoot, `apps/${name}/app.config.js`)
+  const routeAbs = join(projectRoot, `apps/${name}/routes/index.js`)
+  const testAbs = join(projectRoot, `test/apps/${name}/index.test.js`)
+  const vars = { ...base, name }
+  return [
+    { outAbs: configAbs, role: 'code', content: renderTemplate(readTpl('app', 'app.config.tpl'), vars) },
+    { outAbs: routeAbs, role: 'route', content: renderTemplate(readTpl('app', 'route.tpl'), vars) },
+    {
+      outAbs: testAbs,
+      role: 'test',
+      content: renderTemplate(readTpl('app', 'test.tpl'), { ...vars, importPath: relImport(testAbs, routeAbs) }),
+    },
+  ]
+}
+
+/**
+ * `--version` 입력을 `v<N>` 으로 정규화. 'v2'/'2'/'V2' 모두 'v2'. 빈 값은 null.
+ * @param {unknown} raw @returns {string|null}
+ */
+function normalizeVersion(raw) {
+  if (raw == null || raw === false || raw === '') return null
+  const m = String(raw).match(/\d+/)
+  if (!m) throw new Error(`--version must contain a number (e.g. v2). Got '${raw}'.`)
+  return `v${m[0]}`
+}
+
+/**
+ * 계획된 artifact 를 디스크에 쓴다. 이미 있으면 건너뛴다(force 면 덮어씀).
+ * @param {Artifact[]} artifacts
+ * @param {{ force?: boolean }} [opts]
+ * @returns {{ written: string[], skipped: string[] }}
+ */
+export function writeArtifacts(artifacts, { force = false } = {}) {
+  /** @type {string[]} */ const written = []
+  /** @type {string[]} */ const skipped = []
+  for (const a of artifacts) {
+    if (existsSync(a.outAbs) && !force) {
+      skipped.push(a.outAbs)
+      continue
+    }
+    mkdirSync(dirname(a.outAbs), { recursive: true })
+    writeFileSync(a.outAbs, a.content)
+    written.push(a.outAbs)
+  }
+  return { written, skipped }
+}
+
+/**
+ * `mega g <kind> <name>` 실행 — 계획 → 쓰기 → 결과 반환.
+ * @param {string} kind
+ * @param {string} rawName
+ * @param {object} [opts] - { app, version, kind(adapter), lng, force }
+ * @param {string} [projectRoot]
+ * @returns {{ kind: string, name: string, written: string[], skipped: string[] }}
+ */
+export function generate(kind, rawName, opts = {}, projectRoot = process.cwd()) {
+  if (!GENERATOR_KINDS.includes(/** @type {any} */ (kind))) {
+    throw new Error(`Unknown generator '${kind}'. Supported: ${GENERATOR_KINDS.join(', ')}.`)
+  }
+  if (typeof rawName !== 'string' || rawName.trim().length === 0) {
+    throw new Error(`mega g ${kind}: a name is required (e.g. 'mega g ${kind} users').`)
+  }
+  const artifacts = planArtifacts(kind, rawName, opts, projectRoot)
+  const { written, skipped } = writeArtifacts(artifacts, { force: /** @type {any} */ (opts).force === true })
+  return { kind, name: rawName, written, skipped }
+}