Buckets:
AnonymousSpottedToad/candidate_bucket / codebase /python /Consiliency_treesitter-chunker /scripts /validate_examples.py
| #!/usr/bin/env python3 | |
| """Validate all cookbook examples and documentation code snippets.""" | |
| import os | |
| import re | |
| import subprocess | |
| import sys | |
| import tempfile | |
| from pathlib import Path | |
| from typing import Dict, List, Tuple | |
| class ExampleValidator: | |
| """Validates code examples in documentation.""" | |
| def __init__(self): | |
| self.project_root = Path(__file__).parent.parent | |
| self.results = {"passed": [], "failed": [], "skipped": [], "total": 0} | |
| def find_code_blocks(self, file_path: Path) -> list[tuple[str, int, str]]: | |
| """Extract code blocks from markdown files.""" | |
| code_blocks = [] | |
| if not file_path.exists(): | |
| return code_blocks | |
| try: | |
| content = file_path.read_text(encoding="utf-8") | |
| lines = content.split("\n") | |
| in_code_block = False | |
| current_block = [] | |
| start_line = 0 | |
| language = "" | |
| for i, line in enumerate(lines, 1): | |
| # Check for code block start | |
| if line.startswith("```"): | |
| if not in_code_block: | |
| # Starting new block | |
| in_code_block = True | |
| start_line = i | |
| language = line[3:].strip() | |
| current_block = [] | |
| else: | |
| # Ending block | |
| in_code_block = False | |
| if current_block: | |
| code_blocks.append( | |
| ("\n".join(current_block), start_line, language), | |
| ) | |
| current_block = [] | |
| elif in_code_block: | |
| current_block.append(line) | |
| except Exception as e: | |
| print(f"❌ Error reading {file_path}: {e}") | |
| return code_blocks | |
| def is_type_hint_or_signature(self, code: str) -> bool: | |
| """Check if code block contains only type hints or function signatures.""" | |
| lines = code.strip().split("\n") | |
| # Common patterns that indicate type hints or signatures | |
| type_hint_patterns = [ | |
| # Variable type hints | |
| r"^[a-zA-Z_][a-zA-Z0-9_]*\s*:\s*[a-zA-Z_][a-zA-Z0-9_\[\]|, \.]*\s*$", # var: type | |
| # Function signatures with return types | |
| r"^def\s+[a-zA-Z_][a-zA-Z0-9_]*\s*\([^)]*\)\s*->\s*[a-zA-Z_][a-zA-Z0-9_\[\]|, \.]*\s*$", # def func() -> type | |
| # Function signatures without return types | |
| r"^def\s+[a-zA-Z_][a-zA-Z0-9_]*\s*\([^)]*\)\s*$", # def func() | |
| # Class definitions | |
| r"^class\s+[a-zA-Z_][a-zA-Z0-9_]*\s*\([^)]*\)\s*$", # class Class() | |
| r"^class\s+[a-zA-Z_][a-zA-Z0-9_]*\s*$", # class Class | |
| # Simple assignments | |
| r"^[a-zA-Z_][a-zA-Z0-9_]*\s*=\s*[a-zA-Z_][a-zA-Z0-9_]*\s*$", # var = value | |
| # Import statements | |
| r"^from\s+[a-zA-Z_][a-zA-Z0-9_.]*\s+import\s+[a-zA-Z_][a-zA-Z0-9_, \*]*\s*$", # from x import y | |
| r"^import\s+[a-zA-Z_][a-zA-Z0-9_, \.]*\s*$", # import x | |
| # Type aliases | |
| r"^[A-Z][a-zA-Z0-9_]*\s*=\s*[a-zA-Z_][a-zA-Z0-9_\[\]|, \.]*\s*$", # Type = Union[...] | |
| # Property decorators | |
| r"^@property\s*$", # @property | |
| # Method decorators | |
| r"^@[a-zA-Z_][a-zA-Z0-9_]*\s*$", # @decorator | |
| ] | |
| # Check if all lines match type hint patterns | |
| for line in lines: | |
| line = line.strip() | |
| if not line: # Skip empty lines | |
| continue | |
| # Check if line matches any type hint pattern | |
| is_type_hint = False | |
| for pattern in type_hint_patterns: | |
| if re.match(pattern, line): | |
| is_type_hint = True | |
| break | |
| # If any line doesn't match type hint patterns, it's not just type hints | |
| if not is_type_hint: | |
| return False | |
| return True | |
| def is_documentation_example(self, code: str) -> bool: | |
| """Check if code block is a documentation example (API signature, type definition, etc.).""" | |
| lines = code.strip().split("\n") | |
| # If it's just one line, it's likely a function signature | |
| if len(lines) == 1: | |
| return True | |
| # Check if it's a class definition without body | |
| if len(lines) <= 5: | |
| return True | |
| # Check if it contains incomplete Python syntax (missing colons, etc.) | |
| incomplete_patterns = [ | |
| r"def\s+[a-zA-Z_][a-zA-Z0-9_]*\s*\([^)]*\)\s*$", # def func() without colon | |
| r"[a-zA-Z_][a-zA-Z0-9_]*\s*:\s*[a-zA-Z_][a-zA-Z0-9_\[\]|, \.]*\s*$", # var: type | |
| r"[a-zA-Z_][a-zA-Z0-9_]*\s*=\s*[a-zA-Z_][a-zA-Z0-9_\[\]|, \.]*\s*$", # var = type | |
| r"[a-zA-Z_][a-zA-Z0-9_]*\s*\([^)]*\)\s*->\s*[a-zA-Z_][a-zA-Z0-9_\[\]|, \.]*\s*$", # func() -> type | |
| r"[a-zA-Z_][a-zA-Z0-9_]*\s*\([^)]*\)\s*$", # func() without colon | |
| ] | |
| # If any line matches incomplete patterns, consider it documentation | |
| for line in lines: | |
| line = line.strip() | |
| if not line or line.startswith("@"): | |
| continue | |
| for pattern in incomplete_patterns: | |
| if re.search(pattern, line): | |
| return True | |
| return False | |
| def validate_python_example( | |
| self, | |
| code: str, | |
| file_path: Path, | |
| line_num: int, | |
| ) -> bool: | |
| """Validate Python code example.""" | |
| try: | |
| # Skip documentation examples (API signatures, type definitions) | |
| if self.is_documentation_example(code): | |
| return True | |
| # Create temporary file | |
| with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f: | |
| f.write(code) | |
| temp_file = f.name | |
| # Try to compile the code | |
| result = subprocess.run( | |
| [sys.executable, "-m", "py_compile", temp_file], | |
| capture_output=True, | |
| text=True, | |
| check=False, | |
| ) | |
| # Clean up | |
| Path(temp_file).unlink() | |
| if result.returncode == 0: | |
| return True | |
| print(f"❌ Python syntax error in {file_path}:{line_num}") | |
| print(f" Error: {result.stderr.strip()}") | |
| return False | |
| except Exception as e: | |
| print(f"❌ Error validating Python example: {e}") | |
| return False | |
| def validate_bash_example(self, code: str, file_path: Path, line_num: int) -> bool: | |
| """Validate bash/shell code example.""" | |
| try: | |
| # Basic bash syntax check | |
| result = subprocess.run( | |
| ["bash", "-n", "-c", code], | |
| capture_output=True, | |
| text=True, | |
| check=False, | |
| ) | |
| if result.returncode == 0: | |
| return True | |
| print(f"❌ Bash syntax error in {file_path}:{line_num}") | |
| print(f" Error: {result.stderr.strip()}") | |
| return False | |
| except Exception as e: | |
| print(f"❌ Error validating bash example: {e}") | |
| return False | |
| def validate_markdown_example( | |
| self, | |
| code: str, | |
| file_path: Path, | |
| line_num: int, | |
| ) -> bool: | |
| """Validate markdown code example.""" | |
| # For now, just check if it's not empty | |
| if code.strip(): | |
| return True | |
| print(f"❌ Empty markdown example in {file_path}:{line_num}") | |
| return False | |
| def validate_example( | |
| self, | |
| code: str, | |
| language: str, | |
| file_path: Path, | |
| line_num: int, | |
| ) -> bool: | |
| """Validate a single code example.""" | |
| self.results["total"] += 1 | |
| # Skip non-code blocks | |
| if not language or language in ["", "text", "plain"]: | |
| self.results["skipped"].append(f"{file_path}:{line_num}") | |
| return True | |
| # Validate based on language | |
| if language in ["python", "py"]: | |
| success = self.validate_python_example(code, file_path, line_num) | |
| elif language in ["bash", "sh", "shell"]: | |
| success = self.validate_bash_example(code, file_path, line_num) | |
| elif language in ["markdown", "md"]: | |
| success = self.validate_markdown_example(code, file_path, line_num) | |
| else: | |
| # Skip unsupported languages for now | |
| self.results["skipped"].append(f"{file_path}:{line_num} ({language})") | |
| return True | |
| if success: | |
| self.results["passed"].append(f"{file_path}:{line_num}") | |
| else: | |
| self.results["failed"].append(f"{file_path}:{line_num}") | |
| return success | |
| def validate_file(self, file_path: Path) -> None: | |
| """Validate all examples in a single file.""" | |
| print(f"🔍 Validating: {file_path}") | |
| code_blocks = self.find_code_blocks(file_path) | |
| for code, line_num, language in code_blocks: | |
| self.validate_example(code, language, file_path, line_num) | |
| def validate_documentation(self) -> None: | |
| """Validate all documentation files.""" | |
| print("🚀 Starting documentation validation...") | |
| print("=" * 50) | |
| # Files to validate | |
| doc_files = [ | |
| self.project_root / "README.md", | |
| self.project_root / "docs" / "index.md", | |
| self.project_root / "docs" / "getting-started.md", | |
| self.project_root / "docs" / "api-reference.md", | |
| self.project_root / "CHANGELOG.md", | |
| self.project_root / "CONTRIBUTING.md", | |
| self.project_root / "SECURITY.md", | |
| self.project_root / "SUPPORT.md", | |
| self.project_root / "DEPLOYMENT.md", | |
| ] | |
| for doc_file in doc_files: | |
| if doc_file.exists(): | |
| self.validate_file(doc_file) | |
| else: | |
| print(f"⚠️ Skipping (not found): {doc_file}") | |
| print("=" * 50) | |
| self.print_results() | |
| def print_results(self) -> None: | |
| """Print validation results.""" | |
| print("\n VALIDATION RESULTS") | |
| print("=" * 30) | |
| print(f"✅ Passed: {len(self.results['passed'])}") | |
| print(f"❌ Failed: {len(self.results['failed'])}") | |
| print(f"⏭️ Skipped: {len(self.results['skipped'])}") | |
| print(f"📝 Total: {self.results['total']}") | |
| if self.results["failed"]: | |
| print("\n❌ FAILED EXAMPLES:") | |
| for failed in self.results["failed"]: | |
| print(f" - {failed}") | |
| if self.results["skipped"]: | |
| print("\n⏭️ SKIPPED EXAMPLES:") | |
| for skipped in self.results["skipped"]: | |
| print(f" - {skipped}") | |
| # Overall success | |
| success_rate = ( | |
| len(self.results["passed"]) / max(self.results["total"], 1) | |
| ) * 100 | |
| print(f"\n🎯 Success Rate: {success_rate:.1f}%") | |
| if self.results["failed"]: | |
| print("\n💡 RECOMMENDATIONS:") | |
| print(" - Fix failed examples before deployment") | |
| print(" - Test examples manually to ensure they work") | |
| print(" - Update documentation with working examples") | |
| sys.exit(1) | |
| else: | |
| print("\n🎉 All examples validated successfully!") | |
| print(" Ready for deployment!") | |
| def main(): | |
| """Main validation function.""" | |
| validator = ExampleValidator() | |
| validator.validate_documentation() | |
| if __name__ == "__main__": | |
| main() | |
Xet Storage Details
- Size:
- 11.7 kB
- Xet hash:
- b8a8f00605a7b8b011463e8093e7ca38e8ab5adfa25354ad17f1888e40b92fd8
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.