@gaonjs/cli 0.52.0 → 0.56.0

package/dist/doctor/channel-collision.js

@@ -0,0 +1,119 @@
+// @gaonjs/cli · doctor · 앱간 동명 채널 검사 (§7 실시간)
+//
+// 채널 이름은 **전역 네임스페이스**다. 브로드캐스트 subject(`gaon.chan.<이름>`)와
+// 프레즌스 KV 키(`presence.<이름>.<멤버>`) 어디에도 앱 프리픽스가 없다(async/keys.ts).
+// 그래서 `apps/web/channels/room.ts` 와 `apps/admin/channels/room.ts` 처럼 두 앱이
+// 같은 파일명(=채널명)으로 **각자** 채널을 정의하면:
+//   · 한쪽 앱에서 broadcast 한 메시지가 다른 앱 연결로도 팬아웃되고,
+//   · 접속자 목록(presence)이 두 앱 것으로 병합되며,
+//   · 두 정의의 authorize/presenceInfo 가 갈려 한쪽의 공개 규칙이 다른 앱의 비공개
+//     메시지를 새게 한다(연결이 어느 앱 WS 로 붙었느냐로 훅이 갈리기 때문).
+// 잡·리스너의 동명 등록은 런타임에 throw 로 막지만(결정 271), 채널은 앱별 맵에
+// 따로 담겨 런타임 충돌 신호가 없다 — 그래서 정적 검사로 잡는다.
+//
+// 의도적 공유의 탈출구: 정의를 `shared/channels/<이름>.ts` 하나에 두고 각 앱 채널
+// 파일이 **재수출**하면 통과한다(정의 하나 = 훅·인가 규칙 하나 · shared 는 앱을
+// 모르므로 의존 방향 4규칙에도 맞다).
+//
+// 판정은 소스 텍스트 기반(가벼운 정적 검사) — 채널 모듈을 실행하지 않는다.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, resolve, dirname } from 'node:path';
+import { stripComments } from './source-scan.js';
+/**
+ * 소스가 default 를 다른 모듈에서 그대로 재수출만 하는지 판정하고 그 모듈 지정자를 낸다.
+ * `export { default } from '...'` · `export { default as default } from '...'` ·
+ * `export * from '...'` 를 인정한다(주석 제외 후 판정).
+ */
+export function reexportSpecifier(source) {
+    const src = stripComments(source);
+    const named = src.match(/export\s*\{\s*default(?:\s+as\s+default)?\s*\}\s*from\s*['"]([^'"]+)['"]/);
+    if (named)
+        return named[1];
+    const star = src.match(/export\s*\*\s*from\s*['"]([^'"]+)['"]/);
+    if (star)
+        return star[1];
+    return undefined;
+}
+/** 모듈 지정자를 파일 기준 절대경로로 해석한다(ESM `.js` → 소스 `.ts` 정규화). */
+function resolveSpecifier(fromFile, spec) {
+    if (!spec.startsWith('.'))
+        return undefined; // 패키지 지정자는 동일성 판정 불가.
+    const abs = resolve(dirname(fromFile), spec);
+    return abs.replace(/\.js$/, '.ts');
+}
+/** apps/ 를 훑어 앱간 동명 채널을 낸다. */
+export async function checkChannelCollision(cwd) {
+    const appsDir = join(cwd, 'apps');
+    // 채널 이름 → 정의 파일들.
+    const byName = new Map();
+    for (const app of await safeListDirs(appsDir)) {
+        const chDir = join(appsDir, app, 'channels');
+        for (const file of await safeListFiles(chDir)) {
+            if (!file.endsWith('.ts') || file.endsWith('.d.ts') || file.endsWith('.test.ts'))
+                continue;
+            const abs = join(chDir, file);
+            const name = file.slice(0, -3);
+            const spec = reexportSpecifier(await readFile(abs, 'utf8'));
+            const entry = {
+                app,
+                rel: relative(cwd, abs),
+                reexportTarget: spec ? resolveSpecifier(abs, spec) : undefined,
+            };
+            const list = byName.get(name);
+            if (list)
+                list.push(entry);
+            else
+                byName.set(name, [entry]);
+        }
+    }
+    const issues = [];
+    for (const [name, entries] of [...byName.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        if (entries.length < 2)
+            continue;
+        // readdir 순서에 보고가 흔들리지 않게 앱 이름으로 고정한다.
+        const files = [...entries].sort((a, b) => (a.app < b.app ? -1 : a.app > b.app ? 1 : 0));
+        // 전부 같은 모듈을 재수출하면 정의는 하나다 — 의도적 공유로 인정한다.
+        const targets = files.map((f) => f.reexportTarget);
+        if (targets.every((t) => t !== undefined && t === targets[0]))
+            continue;
+        const apps = files.map((f) => f.app).join(', ');
+        const list = files.map((f) => f.rel).join(' · ');
+        // 이름 변경을 권할 대상 — web 은 프리픽스 '/' 의 기본 앱이라 되도록 그대로 두고
+        // 비-web 앱 쪽 이름을 바꾸도록 제안한다(둘 다 비-web 이면 두 번째).
+        const target = files.find((f) => f.app !== 'web') ?? files[1];
+        const renamed = `${target.app}${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+        issues.push({
+            rule: 'channel-collision',
+            level: 'error',
+            file: files[0].rel,
+            message: `앱간 동명 채널 '${name}': ${apps} 앱이 각각 정의합니다(${list}).\n` +
+                `채널 이름은 전역입니다 — 브로드캐스트 subject(gaon.chan.${name})와 프레즌스 키에 앱 프리픽스가 ` +
+                `없어 두 앱의 연결이 같은 채널로 팬아웃되고 접속자 목록이 병합됩니다. 두 정의의 authorize 가 다르면 ` +
+                `한쪽의 공개 규칙으로 다른 앱 메시지가 샙니다.\n` +
+                `→ 앱마다 이름을 분리하세요: apps/${target.app}/channels/${renamed}.ts ` +
+                `(클라이언트 useChannel('${renamed}') 도 함께 바꿉니다).\n` +
+                `→ 일부러 공유하는 채널이면 정의를 shared/channels/${name}.ts 하나에 두고 각 앱 채널 파일에서 재수출하세요:\n` +
+                `   export { default } from '../../../shared/channels/${name}.js'`,
+            detail: { channel: name, apps: files.map((f) => f.app), files: files.map((f) => f.rel) },
+        });
+    }
+    return { rule: 'channel-collision', issues };
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+async function safeListFiles(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isFile()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/doctor/fixers/index.d.ts

@@ -14,7 +14,7 @@ export declare const FIXERS: Partial<Record<DoctorRule, Fixer>>;
  * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
  * 수동 · 이유는 무엇인지 표시하는 데 쓴다(진단 = 수리 안내서 · §7.5.3).
  *
- * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 28종을 **빠짐없이** 담는다 —
+ * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 29종을 **빠짐없이** 담는다 —
  * fixer 가 없는 규칙도 `hasFixer:false` + 구체적 수동 안내로 명시한다. 항목이
  * 빠지면 --fix 리포트가 그 규칙 위반에 대해 일반 문구("수동 수정 필요")만 내
  * 사용자가 왜 자동이 안 되는지 알 수 없다. 전수성은 테스트가 고정한다

package/dist/doctor/fixers/index.js

@@ -28,7 +28,7 @@ export const FIXERS = {
  * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
  * 수동 · 이유는 무엇인지 표시하는 데 쓴다(진단 = 수리 안내서 · §7.5.3).
  *
- * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 28종을 **빠짐없이** 담는다 —
+ * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 29종을 **빠짐없이** 담는다 —
  * fixer 가 없는 규칙도 `hasFixer:false` + 구체적 수동 안내로 명시한다. 항목이
  * 빠지면 --fix 리포트가 그 규칙 위반에 대해 일반 문구("수동 수정 필요")만 내
  * 사용자가 왜 자동이 안 되는지 알 수 없다. 전수성은 테스트가 고정한다
@@ -175,4 +175,9 @@ export const FIXER_CAPABILITIES = [
         hasFixer: false,
         note: '수동 · 로케일 간 누락 키는 각 카탈로그(locales/*.json)에 채우세요 — 번역문은 사람이 작성합니다(결정 216).',
     },
+    {
+        rule: 'channel-collision',
+        hasFixer: false,
+        note: '수동 · 앱마다 채널 이름을 분리(파일명 + 클라이언트 useChannel 인자 동시 변경)하거나, 의도적 공유면 정의를 shared/channels/ 하나로 옮기고 각 앱에서 재수출하세요 — 어느 쪽인지는 설계 판단이라 자동 정정하지 않습니다.',
+    },
 ];

package/dist/doctor/locale-parity.js

@@ -11,7 +11,7 @@
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { loadLocales, flattenKeys } from '@gaonjs/i18n';
-import { analyzeProjectI18n } from '../i18n-config.js';
+import { analyzeProjectI18n, resolveLocalesDir } from '../i18n-config.js';
 // 경고 한 줄이 폭주하지 않게 나열 상한 — 넘으면 "…외 N개" 로 접는다(detail 에는 전량).
 const MAX_KEYS_SHOWN = 20;
 // i18next 복수형 접미사(결정 181 · generator.ts 와 동일 규약). 로케일마다 필요한 접미사만
@@ -29,7 +29,7 @@ function pluralBase(key) {
 export async function checkLocaleParity(cwd) {
     // 결정 352: 카탈로그 위치는 config i18n.dir 을 따른다(정적 분석 · 하드코딩이던
     // 'locales' 는 dir 커스텀 프로젝트에서 이 검사를 무소음으로 껐다).
-    const localesDir = join(cwd, analyzeProjectI18n(cwd).dir ?? 'locales');
+    const localesDir = resolveLocalesDir(cwd, analyzeProjectI18n(cwd).dir);
     if (!existsSync(localesDir))
         return { rule: 'locale-parity', issues: [] };
     const resources = loadLocales(localesDir);

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env' | 'locale-parity' | 'render-return';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env' | 'locale-parity' | 'render-return' | 'channel-collision';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor.d.ts

@@ -24,17 +24,25 @@ export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActio
 export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
 export { checkLocaleParity } from './doctor/locale-parity.js';
+export { checkChannelCollision, reexportSpecifier } from './doctor/channel-collision.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 28개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 29개 모두.
  */
 /**
- * doctor 정적 검사 28종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 29종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */
 export declare const ALL_RULES: readonly DoctorRule[];
+/**
+ * `gaon help` 이 doctor 한 줄에 요약할 규칙별 문구(§2.2 상세는 AGENTS). 타입이
+ * `Record<DoctorRule, …>` 라 **규칙을 늘리면 여기도 채워야 컴파일된다** — 손유지
+ * 산문 열거가 뒤처져 새 검사가 help 에서 통째로 빠지던 표류를 컴파일 에러로 바꾼다
+ * (channel-collision 편입 때 실제로 한 곳이 누락됐다).
+ */
+export declare const RULE_SUMMARIES: Record<DoctorRule, string>;
 export interface DoctorCommandOptions {
     readonly cwd?: string;
     readonly json?: boolean;

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 28 검사를 조립한다:
+ * 29 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -30,6 +30,7 @@
  * 26) no-import-meta-env (결정 198 · F-9 ② · `.vue` 의 import.meta.env = TS1470 → env 접근자 안내 error)
  * 27) locale-parity (결정 216 · 13차 W4 · 로케일 간 키 부분 누락 = fallback 조용 노출 경고)
  * 28) render-return (결정 340 · this.render/redirect/json 호출만 하고 return 누락 = 무신호 204 경고)
+ * 29) channel-collision (§7 · 앱간 동명 채널 = 전역 subject·프레즌스 병합 error)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -70,6 +71,7 @@ import { checkPageLayoutBreakpoint } from './doctor/page-layout-breakpoint.js';
 import { checkLinkButtonNesting } from './doctor/link-button-nesting.js';
 import { checkNoImportMetaEnv } from './doctor/no-import-meta-env.js';
 import { checkLocaleParity } from './doctor/locale-parity.js';
+import { checkChannelCollision } from './doctor/channel-collision.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -97,13 +99,14 @@ export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActio
 export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
 export { checkLocaleParity } from './doctor/locale-parity.js';
+export { checkChannelCollision, reexportSpecifier } from './doctor/channel-collision.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 28개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 29개 모두.
  */
 /**
- * doctor 정적 검사 28종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 29종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */
@@ -136,7 +139,45 @@ export const ALL_RULES = [
     'no-import-meta-env',
     'locale-parity',
     'render-return',
+    'channel-collision',
 ];
+/**
+ * `gaon help` 이 doctor 한 줄에 요약할 규칙별 문구(§2.2 상세는 AGENTS). 타입이
+ * `Record<DoctorRule, …>` 라 **규칙을 늘리면 여기도 채워야 컴파일된다** — 손유지
+ * 산문 열거가 뒤처져 새 검사가 help 에서 통째로 빠지던 표류를 컴파일 에러로 바꾼다
+ * (channel-collision 편입 때 실제로 한 곳이 누락됐다).
+ */
+export const RULE_SUMMARIES = {
+    'response-mixing': '응답 혼용',
+    'n-plus-one': 'N+1',
+    'dependency-direction': '의존 방향',
+    connections: '커넥션',
+    'migration-diff': '마이그 diff',
+    'shared-purity': 'shared 순수',
+    'no-auto-import': '자동 import',
+    'schema-filename': '스키마 파일명',
+    'agents-doc-index': 'AGENTS 색인',
+    'column-casing': '컬럼 casing',
+    'model-filename': '모델 파일명',
+    'page-filename': '페이지 파일명',
+    'auth-wiring': '인증 배선',
+    'ui-kit-wiring': 'UI 킷 배선',
+    'route-registration': '라우트 등록',
+    'static-collision': '정적 충돌',
+    'method-override': '_method',
+    'csrf-wiring': 'CSRF 배선',
+    'internal-anchor': '내부 앵커',
+    'pageprops-destructure': 'pageProps 구조분해',
+    'async-offload': '비동기 오프로드',
+    'page-layout-breakpoint': '페이지 레이아웃 브레이크포인트',
+    'link-button-nesting': 'Link>Button 중첩',
+    'seal-security': 'seal 클라 배선·보안 역전',
+    'schema-relations': '§4.5 관계',
+    'no-import-meta-env': 'import.meta.env',
+    'locale-parity': '로케일 커버리지',
+    'render-return': 'render return 누락',
+    'channel-collision': '앱간 동명 채널',
+};
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
     'n-plus-one': checkNPlusOne,
@@ -166,6 +207,7 @@ const CHECKERS = {
     'no-import-meta-env': checkNoImportMetaEnv,
     'locale-parity': checkLocaleParity,
     'render-return': checkRenderReturn,
+    'channel-collision': checkChannelCollision,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/generate.d.ts

@@ -32,6 +32,11 @@ export interface ScaffoldResult {
      */
     readonly incomplete: boolean;
 }
+/**
+ * 결정 338: 앱별 JWT secret 환경변수명 — '<APP>_JWT_SECRET' (세션 secret 관례와 대칭).
+ * doctor auth-wiring 의 JWT 수리 안내가 같은 이름을 제시해야 해 export 한다(단일 출처).
+ */
+export declare function jwtSecretEnvFor(app: string): string;
 /**
  * 결정 155·142: `g auth --app <앱>` 이 앱별 세션 secret 환경변수를 .env·.env.example
  * 에도 시드한다. web 은 SESSION_SECRET 이 프로젝트 스캐폴드(.env.example.tpl)에 이미

package/dist/generate.js

@@ -65,8 +65,11 @@ function devSessionSecretFor(app) {
 function envSecretPlaceholderFor(app) {
     return `change-me-to-a-32-char-${app}-session-secret!!`;
 }
-/** 결정 338: 앱별 JWT secret 환경변수명 — '<APP>_JWT_SECRET' (세션 secret 관례와 대칭). */
-function jwtSecretEnvFor(app) {
+/**
+ * 결정 338: 앱별 JWT secret 환경변수명 — '<APP>_JWT_SECRET' (세션 secret 관례와 대칭).
+ * doctor auth-wiring 의 JWT 수리 안내가 같은 이름을 제시해야 해 export 한다(단일 출처).
+ */
+export function jwtSecretEnvFor(app) {
     return `${app.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_JWT_SECRET`;
 }
 /** .env(.example)에 시드할 앱별 JWT secret 플레이스홀더(32자 이상 · 운영은 교체 — 결정 337 가드 대상). */
@@ -382,8 +385,13 @@ export function runGenerateAuthCommand(opts = {}) {
     const app = opts.app ?? 'web';
     // 결정 338: JWT 는 API 앱 전용(§7 · web 은 세션이 정본). 형식 불량은 즉시 수리 안내.
     if (opts.jwt && (opts.app === undefined || app === 'web')) {
+        // 결정 338: API(JWT) 앱은 이 명령 **하나**가 앱 폴더째 만든다(routes·컨트롤러·app.config).
+        // 이전 힌트는 `gaon g app api && gaon g auth --jwt --app api` 를 권했는데, 앞 명령이
+        // 만든 app.config.ts·Vue 프론트(pages/layouts) 때문에 뒤 명령이 JWT 배선을 자동 추가하지
+        // 못하고 incomplete → exit 1 로 끝났다(결정 361). API 앱에는 쓰지 않는 Vue 페이지까지
+        // 남는다 — 권하는 순서가 곧 실패 경로였던 셈이라 단독 실행을 정본으로 못박는다.
         process.stderr.write(`  ✗ gaon g auth --jwt: JWT 는 API 앱 전용입니다 — 대상 API 앱을 --app 으로 지정하세요(web 불가 · 세션이 정본).\n` +
-            `  → 예: gaon g app api && gaon g auth --jwt --app api\n`);
+            `  → 예: gaon g auth --jwt --app api  (이 명령 하나가 apps/api/ 를 통째로 만듭니다 — gaon g app 을 먼저 돌리지 마세요)\n`);
         return 1;
     }
     if (opts.jwt && opts.public) {

package/dist/i18n-config.d.ts

@@ -5,8 +5,28 @@ export interface ConfigI18nAnalysis {
     readonly dir?: string;
     /** 정적 리터럴로 읽힌 fallbackLng. 못 읽으면 undefined. */
     readonly fallbackLng?: string;
+    /** 정적 리터럴 배열로 읽힌 supportedLngs(결정 413 · check 미러용). 못 읽으면 undefined. */
+    readonly supportedLngs?: readonly string[];
+    /**
+     * 결정 412: **선언은 있는데 정적으로 못 읽은** 키들(예 `dir: LOCALES_DIR`).
+     * 이 경우 런타임은 실값을, 타입 축·doctor 는 폴백('locales'·정렬 첫 로케일)을 써서
+     * 두 축이 갈라진다 — 호출자가 경고를 낼 수 있게 표면화한다(무신호 금지).
+     */
+    readonly unresolved: readonly ('dir' | 'fallbackLng')[];
 }
 /** gaon.config.ts 소스에서 i18n 블록의 dir·fallbackLng 리터럴을 뽑는다. */
 export declare function analyzeConfigI18n(source: string): ConfigI18nAnalysis;
 /** cwd 의 gaon.config.ts 를 읽어 i18n 블록을 분석한다. 파일이 없으면 미선언. */
 export declare function analyzeProjectI18n(cwd: string): ConfigI18nAnalysis;
+/**
+ * 결정 412: 카탈로그 디렉터리의 절대 경로. `dir` 이 절대 경로면 그대로 쓴다 —
+ * wire(런타임)는 이미 그렇게 해석하는데 CLI 축만 무조건 join 해서
+ * `join('/proj','/var/locales')` = `/proj/var/locales` 로 조용히 빗나갔다.
+ */
+export declare function resolveLocalesDir(cwd: string, dir: string | undefined): string;
+/**
+ * 결정 412: 정적으로 못 읽은 i18n 키를 한 줄 경고로 알린다(무신호 금지). 런타임은
+ * 실값을, 타입 축·doctor 는 폴백을 쓰므로 messages.d.ts 가 엉뚱한 카탈로그를 보거나
+ * 아예 안 생길 수 있다 — 어느 형태로 바꾸면 되는지까지 쓴다(§7.5.3).
+ */
+export declare function warnUnresolvedI18n(analysis: ConfigI18nAnalysis, write: (s: string) => void): void;

package/dist/i18n-config.js

@@ -15,23 +15,64 @@ export function analyzeConfigI18n(source) {
     let declared = false;
     let dir;
     let fallbackLng;
+    let supportedLngs;
+    const unresolved = new Set();
+    // 결정 412: `as`·`satisfies` 래핑을 벗긴다 — defineConfig({...} satisfies GaonConfig)
+    // 는 실사용 형태인데 종전엔 객체 리터럴이 아니라고 보고 i18n 선언 자체를 놓쳤다.
+    const unwrap = (node) => {
+        let e = node;
+        while (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isSatisfiesExpression(e)) {
+            e = e.expression;
+        }
+        return e;
+    };
+    // 문자열 리터럴 + 치환 없는 템플릿 리터럴(`translations`)을 함께 읽는다 — 개발자
+    // 눈에는 똑같은 리터럴인데 종전엔 템플릿만 무소음으로 빠졌다(결정 412).
+    const literalText = (e) => {
+        const n = unwrap(e);
+        if (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n))
+            return n.text;
+        return undefined;
+    };
     // i18n 초기화식에서 객체 리터럴을 찾는다 — 삼항·??·&&·괄호는 양변을 훑는다
     // (connections.ts 와 동일 규약 · env 조건부 블록 대응). 두 분기가 서로 다른
     // 리터럴을 주는 병리적 케이스는 먼저 읽힌 값을 쓴다(실사용 형태 아님).
-    const collect = (node) => {
-        if (ts.isParenthesizedExpression(node))
-            return collect(node.expression);
+    const collect = (raw) => {
+        const node = unwrap(raw);
         if (ts.isObjectLiteralExpression(node)) {
             for (const p of node.properties) {
+                // 결정 412: shorthand(`{ i18n }`)·스프레드는 값을 여기서 알 수 없다 — 조용히
+                // 넘기지 않고 미해석으로 표시한다.
+                if (ts.isShorthandPropertyAssignment(p) || ts.isSpreadAssignment(p)) {
+                    unresolved.add('dir');
+                    unresolved.add('fallbackLng');
+                    continue;
+                }
                 if (!ts.isPropertyAssignment(p))
                     continue;
                 const name = propNameText(p.name);
-                if (name === 'dir' && ts.isStringLiteral(p.initializer) && dir === undefined) {
-                    dir = p.initializer.text;
+                // 결정 413: supportedLngs 는 리터럴 배열일 때만 읽는다(check 정적 미러용).
+                if (name === 'supportedLngs' && supportedLngs === undefined) {
+                    const arr = unwrap(p.initializer);
+                    if (ts.isArrayLiteralExpression(arr)) {
+                        const items = arr.elements.map((el) => literalText(el));
+                        if (items.every((v) => v !== undefined))
+                            supportedLngs = items;
+                    }
+                    continue;
                 }
-                if (name === 'fallbackLng' && ts.isStringLiteral(p.initializer) && fallbackLng === undefined) {
-                    fallbackLng = p.initializer.text;
+                if (name !== 'dir' && name !== 'fallbackLng')
+                    continue;
+                const text = literalText(p.initializer);
+                if (text === undefined) {
+                    // 변수 참조·env 표현식 등 — 런타임 실값과 갈라지는 지점.
+                    unresolved.add(name);
+                    continue;
                 }
+                if (name === 'dir' && dir === undefined)
+                    dir = text;
+                if (name === 'fallbackLng' && fallbackLng === undefined)
+                    fallbackLng = text;
             }
             return;
         }
@@ -53,8 +94,16 @@ export function analyzeConfigI18n(source) {
     const visit = (node) => {
         if (ts.isCallExpression(node) && isDefineConfig(node.expression)) {
             const arg = node.arguments[0];
-            if (arg && ts.isObjectLiteralExpression(arg)) {
-                for (const p of arg.properties) {
+            const obj = arg ? unwrap(arg) : undefined;
+            if (obj && ts.isObjectLiteralExpression(obj)) {
+                for (const p of obj.properties) {
+                    if (ts.isShorthandPropertyAssignment(p) && p.name.text === 'i18n') {
+                        // `defineConfig({ i18n })` — 선언은 확실하나 값은 정적으로 못 읽는다.
+                        declared = true;
+                        unresolved.add('dir');
+                        unresolved.add('fallbackLng');
+                        continue;
+                    }
                     if (ts.isPropertyAssignment(p) && propNameText(p.name) === 'i18n') {
                         declared = true;
                         collect(p.initializer);
@@ -65,20 +114,46 @@ export function analyzeConfigI18n(source) {
         ts.forEachChild(node, visit);
     };
     visit(sf);
-    return { declared, dir, fallbackLng };
+    // 읽힌 키는 미해석 목록에서 뺀다(한 분기만 리터럴인 경우 값이 있으면 그 값을 쓴다).
+    if (dir !== undefined)
+        unresolved.delete('dir');
+    if (fallbackLng !== undefined)
+        unresolved.delete('fallbackLng');
+    return { declared, dir, fallbackLng, supportedLngs, unresolved: [...unresolved] };
 }
 /** cwd 의 gaon.config.ts 를 읽어 i18n 블록을 분석한다. 파일이 없으면 미선언. */
 export function analyzeProjectI18n(cwd) {
     const configPath = join(cwd, 'gaon.config.ts');
     if (!existsSync(configPath))
-        return { declared: false };
+        return { declared: false, unresolved: [] };
     try {
         return analyzeConfigI18n(readFileSync(configPath, 'utf8'));
     }
     catch {
-        return { declared: false };
+        return { declared: false, unresolved: [] };
     }
 }
+/**
+ * 결정 412: 카탈로그 디렉터리의 절대 경로. `dir` 이 절대 경로면 그대로 쓴다 —
+ * wire(런타임)는 이미 그렇게 해석하는데 CLI 축만 무조건 join 해서
+ * `join('/proj','/var/locales')` = `/proj/var/locales` 로 조용히 빗나갔다.
+ */
+export function resolveLocalesDir(cwd, dir) {
+    const d = dir ?? 'locales';
+    return d.startsWith('/') ? d : join(cwd, d);
+}
+/**
+ * 결정 412: 정적으로 못 읽은 i18n 키를 한 줄 경고로 알린다(무신호 금지). 런타임은
+ * 실값을, 타입 축·doctor 는 폴백을 쓰므로 messages.d.ts 가 엉뚱한 카탈로그를 보거나
+ * 아예 안 생길 수 있다 — 어느 형태로 바꾸면 되는지까지 쓴다(§7.5.3).
+ */
+export function warnUnresolvedI18n(analysis, write) {
+    if (analysis.unresolved.length === 0)
+        return;
+    write(`  ! gaon.config.ts 의 i18n ${analysis.unresolved.join('·')} 을(를) 정적으로 읽지 못했습니다 — ` +
+        `타입 축(.gaon/messages.d.ts)과 doctor 는 기본값(dir='locales' · 기준=정렬 첫 로케일)을 씁니다.\n` +
+        `    → 문자열 리터럴로 직접 쓰면 정확히 반영됩니다: i18n: { dir: 'locales', fallbackLng: 'ko' }\n`);
+}
 function isDefineConfig(e) {
     if (ts.isIdentifier(e) && e.text === 'defineConfig')
         return true;