agent-enderun 0.7.1 → 0.7.5

package/framework-mcp/dist/tools/governance.js

@@ -0,0 +1,696 @@
+/**
+ * Governance Tools - MCP Tools for enforcing corporate governance standards
+ *
+ * These tools bridge the .gemini/knowledge/corporate-governance/ knowledge base
+ * with actual code-level compliance verification.
+ *
+ * Philosophy: We do not just document standards — we actively verify them.
+ *
+ * All tools now return a standardized GovernanceToolResult format for consistency.
+ */
+import fs from "fs";
+import path from "path";
+import { Project, SyntaxKind } from "ts-morph";
+// --- Shared Helper Functions ---
+function createEmptyGovernanceReport() {
+    return {
+        compliance_score: 0,
+        total_checks: 0,
+        violations: [],
+        passed_checks: 0,
+        summary: "",
+        recommendations: [],
+    };
+}
+/**
+ * Creates a standardized result object for Governance tools.
+ */
+function createGovernanceToolResult(toolName, 
+// Dynamic tool output shape
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+data, summary, success = true, error) {
+    const base = {
+        tool: toolName,
+        success,
+        executed_at: new Date().toISOString(),
+        summary,
+        data,
+        error,
+    };
+    // Eğer data bir GovernanceReport ise, ekstra alanları doldur
+    if (data && typeof data === "object" && "compliance_score" in data) {
+        const report = data;
+        base.score = report.compliance_score;
+        base.violations_count = report.violations.length;
+    }
+    return base;
+}
+// --- Helper Functions ---
+function collectTypeFiles(dir) {
+    const files = [];
+    if (!fs.existsSync(dir))
+        return files;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...collectTypeFiles(fullPath));
+        }
+        else if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function getFunctionLikeName(node) {
+    if (!node)
+        return '<anonymous>';
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if (typeof node.getName === 'function') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const n = node.getName();
+        if (n)
+            return n;
+    }
+    const parent = node.getParent?.();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if (parent && typeof parent.getName === 'function') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const pn = parent.getName();
+        if (pn)
+            return pn;
+    }
+    return '<anonymous>';
+}
+function getFunctionLikeParameters(node) {
+    if (!node)
+        return [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if (typeof node.getParameters === 'function') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return node.getParameters();
+    }
+    return [];
+}
+function collectSourceFiles(dir) {
+    const files = [];
+    if (!fs.existsSync(dir))
+        return files;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...collectSourceFiles(fullPath));
+        }
+        else if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+/**
+ * Creates a standard ts-morph Project instance for analysis.
+ */
+function createAnalysisProject(projectRoot) {
+    return new Project({
+        tsConfigFilePath: path.join(projectRoot, "tsconfig.json"),
+        skipAddingFilesFromTsConfig: true,
+    });
+}
+/**
+ * Returns high-risk action patterns.
+ *
+ * Currently uses a stable, curated list derived from corporate-governance standards.
+ * This approach is much more reliable than parsing markdown files with regex.
+ *
+ * In the future, this can be expanded to read from a structured JSON/YAML file
+ * if more dynamic rule management is needed.
+ */
+function loadHighRiskPatterns(_projectRoot) {
+    // Stable, well-defined high-risk keywords based on corporate governance standards
+    // (high-risk-actions-managerapproval.md and related documents)
+    return [
+        // Role & Permission elevation
+        "promote", "elevate", "superadmin", "admin", "role", "permission", "grant", "revoke",
+        // Destructive operations
+        "delete", "purge", "bulk",
+        // System configuration & reset
+        "reset", "configure", "config", "system",
+        // Sensitive data operations
+        "export", "audit"
+    ];
+}
+/**
+ * Determines if a function is likely performing a high-risk administrative action.
+ * This is the central detection logic for verify_high_risk_compliance.
+ */
+function isHighRiskFunction(functionName, bodyText, highRiskKeywords) {
+    const name = functionName.toLowerCase();
+    const body = bodyText.toLowerCase();
+    const combined = name + body;
+    // 1. Temel yüksek riskli kelimeler
+    const hasKeyword = highRiskKeywords.some(kw => name.includes(kw) || body.includes(kw));
+    // 2. Route ve endpoint pattern'ları (REST + admin rotaları)
+    const routePatterns = [
+        /post.*role|put.*role|patch.*role|delete.*user/i,
+        /post.*admin|put.*permission/i,
+        /\/(api|admin|users?|roles?|permissions?)\/.*(role|admin|permission|promote|elevate|grant|revoke)/i
+    ];
+    const hasRoutePattern = routePatterns.some(regex => regex.test(combined));
+    // 3. Semantic yetki değiştirme desenleri (kod içinde privilege manipülasyonu)
+    const semanticPatterns = [
+        /changeRole|assignRole|updateRole|setPermission|grantPermission|revokePermission|makeAdmin|setAdmin/i,
+        /role\s*=\s*['"`]?(admin|superadmin|super_admin)/i,
+        /permissions?\s*\.\s*(push|add)/i
+    ];
+    const hasSemanticPrivilegeChange = semanticPatterns.some(regex => regex.test(body));
+    return hasKeyword || hasRoutePattern || hasSemanticPrivilegeChange;
+}
+function findInterface(sourceFiles, interfaceName) {
+    for (const sf of sourceFiles) {
+        const iface = sf.getInterface(interfaceName);
+        if (iface)
+            return iface;
+    }
+    return undefined;
+}
+function getInterfaceProperties(iface) {
+    return iface.getProperties().map((p) => p.getName());
+}
+// --- Tool Definitions ---
+export const governanceTools = [
+    {
+        name: "verify_high_risk_compliance",
+        description: "Analyzes high-risk administrative endpoints and verifies compliance with corporate governance standards (managerApproval, branded types, audit logging, error handling).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                backendPath: {
+                    type: "string",
+                    description: "Relative path to backend source (default: apps/backend/src)",
+                },
+                strictMode: {
+                    type: "boolean",
+                    description: "If true, treats warnings as violations (default: false)",
+                },
+            },
+        },
+    },
+    {
+        name: "detect_contract_drift",
+        description: "Detects contract drift between backend types and frontend copies, with focus on corporate governance contracts (Branded Types, ManagerApproval, etc.).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                backendTypesPath: {
+                    type: "string",
+                    description: "Path to backend types directory (default: apps/backend/src/types)",
+                },
+                frontendTypesPath: {
+                    type: "string",
+                    description: "Path to frontend type copies (default: apps/web/src/types)",
+                },
+            },
+        },
+    },
+    {
+        name: "validate_branded_types_usage",
+        description: "Scans the codebase for proper usage of Branded Types as defined in corporate governance standards.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                targetPath: {
+                    type: "string",
+                    description: "Directory to scan (default: apps/backend/src)",
+                },
+            },
+        },
+    },
+    {
+        name: "audit_governance_compliance",
+        description: "Performs a high-level governance audit of the entire project by combining results from other governance tools. Returns an overall compliance score and prioritized issues.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                backendPath: {
+                    type: "string",
+                    description: "Path to backend source (default: apps/backend/src)",
+                },
+                includeContractCheck: {
+                    type: "boolean",
+                    description: "Whether to also run contract drift detection (default: true)",
+                },
+            },
+        },
+    },
+];
+// --- Handlers (Implementation starts here) ---
+// args is any because these are dynamic MCP tool handlers
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const governanceHandlers = {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    verify_high_risk_compliance: async (args, projectRoot) => {
+        const backendPath = args.backendPath || "apps/backend/src";
+        const fullBackendPath = path.join(projectRoot, backendPath);
+        if (!fs.existsSync(fullBackendPath)) {
+            const result = createGovernanceToolResult("verify_high_risk_compliance", createEmptyGovernanceReport(), `Backend source directory not found: ${backendPath}`, false);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        const project = createAnalysisProject(projectRoot);
+        const sourceFiles = collectSourceFiles(fullBackendPath).map(f => project.addSourceFileAtPath(f));
+        const report = createEmptyGovernanceReport();
+        // Load high-risk patterns dynamically from corporate governance knowledge
+        const highRiskKeywords = loadHighRiskPatterns(projectRoot);
+        let highRiskFunctionsFound = 0;
+        for (const sourceFile of sourceFiles) {
+            // Daha kapsamlı fonksiyon + method + route handler tespiti
+            const functions = [
+                ...sourceFile.getFunctions(),
+                ...sourceFile.getDescendantsOfKind(SyntaxKind.MethodDeclaration),
+                ...sourceFile.getDescendantsOfKind(SyntaxKind.ArrowFunction),
+            ];
+            for (const func of functions) {
+                const name = getFunctionLikeName(func);
+                const bodyText = func.getBodyText() || "";
+                // === GÜÇLENDİRİLMİŞ HIGH-RISK FONKSİYON TESPİTİ ===
+                const isLikelyHighRisk = isHighRiskFunction(name, bodyText, highRiskKeywords);
+                if (!isLikelyHighRisk)
+                    continue;
+                highRiskFunctionsFound++;
+                // === Daha Derin ve Yapısal AST Tabanlı Kontroller ===
+                const parameters = getFunctionLikeParameters(func);
+                // 1. High-risk validation kontrolü (daha güçlü AST + semantic)
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const hasProperHighRiskCheck = func.getDescendantsOfKind(SyntaxKind.IfStatement).some((ifStmt) => {
+                    const conditionText = ifStmt.getExpression().getText().toLowerCase();
+                    const hasFlag = conditionText.includes("ishighriskadminaction");
+                    const hasApproval = conditionText.includes("managerapproval");
+                    return hasFlag && hasApproval;
+                });
+                if (!hasProperHighRiskCheck) {
+                    report.violations.push({
+                        file: path.relative(projectRoot, sourceFile.getFilePath()),
+                        line: func.getStartLineNumber(),
+                        rule: "insufficient_high_risk_validation",
+                        severity: "critical",
+                        message: `High-risk function "${name}" does not contain proper conditional check for both isHighRiskAdminAction and managerApproval.`,
+                        suggestion: "Add: if (!body.isHighRiskAdminAction || !body.managerApproval) { throw new HighRiskActionRequiresApprovalError(...) }"
+                    });
+                }
+                else {
+                    // Ekstra: ManagerApproval yapısal validasyonu (approvedBy kontrolü)
+                    const hasApprovedByCheck = /approvedBy|approval\.approvedBy/i.test(bodyText);
+                    if (!hasApprovedByCheck) {
+                        report.violations.push({
+                            file: path.relative(projectRoot, sourceFile.getFilePath()),
+                            line: func.getStartLineNumber(),
+                            rule: "weak_manager_approval_validation",
+                            severity: "high",
+                            message: `High-risk function "${name}" checks managerApproval but does not validate approvedBy field.`,
+                            suggestion: "Add check: if (managerApproval.approvedBy !== 'manager') { ... }"
+                        });
+                    }
+                }
+                // 2. Typed Error kullanımı (daha doğru tespit)
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const throwsTypedError = func.getDescendantsOfKind(SyntaxKind.ThrowStatement).some((throwStmt) => {
+                    const expr = throwStmt.getExpression().getText();
+                    return expr.includes("HighRiskActionRequiresApprovalError") || expr.includes("DomainError");
+                });
+                if (!throwsTypedError && hasProperHighRiskCheck) {
+                    report.violations.push({
+                        file: path.relative(projectRoot, sourceFile.getFilePath()),
+                        line: func.getStartLineNumber(),
+                        rule: "missing_typed_error",
+                        severity: "high",
+                        message: `High-risk function "${name}" performs governance checks but does not throw a typed DomainError.`,
+                        suggestion: "Throw HighRiskActionRequiresApprovalError for high-risk governance violations."
+                    });
+                }
+                // 3. Audit Logging kontrolü (daha iyi tespit)
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const hasAuditLogging = func.getDescendantsOfKind(SyntaxKind.CallExpression).some((call) => {
+                    const callText = call.getExpression().getText().toLowerCase();
+                    return callText.includes("audit") || callText.includes("log");
+                }) || /auditLog|audit\.create/i.test(bodyText);
+                if (!hasAuditLogging) {
+                    report.violations.push({
+                        file: path.relative(projectRoot, sourceFile.getFilePath()),
+                        line: func.getStartLineNumber(),
+                        rule: "missing_audit_logging",
+                        severity: "high",
+                        message: `High-risk function "${name}" does not create an audit log entry.`,
+                        suggestion: "Always create an audit log entry for high-risk actions (see audit-logging-standard.md)."
+                    });
+                }
+                // 4. Branded Types kullanımı (parametre seviyesinde gerçek tip kontrolü)
+                let hasBrandedTypesInParams = false;
+                for (const param of parameters) {
+                    const typeText = param.getType().getText();
+                    if (/\b(UserID|RoleID|ApprovalID|TraceID)\b/.test(typeText)) {
+                        hasBrandedTypesInParams = true;
+                        break;
+                    }
+                }
+                if (!hasBrandedTypesInParams) {
+                    report.violations.push({
+                        file: path.relative(projectRoot, sourceFile.getFilePath()),
+                        line: func.getStartLineNumber(),
+                        rule: "missing_branded_types",
+                        severity: "high",
+                        message: `High-risk function "${name}" does not use Branded Types in its parameters.`,
+                        suggestion: "Use UserID, RoleID, ApprovalID etc. instead of plain string or number."
+                    });
+                }
+            }
+        }
+        // Her high-risk fonksiyon için şu kontroller yapılıyor:
+        // 1. High-risk flag + managerApproval kontrolü
+        // 2. Typed DomainError (HighRiskActionRequiresApprovalError) kullanımı
+        // 3. Audit logging çağrısı
+        // 4. Branded Types kullanımı (parametrelerde)
+        const totalChecks = highRiskFunctionsFound * 4;
+        const violationsCount = report.violations.length;
+        const passed = Math.max(0, totalChecks - violationsCount);
+        report.total_checks = totalChecks;
+        report.passed_checks = passed;
+        report.compliance_score = totalChecks > 0
+            ? Math.round((passed / totalChecks) * 100)
+            : 100;
+        if (violationsCount === 0 && highRiskFunctionsFound > 0) {
+            report.summary = `✅ Good compliance. Analyzed ${highRiskFunctionsFound} high-risk functions.`;
+        }
+        else if (highRiskFunctionsFound === 0) {
+            report.summary = "No high-risk functions matching governance patterns were detected.";
+        }
+        else {
+            report.summary = `Analyzed ${highRiskFunctionsFound} high-risk functions. Found ${violationsCount} governance violations.`;
+        }
+        if (violationsCount > 0) {
+            report.recommendations.push("Review all critical violations first (missing managerApproval checks).");
+            report.recommendations.push("Load corporate-governance/high-risk-actions-managerapproval.md for the exact expected pattern.");
+        }
+        const finalResult = createGovernanceToolResult("verify_high_risk_compliance", report, report.summary || "High-risk compliance analysis completed.");
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(finalResult, null, 2)
+                }]
+        };
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    detect_contract_drift: async (args, projectRoot) => {
+        const backendTypesPath = args.backendTypesPath || "apps/backend/src/types";
+        const frontendTypesPath = args.frontendTypesPath || "apps/web/src/types";
+        const backendDir = path.join(projectRoot, backendTypesPath);
+        const frontendDir = path.join(projectRoot, frontendTypesPath);
+        if (!fs.existsSync(backendDir)) {
+            const result = createGovernanceToolResult("detect_contract_drift", { drift_detected: false }, `Backend types directory not found: ${backendTypesPath}`, false);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        const project = createAnalysisProject(projectRoot);
+        // Load backend types
+        const backendFiles = collectTypeFiles(backendDir);
+        const backendSourceFiles = backendFiles.map(f => project.addSourceFileAtPath(f));
+        // Load frontend type copies (if exists)
+        let frontendSourceFiles = [];
+        if (fs.existsSync(frontendDir)) {
+            const frontendFiles = collectTypeFiles(frontendDir);
+            frontendSourceFiles = frontendFiles.map(f => project.addSourceFileAtPath(f));
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const drifts = [];
+        // Compare interfaces (focus on governance-related types)
+        const governanceTypeNames = [
+            "UserID", "RoleID", "ApprovalID", "TraceID",
+            "ManagerApproval", "HighRiskActionPayload",
+            "User", "Role", "DomainError"
+        ];
+        for (const typeName of governanceTypeNames) {
+            const backendInterface = findInterface(backendSourceFiles, typeName);
+            const frontendInterface = findInterface(frontendSourceFiles, typeName);
+            if (backendInterface && !frontendInterface) {
+                drifts.push({
+                    type: typeName,
+                    issue: "MISSING_IN_FRONTEND",
+                    severity: "high",
+                    message: `Governance type "${typeName}" exists in backend but is missing in frontend copies.`,
+                });
+            }
+            if (backendInterface && frontendInterface) {
+                const backendProps = getInterfaceProperties(backendInterface);
+                const frontendProps = getInterfaceProperties(frontendInterface);
+                const missingInFrontend = backendProps.filter(p => !frontendProps.includes(p));
+                const extraInFrontend = frontendProps.filter(p => !backendProps.includes(p));
+                if (missingInFrontend.length > 0 || extraInFrontend.length > 0) {
+                    drifts.push({
+                        type: typeName,
+                        issue: "STRUCTURE_MISMATCH",
+                        severity: "high",
+                        missing_in_frontend: missingInFrontend,
+                        extra_in_frontend: extraInFrontend,
+                        message: `Structural drift detected in governance type "${typeName}".`,
+                    });
+                }
+            }
+        }
+        const report = {
+            drift_detected: drifts.length > 0,
+            total_governance_types_checked: governanceTypeNames.length,
+            drifts,
+            backend_types_path: backendTypesPath,
+            frontend_types_path: frontendTypesPath,
+            recommendation: drifts.length > 0
+                ? "Run update_contract_hash after aligning frontend copies. Consider using corporate-governance-playbook.md for alignment process."
+                : "No significant drift detected in core governance types.",
+        };
+        const summary = drifts.length > 0
+            ? `Contract drift detected in ${drifts.length} governance types.`
+            : "No significant contract drift found in core governance types.";
+        const finalResult = createGovernanceToolResult("detect_contract_drift", report, summary);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(finalResult, null, 2)
+                }]
+        };
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    validate_branded_types_usage: async (args, projectRoot) => {
+        const targetPath = args.targetPath || "apps/backend/src";
+        const fullPath = path.join(projectRoot, targetPath);
+        const report = {
+            total_files_scanned: 0,
+            branded_types_found: 0,
+            plain_id_violations: [],
+            summary: "",
+            recommendations: [],
+        };
+        if (!fs.existsSync(fullPath)) {
+            const result = createGovernanceToolResult("validate_branded_types_usage", { total_files_scanned: 0, plain_id_violations: [] }, `Target directory not found: ${targetPath}`, false);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        const project = createAnalysisProject(projectRoot);
+        const sourceFiles = collectSourceFiles(fullPath).map(f => project.addSourceFileAtPath(f));
+        report.total_files_scanned = sourceFiles.length;
+        // Branded type names we care about (from our governance standards)
+        const brandedTypeNames = ["UserID", "RoleID", "ApprovalID", "TraceID"];
+        for (const sourceFile of sourceFiles) {
+            // Check interface/type definitions first
+            const interfaces = sourceFile.getInterfaces();
+            for (const iface of interfaces) {
+                for (const prop of iface.getProperties()) {
+                    const typeText = prop.getType().getText();
+                    const propName = prop.getName().toLowerCase();
+                    // Look for ID fields that should be branded
+                    if (propName.includes("id") || propName.includes("userid") || propName.includes("roleid")) {
+                        const isBranded = brandedTypeNames.some(bt => typeText.includes(bt));
+                        if (!isBranded && (typeText.includes("string") || typeText.includes("number"))) {
+                            report.plain_id_violations.push({
+                                file: path.relative(projectRoot, sourceFile.getFilePath()),
+                                line: prop.getStartLineNumber(),
+                                issue: "plain_id_in_interface",
+                                message: `Property "${prop.getName()}" uses plain ${typeText} instead of a branded type.`,
+                            });
+                        }
+                    }
+                }
+            }
+            // Check function parameters and variables
+            const functions = [
+                ...sourceFile.getFunctions(),
+                ...sourceFile.getDescendantsOfKind(SyntaxKind.MethodDeclaration),
+            ];
+            for (const func of functions) {
+                // Parameters
+                for (const param of getFunctionLikeParameters(func)) {
+                    const typeText = param.getType().getText();
+                    const paramName = param.getName().toLowerCase();
+                    if (paramName.includes("id") || paramName.includes("userid") || paramName.includes("roleid")) {
+                        const isBranded = brandedTypeNames.some(bt => typeText.includes(bt));
+                        if (!isBranded && (typeText.includes("string") || typeText.includes("number"))) {
+                            report.plain_id_violations.push({
+                                file: path.relative(projectRoot, sourceFile.getFilePath()),
+                                line: param.getStartLineNumber(),
+                                issue: "plain_id_in_parameter",
+                                message: `Parameter "${param.getName()}" uses plain ${typeText} instead of branded type (e.g. UserID).`,
+                            });
+                        }
+                        else if (isBranded) {
+                            report.branded_types_found++;
+                        }
+                    }
+                }
+            }
+        }
+        const violationCount = report.plain_id_violations.length;
+        if (violationCount === 0) {
+            report.summary = `✅ Good. No plain ID usages found in governance-related contexts across ${report.total_files_scanned} files.`;
+        }
+        else {
+            report.summary = `Found ${violationCount} violations where plain string/number was used instead of branded types.`;
+            report.recommendations.push("Replace plain IDs with branded types (UserID, RoleID, ApprovalID, etc.).");
+            report.recommendations.push("See branded-types-law.md for the full standard.");
+        }
+        const summary = violationCount === 0
+            ? `No branded type violations found in ${report.total_files_scanned} files.`
+            : `${violationCount} plain ID violations detected.`;
+        const finalResult = createGovernanceToolResult("validate_branded_types_usage", report, summary);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(finalResult, null, 2)
+                }]
+        };
+    },
+    // ============================================
+    // audit_governance_compliance (Bağımsız Versiyon)
+    // ============================================
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    audit_governance_compliance: async (args, projectRoot) => {
+        const backendPath = args.backendPath || "apps/backend/src";
+        const includeContractCheck = args.includeContractCheck ?? true;
+        const fullBackendPath = path.join(projectRoot, backendPath);
+        const frontendTypesPath = path.join(projectRoot, "apps/web/src/types");
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const overview = {
+            overall_score: 0,
+            areas: {},
+            critical_issues: [],
+            summary: "",
+            recommendations: [],
+        };
+        // ============================================
+        // 1. High-Risk Compliance (Bağımsız basit analiz)
+        // ============================================
+        let highRiskViolations = 0;
+        if (fs.existsSync(fullBackendPath)) {
+            const project = createAnalysisProject(projectRoot);
+            const sourceFiles = collectSourceFiles(fullBackendPath).map(f => project.addSourceFileAtPath(f));
+            const highRiskKeywords = ["promote", "elevate", "superadmin", "admin", "role", "delete", "purge", "reset"];
+            for (const sourceFile of sourceFiles) {
+                const functions = [
+                    ...sourceFile.getFunctions(),
+                    ...sourceFile.getDescendantsOfKind(SyntaxKind.MethodDeclaration),
+                    ...sourceFile.getDescendantsOfKind(SyntaxKind.ArrowFunction),
+                ];
+                for (const func of functions) {
+                    const name = getFunctionLikeName(func);
+                    const bodyText = func.getBodyText() || "";
+                    const lowerBody = bodyText.toLowerCase();
+                    const isHighRisk = highRiskKeywords.some(kw => name.toLowerCase().includes(kw) || lowerBody.includes(kw));
+                    if (isHighRisk) {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const hasFlagAndApproval = func.getDescendantsOfKind(SyntaxKind.IfStatement).some((ifStmt) => {
+                            const cond = ifStmt.getExpression().getText().toLowerCase();
+                            return cond.includes("ishighriskadminaction") && cond.includes("managerapproval");
+                        });
+                        if (!hasFlagAndApproval)
+                            highRiskViolations++;
+                    }
+                }
+            }
+        }
+        overview.areas.high_risk = {
+            violations: highRiskViolations,
+            status: highRiskViolations === 0 ? "good" : "issues_found",
+        };
+        // ============================================
+        // 2. Branded Types (Bağımsız basit analiz)
+        // ============================================
+        let brandedViolations = 0;
+        if (fs.existsSync(fullBackendPath)) {
+            const project = createAnalysisProject(projectRoot);
+            const sourceFiles = collectSourceFiles(fullBackendPath).map(f => project.addSourceFileAtPath(f));
+            const brandedNames = ["UserID", "RoleID", "ApprovalID", "TraceID"];
+            for (const sourceFile of sourceFiles) {
+                const functions = [
+                    ...sourceFile.getFunctions(),
+                    ...sourceFile.getDescendantsOfKind(SyntaxKind.MethodDeclaration),
+                ];
+                for (const func of functions) {
+                    const params = func.getParameters();
+                    for (const param of params) {
+                        const typeText = param.getType().getText();
+                        const paramName = param.getName().toLowerCase();
+                        if ((paramName.includes("id") || paramName.includes("userid") || paramName.includes("roleid")) &&
+                            !brandedNames.some(b => typeText.includes(b)) &&
+                            (typeText.includes("string") || typeText.includes("number"))) {
+                            brandedViolations++;
+                        }
+                    }
+                }
+            }
+        }
+        overview.areas.branded_types = {
+            violations: brandedViolations,
+            status: brandedViolations === 0 ? "good" : "issues_found",
+        };
+        // ============================================
+        // 3. Contract Drift (basit klasör karşılaştırması)
+        // ============================================
+        if (includeContractCheck) {
+            const backendTypesExist = fs.existsSync(path.join(projectRoot, "apps/backend/src/types"));
+            const frontendTypesExist = fs.existsSync(frontendTypesPath);
+            overview.areas.contract_drift = {
+                backend_types_present: backendTypesExist,
+                frontend_types_present: frontendTypesExist,
+                likely_drift: backendTypesExist && !frontendTypesExist,
+            };
+        }
+        // ============================================
+        // Genel Skor Hesaplama
+        // ============================================
+        const highRiskScore = overview.areas.high_risk.violations === 0 ? 85 : 55;
+        const brandedScore = overview.areas.branded_types.violations === 0 ? 90 : 60;
+        const contractScore = overview.areas.contract_drift?.likely_drift === false ? 80 : 50;
+        const scores = [highRiskScore, brandedScore, contractScore].filter(Boolean);
+        overview.overall_score = Math.round(scores.reduce((a, b) => a + b, 0) / scores.length);
+        // Kritik sorunları topla
+        if (overview.areas.high_risk.violations > 0) {
+            overview.critical_issues.push({
+                area: "high_risk",
+                count: overview.areas.high_risk.violations,
+                message: "High-risk functions without proper managerApproval validation detected.",
+            });
+        }
+        if (overview.areas.branded_types.violations > 0) {
+            overview.critical_issues.push({
+                area: "branded_types",
+                count: overview.areas.branded_types.violations,
+                message: "Plain string/number IDs used instead of Branded Types.",
+            });
+        }
+        overview.summary = `Overall governance compliance score: ${overview.overall_score}/100 (Independent analysis)`;
+        if (overview.overall_score < 70) {
+            overview.recommendations.push("Focus on high-risk validation and Branded Types first.");
+        }
+        const finalResult = createGovernanceToolResult("audit_governance_compliance", overview, overview.summary);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(finalResult, null, 2)
+                }]
+        };
+    },
+};