@gaonjs/cli 0.63.1 → 0.65.0

package/dist/doctor/i18n-app-scope.js

@@ -1,4 +1,4 @@
-// @gaonjs/cli · doctor · 앱 경계를 넘는 클라 번역 키 (결정 454 · 에러)
+// @gaonjs/cli · doctor · 앱 경계를 넘는 클라 번역 키 (결정 454 · 459 · 에러)
 //
 // **왜 doctor 가 필요한가(타입으로 못 잡는 축)**: 두 앱이 `GaonMessages.keys` 를 서로 다른
 // 유니온으로 augment 하면 TS2717(Subsequent property declarations must have the same type)이
@@ -8,14 +8,22 @@
 //   · 정적   = 이 검사 — 앱 코드가 **다른 앱 전용 키**를 쓰면 에러로 잡는다.
 //
 // 그냥 두면 컴파일은 통과하고 화면에는 키 문자열이 그대로 뜬다(조용한 실패).
+//
+// 결정 459 로 두 가지가 바뀐다:
+//   · 공용 frontend 스코프가 폐지돼 그 앱이 보는 키 = **자기 앱 frontend 뿐**이다.
+//   · `shared/**` 컴포넌트의 t() 키는 **모든 앱**에 있어야 한다(O1) — shared 는 어느 앱
+//     번들에도 실릴 수 있는데 키가 한 앱에만 있으면 다른 앱 화면에서만 키가 뜬다.
+//     문구를 props 로 끌어올리는 대안(O1 (b))은 원자 컴포넌트마다 label prop 이 생겨
+//     결정 454 가 없앤 "선언 지점 3곳" 통증을 되살리므로 기각했다 — 복제 + 이 검사다.
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { flattenKeys, loadAppLocales, loadScopedLocales, withPluralBaseKeys } from '@gaonjs/i18n';
-import { analyzeProjectI18n, resolveLocalesDir } from '../i18n-config.js';
+import { flattenKeys, loadProjectLocales, withPluralBaseKeys } from '@gaonjs/i18n';
+import { analyzeProjectI18n } from '../i18n-config.js';
 // `import { t } from 'gaonjs/vue'` 를 쓴 파일에서만 본다 — 서버 t(gaonjs/i18n)는 대상이 아니다.
 const CLIENT_T_IMPORT = /from\s+['"]gaonjs\/vue['"]/;
 // t('key') · t("key") · t(`key`) 의 리터럴 키만 본다(동적 키는 정적 검출 대상 아님).
-const T_CALL = /\bt\(\s*['"`]([^'"`]+)['"`]/g;
+// i18n-server-scope(결정 459)가 같은 규약으로 서버 t() 를 훑는다 — 한 벌만 둔다.
+export const T_CALL = /\bt\(\s*['"`]([^'"`]+)['"`]/g;
 /**
  * 주석을 공백으로 지운다(문자열 리터럴 안의 `//`·`/*` 는 보존). 스캐폴드·문서 주석이
  * 예시로 적은 `t('키')` 를 실 호출로 오인해 **오탐 에러**를 내던 것을 막는다(브라우저 e2e
@@ -79,7 +87,8 @@ export function stripComments(src) {
 }
 const SOURCE_EXT = ['.vue', '.ts'];
 const SKIP_DIRS = new Set(['node_modules', 'dist', '.gaon']);
-function walk(dir, out = []) {
+/** 소스 파일을 재귀 수집한다(생성물·의존성 제외). i18n-server-scope 와 공유. */
+export function walkSources(dir, exts = SOURCE_EXT, out = []) {
     if (!existsSync(dir))
         return out;
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -89,90 +98,110 @@ function walk(dir, out = []) {
             continue;
         const p = join(dir, entry.name);
         if (entry.isDirectory())
-            walk(p, out);
-        else if (SOURCE_EXT.some((e) => entry.name.endsWith(e)))
+            walkSources(p, exts, out);
+        else if (exts.some((e) => entry.name.endsWith(e)))
             out.push(p);
     }
     return out;
 }
-/** 그 앱의 클라가 실제로 받는 키 집합 = 공용 frontend ∪ 자기 앱 카탈로그(전 로케일 합집합). */
-function keysForApp(localesDir, appLocalesDir) {
-    const scoped = loadScopedLocales(localesDir);
+/** 카탈로그의 전 로케일 키 합집합(복수형 base 포함). */
+function keysOf(res) {
     const keys = new Set();
-    for (const res of Object.values(scoped.frontend)) {
-        for (const k of withPluralBaseKeys(flattenKeys(res.translation)))
-            keys.add(k);
-    }
-    for (const res of Object.values(loadAppLocales(appLocalesDir))) {
-        for (const k of withPluralBaseKeys(flattenKeys(res.translation)))
+    for (const entry of Object.values(res)) {
+        for (const k of withPluralBaseKeys(flattenKeys(entry.translation)))
             keys.add(k);
     }
     return keys;
 }
-/** 프로젝트 전체(모든 앱)의 클라 키 — "다른 앱에는 있는 키" 인지 구분해 안내를 정확히 한다. */
-function allClientKeys(localesDir, appDirs) {
-    const keys = keysForApp(localesDir, '');
-    for (const appDir of appDirs) {
-        for (const res of Object.values(loadAppLocales(join(appDir, 'locales')))) {
-            for (const k of withPluralBaseKeys(flattenKeys(res.translation)))
-                keys.add(k);
-        }
-    }
-    return keys;
+/** 파일에서 클라 t() 리터럴 키를 뽑는다(주석 안 예시는 제외 · 줄 번호 포함). */
+function clientKeyUses(file) {
+    const raw = readFileSync(file, 'utf8');
+    if (!CLIENT_T_IMPORT.test(raw))
+        return [];
+    // 주석 안 예시(`t('키')` 같은 설명)를 실 호출로 세지 않는다 — 오탐은 빌드를 세운다.
+    const src = stripComments(raw);
+    return [...src.matchAll(T_CALL)].map((m) => ({
+        key: m[1],
+        line: src.slice(0, m.index).split('\n').length,
+    }));
 }
 export async function checkI18nAppScope(cwd) {
-    const appsDir = join(cwd, 'apps');
-    if (!existsSync(appsDir))
-        return { rule: 'i18n-app-scope', issues: [] };
-    const cfg = analyzeProjectI18n(cwd);
-    const localesDir = resolveLocalesDir(cwd, cfg.dir);
-    if (!existsSync(localesDir))
-        return { rule: 'i18n-app-scope', issues: [] };
-    const appDirs = readdirSync(appsDir, { withFileTypes: true })
-        .filter((e) => e.isDirectory())
-        .map((e) => join(appsDir, e.name));
-    // frontend 카탈로그가 하나도 없으면(레거시 레이아웃) 클라 t() 자체가 없다 — 무소음.
-    const scoped = loadScopedLocales(localesDir);
-    if (Object.keys(scoped.frontend).length === 0)
-        return { rule: 'i18n-app-scope', issues: [] };
-    const everyKey = allClientKeys(localesDir, appDirs);
+    const rule = 'i18n-app-scope';
+    if (!existsSync(join(cwd, 'apps')))
+        return { rule, issues: [] };
+    if (!analyzeProjectI18n(cwd).declared)
+        return { rule, issues: [] };
+    let project;
+    try {
+        project = loadProjectLocales(cwd);
+    }
+    catch {
+        // 로더 fail-loud 는 i18n-layout·check 가 소유한다 — 여기선 침묵(중복 진단 금지).
+        return { rule, issues: [] };
+    }
+    const frontendByApp = new Map();
+    for (const [app, scoped] of Object.entries(project.apps))
+        frontendByApp.set(app, keysOf(scoped.frontend));
+    // frontend 카탈로그가 하나도 없으면 클라 t() 축 자체가 없다 — 무소음.
+    if ([...frontendByApp.values()].every((s) => s.size === 0))
+        return { rule, issues: [] };
+    const everyKey = new Set();
+    for (const keys of frontendByApp.values())
+        for (const k of keys)
+            everyKey.add(k);
     const issues = [];
-    for (const appDir of appDirs) {
-        const appLocales = join(appDir, 'locales');
-        const own = keysForApp(localesDir, appLocales);
-        for (const file of walk(appDir)) {
+    // ① 앱 코드 — 그 앱 frontend 에 있어야 한다(결정 459: 공용 스코프가 없어 폴백이 1단).
+    for (const [app, own] of frontendByApp) {
+        const appDir = join(cwd, 'apps', app);
+        for (const file of walkSources(appDir)) {
             if (!statSync(file).isFile())
                 continue;
-            const raw = readFileSync(file, 'utf8');
-            if (!CLIENT_T_IMPORT.test(raw))
-                continue;
-            // 주석 안 예시(`t('키')` 같은 설명)를 실 호출로 세지 않는다 — 오탐은 빌드를 세운다.
-            const src = stripComments(raw);
-            for (const m of src.matchAll(T_CALL)) {
-                const key = m[1];
+            for (const { key, line } of clientKeyUses(file)) {
                 if (own.has(key))
                     continue;
-                const line = src.slice(0, m.index).split('\n').length;
                 const rel = relative(cwd, file);
                 const elsewhere = everyKey.has(key);
                 issues.push({
-                    rule: 'i18n-app-scope',
+                    rule,
                     level: 'error',
                     file: rel,
                     line,
-                    message: elsewhere
-                        ? `'${key}' 는 **다른 앱 전용** 번역 키입니다 — 이 앱의 카탈로그에 없습니다: ${rel}:${line} (결정 454)\n` +
-                            `  앱 번들에는 그 앱 카탈로그만 실리므로 런타임에 번역 대신 키 문자열이 그대로 보입니다.\n` +
-                            `→ 이 앱에서도 쓸 문구면 공용 ${relative(cwd, join(localesDir, '<로케일>', 'frontend.json'))} 로 옮기고,\n` +
-                            `→ 이 앱 전용 문구면 ${relative(cwd, join(appLocales, '<로케일>.json'))} 에 추가한 뒤 gaon gen 을 실행하세요.`
-                        : `'${key}' 를 어느 카탈로그에서도 찾을 수 없습니다: ${rel}:${line} (결정 454)\n` +
-                            `→ ${relative(cwd, join(appLocales, '<로케일>.json'))}(앱 전용) 또는 ` +
-                            `${relative(cwd, join(localesDir, '<로케일>', 'frontend.json'))}(앱 공용)에 키를 추가하고 gaon gen 을 실행하세요.\n` +
-                            `  (서버 전용 문구는 backend.json 에 두고 서버 t()(gaonjs/i18n)로 쓰세요 — 클라로 나가지 않습니다.)`,
-                    detail: { key, app: relative(cwd, appDir), definedInAnotherApp: elsewhere },
+                    message: (elsewhere
+                        ? `'${key}' 는 **다른 앱 전용** 번역 키입니다 — 이 앱의 카탈로그에 없습니다: ${rel}:${line} (결정 459)\n`
+                        : `'${key}' 를 어느 앱 카탈로그에서도 찾을 수 없습니다: ${rel}:${line} (결정 459)\n`) +
+                        `  앱 번들에는 그 앱 카탈로그만 실리므로 런타임에 번역 대신 키 문자열이 그대로 보입니다.\n` +
+                        `→ apps/${app}/locales/<로케일>/frontend.json 에 이 키를 추가하고 gaon gen 을 실행하세요.\n` +
+                        `  (여러 앱이 함께 쓰는 문구면 각 앱의 frontend.json 에 같은 키를 둡니다 — 공용 카탈로그는 없습니다.)\n` +
+                        `  (서버 전용 문구는 backend.json 에 두고 서버 t()(gaonjs/i18n)로 쓰세요 — 클라로 나가지 않습니다.)`,
+                    detail: { key, app, definedInAnotherApp: elsewhere },
                 });
             }
         }
     }
-    return { rule: 'i18n-app-scope', issues };
+    // ② shared 코드 — **모든 앱**에 있어야 한다(결정 459 O1). shared 컴포넌트는 어느 앱
+    //    번들에도 실릴 수 있어, 키가 한 앱에만 있으면 다른 앱 화면에서만 조용히 키가 뜬다.
+    const allApps = [...frontendByApp.keys()].sort();
+    for (const file of walkSources(join(cwd, 'shared'))) {
+        if (!statSync(file).isFile())
+            continue;
+        for (const { key, line } of clientKeyUses(file)) {
+            const missing = allApps.filter((a) => !frontendByApp.get(a).has(key));
+            if (missing.length === 0)
+                continue;
+            const rel = relative(cwd, file);
+            issues.push({
+                rule,
+                level: 'error',
+                file: rel,
+                line,
+                message: `shared 컴포넌트가 쓰는 '${key}' 가 일부 앱 카탈로그에 없습니다(누락: ${missing.join(', ')}): ${rel}:${line} (결정 459)\n` +
+                    `  shared/ 는 어느 앱 번들에도 실릴 수 있으므로, 그 키는 **모든 앱**에 있어야 합니다.\n` +
+                    `  한 앱에만 있으면 다른 앱 화면에서만 키 문자열이 뜨는 조용한 실패가 됩니다.\n` +
+                    `→ ${missing.map((a) => `apps/${a}/locales/<로케일>/frontend.json`).join(' · ')} 에 같은 키를 추가하고 gaon gen 을 실행하세요.\n` +
+                    `  (공용 카탈로그는 없습니다 — UI 원자 문구는 앱마다 복제하고 이 검사가 전 앱 존재를 강제합니다.)`,
+                detail: { key, scope: 'shared', missingApps: missing },
+            });
+        }
+    }
+    return { rule, issues };
 }

package/dist/doctor/i18n-layout.d.ts

@@ -1,4 +1,4 @@
 import type { RuleReport } from './types.js';
-/** 레거시 단일 파일 로케일 목록(폴더 레이아웃과 공존하면 로더가 별도로 fail-loud). */
+/** 폴더의 레거시 평면 로케일 파일 목록(`<로케일>.json`). */
 export declare function legacyLocaleFiles(localesDir: string): string[];
 export declare function checkI18nLayout(cwd: string): Promise<RuleReport>;

package/dist/doctor/i18n-layout.js

@@ -1,17 +1,25 @@
-// @gaonjs/cli · doctor · i18n 카탈로그 레이아웃 안내 (결정 454 · 경고)
+// @gaonjs/cli · doctor · i18n 카탈로그 레이아웃 이관 안내 (결정 454 · 459)
 //
-// 결정 454 의 정본 저작 레이아웃은 언어별 폴더 + 스코프 분리다:
-//   locales/<로케일>/backend.json  — 메일·잡·검증 등 **서버 전용**(클라로 안 나감)
-//   locales/<로케일>/frontend.json — 화면 문구(클라 t() 가 쓰는 카탈로그)
+// 결정 459 의 정본 저작 레이아웃은 **소유자 2개 × 스코프 파일**이다:
+//   domain/locales/<로케일>/backend.json      도메인 공통 서버 문구(메일·잡·검증)
+//   apps/<앱>/locales/<로케일>/frontend.json  그 앱 화면 문구(필수)
+//   apps/<앱>/locales/<로케일>/backend.json   그 앱 컨트롤러 서버 문구(선택)
 //
-// 레거시 단일 파일(`locales/<로케일>.json`)도 계속 **동작**하지만, 미분류 카탈로그는
-// 안전 기본으로 전량 backend 취급이라 **클라 `t()` 를 쓸 수 없다**(클라 키 축 미생성).
-// 그 사실을 조용히 두면 "왜 gaonjs/vue 의 t 가 키를 그대로 뱉지?" 로 시간을 태운다 —
-// 경고로 짚고 `--fix` 로 폴더 이관까지 해 준다(노출 방향 자동 분류는 하지 않는다).
+// 이 검사는 **옛 배치에서 새 배치로 가는 길**을 지목한다. 결정 459 O4 대로 전이 기간
+// (듀얼 리드)은 두지 않는다 — 한 릴리스 동안 "정답이 둘" 을 공식화하고 그 코드가 잔재로
+// 남는다. 대신 **조용한 degrade 를 금지**한다: 옛 배치를 그냥 두면 아무도 읽지 않는
+// 폴더가 되어 전 화면·전 메일이 키 문자열로 degrade 하므로(결정 455 는 그걸 우아하게
+// 만들 뿐 대량 누락은 사고다), 여기서 warning/error 로 짚고 `--fix` 로 옮겨 준다.
+//
+// 검출 4종:
+//   ① 루트 `locales/`          — 폐지된 공용 스코프(warning · --fix 로 이관)
+//   ② 앱 평면 `<로케일>.json`  — 스코프 폴더 이전 배치(warning · --fix 로 rename)
+//   ③ `domain/locales/<로케일>/frontend.json` — 도메인은 화면을 소유하지 않는다(error)
+//   ④ `gaon.config.ts` 의 `i18n.dir`         — 제거된 설정(error · O3)
 import { existsSync, readdirSync } from 'node:fs';
 import { basename, join, relative } from 'node:path';
-import { analyzeProjectI18n, resolveLocalesDir } from '../i18n-config.js';
-/** 레거시 단일 파일 로케일 목록(폴더 레이아웃과 공존하면 로더가 별도로 fail-loud). */
+import { analyzeProjectI18n } from '../i18n-config.js';
+/** 폴더의 레거시 평면 로케일 파일 목록(`<로케일>.json`). */
 export function legacyLocaleFiles(localesDir) {
     if (!existsSync(localesDir))
         return [];
@@ -20,28 +28,145 @@ export function legacyLocaleFiles(localesDir) {
         .map((e) => basename(e.name, '.json'))
         .sort();
 }
+/** 폴더의 언어 폴더 목록(`<로케일>/`). */
+function localeDirs(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort();
+}
+/** `apps/` 아래 앱 폴더 이름들(없으면 빈 배열). */
+function appNames(cwd) {
+    try {
+        return readdirSync(join(cwd, 'apps'), { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
 export async function checkI18nLayout(cwd) {
+    const rule = 'i18n-layout';
+    const issues = [];
+    const apps = appNames(cwd);
+    // ① 루트 locales/ — 폐지된 공용 스코프. backend 는 도메인으로, frontend 는 전 앱으로.
+    const rootLocales = join(cwd, 'locales');
+    if (existsSync(rootLocales)) {
+        for (const lng of localeDirs(rootLocales)) {
+            const backend = join(rootLocales, lng, 'backend.json');
+            const frontend = join(rootLocales, lng, 'frontend.json');
+            if (existsSync(backend)) {
+                const from = relative(cwd, backend);
+                const to = `domain/locales/${lng}/backend.json`;
+                issues.push({
+                    rule,
+                    level: 'warning',
+                    file: from,
+                    message: `루트 공용 카탈로그는 폐지됐습니다: ${from} (결정 459)\n` +
+                        `  이 파일은 더 이상 읽히지 않습니다 — 그대로 두면 메일·잡·검증 문구가 전부\n` +
+                        `  키 문자열로 degrade 합니다.\n` +
+                        `→ 자동 이관: gaon doctor --fix  (${from} → ${to})\n` +
+                        `  (도메인 공통 서버 문구의 새 정본 위치입니다. 내용·키는 그대로입니다.)`,
+                    detail: { locale: lng, kind: 'root-backend', from, to },
+                });
+            }
+            if (existsSync(frontend)) {
+                const from = relative(cwd, frontend);
+                // 화면 문구는 소유자가 앱이다 — 전 앱에 **복제**한다(어느 앱이 실제로 쓰는지는
+                // 정적으로 판정할 수 없다: 동적 키가 섞이면 오판이 화면 누락으로 나타난다).
+                // 되돌리기 쉬운 방향(복제 후 사람이 잉여 정리)만 자동화한다.
+                const to = apps.map((a) => `apps/${a}/locales/${lng}/frontend.json`);
+                issues.push({
+                    rule,
+                    level: 'warning',
+                    file: from,
+                    message: `루트 공용 카탈로그는 폐지됐습니다: ${from} (결정 459)\n` +
+                        `  화면 문구의 소유자는 **그 앱**입니다 — 이 파일은 더 이상 어느 번들에도 실리지 않습니다.\n` +
+                        (apps.length > 0
+                            ? `→ 자동 이관: gaon doctor --fix  (${to.join(' · ')} 로 **복제** · 기존 키와 병합)\n` +
+                                `  그 뒤 각 앱이 실제로 쓰지 않는 키는 사람이 지웁니다(doctor 가 남은 것을 계속 안내합니다).\n` +
+                                `  shared/ 컴포넌트가 쓰는 키는 **모든 앱에 있어야** 합니다 — i18n-app-scope 가 강제합니다.`
+                            : `→ apps/ 아래 앱이 없습니다. 앱을 만든 뒤(gaon g app) 다시 실행하세요.`),
+                    detail: { locale: lng, kind: 'root-frontend', from, to },
+                });
+            }
+        }
+        // 루트 레거시 단일 파일(`locales/ko.json`) — 미분류 = 서버 전용 취급이 안전 기본.
+        for (const lng of legacyLocaleFiles(rootLocales)) {
+            const from = relative(cwd, join(rootLocales, `${lng}.json`));
+            const to = `domain/locales/${lng}/backend.json`;
+            issues.push({
+                rule,
+                level: 'warning',
+                file: from,
+                message: `루트 공용 카탈로그(단일 파일 레이아웃)는 폐지됐습니다: ${from} (결정 459)\n` +
+                    `  이 파일은 더 이상 읽히지 않습니다.\n` +
+                    `→ 자동 이관: gaon doctor --fix  (${from} → ${to} · 내용·키 무변경)\n` +
+                    `  미분류 카탈로그는 **서버 전용**으로 옮깁니다(클라 노출은 되돌리기 어려운 방향이라\n` +
+                    `  자동화하지 않습니다). 화면 문구는 그 뒤 apps/<앱>/locales/<로케일>/frontend.json 으로 옮기세요.`,
+                detail: { locale: lng, kind: 'root-legacy', from, to },
+            });
+        }
+    }
+    // ② 앱 평면 `<로케일>.json` — 스코프 폴더 배치로 rename. 앱 카탈로그는 정의상
+    //    frontend 였으므로(결정 454 R7) frontend.json 으로 간다 — backend 로 보내면
+    //    화면이 즉시 빈다(방향이 루트와 반대인 이유).
+    for (const app of apps) {
+        const dir = join(cwd, 'apps', app, 'locales');
+        for (const lng of legacyLocaleFiles(dir)) {
+            const from = relative(cwd, join(dir, `${lng}.json`));
+            const to = `apps/${app}/locales/${lng}/frontend.json`;
+            issues.push({
+                rule,
+                level: 'warning',
+                file: from,
+                message: `앱 카탈로그가 평면 파일 레이아웃입니다: ${from} (결정 459)\n` +
+                    `  새 배치는 언어 폴더 + 스코프 파일입니다 — frontend(화면)와 backend(그 앱 서버 문구)를 나눕니다.\n` +
+                    `→ 자동 이관: gaon doctor --fix  (${from} → ${to} · 내용·키 무변경)\n` +
+                    `  앱 카탈로그는 지금까지 화면 문구 전용이었으므로 frontend 로 옮깁니다.\n` +
+                    `  그중 서버 전용 문구가 있으면 그 뒤 같은 폴더의 backend.json 으로 옮기세요.`,
+                detail: { locale: lng, kind: 'app-legacy', app, from, to },
+            });
+        }
+    }
+    // ③ domain/locales/<로케일>/frontend.json — 도메인은 화면을 소유하지 않는다(O8).
+    //    로더도 부팅에서 throw 한다 — 여기서 같은 사유를 먼저 낸다(정적 미러).
+    const domainLocales = join(cwd, 'domain', 'locales');
+    for (const lng of localeDirs(domainLocales)) {
+        const f = join(domainLocales, lng, 'frontend.json');
+        if (!existsSync(f))
+            continue;
+        const from = relative(cwd, f);
+        issues.push({
+            rule,
+            level: 'error',
+            file: from,
+            message: `도메인 카탈로그에는 frontend.json 을 둘 수 없습니다: ${from} (결정 459)\n` +
+                `  화면 문구의 소유자는 **그 앱**입니다 — 도메인은 화면을 소유하지 않습니다.\n` +
+                `  (이 상태로는 gaon serve 가 부팅에서 실패합니다.)\n` +
+                `→ apps/<앱>/locales/${lng}/frontend.json 으로 옮기세요(여러 앱이 쓰면 각 앱에 같은 키를).\n` +
+                `→ 서버 전용 문구라면 같은 폴더의 backend.json 으로 옮기세요.`,
+            detail: { locale: lng, kind: 'domain-frontend', from },
+        });
+    }
+    // ④ i18n.dir — 제거된 설정(O3). 위치가 관례로 고정된 이상 "정답이 둘" 을 만든다.
     const cfg = analyzeProjectI18n(cwd);
-    const localesDir = resolveLocalesDir(cwd, cfg.dir);
-    if (!existsSync(localesDir))
-        return { rule: 'i18n-layout', issues: [] };
-    const legacy = legacyLocaleFiles(localesDir);
-    if (legacy.length === 0)
-        return { rule: 'i18n-layout', issues: [] };
-    const issues = legacy.map((lng) => {
-        const rel = relative(cwd, join(localesDir, `${lng}.json`));
-        const dirRel = relative(cwd, join(localesDir, lng));
-        return {
-            rule: 'i18n-layout',
-            level: 'warning',
-            file: rel,
-            message: `로케일 '${lng}' 이 단일 파일 레이아웃입니다: ${rel} (결정 454)\n` +
-                `  이 카탈로그는 **서버 전용**으로 취급돼 클라이언트 t()(gaonjs/vue)가 쓸 수 없습니다.\n` +
-                `→ 자동 이관: gaon doctor --fix  (${rel} → ${dirRel}/backend.json)\n` +
-                `→ 그 뒤 화면에 보이는 문구만 ${dirRel}/frontend.json 으로 옮기고 gaon gen 을 실행하세요.\n` +
-                `  (frontend 만 클라 번들 청크로 나갑니다 — backend 문구는 노출되지 않습니다.)`,
-            detail: { locale: lng, from: rel, to: `${dirRel}/backend.json` },
-        };
-    });
-    return { rule: 'i18n-layout', issues };
+    if (cfg.dir !== undefined) {
+        issues.push({
+            rule,
+            level: 'error',
+            file: 'gaon.config.ts',
+            message: `gaon.config.ts 의 i18n.dir 은 제거된 설정입니다(dir: '${cfg.dir}') — 결정 459\n` +
+                `  카탈로그 위치는 이제 관례로 고정입니다: domain/locales/ · apps/<앱>/locales/.\n` +
+                `  이 설정은 아무 효과가 없으므로, 남겨 두면 "설정한 폴더를 읽겠지" 라는 오해만 만듭니다.\n` +
+                `→ gaon.config.ts 의 i18n 블록에서 dir 을 지우세요: i18n: { fallbackLng: '...', supportedLngs: [...] }\n` +
+                `→ 그 폴더에 카탈로그가 있다면 gaon doctor --fix 로 새 위치에 이관하세요.`,
+            detail: { kind: 'config-dir', dir: cfg.dir },
+        });
+    }
+    return { rule, issues };
 }

package/dist/doctor/i18n-server-scope.d.ts

@@ -0,0 +1,2 @@
+import type { RuleReport } from './types.js';
+export declare function checkI18nServerScope(cwd: string): Promise<RuleReport>;

package/dist/doctor/i18n-server-scope.js

@@ -0,0 +1,124 @@
+// @gaonjs/cli · doctor · 서버 번역 키의 소유자 경계 (결정 459 · 에러)
+//
+// **왜 새 검사가 필요한가**: 결정 459 가 서버 카탈로그를 두 소유자로 쪼개면서
+// **지금까지 없던 실패 유형**이 생겼다 — 도메인 코드(`domain/**`)가 앱 backend 키를
+// 쓰는 경우다. 이건 두 층 모두 놓친다:
+//
+//   · 타입   — 서버 키 유니온은 domain ∪ 전 앱(결정 459 O5)이라 **컴파일을 통과**한다.
+//     앱별로 유니온을 쪼개는 것은 TS2717 로 구조적으로 불가(결정 454 실측).
+//   · 런타임 — 요청 컨텍스트에서는 앱 네임스페이스가 상속돼(O6) **우연히 해석된다**.
+//     같은 코드가 워커(`gaon work`)·크론에서 불리면 앱 스코프가 없어 키가 빈다.
+//
+// 즉 "개발 중엔 되는데 잡에서만 키 문자열이 뜬다" 는 가장 나쁜 형태로 샌다. 결정 455 의
+// 2단 계약(빌드=차단 / 런타임=키 렌더+경고)에서 **빌드=차단의 절반이 무너지는** 지점이라
+// 정적으로 못박는다.
+//
+// 검사 대상은 서버 t(`import { t } from 'gaonjs/i18n'`)뿐이다 — 클라 t(`gaonjs/vue`)의
+// 앱 경계는 `i18n-app-scope` 가 소유한다(축이 다르고 수리 안내가 갈린다 · ADR §6-C).
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { flattenKeys, loadProjectLocales, withPluralBaseKeys } from '@gaonjs/i18n';
+import { analyzeProjectI18n } from '../i18n-config.js';
+import { stripComments, walkSources, T_CALL } from './i18n-app-scope.js';
+// `import { t } from 'gaonjs/i18n'` 를 쓴 파일에서만 본다.
+const SERVER_T_IMPORT = /from\s+['"]gaonjs\/i18n['"]/;
+/** 카탈로그의 전 로케일 키 합집합(복수형 base 포함). */
+function keysOf(...resources) {
+    const out = new Set();
+    for (const res of resources) {
+        for (const entry of Object.values(res)) {
+            for (const k of withPluralBaseKeys(flattenKeys(entry.translation)))
+                out.add(k);
+        }
+    }
+    return out;
+}
+export async function checkI18nServerScope(cwd) {
+    const rule = 'i18n-server-scope';
+    // i18n 을 안 쓰는 프로젝트는 무소음(카탈로그가 없으면 키 검사 자체가 의미 없다).
+    if (!analyzeProjectI18n(cwd).declared)
+        return { rule, issues: [] };
+    let project;
+    try {
+        project = loadProjectLocales(cwd);
+    }
+    catch {
+        // 로더 fail-loud(도메인 frontend.json 등)는 i18n-layout·check 가 소유한다 — 여기선 침묵.
+        return { rule, issues: [] };
+    }
+    const domainKeys = keysOf(project.domain.backend);
+    if (domainKeys.size === 0 && Object.keys(project.apps).length === 0)
+        return { rule, issues: [] };
+    const issues = [];
+    // ① 도메인 코드 — domain-backend 만 보인다. 앱 스코프는 요청 컨텍스트에서만 상속되므로
+    //    도메인이 앱 키에 기대면 워커·크론에서 조용히 빈다.
+    for (const file of walkSources(`${cwd}/domain`, ['.ts'])) {
+        const raw = readFileSync(file, 'utf8');
+        if (!SERVER_T_IMPORT.test(raw))
+            continue;
+        const src = stripComments(raw);
+        for (const m of src.matchAll(T_CALL)) {
+            const key = m[1];
+            if (domainKeys.has(key))
+                continue;
+            const line = src.slice(0, m.index).split('\n').length;
+            const rel = relative(cwd, file);
+            const owner = appsOwning(project, key);
+            issues.push({
+                rule,
+                level: 'error',
+                file: rel,
+                line,
+                message: (owner.length > 0
+                    ? `'${key}' 는 앱 전용 번역 키인데 도메인 코드가 씁니다(소유 앱: ${owner.join(', ')}): ${rel}:${line} (결정 459)\n`
+                    : `'${key}' 를 도메인 카탈로그에서 찾을 수 없습니다: ${rel}:${line} (결정 459)\n`) +
+                    `  도메인 코드는 요청 밖(잡·크론·워커)에서도 불립니다 — 그때는 앱 스코프가 없어\n` +
+                    `  번역 대신 키 문자열이 그대로 나갑니다(요청 안에서는 우연히 해석돼 더 늦게 발견됩니다).\n` +
+                    `→ 이 문구를 도메인이 소유해야 하면 domain/locales/<로케일>/backend.json 으로 옮기고 gaon gen 을 실행하세요.\n` +
+                    `→ 화면·앱 전용 문구라면 이 호출을 도메인 밖(앱 컨트롤러)으로 옮기세요.`,
+                detail: { key, scope: 'domain', ownedByApps: owner },
+            });
+        }
+    }
+    // ② 앱 서버 코드 — app-backend ∪ app-frontend ∪ domain-backend 가 보인다(O5).
+    for (const [app, scoped] of Object.entries(project.apps)) {
+        const own = keysOf(scoped.backend, scoped.frontend, project.domain.backend);
+        for (const file of walkSources(`${cwd}/apps/${app}`, ['.ts'])) {
+            const raw = readFileSync(file, 'utf8');
+            if (!SERVER_T_IMPORT.test(raw))
+                continue;
+            const src = stripComments(raw);
+            for (const m of src.matchAll(T_CALL)) {
+                const key = m[1];
+                if (own.has(key))
+                    continue;
+                const line = src.slice(0, m.index).split('\n').length;
+                const rel = relative(cwd, file);
+                const owner = appsOwning(project, key).filter((a) => a !== app);
+                issues.push({
+                    rule,
+                    level: 'error',
+                    file: rel,
+                    line,
+                    message: (owner.length > 0
+                        ? `'${key}' 는 **다른 앱 전용** 번역 키입니다(소유 앱: ${owner.join(', ')}): ${rel}:${line} (결정 459)\n`
+                        : `'${key}' 를 이 앱·도메인 카탈로그 어디에서도 찾을 수 없습니다: ${rel}:${line} (결정 459)\n`) +
+                        `  앱 스코프 t() 는 apps/${app}/locales 와 domain/locales 만 봅니다 — 없으면 키 문자열이 그대로 나갑니다.\n` +
+                        `→ 이 앱 전용 서버 문구면 apps/${app}/locales/<로케일>/backend.json 에,\n` +
+                        `→ 메일·잡 등 도메인 공통 문구면 domain/locales/<로케일>/backend.json 에 추가하고 gaon gen 을 실행하세요.`,
+                    detail: { key, scope: `app:${app}`, app, ownedByApps: owner },
+                });
+            }
+        }
+    }
+    return { rule, issues };
+}
+/** 이 키를 가진 앱 목록(안내에 "어디 있는 키인지" 를 정확히 쓰기 위해). */
+function appsOwning(project, key) {
+    const out = [];
+    for (const [app, scoped] of Object.entries(project.apps)) {
+        if (keysOf(scoped.backend, scoped.frontend).has(key))
+            out.push(app);
+    }
+    return out.sort();
+}