archrisk-engine 1.0.0

package/dist/deepAnalysis.js

@@ -0,0 +1,101 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDeepAnalysis = runDeepAnalysis;
+const generative_ai_1 = require("@google/generative-ai");
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+async function runDeepAnalysis(repoDir, provider, apiKey) {
+    if (provider !== 'GEMINI') {
+        throw new Error(`Provider ${provider} is not yet supported in Deep Analysis.`);
+    }
+    const genAI = new generative_ai_1.GoogleGenerativeAI(apiKey);
+    const model = genAI.getGenerativeModel({ model: 'gemini-1.5-flash' });
+    // Gather some context (simplified for MVP)
+    const files = await getRelevantFiles(repoDir);
+    const codeContext = await Promise.all(files.map(async (f) => {
+        const content = await fs.readFile(f, 'utf8');
+        return `File: ${path.relative(repoDir, f)}\nContent:\n${content.substring(0, 1000)}...`;
+    }));
+    const prompt = `
+    You are an expert Software Architect. Analyze the following project for:
+    1. Code smells and anti-patterns.
+    2. Specific refactoring suggestions.
+    3. Technical debt estimation.
+
+    Project Context:
+    ${codeContext.join('\n\n')}
+
+    Return JSON format:
+    {
+      "summary": "High level overview",
+      "refactoringGuides": [
+        {"file": "filename", "description": "why it needs refactoring", "suggestion": "how to refactor"}
+      ],
+      "techDebtScore": 0-100
+    }
+  `;
+    const result = await model.generateContent(prompt);
+    const response = await result.response;
+    const text = response.text();
+    try {
+        const jsonStr = text.match(/\{[\s\S]*\}/)?.[0] || '{}';
+        return JSON.parse(jsonStr);
+    }
+    catch (e) {
+        return {
+            summary: "AI analysis completed but failed to parse structured data.",
+            refactoringGuides: [],
+            techDebtScore: 50
+        };
+    }
+}
+async function getRelevantFiles(dir) {
+    const allFiles = [];
+    const items = await fs.readdir(dir);
+    for (const item of items) {
+        if (item === 'node_modules' || item.startsWith('.'))
+            continue;
+        const fullPath = path.join(dir, item);
+        const stat = await fs.stat(fullPath);
+        if (stat.isDirectory()) {
+            allFiles.push(...await getRelevantFiles(fullPath));
+        }
+        else if (item.endsWith('.py') || item.endsWith('.ts') || item.endsWith('.js')) {
+            allFiles.push(fullPath);
+        }
+    }
+    return allFiles.slice(0, 5); // MVP: Limit to 5 files for context
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './analyzer.js';
+export * from './aiDiagnosis.js';
+export * from './archScanner.js';
+export * from './repoAnalyzer.js';
+export * from './deepAnalysis.js';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./analyzer.js"), exports);
+__exportStar(require("./aiDiagnosis.js"), exports);
+__exportStar(require("./archScanner.js"), exports);
+__exportStar(require("./repoAnalyzer.js"), exports);
+__exportStar(require("./deepAnalysis.js"), exports);

package/dist/repoAnalyzer.d.ts

@@ -0,0 +1,43 @@
+export interface RepoAnalysisResult {
+    score: number;
+    status: 'Ready for Production' | 'Needs Attention' | 'Not Ready for Deployment';
+    findings: {
+        title: string;
+        file: string;
+        line: number;
+        type: string;
+        category: 'Service Interruption' | 'Scalability' | 'Maintenance' | 'Security';
+        evidence: string;
+        standard: string;
+        impact: string;
+        action: string;
+        reference: string;
+        whenItMatters: string;
+    }[];
+    metrics: {
+        totalFiles: number;
+        pythonFiles: number;
+        criticalRisks: number;
+        operationalGaps: number;
+    };
+    graphUrl?: string;
+    disclosure?: string;
+    cta?: string;
+}
+/**
+ * CEO-ready "Business Translation" for technical risks
+ */
+/**
+ * 3-Tier Business Audit Translation
+ */
+export declare function getAuditDetails(type: string, issue: string): {
+    title: string;
+    category: RepoAnalysisResult['findings'][0]['category'];
+    evidence: string;
+    standard: string;
+    impact: string;
+    action: string;
+    reference: string;
+    whenItMatters: string;
+};
+export declare function analyzeRepository(repoPath: string, resultsDir?: string): Promise<RepoAnalysisResult>;

package/dist/repoAnalyzer.js

@@ -0,0 +1,299 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAuditDetails = getAuditDetails;
+exports.analyzeRepository = analyzeRepository;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const analyzer_js_1 = require("./analyzer.js");
+const archScanner_js_1 = require("./archScanner.js");
+/**
+ * CEO-ready "Business Translation" for technical risks
+ */
+/**
+ * 3-Tier Business Audit Translation
+ */
+function getAuditDetails(type, issue) {
+    if (type === 'SecurityRisk') {
+        return {
+            title: "보안 취약점 위험 (Security Vulnerability)",
+            category: 'Security',
+            evidence: issue,
+            standard: "OWASP Top 10 A03:2021 – Injection",
+            impact: "외부 공격자가 시스템 권한을 탈취하거나 민감 정보를 유출할 수 있는 통로가 됩니다. 보안 사고 발생 시 법적 책임 및 서비스 중단이 불가피합니다.",
+            action: "해당 코드를 즉시 격리하고 subprocess.run(shell=False) 또는 환경 변수(.env)를 활용하여 민감 정보를 분리하세요.",
+            reference: "https://docs.python.org/3/library/subprocess.html#security-considerations",
+            whenItMatters: "배포 즉시 자동화된 스캐너나 공격자에 의해 탐지될 수 있는 0순위 리스크입니다."
+        };
+    }
+    if (type === 'ProductionRisk') {
+        if (issue.includes('테스트')) {
+            return {
+                title: "자동화 테스트 부재 (Missing Automated Tests)",
+                category: 'Service Interruption',
+                evidence: "tests/ 디렉토리 또는 pytest/unittest 관련 설정을 찾을 수 없습니다.",
+                standard: "Stability Standard: Code Coverage > 70%",
+                impact: "수동 테스트에 의존하게 되어 코드 변경 시마다 예상치 못한 장애가 운영 환경에 배포될 위험이 높으며, 장애 복구 시간(MTTR)이 매우 길어집니다.",
+                action: "pytest를 설치하고 핵심 로직에 대한 Smoke Test 3개를 먼저 작성하세요.",
+                reference: "https://docs.pytest.org/en/7.1.x/getting-started.html",
+                whenItMatters: "코드 변경 주기가 빨라지거나 팀원이 2명 이상으로 늘어날 때 병목이 발생합니다."
+            };
+        }
+        if (issue.includes('CI')) {
+            return {
+                title: "배포 자동화 파이프라인 부재 (Missing CI Pipeline)",
+                category: 'Service Interruption',
+                evidence: "GitHub Actions 또는 CI 도구 워크플로우 설정을 발견할 수 없습니다.",
+                standard: "Modern DevOps Standard: Continuous Integration",
+                impact: "코드 머지 전 검증 자동화가 불가능하여, 사람이 개입하는 과정에서 실수가 반복됩니다. 이는 배포 안정성을 근본적으로 파악할 수 없게 만듭니다.",
+                action: ".github/workflows/main.yml 파일을 생성하고 자동 테스트 프로세스를 구축하세요.",
+                reference: "https://github.com/features/actions",
+                whenItMatters: "하루에 2회 이상 배포를 시도할 때 검증 누락으로 인한 사고 확률이 80%를 상회하게 됩니다."
+            };
+        }
+        if (issue.includes('Docker')) {
+            return {
+                title: "컨테이너화 구성 누락 (Environment Inconsistency)",
+                category: 'Service Interruption',
+                evidence: "Dockerfile 또는 docker-compose.yml 파일이 존재하지 않습니다.",
+                standard: "Cloud Native Standard: Immutable Infrastructure",
+                impact: "로컬 개발 환경과 실제 운영 환경의 버전 차이로 인해 '내 컴퓨터에선 되는데 서버에선 안 되는' 예측 불가능한 장애가 발생합니다.",
+                action: "Dockerfile을 작성하여 환경 설정을 컨테이너화하세요.",
+                reference: "https://docs.docker.com/engine/reference/builder/",
+                whenItMatters: "신규 개발자가 팀에 합류하거나 클라우드 인프라 확장이 필요할 때 시간 낭비가 심화됩니다."
+            };
+        }
+        return {
+            title: "운영 준비도 미흡 (Production Readiness Gap)",
+            category: 'Service Interruption',
+            evidence: issue,
+            standard: "Production Readiness Checklist v1.0",
+            impact: "실제 운영 환경에서 예기치 못한 장애 발생 시 복구가 불가능하거나 매우 지연될 수 있는 핵심 요소입니다.",
+            action: "해당 설정 파일을 추가하거나 환경 설정을 고정하여 재현 가능성을 확보하세요.",
+            reference: "https://google.github.io/styleguide/pyguide.html",
+            whenItMatters: "장애 발생 시 원인 파악을 수분 내에 완료하지 못할 경우 다운타임이 기하급수적으로 늘어납니다."
+        };
+    }
+    if (type === 'ArchitectureRisk' || type === 'CircularDependency') {
+        return {
+            title: "구조적 의존성 결함 (Structural Dependency Issue)",
+            category: 'Scalability',
+            evidence: type === 'CircularDependency' ? "모듈 간의 상호 참조 구조가 감지되었습니다." : issue,
+            standard: "Clean Architecture: Dependency Rule",
+            impact: "모듈 간 결합도가 높아져 성능 저하 및 무한 루프 위험이 있으며, 코드 한 곳을 수정할 때 전혀 다른 곳에서 장애가 발생하는 '기술 부채'의 원인이 됩니다.",
+            action: "의존성 방향을 한 방향으로 정리하세요.",
+            reference: "https://peps.python.org/pep-0008/#imports",
+            whenItMatters: "프로젝트 코드 베이스가 5,000줄 이상으로 늘어날 때 유지보수가 불가능한 시크릿 코드로 변질됩니다."
+        };
+    }
+    return {
+        title: "기타 잠재적 리스크 (Other Potential Risks)",
+        category: 'Maintenance',
+        evidence: issue,
+        standard: "General Coding Best Practices",
+        impact: "비즈니스 안정성에 위협이 될 수 있습니다.",
+        action: "지속적인 모니터링이 필요합니다.",
+        reference: "#",
+        whenItMatters: "지속적인 관찰 없이는 언젠가 운영 환경에서 비용적 손실로 이어집니다."
+    };
+}
+async function analyzeRepository(repoPath, resultsDir) {
+    const files = [];
+    const IGNORE_DIRS = ["node_modules", ".git", "dist", "build", "venv", ".venv", "__pycache__"];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            const full = path.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                if (IGNORE_DIRS.includes(ent.name))
+                    continue;
+                walk(full);
+            }
+            else if (ent.isFile() && (ent.name.endsWith('.py') || ent.name.endsWith('.ts') || ent.name.endsWith('.js'))) {
+                files.push(full);
+            }
+        }
+    }
+    walk(repoPath);
+    const findings = [];
+    let criticalCount = 0;
+    let operationalGapCount = 0;
+    // 1. Operational Audit (Critical -30 each)
+    const auditChecks = [
+        { name: 'tests', type: 'directory', pattern: /tests?|spec/, message: '[서비스 중단 리스크] 테스트 코드가 없습니다. 장애 발생 시 복구 시간(MTTR)이 급증할 위험이 있습니다.' },
+        { name: 'CI', type: 'directory', pattern: /\.github\/workflows|\.circleci|jenkins|gitlab/, message: '[서비스 중단 리스크] 자동화된 CI 환경이 없습니다. 배포 안정성을 보장할 수 없습니다.' },
+        { name: 'Docker', type: 'file', pattern: /Dockerfile|docker-compose/, message: '[인프라 리스크] 컨테이너 기반 환경 설정이 없습니다. 로컬과 운영 환경 불일치로 인한 장애 발생 가능성이 높습니다.' },
+        { name: 'Pinning', type: 'file', pattern: /requirements\.txt|poetry\.lock|pyproject\.toml|package-lock\.json|pnpm-lock\.yaml/, message: '[인프라 리스크] 종속성 버전 고정 파일이 없습니다. 외부 라이브러리 업데이트 시 서비스가 즉시 중단될 수 있습니다.' },
+        { name: 'Env', type: 'file', pattern: /\.env\.example|\.env\.sample/, message: '[유지보수 리스크] 환경 설정 예시 파일(.env.example)이 없습니다. 신규 투입 인력의 셋업 비용이 발생하며 사고 대응이 늦어집니다.' },
+    ];
+    for (const check of auditChecks) {
+        let found = false;
+        try {
+            if (check.type === 'directory') {
+                const dirs = fs.readdirSync(repoPath, { withFileTypes: true }).filter(d => d.isDirectory());
+                found = dirs.some(d => check.pattern.test(d.name.toLowerCase()));
+            }
+            else {
+                const allFiles = fs.readdirSync(repoPath);
+                found = allFiles.some(f => check.pattern.test(f.toLowerCase()));
+            }
+        }
+        catch (e) {
+            found = false;
+        }
+        if (!found) {
+            const details = getAuditDetails('ProductionRisk', check.message);
+            findings.push({
+                file: 'Repository Root',
+                line: 0,
+                type: 'ProductionRisk',
+                ...details
+            });
+            operationalGapCount++;
+        }
+    }
+    // New Ritual Checks: Logging & Git Hygiene
+    const hasGitIgnore = fs.existsSync(path.join(repoPath, '.gitignore'));
+    if (!hasGitIgnore) {
+        const details = getAuditDetails('ProductionRisk', '[운영 리스크] .gitignore 파일이 없습니다. 민감한 정보가 저장소에 포함될 위험이 매우 높습니다.');
+        findings.push({ file: 'Repository Root', line: 0, type: 'ProductionRisk', ...details });
+        operationalGapCount++;
+    }
+    let hasLogging = false;
+    // 2. Code Level Analysis (Python logic)
+    for (const f of files.filter(f => f.endsWith('.py'))) {
+        try {
+            const code = fs.readFileSync(f, 'utf8');
+            const lines = code.split('\n');
+            const relativePath = path.relative(repoPath, f);
+            // Logging Check
+            if (code.includes('import logging') || code.includes('from loguru import logger')) {
+                hasLogging = true;
+            }
+            // God Module Check (>500 lines)
+            if (lines.length > 500) {
+                const details = getAuditDetails('ProductionRisk', `[유지보수 리스크] 거대 모듈(${lines.length}줄)이 감지되었습니다. 단일 파일의 책임이 과도하여 변경 시 장애 파급력이 큽니다.`);
+                findings.push({ file: relativePath, line: 0, type: 'ProductionRisk', ...details });
+                operationalGapCount++;
+            }
+            const result = await (0, analyzer_js_1.analyzePythonCode)(code, relativePath);
+            if (result.hasError) {
+                const details = getAuditDetails(result.type || 'Error', result.error || 'Unknown Issue');
+                findings.push({
+                    file: relativePath,
+                    line: result.line || 0,
+                    type: result.type || 'Error',
+                    ...details
+                });
+                if (result.type === 'SecurityRisk')
+                    criticalCount++;
+            }
+        }
+        catch (e) {
+            console.error(`Error analyzing ${f}:`, e);
+        }
+    }
+    if (!hasLogging && files.filter(f => f.endsWith('.py')).length > 0) {
+        const details = getAuditDetails('ProductionRisk', '[운영 리스크] 로그 시스템 사용이 감지되지 않습니다. 장애 발생 시 원인 파악이 불가능합니다.');
+        findings.push({ file: 'Repository Root', line: 0, type: 'ProductionRisk', ...details });
+        operationalGapCount++;
+    }
+    // 3. Dependency Scan (Scalability -15)
+    const { adj, cycles } = (0, archScanner_js_1.depsScan)(repoPath);
+    for (const cycle of cycles) {
+        const details = getAuditDetails('CircularDependency', '');
+        findings.push({
+            file: cycle[0],
+            line: 0,
+            type: 'CircularDependency',
+            ...details
+        });
+    }
+    // 4. Scoring Logic (PRS: Production Readiness Score)
+    // Max score is 95. Perfect project doesn't exist.
+    let score = 95;
+    score -= operationalGapCount * 30; // Critical operational gaps
+    score -= criticalCount * 45; // Security risks
+    score -= cycles.length * 15; // Structural issues
+    score = Math.max(0, score);
+    let status = 'Ready for Production';
+    if (score < 70)
+        status = 'Not Ready for Deployment';
+    else if (score < 90)
+        status = 'Needs Attention';
+    // 5. Visualization
+    let graphUrl = "";
+    if (resultsDir && fs.existsSync(resultsDir)) {
+        const scanId = `graph_${Date.now()}`;
+        const outputImgPath = path.join(resultsDir, `${scanId}.png`);
+        const configPath = path.join(resultsDir, `${scanId}.json`);
+        const edges = [];
+        adj.forEach((targets, source) => {
+            targets.forEach(target => edges.push([source, target]));
+        });
+        const config = { edges, cycles, output_path: outputImgPath };
+        fs.writeFileSync(configPath, JSON.stringify(config));
+        try {
+            const toolsDir = path.resolve(process.cwd(), "..", "..", "tools");
+            const visualizerPath = path.join(toolsDir, "visualizer.py");
+            (0, child_process_1.execSync)(`python3 ${visualizerPath} ${configPath}`);
+            graphUrl = `/results/${scanId}.png`;
+        }
+        catch (e) {
+            console.error("Visualization failed:", e.message);
+        }
+    }
+    return {
+        score,
+        status,
+        findings,
+        metrics: {
+            totalFiles: files.length,
+            pythonFiles: files.filter(f => f.endsWith('.py')).length,
+            criticalRisks: criticalCount,
+            operationalGaps: operationalGapCount
+        },
+        graphUrl,
+        disclosure: `배포 전 감사가 완료되었습니다. 발견된 리스크들은 실제 운영 환경에서 예기치 못한 서비스 중단이나 데이터 손실을 야기할 수 있는 항목들입니다.`,
+        cta: `배포 루틴 자동화를 위해 GitHub App을 설치하고 지속적인 배포 준비도(Release Readiness)를 관리하세요.`
+    };
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+    "name": "archrisk-engine",
+    "version": "1.0.0",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "build": "tsc",
+        "test": "jest"
+    },
+    "dependencies": {
+        "@google/generative-ai": "^0.21.0",
+        "fs-extra": "^11.1.1"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "@types/fs-extra": "^11.0.1",
+        "typescript": "^5.0.0",
+        "jest": "^29.0.0",
+        "ts-jest": "^29.0.0"
+    }
+}

package/src/aiDiagnosis.ts

@@ -0,0 +1,159 @@
+/**
+ * [The Brain] AI Diagnosis Engine (TypeScript Version)
+ * 
+ * Transforms errors and architecture issues into actionable solutions using Gemini API.
+ */
+
+import { ArchIssue } from "./archScanner.js";
+
+export interface DiagnosisResult {
+    severity: 'error' | 'warning';
+    issue: string;
+    suggestion: string;
+    fixedCode: string;
+    confidence: number;
+}
+
+const diagnosisCache = new Map<string, DiagnosisResult>();
+
+/**
+ * Call Gemini API with structured prompt
+ */
+async function callGeminiAPI(prompt: string): Promise<DiagnosisResult> {
+    const apiKey = process.env.GEMINI_API_KEY;
+
+    if (!apiKey) {
+        console.warn('[Brain] Gemini API key not configured. Returning mock diagnosis.');
+        return mockDiagnosis();
+    }
+
+    const model = process.env.AI_DIAGNOSIS_MODEL || 'gemini-2.0-flash';
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${apiKey}`;
+
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                contents: [{
+                    parts: [{ text: prompt }]
+                }],
+                generationConfig: {
+                    temperature: 0.2,
+                    maxOutputTokens: parseInt(process.env.AI_DIAGNOSIS_MAX_TOKENS || '1024')
+                }
+            })
+        });
+
+        const data = await response.json();
+
+        if (data.error) {
+            throw new Error(data.error.message);
+        }
+
+        const text = data.candidates[0].content.parts[0].text;
+
+        const jsonMatch = text.match(/```json\n([\s\S]*?)\n```/) || text.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+            return JSON.parse(jsonMatch[1] || jsonMatch[0]);
+        }
+
+        throw new Error('Failed to parse JSON from Gemini response');
+    } catch (error: any) {
+        console.error('[Brain] Gemini API error:', error.message);
+        return mockDiagnosis('AI Diagnosis limited - using fallback', error.message);
+    }
+}
+
+function mockDiagnosis(
+    issue = 'API key not configured - using mock diagnosis',
+    suggestion = 'Set GEMINI_API_KEY in environment variables'
+): DiagnosisResult {
+    return {
+        severity: 'error',
+        issue: issue,
+        suggestion: suggestion,
+        fixedCode: '# Gemini API quota exceeded or key missing. Using static fallback analysis.',
+        confidence: 0.0
+    };
+}
+
+/**
+ * Diagnose code error using Gemini AI
+ */
+export async function diagnoseCodeError(
+    file: string,
+    line: number,
+    errorType: string,
+    errorMessage: string,
+    codeContext: string
+): Promise<DiagnosisResult> {
+    const cacheKey = `${file}:${line}:${errorType}`;
+    if (diagnosisCache.has(cacheKey)) {
+        return diagnosisCache.get(cacheKey)!;
+    }
+
+    const prompt = `당신은 AI-to-Job 컴파일러입니다. Python 에러를 실행 가능한 작업 정의로 변환하는 역할입니다.
+
+**에러 정보:**
+- 타입: ${errorType}
+- 라인: ${line}
+- 파일: ${file}
+- 에러 메시지: ${errorMessage}
+
+**코드 컨텍스트:**
+\`\`\`python
+${codeContext}
+\`\`\`
+
+**작업:**
+이 에러를 분석하고 다음의 정확한 구조로 JSON 응답만 제공하세요:
+{
+    "severity": "error" | "warning",
+    "issue": "문제에 대한 간단한 설명 (한글)",
+    "suggestion": "실행 가능한 수정 지침 (한글)",
+    "fixedCode": "수정된 코드 스니펫",
+    "confidence": 0.0 ~ 1.0 사이의 값
+}
+
+**중요**: 유효한 JSON만 응답하세요. 설명이나 JSON 블록 밖의 마크다운은 작성하지 마세요.`;
+
+    const diagnosis = await callGeminiAPI(prompt);
+    diagnosisCache.set(cacheKey, diagnosis);
+    return diagnosis;
+}
+
+/**
+ * Diagnose architecture issue using Gemini AI
+ */
+export async function diagnoseArchIssue(
+    issue: ArchIssue,
+    fileContexts: { path: string, content: string }[]
+): Promise<DiagnosisResult> {
+    const contexts = fileContexts.map(f => `--- File: ${f.path} ---\n${f.content.slice(0, 2000)}...`).join('\n\n');
+
+    const prompt = `당신은 Senior Software Architect AI입니다. 현재 프로젝트의 아키텍처 결함을 분석하고 리팩토링 방안을 제시하는 역할입니다.
+
+**탐지된 이슈 정보:**
+- 타입(RuleId): ${issue.ruleId}
+- 제목: ${issue.title}
+- 상세 설명: ${issue.details}
+- 관련 경로: ${issue.relatedPaths?.join(', ') || 'N/A'}
+
+**코드 컨텍스트 (일부):**
+${contexts}
+
+**작업:**
+이 아키텍처 이슈를 분석하고 다음의 정확한 구조로 JSON 응답만 제공하세요:
+{
+    "severity": "error" | "warning",
+    "issue": "아키텍처 문제에 대한 구조적 분석 (한글)",
+    "suggestion": "구체적인 리팩토링 가이드 및 단계별 조치 사항 (한글)",
+    "fixedCode": "리팩토링에 도움이 되는 코드 스니펫 또는 인터페이스 설계 예시",
+    "confidence": 0.0 ~ 1.0 사이의 값
+}
+
+**중요**: 유효한 JSON만 응답하세요. 설명이나 JSON 블록 밖의 마크다운은 작성하지 마세요.`;
+
+    return await callGeminiAPI(prompt);
+}