mega-framework 0.1.6 → 0.1.8

package/src/cli/watch.js

@@ -0,0 +1,188 @@
+// @ts-check
+/**
+ * `mega start --watch` 의 dev watch supervisor (ADR-220, ADR-182 개정).
+ *
+ * Node 내장 `--watch-path` 재실행(구 ADR-182)은 **ignore 패턴이 없어** 런타임이 쓰는 파일까지
+ * 재시작을 유발했다 — dev 의 i18n saveMissing 이 `locales/*.json` 자동 기입(재시작 무한 루프),
+ * 업로드가 `uploads/`/`var/` 에 파일 저장(사용자 입력이 서버를 재시작), 마이그레이션 generate 가
+ * `.mega/` journal 갱신. 본 모듈이 그 재실행을 **자체 supervisor**(fs.watch recursive + 미니 glob
+ * ignore + debounce + SIGTERM respawn)로 대체한다 — 신규 dep 0(chokidar 미도입: 필요한 매칭이
+ * `**`/`*`/`?` 수준이라 풀스펙 glob 라이브러리가 과함).
+ *
+ * ignore 합성 = config `watch.ignore` + CLI `--watch-ignore`. **숨은 코드 디폴트는 없다**(사용자
+ * 결정 — 개발자가 보지 못하는 목록은 폴더명이 다른 프로젝트에서 오히려 혼란) — 권장 목록은 스캐폴드
+ * `.env` 의 `WATCH_IGNORE` 가 실값으로 명시하고 `mega.config.js` 가 읽어 `watch.ignore` 로 넘긴다.
+ * ignore 0 이면 supervisor 가 기동 시 경고 1줄을 낸다(locales saveMissing 루프 등 위험 가시화).
+ *
+ * @module cli/watch
+ */
+import { watch as fsWatch, existsSync, statSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+
+/**
+ * 미니 glob → RegExp. 지원: 더블스타+슬래시(0개 이상의 디렉토리), 더블스타(경로 전체), `*`(세그먼트
+ * 내), `?`(1글자). 그 외 문자는 리터럴(정규식 특수문자 escape). 매칭 대상은 루트 상대 POSIX 경로
+ * 전체(^…$). 패턴 예시는 스캐폴드 `.env` 의 `WATCH_IGNORE` 참조 — JS 블록 주석 안에는
+ * 더블스타+슬래시 시퀀스를 쓸 수 없어(주석 조기 종료) 여기 직접 못 적는다.
+ *
+ * @param {string} pattern - glob 패턴(예 `.env.*`).
+ * @returns {RegExp}
+ */
+export function globToRegExp(pattern) {
+  let re = ''
+  let i = 0
+  while (i < pattern.length) {
+    const ch = pattern[i]
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        // `**/` 는 0개 이상의 디렉토리(루트 레벨 포함), 그 외 `**` 는 임의 문자열.
+        if (pattern[i + 2] === '/') {
+          re += '(?:.*/)?'
+          i += 3
+        } else {
+          re += '.*'
+          i += 2
+        }
+      } else {
+        re += '[^/]*'
+        i += 1
+      }
+    } else if (ch === '?') {
+      re += '[^/]'
+      i += 1
+    } else {
+      re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      i += 1
+    }
+  }
+  return new RegExp(`^${re}$`)
+}
+
+/**
+ * ignore 패턴 합성 — config(`watch.ignore`) + CLI(`--watch-ignore a,b`). 숨은 디폴트 없음(모듈
+ * docstring 참조). 잘못된 모양은 fail-fast(silent 무시 금지).
+ *
+ * @param {{ ignore?: unknown }} [watchConfig] - mega.config.js 의 `watch`.
+ * @param {string | undefined} [cliIgnore] - `--watch-ignore` 값(콤마 구분).
+ * @returns {string[]}
+ * @throws {TypeError} config `watch.ignore` 가 문자열 배열이 아닐 때.
+ */
+export function mergeWatchIgnore(watchConfig = {}, cliIgnore = undefined) {
+  /** @type {string[]} */
+  const merged = []
+  if (watchConfig.ignore !== undefined) {
+    if (!Array.isArray(watchConfig.ignore) || watchConfig.ignore.some((p) => typeof p !== 'string' || p.length === 0)) {
+      throw new TypeError('config watch.ignore 는 비어있지 않은 문자열 배열이어야 합니다.')
+    }
+    merged.push(...watchConfig.ignore)
+  }
+  if (typeof cliIgnore === 'string' && cliIgnore.length > 0) {
+    merged.push(...cliIgnore.split(',').map((p) => p.trim()).filter((p) => p.length > 0))
+  }
+  return merged
+}
+
+/**
+ * 루트 상대 경로가 ignore 에 걸리는지 (Boolean — `is*`).
+ * @param {string} rel - 루트 상대 POSIX 경로(예 `apps/main/locales/ko.json`).
+ * @param {RegExp[]} regexps - {@link globToRegExp} 컴파일 결과.
+ * @returns {boolean}
+ */
+export function isIgnoredPath(rel, regexps) {
+  return regexps.some((r) => r.test(rel))
+}
+
+/**
+ * watch supervisor — 감시 경로의 변경(ignore 통과분)을 debounce 후 자식(`mega start`)을
+ * SIGTERM → respawn 한다. 자식이 스스로 죽으면(crash) 재시작하지 않고 다음 변경을 기다린다
+ * (crash-loop 방지 — nodemon 의 "app crashed - waiting for file changes" 와 동형).
+ *
+ * @param {object} o
+ * @param {string} o.projectRoot
+ * @param {string[]} o.watchPaths - 감시할 절대경로(존재하는 것만 — 호출측이 필터).
+ * @param {string[]} o.ignore - glob 패턴 목록.
+ * @param {() => import('node:child_process').ChildProcess} o.spawnChild - 자식 기동 팩토리(주입 — 테스트).
+ * @param {(msg: string) => void} o.out
+ * @param {number} [o.debounceMs=500] - 연속 변경 디바운스.
+ * @param {(dir: string, opts: object, cb: (event: string, filename: string | Buffer | null) => void) => { close(): void }} [o.watchFn] -
+ *   fs.watch 주입(테스트). 기본 node:fs watch.
+ * @returns {Promise<number>} 부모(supervisor)의 exit code — SIGINT/SIGTERM 수신 시 자식 정리 후 0.
+ */
+export function startWatchSupervisor({ projectRoot, watchPaths, ignore, spawnChild, out, debounceMs = 500, watchFn = /** @type {any} */ (fsWatch) }) {
+  const regexps = ignore.map(globToRegExp)
+  /** @type {import('node:child_process').ChildProcess | null} */
+  let child = null
+  /** @type {NodeJS.Timeout | null} */
+  let pending = null
+  let shuttingDown = false
+  let restarting = false
+
+  const start = () => {
+    child = spawnChild()
+    child.on('exit', (code, signal) => {
+      if (shuttingDown) return
+      if (restarting) {
+        restarting = false
+        start()
+        return
+      }
+      // 자식이 스스로 종료(crash/정상) — 재시작 폭주 대신 다음 변경 대기(P4: 이유 출력).
+      out(`mega: app exited (code=${code ?? `signal:${signal}`}) — waiting for file changes before restart`)
+      child = null
+    })
+  }
+
+  const scheduleRestart = (/** @type {string} */ rel) => {
+    if (pending) clearTimeout(pending)
+    pending = setTimeout(() => {
+      pending = null
+      out(`mega: restarting due to changes (${rel})`)
+      if (child && child.exitCode === null && !child.killed) {
+        restarting = true
+        child.kill('SIGTERM') // graceful — exit 핸들러가 respawn.
+      } else {
+        start() // crash 후 대기 상태 — 변경으로 재기동.
+      }
+    }, debounceMs)
+  }
+
+  /** @type {Array<{ close(): void }>} */
+  const watchers = []
+  for (const abs of watchPaths) {
+    const isDir = statSync(abs).isDirectory()
+    const watcher = watchFn(abs, { recursive: isDir }, (_event, filename) => {
+      // filename 은 감시 루트 상대(파일 watch 면 basename) — 루트 상대로 정규화해 ignore 매칭.
+      const name = typeof filename === 'string' ? filename : (filename ? String(filename) : '')
+      const rel = relative(projectRoot, isDir ? join(abs, name) : abs).split(sep).join('/')
+      if (isIgnoredPath(rel, regexps)) return
+      scheduleRestart(rel)
+    })
+    watchers.push(watcher)
+  }
+
+  start()
+
+  return new Promise((resolve) => {
+    /** @type {NodeJS.Signals[]} */
+    const sigs = ['SIGINT', 'SIGTERM']
+    const onSignal = () => {
+      shuttingDown = true
+      if (pending) clearTimeout(pending)
+      for (const w of watchers) w.close()
+      for (const s of sigs) process.removeListener(s, onSignal)
+      if (child && child.exitCode === null && !child.killed) {
+        child.once('exit', () => resolve(0))
+        child.kill('SIGTERM')
+      } else {
+        resolve(0)
+      }
+    }
+    for (const s of sigs) process.on(s, onSignal)
+  })
+}
+
+/** {@link startWatchSupervisor} 의 watchPaths 기본 집합 — 존재하는 것만.
+ * @param {string} projectRoot @returns {string[]} */
+export function defaultWatchPaths(projectRoot) {
+  return [join(projectRoot, 'apps'), join(projectRoot, 'shared'), join(projectRoot, 'mega.config.js')].filter(existsSync)
+}

package/src/core/ajv-mapper.js

@@ -15,6 +15,16 @@ const SENSITIVE_FIELD_RE = /(password|secret|token)/i
 /** PII 마스킹된 value 표기. */
 const REDACTED = '[REDACTED]'
 
+/**
+ * envelope `details` 배열 상한 (ADR-193 — allErrors DoS 방어의 응답측 bound).
+ *
+ * allErrors:true 는 위반을 전수 수집하므로(@fastify/ajv-compiler 디폴트가 allErrors:false 인 이유 =
+ * DoS 가능성 명시) 악의적 페이로드가 수천 개 위반을 만들 수 있다. 입력측은 Fastify bodyLimit
+ * (기본 1 MiB)이 막고, 응답·로그측은 이 cap 이 막는다 — 초과분은 잘라내되 silent 가 아니라
+ * `rule:'truncated'` 합성 항목으로 생략 개수를 명시한다.
+ */
+export const MAX_VALIDATION_DETAILS = 20
+
 /**
  * Fastify 가 던진 AJV 검증 에러 객체 → MegaValidationError 로 매핑.
  *
@@ -30,7 +40,17 @@ const REDACTED = '[REDACTED]'
  */
 export function ajvErrorToValidationError(err) {
   if (!err || !Array.isArray(err.validation)) return null
-  const details = err.validation.map((e) => ajvItemToDetail(e))
+  const omitted = Math.max(0, err.validation.length - MAX_VALIDATION_DETAILS)
+  const details = err.validation.slice(0, MAX_VALIDATION_DETAILS).map((e) => ajvItemToDetail(e))
+  if (omitted > 0) {
+    // cap 초과는 silent 절단 금지 — 생략 개수를 합성 항목으로 명시(클라이언트·로그 양쪽에서 보임).
+    details.push({
+      field: '',
+      rule: 'truncated',
+      value: { omitted },
+      message: `... and ${omitted} more validation errors (details capped at ${MAX_VALIDATION_DETAILS})`,
+    })
+  }
   const context = err.validationContext ?? 'request'
   return new MegaValidationError('validation.failed', `Validation failed for ${context}`, {
     details,
@@ -45,11 +65,18 @@ export function ajvErrorToValidationError(err) {
  */
 function ajvItemToDetail(e) {
   // instancePath 예: '/email' → field = 'email'. '/items/0/name' → 'items[0].name'
-  const field = ajvPathToField(e.instancePath || e.dataPath || '')
+  let field = ajvPathToField(e.instancePath || e.dataPath || '')
   // ADR-090: required 같은 키워드는 instancePath 가 부모라 params.missingProperty 가 실제 필드.
   // 마스킹 판단은 instancePath 필드 + missingProperty 둘 다 본다.
   const missing = e.params && typeof e.params.missingProperty === 'string' ? e.params.missingProperty : ''
-  const isSensitive = SENSITIVE_FIELD_RE.test(field) || SENSITIVE_FIELD_RE.test(missing)
+  // required 위반의 field 는 누락 필드 경로로 보정 — 루트 required 면 field 가 '' 라 클라이언트가
+  // 어느 필드인지 알 수 없던 것을 missingProperty 로 채운다(ADR-188). 부모 경로가 있으면 dot 연결.
+  if (e.keyword === 'required' && missing) {
+    field = field ? `${field}.${missing}` : missing
+  }
+  // 정규식 1회 실행 (G1 M-2, ADR-214) — field·missingProperty 를 합쳐 한 번만 검사한다. allErrors
+  // (ADR-193) 이후 400 1건당 detail × 2회 실행되던 비용 절반화. 매칭 의미는 동일(부분 일치 OR).
+  const isSensitive = SENSITIVE_FIELD_RE.test(missing ? `${field} ${missing}` : field)
   return {
     field,
     rule: e.keyword || 'unknown',