check_md_code_blocks.py

# Copyright (c) Microsoft. All rights reserved.

"""Check code blocks in Markdown files for syntax errors."""

import argparse
from enum import Enum
import logging
import tempfile
import subprocess # nosec

from pygments import highlight # type: ignore
from pygments.formatters import TerminalFormatter
from pygments.lexers import PythonLexer

logger = logging.getLogger(__name__)
logger.addHandler(logging.StreamHandler())
logger.setLevel(logging.INFO)


class Colors(str, Enum):
 CEND = "\33[0m"
 CRED = "\33[31m"
 CREDBG = "\33[41m"
 CGREEN = "\33[32m"
 CGREENBG = "\33[42m"
 CVIOLET = "\33[35m"
 CGREY = "\33[90m"


def with_color(text: str, color: Colors) -> str:
 """Prints a string with the specified color."""
 return f"{color.value}{text}{Colors.CEND.value}"


def extract_python_code_blocks(markdown_file_path: str) -> list[tuple[str, int]]:
 """Extract Python code blocks from a Markdown file."""
 with open(markdown_file_path, encoding="utf-8") as file:
 lines = file.readlines()

 code_blocks: list[tuple[str, int]] = []
 in_code_block = False
 current_block: list[str] = []

 for i, line in enumerate(lines):
 if line.strip().startswith("```python"):
 in_code_block = True
 current_block = []
 elif line.strip().startswith("```"):
 in_code_block = False
 code_blocks.append(("\n".join(current_block), i - len(current_block) + 1))
 elif in_code_block:
 current_block.append(line)

 return code_blocks


def check_code_blocks(markdown_file_paths: list[str], exclude_patterns: list[str] | None = None) -> None:
 """Check Python code blocks in a Markdown file for syntax errors."""
 files_with_errors: list[str] = []
 exclude_patterns = exclude_patterns or []

 for markdown_file_path in markdown_file_paths:
 # Skip files that match any exclude pattern
 if any(pattern in markdown_file_path for pattern in exclude_patterns):
 logger.info(f"Skipping {markdown_file_path} (matches exclude pattern)")
 continue
 code_blocks = extract_python_code_blocks(markdown_file_path)
 had_errors = False
 for code_block, line_no in code_blocks:
 markdown_file_path_with_line_no = f"{markdown_file_path}:{line_no}"
 logger.info("Checking a code block in %s...", markdown_file_path_with_line_no)

 # Skip blocks that don't import agent_framework modules or import lab modules
 if (all(
 all(import_code not in code_block for import_code in [f"import {module}", f"from {module}"])
 for module in ["agent_framework"]
 ) or "agent_framework.lab" in code_block):
 logger.info(f' {with_color("OK[ignored]", Colors.CGREENBG)}')
 continue

 with tempfile.NamedTemporaryFile(suffix=".py", delete=False) as temp_file:
 temp_file.write(code_block.encode("utf-8"))
 temp_file.flush()

 # Run pyright on the temporary file using subprocess.run

 result = subprocess.run(["uv", "run", "pyright", temp_file.name], capture_output=True, text=True, cwd=".") # nosec
 if result.returncode != 0:
 highlighted_code = highlight(code_block, PythonLexer(), TerminalFormatter()) # type: ignore
 logger.info(
 f" {with_color('FAIL', Colors.CREDBG)}\n"
 f"{with_color('========================================================', Colors.CGREY)}\n"
 f"{with_color('Error', Colors.CRED)}: Pyright found issues in {with_color(markdown_file_path_with_line_no, Colors.CVIOLET)}:\n"
 f"{with_color('--------------------------------------------------------', Colors.CGREY)}\n"
 f"{highlighted_code}\n"
 f"{with_color('--------------------------------------------------------', Colors.CGREY)}\n"
 "\n"
 f"{with_color('pyright output:', Colors.CVIOLET)}\n"
 f"{with_color(result.stdout, Colors.CRED)}"
 f"{with_color('========================================================', Colors.CGREY)}\n"
 )
 had_errors = True
 else:
 logger.info(f" {with_color('OK', Colors.CGREENBG)}")

 if had_errors:
 files_with_errors.append(markdown_file_path)

 if files_with_errors:
 raise RuntimeError("Syntax errors found in the following files:\n" + "\n".join(files_with_errors))


if __name__ == "__main__":
 parser = argparse.ArgumentParser(description="Check code blocks in Markdown files for syntax errors.")
 # Argument is a list of markdown files containing glob patterns
 parser.add_argument("markdown_files", nargs="+", help="Markdown files to check.")
 parser.add_argument("--exclude", action="append", help="Exclude files containing this pattern.")
 args = parser.parse_args()
 check_code_blocks(args.markdown_files, args.exclude)