@zntc/core 0.1.0

package/bin/rn-dev-input.mjs

@@ -0,0 +1,225 @@
+// `runRnDev` 의 config + opts 추출 helper. zntc.mjs 에서 import + 사용.
+// 별도 module 로 분리해 단위 테스트가 zntc.mjs 의 entry main() 트리거 없이
+// helper 만 import 가능.
+
+import { resolve } from 'node:path';
+
+/**
+ * config 의 미지원 필드는 stderr 에 한 번 경고 — silent drop 방지. zntc 의
+ * RN dev server 가 아직 wire-up 안 한 영역 (graph-bundler 전용 필드 + dummy
+ * placeholder) 을 사용자가 적었을 때 "왜 동작 안 함?" 디버깅 비용 절감.
+ */
+const UNSUPPORTED_FIELDS = [
+  // graph-bundler (Metro 호환) 전용 — zntc NAPI build 는 미수용.
+  ['transformer', 'inlineRequires'],
+  ['transformer', 'minifier'],
+  ['serializer', 'bundleType'],
+  ['serializer', 'getModulesRunBeforeMainModule'],
+  ['serializer', 'getRunModuleStatement'],
+  ['serializer', 'shouldAddToIgnoreList'],
+  // dummy placeholder — bungae 도 declared-but-unused.
+  ['server', 'verifyConnections'],
+  ['server', 'https'],
+  ['server', 'key'],
+  ['server', 'cert'],
+  ['server', 'unstable_serverRoot'],
+];
+
+function warnUnsupported(config) {
+  for (const [section, key] of UNSUPPORTED_FIELDS) {
+    const sectionVal = config?.[section];
+    if (sectionVal && Object.prototype.hasOwnProperty.call(sectionVal, key)) {
+      process.stderr.write(`[zntc:rn-dev] config.${section}.${key} (zntc 미지원, ignore)\n`);
+    }
+  }
+}
+
+function normalizeStringArray(value, label) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) {
+    throw new TypeError(`config.serializer.${label} must be a string array`);
+  }
+  for (const item of value) {
+    if (typeof item !== 'string') {
+      throw new TypeError(`config.serializer.${label} must contain only strings`);
+    }
+  }
+  return value;
+}
+
+function getSerializerPolyfills(serializer, opts = {}) {
+  const polyfills = [];
+
+  const platform = opts.rnPlatform === 'android' ? 'android' : 'ios';
+  if (typeof serializer.getPolyfills === 'function') {
+    const generated = serializer.getPolyfills({ platform });
+    if (generated && typeof generated.then === 'function') {
+      throw new TypeError('async config.serializer.getPolyfills() is not supported');
+    }
+    polyfills.push(...normalizeStringArray(generated, 'getPolyfills() result'));
+  }
+
+  // Metro prepends getPolyfills() and then appends serializer.polyfillModuleNames.
+  polyfills.push(...normalizeStringArray(serializer.polyfillModuleNames, 'polyfillModuleNames'));
+  // ZNTC also keeps the existing serializer.polyfills compatibility field.
+  polyfills.push(...normalizeStringArray(serializer.polyfills, 'polyfills'));
+
+  return polyfills.length > 0 ? polyfills : undefined;
+}
+
+/**
+ * Metro-shape config (`resolver` / `serializer` / `transformer` / `server` /
+ * `watchFolders` / `sourcemapSourcesRoot`) → `RnBundleInput.extra` 평탄화. dev
+ * server (rn-dev-input) 와 prod bundle (zntc.mjs runRnBundle) 양쪽이 공유.
+ *
+ * `opts.rnWatchFolders` / `opts.rnSourceExts` 만 CLI flag 가 config 위에 우선 —
+ * 나머지 필드는 config-only.
+ */
+export function buildRnBundleExtra(config, opts = {}) {
+  const cfg = config ?? {};
+  const resolver = cfg.resolver ?? {};
+  const transformer = cfg.transformer ?? {};
+  const serializer = cfg.serializer ?? {};
+  const server = cfg.server ?? {};
+  return {
+    watchFolders: opts.rnWatchFolders ?? cfg.watchFolders ?? undefined,
+    nodeModulesPaths: resolver.nodeModulesPaths ?? undefined,
+    sourceExts: opts.rnSourceExts ?? resolver.sourceExts ?? undefined,
+    assetExts: resolver.assetExts ?? undefined,
+    platforms: resolver.platforms ?? undefined,
+    blockList: resolver.blockList ?? undefined,
+    fallback: resolver.extraNodeModules ?? undefined,
+    metroResolveRequest: resolver.resolveRequest ?? undefined,
+    babelTransformerPath: transformer.babelTransformerPath ?? undefined,
+    polyfills: getSerializerPolyfills(serializer, opts),
+    extraVars: serializer.extraVars ?? undefined,
+    prelude: serializer.prelude ?? undefined,
+    babel: transformer.babel ?? undefined,
+    inlineSourceMap: serializer.inlineSourceMap ?? undefined,
+    sourceRoot: cfg.sourcemapSourcesRoot ?? undefined,
+    silentConsoleErrorPatterns: server.silentConsoleErrorPatterns ?? undefined,
+    forwardClientLogs: server.forwardClientLogs !== false,
+  };
+}
+
+function assignRnBuildOptionOverrides(out, config, opts = {}) {
+  const cfg = config ?? {};
+  if (opts.experimentalDecorators === true || cfg.experimentalDecorators === true) {
+    out.experimentalDecorators = true;
+  }
+  if (opts.emitDecoratorMetadata === true || cfg.emitDecoratorMetadata === true) {
+    out.emitDecoratorMetadata = true;
+  }
+  if (opts.useDefineForClassFields === false || cfg.useDefineForClassFields === false) {
+    out.useDefineForClassFields = false;
+  }
+  if (opts.inlineDynamicImports === true || cfg.inlineDynamicImports === true) {
+    out.inlineDynamicImports = true;
+  } else if (opts.inlineDynamicImports === false || cfg.inlineDynamicImports === false) {
+    out.inlineDynamicImports = false;
+  }
+}
+
+/**
+ * Internal helper — RN dev/bundle 경로의 `bundle.override` 객체를 구성한다.
+ * `@zntc/core` package.json `exports` 에 노출되지 않는 CLI bin 전용. 외부에서
+ * deep import 로 호출하지 말 것.
+ *
+ * @param {object} input
+ * @param {object} [input.config]   사용자 `zntc.config.{ts,js,json}` 의 root 객체.
+ *   `alias` / `moduleSpecifierMap` 같은 dict 타입은 RN preset 으로 forwarding.
+ *   `experimentalDecorators` 등은 BuildOptions override 로 forward.
+ * @param {object} [input.opts]     CLI flag 가 우선 적용된 RuntimeOptions
+ *   (`experimentalDecorators`/`emitDecoratorMetadata`/`useDefineForClassFields`).
+ *   config 와 OR 로 합산.
+ * @param {object} [input.override] 호출자(zntc.mjs) 가 build 결과 후 caller-side
+ *   write 를 처리할 때 강제로 덮어 씌우고 싶은 BuildOptions (예: `outfile`,
+ *   `write`). 마지막에 `Object.assign` 으로 머지.
+ * @returns {object | undefined} 빈 object 면 `undefined` 반환 — caller 의 spread/
+ *   merge 로직이 noop 으로 처리되도록.
+ */
+export function buildRnBundleOverride({ config, opts = {}, override } = {}) {
+  const cfg = config ?? {};
+  const out = {};
+  if (
+    (cfg.alias && typeof cfg.alias === 'object') ||
+    (opts.alias && typeof opts.alias === 'object')
+  ) {
+    // RN 경로에서도 일반 zntc `--alias`/config.alias 를 동일하게 적용한다.
+    // Babel module-resolver 를 제외한 프로젝트가 alias 를 native resolver 로 옮길 때 필요하다.
+    out.alias = { ...(cfg.alias ?? {}), ...(opts.alias ?? {}) };
+  }
+  if (cfg.moduleSpecifierMap && typeof cfg.moduleSpecifierMap === 'object') {
+    out.moduleSpecifierMap = cfg.moduleSpecifierMap;
+  }
+  assignRnBuildOptionOverrides(out, cfg, opts);
+  if (override && typeof override === 'object') {
+    Object.assign(out, override);
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * 번개 BungaeConfig 의 `root` / `entry` / `dev` / `minify` / `server.*` /
+ * `resolver.*` / `transformer.*` / `serializer.*` / `symbolicator.*` /
+ * `watchFolders` 영역 인식.
+ *
+ * CLI flag 우선 → config 영역 → default 순서 fallback. entry 가 없으면 null —
+ * caller 가 friendly error 처리.
+ *
+ * 미지원 필드 (graph-bundler 전용 + placeholder) 는 stderr 에 한 번 경고 —
+ * `transformer.inlineRequires` / `transformer.minifier` / `serializer.prelude` /
+ * `serializer.bundleType` / `server.forwardClientLogs` / `server.verifyConnections` 등.
+ */
+export function buildRnDevServerInput(opts, config) {
+  const cfg = config ?? {};
+  const projectRoot = resolve(opts.rnProjectRoot ?? cfg.projectRoot ?? cfg.root ?? '.');
+  const entry = opts.entryPoints?.[0] ?? cfg.entry;
+  if (!entry) return null;
+  const rnPlatform = opts.rnPlatform === 'android' ? 'android' : 'ios';
+  const server = cfg.server ?? {};
+  const resolver = cfg.resolver ?? {};
+  const symbolicator = cfg.symbolicator ?? {};
+
+  warnUnsupported(cfg);
+
+  // server.useGlobalHotkey + CLI `--no-interactive` 둘 다 r/d/? 키보드
+  // shortcut 의 enable gate. CLI flag 우선 — 명시 시 config override.
+  const terminalActions =
+    opts.noInteractive === true || server.useGlobalHotkey === false ? false : undefined;
+  const dev = opts.devMode !== undefined ? Boolean(opts.devMode) : cfg.dev !== false;
+
+  return {
+    bundle: {
+      entry,
+      projectRoot,
+      rnPlatform,
+      // dev server 는 default __DEV__=true / sourcemap=true (bundle 의 default false 와 의도적 비대칭).
+      dev,
+      // dev server 는 항상 sourcemap=true — RN LogBox / DevTools 의 source link
+      // 동작에 필수. zntc.mjs 의 `opts.sourcemap` default 가 false 라 `!== false`
+      // 비교는 무용 (사용자 명시 disable 구분 불가). dev server 컨텍스트에선
+      // sourcemap 필수 default.
+      sourcemap: true,
+      minify:
+        opts.minify ||
+        opts.minifyWhitespace ||
+        opts.minifyIdentifiers ||
+        opts.minifySyntax ||
+        cfg.minify ||
+        false,
+      extra: buildRnBundleExtra(cfg, opts),
+      override: buildRnBundleOverride({ config: cfg, opts }),
+    },
+    port: opts.port ?? server.port ?? 8081,
+    host: opts.host ?? server.host ?? 'localhost',
+    nodeModulesPaths: resolver.nodeModulesPaths ?? [],
+    enhanceMiddleware: server.enhanceMiddleware,
+    rewriteRequestUrl: server.rewriteRequestUrl,
+    symbolicator: symbolicator.customizeFrame
+      ? { customizeFrame: symbolicator.customizeFrame }
+      : undefined,
+    ...(server.hmr === false ? { hmr: false } : {}),
+    ...(terminalActions === false ? { terminalActions: false } : {}),
+  };
+}

package/bin/verify.mjs

@@ -0,0 +1,190 @@
+// `zntc verify <path-or-url>` 진입점. 정적 결과물 (`dist/`) 또는 URL 을 헤드리스
+// Chromium 에 띄우고 pageerror / console.error / 4xx 응답 / request 실패를
+// 수집해 JSON 리포트로 리턴. CI 한 줄로 "번들이 브라우저에서 깨지는지" 검증.
+//
+// playwright 는 optionalDependency — 미설치 시 친절한 안내 후 exit 64.
+
+import { statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// Exit code contract — runVerify 의 public API. CI 가 의존하므로 변경 시 docs/USAGE.md 동기.
+const EXIT_OK = 0;
+const EXIT_EVENTS_FOUND = 1;
+const EXIT_LOAD_FAILED = 2;
+const EXIT_BAD_USAGE = 64;
+
+const PLAYWRIGHT_INSTALL_HINT = [
+  'zntc verify requires Playwright to be installed.',
+  '',
+  '  npm install --save-dev playwright',
+  '  npx playwright install chromium',
+  '',
+].join('\n');
+
+// cwd 의 node_modules 와 verify.mjs 위치 양쪽에서 playwright / @playwright/test 를
+// 순차 탐색. 사용자가 자기 프로젝트에 playwright 를 설치한 경우 그쪽 우선.
+// require() 가 dynamic import 보다 우선 — @playwright/test 는 CJS/ESM dual 인데
+// CJS entry 를 ESM 으로 평가하면 default export 만 노출되고 chromium 같은 named
+// export 는 사라진다. require() 는 CJS entry 의 module.exports 전체를 그대로 반환.
+async function loadChromium() {
+  const requireFromCwd = createRequire(resolve(process.cwd(), 'package.json'));
+  for (const name of ['playwright', '@playwright/test']) {
+    try {
+      const mod = requireFromCwd(name);
+      if (mod?.chromium) return mod.chromium;
+    } catch {}
+    try {
+      const mod = await import(name);
+      if (mod?.chromium) return mod.chromium;
+    } catch {}
+  }
+  return null;
+}
+
+export async function runVerify(opts) {
+  const target = normalizeTarget(opts.verifyTarget);
+  if (!target) {
+    process.stderr.write(
+      'zntc verify: missing or invalid target. Usage: zntc verify <path-or-url> [options]\n',
+    );
+    return { exitCode: EXIT_BAD_USAGE };
+  }
+
+  const chromium = await loadChromium();
+  if (!chromium) {
+    process.stderr.write(PLAYWRIGHT_INSTALL_HINT);
+    return { exitCode: EXIT_BAD_USAGE };
+  }
+
+  const ignorePatterns = (opts.verifyIgnore || []).map((p) => new RegExp(p));
+  const timeout = opts.verifyTimeout ?? 10000;
+  const allowConsoleError = opts.verifyAllowConsoleError ?? false;
+  const events = [];
+
+  const start = Date.now();
+  let browser;
+  let loadOk = false;
+  let loadFailure = null;
+
+  try {
+    browser = await chromium.launch({ headless: true });
+    const ctx = await browser.newContext();
+    const page = await ctx.newPage();
+
+    page.on('pageerror', (err) => {
+      events.push({
+        type: 'pageerror',
+        message: err.message,
+        stack: err.stack ?? '',
+      });
+    });
+    page.on('console', (msg) => {
+      if (msg.type() !== 'error') return;
+      const text = msg.text();
+      if (ignorePatterns.some((re) => re.test(text))) return;
+      const loc = msg.location();
+      events.push({
+        type: 'console_error',
+        text,
+        location: loc?.url ? `${loc.url}:${loc.lineNumber + 1}:${loc.columnNumber + 1}` : '',
+      });
+    });
+    page.on('requestfailed', (req) => {
+      const url = req.url();
+      if (ignorePatterns.some((re) => re.test(url))) return;
+      events.push({
+        type: 'request_failed',
+        url,
+        method: req.method(),
+        failure: req.failure()?.errorText ?? '',
+      });
+    });
+    page.on('response', (res) => {
+      const status = res.status();
+      if (status < 400) return;
+      const url = res.url();
+      if (ignorePatterns.some((re) => re.test(url))) return;
+      events.push({ type: 'response', url, status });
+    });
+
+    await page.goto(target.url, { timeout, waitUntil: 'networkidle' });
+    loadOk = true;
+  } catch (err) {
+    loadFailure = err instanceof Error ? err.message : String(err);
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+  }
+
+  const duration_ms = Date.now() - start;
+  if (loadFailure) {
+    events.push({ type: 'load_failed', message: loadFailure });
+  }
+  const fatalEvents = events.filter((e) => {
+    if (e.type === 'console_error') return !allowConsoleError;
+    return true;
+  });
+  let exitCode = EXIT_OK;
+  if (!loadOk) exitCode = EXIT_LOAD_FAILED;
+  else if (fatalEvents.length > 0) exitCode = EXIT_EVENTS_FOUND;
+
+  const report = {
+    target: target.url,
+    status: exitCode === 0 ? 'pass' : 'fail',
+    duration_ms,
+    events,
+  };
+
+  if (opts.verifyReport) {
+    writeFileSync(opts.verifyReport, `${JSON.stringify(report, null, 2)}\n`);
+  }
+
+  if (opts.verifyJson) {
+    process.stdout.write(`${JSON.stringify(report)}\n`);
+  } else {
+    formatHuman(report, allowConsoleError);
+  }
+
+  return { exitCode };
+}
+
+function normalizeTarget(raw) {
+  if (!raw) return null;
+  if (/^https?:\/\//.test(raw) || raw.startsWith('file://')) {
+    return { url: raw };
+  }
+  const abs = isAbsolute(raw) ? raw : resolve(process.cwd(), raw);
+  try {
+    const stat = statSync(abs);
+    const filePath = stat.isDirectory() ? join(abs, 'index.html') : abs;
+    statSync(filePath);
+    return { url: pathToFileURL(filePath).href };
+  } catch {
+    return null;
+  }
+}
+
+function formatHuman(report, allowConsoleError) {
+  const stream = report.status === 'pass' ? process.stdout : process.stderr;
+  stream.write(`zntc verify: ${report.status.toUpperCase()} (${report.duration_ms} ms)\n`);
+  stream.write(`  target: ${report.target}\n`);
+  if (report.events.length === 0) return;
+  stream.write(`  ${report.events.length} event(s):\n`);
+  for (const e of report.events) {
+    if (e.type === 'pageerror') {
+      stream.write(`    [pageerror] ${e.message}\n`);
+    } else if (e.type === 'console_error') {
+      stream.write(`    [console.error] ${e.text}${e.location ? ` @ ${e.location}` : ''}\n`);
+    } else if (e.type === 'response') {
+      stream.write(`    [HTTP ${e.status}] ${e.url}\n`);
+    } else if (e.type === 'request_failed') {
+      stream.write(`    [request_failed] ${e.url} (${e.failure})\n`);
+    } else if (e.type === 'load_failed') {
+      stream.write(`    [load_failed] ${e.message}\n`);
+    }
+  }
+  if (allowConsoleError && report.events.some((e) => e.type === 'console_error')) {
+    stream.write('  (--verify-allow-console-error: console errors do not affect exit code)\n');
+  }
+}