analyze_changes

Instructions

Implementation Reference

• lucidity/tools/code_analysis.py:287-424 (handler)

  The main tool handler function decorated with @mcp.tool("analyze_changes"). It fetches git diffs, parses changes per file, detects language, generates analysis prompts using analyze_changes_prompt, and returns structured data including prompts and instructions for AI analysis via MCP.

  @mcp.tool("analyze_changes")
  def analyze_changes(workspace_root: str = "", path: str = "") -> dict[str, Any]:
      """Prepare git changes for analysis through MCP.
  
      This tool examines the current git diff, extracts changed code,
      and prepares structured data with context for the AI to analyze.
  
      The tool doesn't perform analysis itself - it formats the git diff data
      and provides analysis instructions which get passed back to the AI model
      through the Model Context Protocol.
  
      Args:
          workspace_root: The root directory of the workspace/git repository
          path: Optional specific file path to analyze
  
      Returns:
          Structured git diff data with analysis instructions for the AI
      """
      logger.info("Starting git change analysis%s in workspace %s", f" for {path}" if path else "", workspace_root)
  
      if not workspace_root:
          return {"status": "error", "message": "workspace_root parameter is required"}
  
      # Get git diff
      logger.debug("Fetching git diff...")
      diff_content, staged_content = get_git_diff(workspace_root, path)
  
      # Get list of all changed files
      changed_files = get_changed_files(workspace_root)
  
      # Combine diff and staged content for complete changes
      combined_diff = diff_content
      if staged_content:
          combined_diff = combined_diff + "\n" + staged_content if combined_diff else staged_content
  
      logger.debug("Combined diff size: %d bytes", len(combined_diff))
  
      if not combined_diff:
          logger.warning("No changes detected in git diff")
          return {"status": "no_changes", "message": "No changes detected in the git diff", "file_list": []}
  
      # Parse the diff
      logger.debug("Parsing git diff...")
      parsed_diff = parse_git_diff(combined_diff)
  
      if not parsed_diff:
          logger.warning("No parseable changes in git diff")
          return {
              "status": "no_changes",
              "message": "No parseable changes detected in the git diff",
              "file_list": changed_files,
          }
  
      logger.info("Found %d files with changes to analyze", len(parsed_diff))
  
      # Process each changed file
      analysis_results = {}
      file_list = []
  
      for filename, diff_info in parsed_diff.items():
          logger.debug("Processing file: %s (status: %s)", filename, diff_info["status"])
          file_list.append(filename)
  
          # Skip certain files
          if filename.endswith((".lock", ".sum", ".mod", "package-lock.json", "yarn.lock", ".DS_Store")):
              logger.debug("Skipping excluded file: %s", filename)
              continue
  
          try:
              # Extract original and modified code
              logger.debug("Extracting code changes for %s", filename)
              original_code, modified_code = extract_code_from_diff(diff_info)
  
              # Skip if no significant code changes
              if len(modified_code.strip()) < 10:
                  logger.debug("Skipping %s - insufficient code changes (< 10 chars)", filename)
                  continue
  
              # Detect language
              language = detect_language(filename)
              logger.debug("Detected language for %s: %s", filename, language)
  
              # Create a prompt for analysis
              logger.debug("Generating analysis prompt for %s", filename)
              from ..prompts import analyze_changes_prompt
  
              analysis_prompt = analyze_changes_prompt(
                  code=modified_code, language=language, original_code=original_code if original_code else None
              )
              logger.debug("Generated analysis prompt of size: %d chars", len(analysis_prompt))
  
              # Store the analysis prompt to be returned
              analysis_results[filename] = {
                  "status": diff_info["status"],
                  "language": language,
                  "analysis_prompt": analysis_prompt,
                  "raw_diff": diff_info["raw_diff"],
                  "original_code": original_code,
                  "modified_code": modified_code,
              }
              logger.info("Successfully analyzed %s", filename)
  
          except Exception as e:
              logger.error("Error analyzing %s: %s", filename, e)
              analysis_results[filename] = {"status": "error", "message": f"Error analyzing file: {e!s}"}
  
      logger.info("Code analysis complete - processed %d files", len(analysis_results))
  
      # Return results with instructions for AI analysis
      return {
          "status": "success",
          "file_count": len(analysis_results),
          "file_list": file_list,
          "all_changed_files": changed_files,
          "results": analysis_results,
          "instructions": """
  This data contains git changes that you should analyze for code quality issues.
  As an AI model receiving this through MCP, your task is to:
  
  1. Review each changed file:
     - Examine the raw diff showing the exact changes
     - Compare the original and modified code
     - Consider the language and file status (added, modified, deleted)
  
  2. For each file, perform the analysis following the provided analysis prompt:
     - Analyze relevant quality dimensions
     - Assign severity levels to issues you identify
     - Provide line-specific explanations
     - Suggest concrete improvements
  
  3. After analyzing all files, provide:
     - An overall assessment of the code changes
     - A prioritized list of improvements
     - Any patterns or systemic issues you've identified
  
  Your analysis should be thorough yet focused on actionable improvements.
  """,
      }

• lucidity/tools/__init__.py:7-9 (registration)

  Package-level registration: imports analyze_changes from code_analysis.py and adds it to __all__, making it available when importing from lucidity.tools.

  from .code_analysis import analyze_changes
  
  __all__ = ["analyze_changes"]

• lucidity/prompts.py:204-220 (helper)

  Helper function decorated with @mcp.prompt("analyze_changes"). Generates a structured prompt for code change analysis, used inside the handler to prepare prompts for each changed file.

  @mcp.prompt("analyze_changes")
  def analyze_changes_prompt(code: str, language: str, original_code: str | None = None) -> str:
      """Generate a prompt for analyzing git code changes via MCP.
  
      This function creates a structured prompt that will be passed back
      to the AI model through the Model Context Protocol, guiding it to
      analyze git changes effectively.
  
      Args:
          code: The changed code to analyze
          language: The programming language of the code
          original_code: The original code before changes (optional)
  
      Returns:
          A formatted prompt for the AI to analyze git changes
      """
      return generate_analysis_prompt(code, language, original_code)