archrisk-engine 1.0.0

package/src/repoAnalyzer.ts

@@ -0,0 +1,298 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { analyzePythonCode, AnalysisResult } from './analyzer.js';
+import { depsScan } from './archScanner.js';
+
+export interface RepoAnalysisResult {
+    score: number; // Release Readiness Score (RRS)
+    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 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 } {
+    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: "지속적인 관찰 없이는 언젠가 운영 환경에서 비용적 손실로 이어집니다."
+    };
+}
+
+export async function analyzeRepository(repoPath: string, resultsDir?: string): Promise<RepoAnalysisResult> {
+    const files: string[] = [];
+    const IGNORE_DIRS = ["node_modules", ".git", "dist", "build", "venv", ".venv", "__pycache__"];
+
+    function walk(dir: string) {
+        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: RepoAnalysisResult['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 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 } = 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: RepoAnalysisResult['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: [string, string][] = [];
+        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");
+            execSync(`python3 ${visualizerPath} ${configPath}`);
+            graphUrl = `/results/${scanId}.png`;
+        } catch (e: any) {
+            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/tsconfig.json

@@ -0,0 +1,22 @@
+{
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "declaration": true
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+        "**/*.test.ts"
+    ]
+}