@mandujs/core 0.12.2 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (173) hide show
  1. package/README.ko.md +304 -304
  2. package/README.md +653 -653
  3. package/package.json +1 -1
  4. package/src/brain/architecture/analyzer.ts +28 -26
  5. package/src/brain/doctor/analyzer.ts +1 -1
  6. package/src/bundler/build.ts +91 -91
  7. package/src/bundler/css.ts +302 -302
  8. package/src/bundler/dev.ts +0 -1
  9. package/src/change/history.ts +3 -3
  10. package/src/change/snapshot.ts +10 -9
  11. package/src/change/transaction.ts +2 -2
  12. package/src/client/Link.tsx +227 -227
  13. package/src/client/globals.ts +44 -44
  14. package/src/client/hooks.ts +267 -267
  15. package/src/client/index.ts +5 -5
  16. package/src/client/island.ts +8 -8
  17. package/src/client/router.ts +435 -435
  18. package/src/client/runtime.ts +23 -23
  19. package/src/client/serialize.ts +404 -404
  20. package/src/client/window-state.ts +101 -101
  21. package/src/config/mandu.ts +94 -96
  22. package/src/config/validate.ts +213 -215
  23. package/src/config/watcher.ts +311 -311
  24. package/src/constants.ts +40 -40
  25. package/src/content/content-layer.ts +314 -314
  26. package/src/content/content.test.ts +433 -433
  27. package/src/content/data-store.ts +245 -245
  28. package/src/content/digest.ts +133 -133
  29. package/src/content/index.ts +164 -164
  30. package/src/content/loader-context.ts +172 -172
  31. package/src/content/loaders/api.ts +216 -216
  32. package/src/content/loaders/file.ts +169 -169
  33. package/src/content/loaders/glob.ts +252 -252
  34. package/src/content/loaders/index.ts +34 -34
  35. package/src/content/loaders/types.ts +137 -137
  36. package/src/content/meta-store.ts +209 -209
  37. package/src/content/types.ts +282 -282
  38. package/src/content/watcher.ts +135 -135
  39. package/src/contract/client-safe.test.ts +42 -42
  40. package/src/contract/client-safe.ts +114 -114
  41. package/src/contract/client.ts +16 -16
  42. package/src/contract/define.ts +459 -459
  43. package/src/contract/handler.ts +10 -10
  44. package/src/contract/normalize.test.ts +276 -276
  45. package/src/contract/normalize.ts +404 -404
  46. package/src/contract/registry.test.ts +206 -206
  47. package/src/contract/registry.ts +568 -568
  48. package/src/contract/schema.ts +48 -48
  49. package/src/contract/types.ts +58 -58
  50. package/src/contract/validator.ts +32 -32
  51. package/src/devtools/ai/context-builder.ts +375 -375
  52. package/src/devtools/ai/index.ts +25 -25
  53. package/src/devtools/ai/mcp-connector.ts +465 -465
  54. package/src/devtools/client/catchers/error-catcher.ts +327 -327
  55. package/src/devtools/client/catchers/index.ts +18 -18
  56. package/src/devtools/client/catchers/network-proxy.ts +363 -363
  57. package/src/devtools/client/components/index.ts +39 -39
  58. package/src/devtools/client/components/kitchen-root.tsx +362 -362
  59. package/src/devtools/client/components/mandu-character.tsx +241 -241
  60. package/src/devtools/client/components/overlay.tsx +368 -368
  61. package/src/devtools/client/components/panel/errors-panel.tsx +259 -259
  62. package/src/devtools/client/components/panel/guard-panel.tsx +244 -244
  63. package/src/devtools/client/components/panel/index.ts +32 -32
  64. package/src/devtools/client/components/panel/islands-panel.tsx +304 -304
  65. package/src/devtools/client/components/panel/network-panel.tsx +292 -292
  66. package/src/devtools/client/components/panel/panel-container.tsx +259 -259
  67. package/src/devtools/client/filters/context-filters.ts +282 -282
  68. package/src/devtools/client/filters/index.ts +16 -16
  69. package/src/devtools/client/index.ts +63 -63
  70. package/src/devtools/client/persistence.ts +335 -335
  71. package/src/devtools/client/state-manager.ts +478 -478
  72. package/src/devtools/design-tokens.ts +263 -263
  73. package/src/devtools/hook/create-hook.ts +207 -207
  74. package/src/devtools/hook/index.ts +13 -13
  75. package/src/devtools/index.ts +439 -439
  76. package/src/devtools/init.ts +266 -266
  77. package/src/devtools/protocol.ts +237 -237
  78. package/src/devtools/server/index.ts +17 -17
  79. package/src/devtools/server/source-context.ts +444 -444
  80. package/src/devtools/types.ts +319 -319
  81. package/src/devtools/worker/index.ts +25 -25
  82. package/src/devtools/worker/redaction-worker.ts +222 -222
  83. package/src/devtools/worker/worker-manager.ts +409 -409
  84. package/src/error/classifier.ts +2 -2
  85. package/src/error/domains.ts +265 -265
  86. package/src/error/formatter.ts +32 -32
  87. package/src/error/result.ts +46 -46
  88. package/src/error/stack-analyzer.ts +5 -0
  89. package/src/error/types.ts +6 -6
  90. package/src/errors/extractor.ts +409 -409
  91. package/src/errors/index.ts +19 -19
  92. package/src/filling/auth.ts +308 -308
  93. package/src/filling/context.ts +569 -569
  94. package/src/filling/deps.ts +238 -238
  95. package/src/generator/contract-glue.ts +2 -1
  96. package/src/generator/generate.ts +12 -10
  97. package/src/generator/index.ts +3 -3
  98. package/src/generator/templates.ts +80 -79
  99. package/src/guard/analyzer.ts +360 -360
  100. package/src/guard/ast-analyzer.ts +806 -806
  101. package/src/guard/auto-correct.ts +1 -1
  102. package/src/guard/check.ts +128 -128
  103. package/src/guard/contract-guard.ts +9 -9
  104. package/src/guard/file-type.test.ts +24 -24
  105. package/src/guard/presets/atomic.ts +70 -70
  106. package/src/guard/presets/clean.ts +77 -77
  107. package/src/guard/presets/cqrs.test.ts +35 -14
  108. package/src/guard/presets/fsd.ts +79 -79
  109. package/src/guard/presets/hexagonal.ts +68 -68
  110. package/src/guard/presets/index.ts +291 -291
  111. package/src/guard/reporter.ts +445 -445
  112. package/src/guard/rules.ts +12 -12
  113. package/src/guard/statistics.ts +578 -578
  114. package/src/guard/suggestions.ts +358 -358
  115. package/src/guard/types.ts +348 -348
  116. package/src/guard/validator.ts +834 -834
  117. package/src/guard/watcher.ts +404 -404
  118. package/src/index.ts +1 -0
  119. package/src/intent/index.ts +310 -310
  120. package/src/island/index.ts +304 -304
  121. package/src/logging/index.ts +22 -22
  122. package/src/logging/transports.ts +365 -365
  123. package/src/paths.test.ts +47 -0
  124. package/src/paths.ts +47 -0
  125. package/src/plugins/index.ts +38 -38
  126. package/src/plugins/registry.ts +377 -377
  127. package/src/plugins/types.ts +363 -363
  128. package/src/report/build.ts +1 -1
  129. package/src/report/index.ts +1 -1
  130. package/src/router/fs-patterns.ts +387 -387
  131. package/src/router/fs-routes.ts +344 -401
  132. package/src/router/fs-scanner.ts +497 -497
  133. package/src/router/fs-types.ts +270 -278
  134. package/src/router/index.ts +81 -81
  135. package/src/runtime/boundary.tsx +232 -232
  136. package/src/runtime/compose.ts +222 -222
  137. package/src/runtime/lifecycle.ts +381 -381
  138. package/src/runtime/logger.test.ts +345 -345
  139. package/src/runtime/logger.ts +677 -677
  140. package/src/runtime/router.test.ts +476 -476
  141. package/src/runtime/router.ts +105 -105
  142. package/src/runtime/security.ts +155 -155
  143. package/src/runtime/server.ts +24 -24
  144. package/src/runtime/session-key.ts +328 -328
  145. package/src/runtime/ssr.ts +367 -367
  146. package/src/runtime/streaming-ssr.ts +1245 -1245
  147. package/src/runtime/trace.ts +144 -144
  148. package/src/seo/index.ts +214 -214
  149. package/src/seo/integration/ssr.ts +307 -307
  150. package/src/seo/render/basic.ts +427 -427
  151. package/src/seo/render/index.ts +143 -143
  152. package/src/seo/render/jsonld.ts +539 -539
  153. package/src/seo/render/opengraph.ts +191 -191
  154. package/src/seo/render/robots.ts +116 -116
  155. package/src/seo/render/sitemap.ts +137 -137
  156. package/src/seo/render/twitter.ts +126 -126
  157. package/src/seo/resolve/index.ts +353 -353
  158. package/src/seo/resolve/opengraph.ts +143 -143
  159. package/src/seo/resolve/robots.ts +73 -73
  160. package/src/seo/resolve/title.ts +94 -94
  161. package/src/seo/resolve/twitter.ts +73 -73
  162. package/src/seo/resolve/url.ts +97 -97
  163. package/src/seo/routes/index.ts +290 -290
  164. package/src/seo/types.ts +575 -575
  165. package/src/slot/validator.ts +39 -39
  166. package/src/spec/index.ts +3 -3
  167. package/src/spec/load.ts +76 -76
  168. package/src/spec/lock.ts +56 -56
  169. package/src/utils/bun.ts +8 -8
  170. package/src/utils/lru-cache.ts +75 -75
  171. package/src/utils/safe-io.ts +188 -188
  172. package/src/utils/string-safe.ts +298 -298
  173. package/src/watcher/rules.ts +5 -5
@@ -1,358 +1,358 @@
1
- /**
2
- * Mandu Guard Suggestions
3
- *
4
- * 스마트 해결 제안 생성기
5
- */
6
-
7
- import type { ViolationType, LayerDefinition, GuardPreset } from "./types";
8
-
9
- // ═══════════════════════════════════════════════════════════════════════════
10
- // Documentation Links
11
- // ═══════════════════════════════════════════════════════════════════════════
12
-
13
- const DOCS: Record<GuardPreset | "default", Record<string, string>> = {
14
- fsd: {
15
- base: "https://feature-sliced.design/docs",
16
- layers: "https://feature-sliced.design/docs/reference/layers",
17
- slices: "https://feature-sliced.design/docs/reference/slices",
18
- segments: "https://feature-sliced.design/docs/reference/segments",
19
- publicApi: "https://feature-sliced.design/docs/reference/public-api",
20
- isolation: "https://feature-sliced.design/docs/reference/isolation",
21
- },
22
- clean: {
23
- base: "https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html",
24
- layers: "https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html",
25
- dependency: "https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html#the-dependency-rule",
26
- },
27
- hexagonal: {
28
- base: "https://alistair.cockburn.us/hexagonal-architecture/",
29
- ports: "https://alistair.cockburn.us/hexagonal-architecture/",
30
- adapters: "https://alistair.cockburn.us/hexagonal-architecture/",
31
- },
32
- atomic: {
33
- base: "https://bradfrost.com/blog/post/atomic-web-design/",
34
- atoms: "https://bradfrost.com/blog/post/atomic-web-design/#atoms",
35
- molecules: "https://bradfrost.com/blog/post/atomic-web-design/#molecules",
36
- organisms: "https://bradfrost.com/blog/post/atomic-web-design/#organisms",
37
- },
38
- cqrs: {
39
- base: "https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs",
40
- commands: "https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs#solution",
41
- queries: "https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs#solution",
42
- layers: "https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html",
43
- },
44
- mandu: {
45
- base: "https://github.com/mandujs/mandu/docs/guard",
46
- layers: "https://github.com/mandujs/mandu/docs/guard#layers",
47
- },
48
- default: {
49
- base: "https://github.com/mandujs/mandu/docs/guard",
50
- },
51
- };
52
-
53
- /**
54
- * 문서 링크 가져오기
55
- */
56
- export function getDocumentationLink(
57
- preset: GuardPreset | undefined,
58
- topic: string = "layers"
59
- ): string {
60
- const presetDocs = preset ? DOCS[preset] : DOCS.default;
61
- return presetDocs[topic] ?? presetDocs.base ?? DOCS.default.base;
62
- }
63
-
64
- // ═══════════════════════════════════════════════════════════════════════════
65
- // Smart Suggestions
66
- // ═══════════════════════════════════════════════════════════════════════════
67
-
68
- interface SuggestionContext {
69
- type: ViolationType;
70
- fromLayer: string;
71
- toLayer: string;
72
- importPath: string;
73
- allowedLayers: string[];
74
- layers: LayerDefinition[];
75
- preset?: GuardPreset;
76
- slice?: string;
77
- }
78
-
79
- /**
80
- * 스마트 제안 생성
81
- */
82
- export function generateSmartSuggestions(context: SuggestionContext): string[] {
83
- const { type, fromLayer, toLayer, importPath, allowedLayers, layers, preset, slice } = context;
84
- const suggestions: string[] = [];
85
-
86
- switch (type) {
87
- case "layer-violation":
88
- suggestions.push(...generateLayerViolationSuggestions(context));
89
- break;
90
-
91
- case "circular-dependency":
92
- suggestions.push(...generateCircularDependencySuggestions(context));
93
- break;
94
-
95
- case "cross-slice":
96
- suggestions.push(...generateCrossSliceSuggestions(context));
97
- break;
98
-
99
- case "deep-nesting":
100
- suggestions.push(...generateDeepNestingSuggestions(context));
101
- break;
102
- }
103
-
104
- return suggestions;
105
- }
106
-
107
- /**
108
- * 레이어 위반 제안 생성
109
- */
110
- function generateLayerViolationSuggestions(context: SuggestionContext): string[] {
111
- const { fromLayer, toLayer, importPath, allowedLayers, preset } = context;
112
- const suggestions: string[] = [];
113
-
114
- // 1. 구체적인 대안 제시
115
- const targetModule = extractModuleName(importPath);
116
-
117
- if (allowedLayers.includes("shared")) {
118
- suggestions.push(
119
- `🔧 FIX: \`${targetModule}\`를 \`@/shared\`로 이동하세요`,
120
- ` 변경 전: import { ${targetModule} } from '${importPath}'`,
121
- ` 변경 후: import { ${targetModule} } from '@/shared/${targetModule.toLowerCase()}'`
122
- );
123
- }
124
-
125
- // 2. Prop drilling 제안
126
- if (toLayer === "widgets" || toLayer === "features") {
127
- suggestions.push(
128
- `🔄 ALTERNATIVE: Props로 전달받는 방식을 사용하세요`,
129
- ` 부모 컴포넌트에서 ${targetModule}를 import하고 props로 전달`
130
- );
131
- }
132
-
133
- // 3. 허용된 레이어에서 유사 기능 찾기 제안
134
- if (allowedLayers.length > 0) {
135
- suggestions.push(
136
- `✅ ALLOWED: 다음 레이어에서 import 가능합니다:`,
137
- ...allowedLayers.map((l) => ` • @/${l}/*`)
138
- );
139
- }
140
-
141
- // 4. Composition pattern 제안 (FSD 전용)
142
- if (preset === "fsd" && (fromLayer === "features" || fromLayer === "entities")) {
143
- suggestions.push(
144
- `📦 PATTERN: Composition을 사용하세요`,
145
- ` 상위 레이어(pages/widgets)에서 조합하여 사용`
146
- );
147
- }
148
-
149
- return suggestions;
150
- }
151
-
152
- /**
153
- * 순환 의존 제안 생성
154
- */
155
- function generateCircularDependencySuggestions(context: SuggestionContext): string[] {
156
- const { fromLayer, toLayer, importPath } = context;
157
- const suggestions: string[] = [];
158
-
159
- suggestions.push(
160
- `🔄 DETECTED: ${fromLayer} ⇄ ${toLayer} 순환 의존`,
161
- ``,
162
- `🔧 FIX OPTIONS:`,
163
- ` 1. 공통 의존성을 shared 레이어로 추출`,
164
- ` 2. 인터페이스/타입을 별도 파일로 분리`,
165
- ` 3. Dependency Injection 패턴 적용`,
166
- ``,
167
- `📊 REFACTORING STEPS:`,
168
- ` Step 1: 순환의 원인이 되는 공통 코드 식별`,
169
- ` Step 2: 공통 코드를 @/shared로 이동`,
170
- ` Step 3: 양쪽에서 shared를 import하도록 변경`
171
- );
172
-
173
- return suggestions;
174
- }
175
-
176
- /**
177
- * Cross-slice 의존 제안 생성
178
- */
179
- function generateCrossSliceSuggestions(context: SuggestionContext): string[] {
180
- const { fromLayer, importPath, slice } = context;
181
- const toSlice = extractSliceFromPath(importPath, fromLayer);
182
- const suggestions: string[] = [];
183
-
184
- suggestions.push(
185
- `🔀 DETECTED: ${fromLayer}/${slice} → ${fromLayer}/${toSlice} cross-slice import`,
186
- ``,
187
- `🔧 FIX OPTIONS:`,
188
- ` 1. 공통 로직을 shared 세그먼트로 추출:`,
189
- ` @/${fromLayer}/${slice}/shared → @/shared/${fromLayer}-common`,
190
- ``,
191
- ` 2. @x notation 사용 (명시적 cross-import):`,
192
- ` import { X } from '@/${fromLayer}/${toSlice}/@x/${slice}'`,
193
- ``,
194
- ` 3. 상위 레이어에서 조합:`,
195
- ` widgets나 pages에서 두 slice를 조합`
196
- );
197
-
198
- return suggestions;
199
- }
200
-
201
- /**
202
- * 깊은 중첩 제안 생성
203
- */
204
- function generateDeepNestingSuggestions(context: SuggestionContext): string[] {
205
- const { importPath } = context;
206
- const parts = importPath.replace(/^[@~]\//, "").split("/");
207
- const publicApiPath = parts.slice(0, 2).join("/");
208
- const suggestions: string[] = [];
209
-
210
- suggestions.push(
211
- `📁 DETECTED: 내부 구현 직접 import`,
212
- ``,
213
- `🔧 FIX:`,
214
- ` 변경 전: import { X } from '${importPath}'`,
215
- ` 변경 후: import { X } from '@/${publicApiPath}'`,
216
- ``,
217
- `📦 PUBLIC API:`,
218
- ` @/${publicApiPath}/index.ts에서 필요한 항목을 export하세요`,
219
- ``,
220
- ` // @/${publicApiPath}/index.ts`,
221
- ` export { X } from './internal/path';`
222
- );
223
-
224
- return suggestions;
225
- }
226
-
227
- // ═══════════════════════════════════════════════════════════════════════════
228
- // Agent-Optimized Format
229
- // ═══════════════════════════════════════════════════════════════════════════
230
-
231
- /**
232
- * 에이전트 최적화 포맷 생성
233
- *
234
- * AI Agent가 파싱하기 쉬운 구조화된 형식
235
- */
236
- export interface AgentViolationFormat {
237
- /** 위반 식별자 */
238
- id: string;
239
- /** 심각도 */
240
- severity: "error" | "warn" | "info";
241
- /** 위치 정보 */
242
- location: {
243
- file: string;
244
- line: number;
245
- column: number;
246
- };
247
- /** 규칙 정보 */
248
- rule: {
249
- name: string;
250
- description: string;
251
- documentation: string;
252
- };
253
- /** 위반 상세 */
254
- violation: {
255
- type: ViolationType;
256
- fromLayer: string;
257
- toLayer: string;
258
- importStatement: string;
259
- importPath: string;
260
- };
261
- /** 수정 방법 */
262
- fix: {
263
- primary: string;
264
- alternatives: string[];
265
- codeChange?: {
266
- before: string;
267
- after: string;
268
- };
269
- };
270
- /** 허용된 import */
271
- allowed: string[];
272
- }
273
-
274
- /**
275
- * 에이전트 친화적 형식으로 변환
276
- */
277
- export function toAgentFormat(
278
- violation: {
279
- type: ViolationType;
280
- filePath: string;
281
- line: number;
282
- column: number;
283
- importStatement: string;
284
- importPath: string;
285
- fromLayer: string;
286
- toLayer: string;
287
- ruleName: string;
288
- ruleDescription: string;
289
- severity: "error" | "warn" | "info";
290
- allowedLayers: string[];
291
- suggestions: string[];
292
- },
293
- preset?: GuardPreset
294
- ): AgentViolationFormat {
295
- const targetModule = extractModuleName(violation.importPath);
296
-
297
- return {
298
- id: `guard-${violation.type}-${violation.line}`,
299
- severity: violation.severity,
300
- location: {
301
- file: violation.filePath,
302
- line: violation.line,
303
- column: violation.column,
304
- },
305
- rule: {
306
- name: violation.ruleName,
307
- description: violation.ruleDescription,
308
- documentation: getDocumentationLink(preset, "layers"),
309
- },
310
- violation: {
311
- type: violation.type,
312
- fromLayer: violation.fromLayer,
313
- toLayer: violation.toLayer,
314
- importStatement: violation.importStatement,
315
- importPath: violation.importPath,
316
- },
317
- fix: {
318
- primary: violation.suggestions[0] ?? "수정 필요",
319
- alternatives: violation.suggestions.slice(1),
320
- codeChange: violation.allowedLayers.includes("shared")
321
- ? {
322
- before: violation.importStatement,
323
- after: `import { ${targetModule} } from '@/shared/${targetModule.toLowerCase()}'`,
324
- }
325
- : undefined,
326
- },
327
- allowed: violation.allowedLayers.map((l) => `@/${l}/*`),
328
- };
329
- }
330
-
331
- // ═══════════════════════════════════════════════════════════════════════════
332
- // Helpers
333
- // ═══════════════════════════════════════════════════════════════════════════
334
-
335
- /**
336
- * Import 경로에서 모듈 이름 추출
337
- */
338
- function extractModuleName(importPath: string): string {
339
- const parts = importPath.replace(/^[@~]\//, "").split("/");
340
- const lastPart = parts[parts.length - 1];
341
- // PascalCase로 변환
342
- return lastPart.charAt(0).toUpperCase() + lastPart.slice(1);
343
- }
344
-
345
- /**
346
- * 경로에서 슬라이스 추출
347
- */
348
- function extractSliceFromPath(importPath: string, fromLayer?: string): string {
349
- const parts = importPath.replace(/^[@~]\//, "").split("/");
350
- if (fromLayer) {
351
- const layerParts = fromLayer.split("/");
352
- const matchesLayer = parts.slice(0, layerParts.length).join("/") === fromLayer;
353
- if (matchesLayer && parts.length > layerParts.length) {
354
- return parts[layerParts.length];
355
- }
356
- }
357
- return parts[1] ?? "unknown";
358
- }
1
+ /**
2
+ * Mandu Guard Suggestions
3
+ *
4
+ * 스마트 해결 제안 생성기
5
+ */
6
+
7
+ import type { ViolationType, LayerDefinition, GuardPreset } from "./types";
8
+
9
+ // ═══════════════════════════════════════════════════════════════════════════
10
+ // Documentation Links
11
+ // ═══════════════════════════════════════════════════════════════════════════
12
+
13
+ const DOCS: Record<GuardPreset | "default", Record<string, string>> = {
14
+ fsd: {
15
+ base: "https://feature-sliced.design/docs",
16
+ layers: "https://feature-sliced.design/docs/reference/layers",
17
+ slices: "https://feature-sliced.design/docs/reference/slices",
18
+ segments: "https://feature-sliced.design/docs/reference/segments",
19
+ publicApi: "https://feature-sliced.design/docs/reference/public-api",
20
+ isolation: "https://feature-sliced.design/docs/reference/isolation",
21
+ },
22
+ clean: {
23
+ base: "https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html",
24
+ layers: "https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html",
25
+ dependency: "https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html#the-dependency-rule",
26
+ },
27
+ hexagonal: {
28
+ base: "https://alistair.cockburn.us/hexagonal-architecture/",
29
+ ports: "https://alistair.cockburn.us/hexagonal-architecture/",
30
+ adapters: "https://alistair.cockburn.us/hexagonal-architecture/",
31
+ },
32
+ atomic: {
33
+ base: "https://bradfrost.com/blog/post/atomic-web-design/",
34
+ atoms: "https://bradfrost.com/blog/post/atomic-web-design/#atoms",
35
+ molecules: "https://bradfrost.com/blog/post/atomic-web-design/#molecules",
36
+ organisms: "https://bradfrost.com/blog/post/atomic-web-design/#organisms",
37
+ },
38
+ cqrs: {
39
+ base: "https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs",
40
+ commands: "https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs#solution",
41
+ queries: "https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs#solution",
42
+ layers: "https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html",
43
+ },
44
+ mandu: {
45
+ base: "https://github.com/mandujs/mandu/docs/guard",
46
+ layers: "https://github.com/mandujs/mandu/docs/guard#layers",
47
+ },
48
+ default: {
49
+ base: "https://github.com/mandujs/mandu/docs/guard",
50
+ },
51
+ };
52
+
53
+ /**
54
+ * 문서 링크 가져오기
55
+ */
56
+ export function getDocumentationLink(
57
+ preset: GuardPreset | undefined,
58
+ topic: string = "layers"
59
+ ): string {
60
+ const presetDocs = preset ? DOCS[preset] : DOCS.default;
61
+ return presetDocs[topic] ?? presetDocs.base ?? DOCS.default.base;
62
+ }
63
+
64
+ // ═══════════════════════════════════════════════════════════════════════════
65
+ // Smart Suggestions
66
+ // ═══════════════════════════════════════════════════════════════════════════
67
+
68
+ interface SuggestionContext {
69
+ type: ViolationType;
70
+ fromLayer: string;
71
+ toLayer: string;
72
+ importPath: string;
73
+ allowedLayers: string[];
74
+ layers: LayerDefinition[];
75
+ preset?: GuardPreset;
76
+ slice?: string;
77
+ }
78
+
79
+ /**
80
+ * 스마트 제안 생성
81
+ */
82
+ export function generateSmartSuggestions(context: SuggestionContext): string[] {
83
+ const { type, fromLayer, toLayer, importPath, allowedLayers, layers, preset, slice } = context;
84
+ const suggestions: string[] = [];
85
+
86
+ switch (type) {
87
+ case "layer-violation":
88
+ suggestions.push(...generateLayerViolationSuggestions(context));
89
+ break;
90
+
91
+ case "circular-dependency":
92
+ suggestions.push(...generateCircularDependencySuggestions(context));
93
+ break;
94
+
95
+ case "cross-slice":
96
+ suggestions.push(...generateCrossSliceSuggestions(context));
97
+ break;
98
+
99
+ case "deep-nesting":
100
+ suggestions.push(...generateDeepNestingSuggestions(context));
101
+ break;
102
+ }
103
+
104
+ return suggestions;
105
+ }
106
+
107
+ /**
108
+ * 레이어 위반 제안 생성
109
+ */
110
+ function generateLayerViolationSuggestions(context: SuggestionContext): string[] {
111
+ const { fromLayer, toLayer, importPath, allowedLayers, preset } = context;
112
+ const suggestions: string[] = [];
113
+
114
+ // 1. 구체적인 대안 제시
115
+ const targetModule = extractModuleName(importPath);
116
+
117
+ if (allowedLayers.includes("shared")) {
118
+ suggestions.push(
119
+ `🔧 FIX: \`${targetModule}\`를 \`@/shared\`로 이동하세요`,
120
+ ` 변경 전: import { ${targetModule} } from '${importPath}'`,
121
+ ` 변경 후: import { ${targetModule} } from '@/shared/${targetModule.toLowerCase()}'`
122
+ );
123
+ }
124
+
125
+ // 2. Prop drilling 제안
126
+ if (toLayer === "widgets" || toLayer === "features") {
127
+ suggestions.push(
128
+ `🔄 ALTERNATIVE: Props로 전달받는 방식을 사용하세요`,
129
+ ` 부모 컴포넌트에서 ${targetModule}를 import하고 props로 전달`
130
+ );
131
+ }
132
+
133
+ // 3. 허용된 레이어에서 유사 기능 찾기 제안
134
+ if (allowedLayers.length > 0) {
135
+ suggestions.push(
136
+ `✅ ALLOWED: 다음 레이어에서 import 가능합니다:`,
137
+ ...allowedLayers.map((l) => ` • @/${l}/*`)
138
+ );
139
+ }
140
+
141
+ // 4. Composition pattern 제안 (FSD 전용)
142
+ if (preset === "fsd" && (fromLayer === "features" || fromLayer === "entities")) {
143
+ suggestions.push(
144
+ `📦 PATTERN: Composition을 사용하세요`,
145
+ ` 상위 레이어(pages/widgets)에서 조합하여 사용`
146
+ );
147
+ }
148
+
149
+ return suggestions;
150
+ }
151
+
152
+ /**
153
+ * 순환 의존 제안 생성
154
+ */
155
+ function generateCircularDependencySuggestions(context: SuggestionContext): string[] {
156
+ const { fromLayer, toLayer, importPath } = context;
157
+ const suggestions: string[] = [];
158
+
159
+ suggestions.push(
160
+ `🔄 DETECTED: ${fromLayer} ⇄ ${toLayer} 순환 의존`,
161
+ ``,
162
+ `🔧 FIX OPTIONS:`,
163
+ ` 1. 공통 의존성을 shared 레이어로 추출`,
164
+ ` 2. 인터페이스/타입을 별도 파일로 분리`,
165
+ ` 3. Dependency Injection 패턴 적용`,
166
+ ``,
167
+ `📊 REFACTORING STEPS:`,
168
+ ` Step 1: 순환의 원인이 되는 공통 코드 식별`,
169
+ ` Step 2: 공통 코드를 @/shared로 이동`,
170
+ ` Step 3: 양쪽에서 shared를 import하도록 변경`
171
+ );
172
+
173
+ return suggestions;
174
+ }
175
+
176
+ /**
177
+ * Cross-slice 의존 제안 생성
178
+ */
179
+ function generateCrossSliceSuggestions(context: SuggestionContext): string[] {
180
+ const { fromLayer, importPath, slice } = context;
181
+ const toSlice = extractSliceFromPath(importPath, fromLayer);
182
+ const suggestions: string[] = [];
183
+
184
+ suggestions.push(
185
+ `🔀 DETECTED: ${fromLayer}/${slice} → ${fromLayer}/${toSlice} cross-slice import`,
186
+ ``,
187
+ `🔧 FIX OPTIONS:`,
188
+ ` 1. 공통 로직을 shared 세그먼트로 추출:`,
189
+ ` @/${fromLayer}/${slice}/shared → @/shared/${fromLayer}-common`,
190
+ ``,
191
+ ` 2. @x notation 사용 (명시적 cross-import):`,
192
+ ` import { X } from '@/${fromLayer}/${toSlice}/@x/${slice}'`,
193
+ ``,
194
+ ` 3. 상위 레이어에서 조합:`,
195
+ ` widgets나 pages에서 두 slice를 조합`
196
+ );
197
+
198
+ return suggestions;
199
+ }
200
+
201
+ /**
202
+ * 깊은 중첩 제안 생성
203
+ */
204
+ function generateDeepNestingSuggestions(context: SuggestionContext): string[] {
205
+ const { importPath } = context;
206
+ const parts = importPath.replace(/^[@~]\//, "").split("/");
207
+ const publicApiPath = parts.slice(0, 2).join("/");
208
+ const suggestions: string[] = [];
209
+
210
+ suggestions.push(
211
+ `📁 DETECTED: 내부 구현 직접 import`,
212
+ ``,
213
+ `🔧 FIX:`,
214
+ ` 변경 전: import { X } from '${importPath}'`,
215
+ ` 변경 후: import { X } from '@/${publicApiPath}'`,
216
+ ``,
217
+ `📦 PUBLIC API:`,
218
+ ` @/${publicApiPath}/index.ts에서 필요한 항목을 export하세요`,
219
+ ``,
220
+ ` // @/${publicApiPath}/index.ts`,
221
+ ` export { X } from './internal/path';`
222
+ );
223
+
224
+ return suggestions;
225
+ }
226
+
227
+ // ═══════════════════════════════════════════════════════════════════════════
228
+ // Agent-Optimized Format
229
+ // ═══════════════════════════════════════════════════════════════════════════
230
+
231
+ /**
232
+ * 에이전트 최적화 포맷 생성
233
+ *
234
+ * AI Agent가 파싱하기 쉬운 구조화된 형식
235
+ */
236
+ export interface AgentViolationFormat {
237
+ /** 위반 식별자 */
238
+ id: string;
239
+ /** 심각도 */
240
+ severity: "error" | "warn" | "info";
241
+ /** 위치 정보 */
242
+ location: {
243
+ file: string;
244
+ line: number;
245
+ column: number;
246
+ };
247
+ /** 규칙 정보 */
248
+ rule: {
249
+ name: string;
250
+ description: string;
251
+ documentation: string;
252
+ };
253
+ /** 위반 상세 */
254
+ violation: {
255
+ type: ViolationType;
256
+ fromLayer: string;
257
+ toLayer: string;
258
+ importStatement: string;
259
+ importPath: string;
260
+ };
261
+ /** 수정 방법 */
262
+ fix: {
263
+ primary: string;
264
+ alternatives: string[];
265
+ codeChange?: {
266
+ before: string;
267
+ after: string;
268
+ };
269
+ };
270
+ /** 허용된 import */
271
+ allowed: string[];
272
+ }
273
+
274
+ /**
275
+ * 에이전트 친화적 형식으로 변환
276
+ */
277
+ export function toAgentFormat(
278
+ violation: {
279
+ type: ViolationType;
280
+ filePath: string;
281
+ line: number;
282
+ column: number;
283
+ importStatement: string;
284
+ importPath: string;
285
+ fromLayer: string;
286
+ toLayer: string;
287
+ ruleName: string;
288
+ ruleDescription: string;
289
+ severity: "error" | "warn" | "info";
290
+ allowedLayers: string[];
291
+ suggestions: string[];
292
+ },
293
+ preset?: GuardPreset
294
+ ): AgentViolationFormat {
295
+ const targetModule = extractModuleName(violation.importPath);
296
+
297
+ return {
298
+ id: `guard-${violation.type}-${violation.line}`,
299
+ severity: violation.severity,
300
+ location: {
301
+ file: violation.filePath,
302
+ line: violation.line,
303
+ column: violation.column,
304
+ },
305
+ rule: {
306
+ name: violation.ruleName,
307
+ description: violation.ruleDescription,
308
+ documentation: getDocumentationLink(preset, "layers"),
309
+ },
310
+ violation: {
311
+ type: violation.type,
312
+ fromLayer: violation.fromLayer,
313
+ toLayer: violation.toLayer,
314
+ importStatement: violation.importStatement,
315
+ importPath: violation.importPath,
316
+ },
317
+ fix: {
318
+ primary: violation.suggestions[0] ?? "수정 필요",
319
+ alternatives: violation.suggestions.slice(1),
320
+ codeChange: violation.allowedLayers.includes("shared")
321
+ ? {
322
+ before: violation.importStatement,
323
+ after: `import { ${targetModule} } from '@/shared/${targetModule.toLowerCase()}'`,
324
+ }
325
+ : undefined,
326
+ },
327
+ allowed: violation.allowedLayers.map((l) => `@/${l}/*`),
328
+ };
329
+ }
330
+
331
+ // ═══════════════════════════════════════════════════════════════════════════
332
+ // Helpers
333
+ // ═══════════════════════════════════════════════════════════════════════════
334
+
335
+ /**
336
+ * Import 경로에서 모듈 이름 추출
337
+ */
338
+ function extractModuleName(importPath: string): string {
339
+ const parts = importPath.replace(/^[@~]\//, "").split("/");
340
+ const lastPart = parts[parts.length - 1];
341
+ // PascalCase로 변환
342
+ return lastPart.charAt(0).toUpperCase() + lastPart.slice(1);
343
+ }
344
+
345
+ /**
346
+ * 경로에서 슬라이스 추출
347
+ */
348
+ function extractSliceFromPath(importPath: string, fromLayer?: string): string {
349
+ const parts = importPath.replace(/^[@~]\//, "").split("/");
350
+ if (fromLayer) {
351
+ const layerParts = fromLayer.split("/");
352
+ const matchesLayer = parts.slice(0, layerParts.length).join("/") === fromLayer;
353
+ if (matchesLayer && parts.length > layerParts.length) {
354
+ return parts[layerParts.length];
355
+ }
356
+ }
357
+ return parts[1] ?? "unknown";
358
+ }