agent-enderun 0.8.8 → 0.9.0

package/framework-mcp/src/tools/governance.ts

@@ -1,891 +0,0 @@
-/**
- * Governance Tools - MCP Tools for enforcing corporate governance standards
- * 
- * These tools bridge the .enderun/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, 
-  SourceFile, 
-  SyntaxKind,
-  FunctionDeclaration,
-  MethodDeclaration,
-  ArrowFunction,
-  Node,
-  InterfaceDeclaration,
-  ParameterDeclaration
-} from "ts-morph";
-
-// --- Standard Types for all Governance Tools ---
-
-export interface GovernanceViolation {
-  file: string;
-  line?: number;
-  rule: string;
-  severity: "critical" | "high" | "medium" | "low";
-  message: string;
-  suggestion?: string;
-}
-
-export interface GovernanceReport {
-  compliance_score: number; // 0-100
-  total_checks: number;
-  violations: GovernanceViolation[];
-  passed_checks: number;
-  summary: string;
-  recommendations: string[];
-}
-
-/**
- * Standard, consistent output format for all Governance Tools.
- * This structure is designed to be both human-readable and machine-friendly.
- */
-export interface GovernanceToolResult {
-  tool: string;
-  success: boolean;
-  executed_at: string;
-  summary: string;                    // Kısa, insan dostu özet
-  score?: number;                     // 0-100 arası uyum skoru (varsa)
-  violations_count?: number;
-  // Dynamic because governance tools return varying report shapes
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  data: GovernanceReport | Record<string, any>;
-  error?: string;
-}
-
-// --- Shared Helper Functions ---
-
-function createEmptyGovernanceReport(): GovernanceReport {
-  return {
-    compliance_score: 0,
-    total_checks: 0,
-    violations: [],
-    passed_checks: 0,
-    summary: "",
-    recommendations: [],
-  };
-}
-
-/**
- * Creates a standardized result object for Governance tools.
- */
-function createGovernanceToolResult(
-  toolName: string,
-  // Dynamic tool output shape
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  data: GovernanceReport | Record<string, any>,
-  summary: string,
-  success = true,
-  error?: string
-): GovernanceToolResult {
-  const base: GovernanceToolResult = {
-    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 as GovernanceReport;
-    base.score = report.compliance_score;
-    base.violations_count = report.violations.length;
-  }
-
-  return base;
-}
-
-// --- Helper Functions ---
-
-function collectTypeFiles(dir: string): string[] {
-  const files: string[] = [];
-  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;
-}
-
-// --- Safe ts-morph helpers for mixed Function / Method / ArrowFunction nodes ---
-type FunctionLike = FunctionDeclaration | MethodDeclaration | ArrowFunction;
-
-function getFunctionLikeName(node: FunctionLike | Node): string {
-  if (!node) return '<anonymous>';
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  if (typeof (node as any).getName === 'function') {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const n = (node as any).getName();
-    if (n) return n;
-  }
-  const parent = node.getParent?.();
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  if (parent && typeof (parent as any).getName === 'function') {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const pn = (parent as any).getName();
-    if (pn) return pn;
-  }
-  return '<anonymous>';
-}
-
-function getFunctionLikeParameters(node: FunctionLike | Node): ParameterDeclaration[] {
-  if (!node) return [];
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  if (typeof (node as any).getParameters === 'function') {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    return (node as any).getParameters();
-  }
-  return [];
-}
-
-function collectSourceFiles(dir: string): string[] {
-  const files: string[] = [];
-  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: string): Project {
-  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: string): string[] {
-  // 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: string, bodyText: string, highRiskKeywords: string[]): boolean {
-  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: SourceFile[], interfaceName: string) {
-  for (const sf of sourceFiles) {
-    const iface = sf.getInterface(interfaceName);
-    if (iface) return iface;
-  }
-  return undefined;
-}
-
-function getInterfaceProperties(iface: InterfaceDeclaration): string[] {
-  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: Record<string, (args: any, _projectRoot: string) => Promise<{ content: Array<{ type: string; text: string }> }>> = {
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  verify_high_risk_compliance: async (args: any, projectRoot: string) => {
-    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: any) => {
-          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: any) => {
-          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: any) => {
-          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: any, projectRoot: string) => {
-    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: SourceFile[] = [];
-    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: any[] = [];
-
-    // 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: any, projectRoot: string) => {
-    const targetPath = args.targetPath || "apps/backend/src";
-
-    const fullPath = path.join(projectRoot, targetPath);
-
-    interface BrandedTypeReport {
-      total_files_scanned: number;
-      branded_types_found: number;
-      plain_id_violations: Array<{
-        file: string;
-        line: number;
-        issue: string;
-        message: string;
-      }>;
-      summary: string;
-      recommendations: string[];
-    }
-
-    const report: BrandedTypeReport = {
-      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: any, projectRoot: string) => {
-    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: any = {
-      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: any) => {
-              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)
-      }]
-    };
-  },
-};