@mandujs/core 0.13.0 → 0.13.2

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 (157) hide show
  1. package/README.ko.md +4 -4
  2. package/README.md +653 -653
  3. package/package.json +1 -1
  4. package/src/bundler/build.ts +91 -91
  5. package/src/bundler/css.ts +302 -302
  6. package/src/client/Link.tsx +227 -227
  7. package/src/client/globals.ts +44 -44
  8. package/src/client/hooks.ts +267 -267
  9. package/src/client/index.ts +5 -5
  10. package/src/client/island.ts +8 -8
  11. package/src/client/router.ts +435 -435
  12. package/src/client/runtime.ts +23 -23
  13. package/src/client/serialize.ts +404 -404
  14. package/src/client/window-state.ts +101 -101
  15. package/src/config/mandu.ts +9 -0
  16. package/src/config/validate.ts +12 -0
  17. package/src/config/watcher.ts +311 -311
  18. package/src/constants.ts +40 -40
  19. package/src/content/content-layer.ts +314 -314
  20. package/src/content/content.test.ts +433 -433
  21. package/src/content/data-store.ts +245 -245
  22. package/src/content/digest.ts +133 -133
  23. package/src/content/index.ts +164 -164
  24. package/src/content/loader-context.ts +172 -172
  25. package/src/content/loaders/api.ts +216 -216
  26. package/src/content/loaders/file.ts +169 -169
  27. package/src/content/loaders/glob.ts +252 -252
  28. package/src/content/loaders/index.ts +34 -34
  29. package/src/content/loaders/types.ts +137 -137
  30. package/src/content/meta-store.ts +209 -209
  31. package/src/content/types.ts +282 -282
  32. package/src/content/watcher.ts +135 -135
  33. package/src/contract/client-safe.test.ts +42 -42
  34. package/src/contract/client-safe.ts +114 -114
  35. package/src/contract/client.ts +16 -16
  36. package/src/contract/define.ts +459 -459
  37. package/src/contract/handler.ts +10 -10
  38. package/src/contract/normalize.test.ts +276 -276
  39. package/src/contract/normalize.ts +404 -404
  40. package/src/contract/registry.test.ts +206 -206
  41. package/src/contract/registry.ts +568 -568
  42. package/src/contract/schema.ts +48 -48
  43. package/src/contract/types.ts +58 -58
  44. package/src/contract/validator.ts +32 -32
  45. package/src/devtools/ai/context-builder.ts +375 -375
  46. package/src/devtools/ai/index.ts +25 -25
  47. package/src/devtools/ai/mcp-connector.ts +465 -465
  48. package/src/devtools/client/catchers/error-catcher.ts +327 -327
  49. package/src/devtools/client/catchers/index.ts +18 -18
  50. package/src/devtools/client/catchers/network-proxy.ts +363 -363
  51. package/src/devtools/client/components/index.ts +39 -39
  52. package/src/devtools/client/components/kitchen-root.tsx +362 -362
  53. package/src/devtools/client/components/mandu-character.tsx +241 -241
  54. package/src/devtools/client/components/overlay.tsx +368 -368
  55. package/src/devtools/client/components/panel/errors-panel.tsx +259 -259
  56. package/src/devtools/client/components/panel/guard-panel.tsx +244 -244
  57. package/src/devtools/client/components/panel/index.ts +32 -32
  58. package/src/devtools/client/components/panel/islands-panel.tsx +304 -304
  59. package/src/devtools/client/components/panel/network-panel.tsx +292 -292
  60. package/src/devtools/client/components/panel/panel-container.tsx +259 -259
  61. package/src/devtools/client/filters/context-filters.ts +282 -282
  62. package/src/devtools/client/filters/index.ts +16 -16
  63. package/src/devtools/client/index.ts +63 -63
  64. package/src/devtools/client/persistence.ts +335 -335
  65. package/src/devtools/client/state-manager.ts +478 -478
  66. package/src/devtools/design-tokens.ts +263 -263
  67. package/src/devtools/hook/create-hook.ts +207 -207
  68. package/src/devtools/hook/index.ts +13 -13
  69. package/src/devtools/index.ts +439 -439
  70. package/src/devtools/init.ts +266 -266
  71. package/src/devtools/protocol.ts +237 -237
  72. package/src/devtools/server/index.ts +17 -17
  73. package/src/devtools/server/source-context.ts +444 -444
  74. package/src/devtools/types.ts +319 -319
  75. package/src/devtools/worker/index.ts +25 -25
  76. package/src/devtools/worker/redaction-worker.ts +222 -222
  77. package/src/devtools/worker/worker-manager.ts +409 -409
  78. package/src/error/domains.ts +265 -265
  79. package/src/error/result.ts +46 -46
  80. package/src/error/types.ts +6 -6
  81. package/src/errors/extractor.ts +409 -409
  82. package/src/errors/index.ts +19 -19
  83. package/src/filling/auth.ts +308 -308
  84. package/src/filling/context.ts +24 -1
  85. package/src/filling/deps.ts +238 -238
  86. package/src/filling/index.ts +4 -0
  87. package/src/filling/sse-catchup.test.ts +56 -0
  88. package/src/filling/sse-catchup.ts +67 -0
  89. package/src/filling/sse.test.ts +168 -0
  90. package/src/filling/sse.ts +162 -0
  91. package/src/generator/index.ts +3 -3
  92. package/src/guard/analyzer.ts +360 -360
  93. package/src/guard/ast-analyzer.ts +806 -806
  94. package/src/guard/contract-guard.ts +9 -9
  95. package/src/guard/file-type.test.ts +24 -24
  96. package/src/guard/presets/atomic.ts +70 -70
  97. package/src/guard/presets/clean.ts +77 -77
  98. package/src/guard/presets/fsd.ts +79 -79
  99. package/src/guard/presets/hexagonal.ts +68 -68
  100. package/src/guard/presets/index.ts +291 -291
  101. package/src/guard/reporter.ts +445 -445
  102. package/src/guard/rules.ts +12 -12
  103. package/src/guard/statistics.ts +578 -578
  104. package/src/guard/suggestions.ts +358 -358
  105. package/src/guard/types.ts +348 -348
  106. package/src/guard/validator.ts +834 -834
  107. package/src/guard/watcher.ts +404 -404
  108. package/src/index.ts +6 -1
  109. package/src/intent/index.ts +310 -310
  110. package/src/island/index.ts +304 -304
  111. package/src/logging/index.ts +22 -22
  112. package/src/logging/transports.ts +365 -365
  113. package/src/plugins/index.ts +38 -38
  114. package/src/plugins/registry.ts +377 -377
  115. package/src/plugins/types.ts +363 -363
  116. package/src/report/index.ts +1 -1
  117. package/src/router/fs-patterns.ts +387 -387
  118. package/src/router/fs-scanner.ts +497 -497
  119. package/src/runtime/boundary.tsx +232 -232
  120. package/src/runtime/compose.ts +222 -222
  121. package/src/runtime/escape.ts +44 -0
  122. package/src/runtime/lifecycle.ts +381 -381
  123. package/src/runtime/logger.test.ts +345 -345
  124. package/src/runtime/logger.ts +677 -677
  125. package/src/runtime/router.test.ts +476 -476
  126. package/src/runtime/router.ts +105 -105
  127. package/src/runtime/security.ts +155 -155
  128. package/src/runtime/server.ts +257 -0
  129. package/src/runtime/session-key.ts +328 -328
  130. package/src/runtime/ssr.ts +16 -21
  131. package/src/runtime/streaming-ssr.ts +24 -33
  132. package/src/runtime/trace.ts +144 -144
  133. package/src/seo/index.ts +214 -214
  134. package/src/seo/integration/ssr.ts +307 -307
  135. package/src/seo/render/basic.ts +427 -427
  136. package/src/seo/render/index.ts +143 -143
  137. package/src/seo/render/jsonld.ts +539 -539
  138. package/src/seo/render/opengraph.ts +191 -191
  139. package/src/seo/render/robots.ts +116 -116
  140. package/src/seo/render/sitemap.ts +137 -137
  141. package/src/seo/render/twitter.ts +126 -126
  142. package/src/seo/resolve/index.ts +353 -353
  143. package/src/seo/resolve/opengraph.ts +143 -143
  144. package/src/seo/resolve/robots.ts +73 -73
  145. package/src/seo/resolve/title.ts +94 -94
  146. package/src/seo/resolve/twitter.ts +73 -73
  147. package/src/seo/resolve/url.ts +97 -97
  148. package/src/seo/routes/index.ts +290 -290
  149. package/src/seo/types.ts +575 -575
  150. package/src/slot/validator.ts +39 -39
  151. package/src/spec/index.ts +3 -3
  152. package/src/spec/load.ts +76 -76
  153. package/src/spec/lock.ts +56 -56
  154. package/src/utils/bun.ts +8 -8
  155. package/src/utils/lru-cache.ts +75 -75
  156. package/src/utils/safe-io.ts +188 -188
  157. package/src/utils/string-safe.ts +298 -298
@@ -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
+ }