scripts/refactor¶
scripts.refactor.__init__¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | The refactor module provides tools for analyzing, comparing, and validating Python code refactoring. |
| Core functionality includes: | |
| - Comparing original and refactored Python modules or directories to detect changes in class and method definitions. | |
| - Analyzing cyclomatic complexity of functions and methods to ensure maintainability. | |
| - Identifying missing or insufficient test coverage for public methods. | |
| - Integrating with code coverage data to enrich analysis results. | |
| - Supporting configuration for complexity thresholds and file/directory ignore patterns. | |
| This module is intended to help developers and teams maintain code quality and test coverage during refactoring processes. | |
| Args | — |
| Returns | — |
scripts.refactor.ast_extractor¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | ast_extractor.py |
| This module provides utilities for analyzing Python source files using the AST (Abstract Syntax Tree) to extract class and method information. | |
| Core features include: | |
| - Extracting all classes and their methods from a Python file, including method start and end line numbers. | |
| - Supporting nested class and method extraction. | |
| - Comparing two sets of class methods to identify missing or newly added methods after refactoring. | |
| - Providing a ClassMethodInfo class to encapsulate class and method metadata for further analysis. | |
| Intended for use in code analysis, refactoring tools, and automated quality checks. | |
| Args | — |
| Returns | — |
📦 Classes¶
ClassMethodInfo¶
Holds information about methods in a single class. Attributes: class_name (str): Name of the class. methods (Dict[str, Tuple[int, int]]): Mapping from method name to a tuple of (start_lineno, end_lineno). Parameters: ['self: Any', 'class_name: str'] Returns: None
ClassMethodExtractor¶
No description available. Parameters: ['self: Any'] Returns: None
🛠️ Functions¶
__init__¶
Initializes ClassMethodInfo with the class name and an empty methods dictionary. Parameters: ['self: Any', 'class_name: str'] Returns: None
add_method¶
Record a method with its start and end line numbers. Parameters: ['self: Any', 'name: str', 'linenos: Tuple[int, int]'] Returns: None
__repr__¶
Returns a string representation of the ClassMethodInfo instance. Parameters: ['self: Any'] Returns: str
extract_class_methods¶
Extracts all classes and their methods from a Python file, including method start and end line numbers. Parameters: ['file_path: str'] Returns: List[ClassMethodInfo]
__init__¶
No description available. Parameters: ['self: Any'] Returns: Any
visit_ClassDef¶
No description available. Parameters: ['self: Any', 'node: ast.AST'] Returns: None
generic_visit¶
Visit all child nodes, to catch nested class definitions. Parameters: ['self: Any', 'node: ast.AST'] Returns: None
compare_class_methods¶
Compare two ClassMethodInfo objects and return which methods are missing in the refactored version and which are newly added. Parameters: ['original: ClassMethodInfo', 'refactored: ClassMethodInfo'] Returns: Dict[str, List[str]]
scripts.refactor.merge_audit_reports¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | merge_audit_reports.py – bespoke normalizer |
| Merges docstring, coverage/complexity, and linting JSON reports into a unified output. | |
| Uses custom normalization logic per input source to ensure accurate matching. | |
| Author: Your Name | |
| Version: 1.0 | |
| Args | — |
| Returns | — |
🛠️ Functions¶
normalize_path¶
Normalize any report path by stripping everything up to and including the project 'scripts' directory and converting to a forward‑slash relative path. Parameters: ['path: str'] Returns: str
load_and_normalize¶
Load JSON and normalize its keys using a common path normalizer. Parameters: ['path: Path'] Returns: Dict[str, Any]
merge_reports¶
Merge docstring, coverage, and linting reports into a single JSON output. Parameters: ['doc_path: Path', 'cov_path: Path', 'lint_path: Path', 'output_path: Path'] Returns: None
main¶
Main entry point for the script. Returns: None
scripts.refactor.method_line_ranges¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | method_line_ranges.py |
| This module provides utilities for extracting the start and end line numbers of all functions and methods in a Python source file using the AST (Abstract Syntax Tree). | |
| Core features include: | |
| - The MethodRangeVisitor class, which traverses the AST to collect line ranges for top-level functions, class methods, and methods in nested classes. | |
| - The extract_method_line_ranges function, which parses a Python file and returns a dictionary mapping each function or method (as "function" or "Class.method") to its (start_lineno, end_lineno) tuple. | |
| - Handles both synchronous and asynchronous functions, and supports Python versions with or without the end_lineno attribute. | |
| - Designed for use in code analysis, refactoring tools, and coverage mapping. | |
| Intended to facilitate precise mapping of code structure for downstream analysis and tooling. | |
| Args | — |
| Returns | — |
📦 Classes¶
MethodRangeVisitor¶
Collects start and end line numbers for each function or async method, keyed by 'ClassName.method' for methods or just 'function' for top-level functions. Nested classes are also visited. Attributes: ranges (Dict[str, Tuple[int, int]]): A dictionary mapping functions or methods to their line ranges. current_class (Optional[str]): The name of the current class being visited. Parameters: ['self: Any'] Returns: None
🛠️ Functions¶
__init__¶
Initializes the MethodRangeVisitor with an empty dictionary for ranges and a placeholder for the current class name. Parameters: ['self: Any'] Returns: None
visit_ClassDef¶
Visits a class definition node and collects line ranges for its methods. Parameters: ['self: Any', 'node: ast.ClassDef'] Returns: None
visit_FunctionDef¶
Visits a function definition node and records its line range. Parameters: ['self: Any', 'node: ast.FunctionDef'] Returns: None
visit_AsyncFunctionDef¶
Visits an asynchronous function definition node and records its line range. Parameters: ['self: Any', 'node: ast.AsyncFunctionDef'] Returns: None
_record_range¶
Records the line range for a function or asynchronous function node. Parameters: ['self: Any', 'node: Union[ast.FunctionDef, ast.AsyncFunctionDef]'] Returns: None
extract_method_line_ranges¶
Parses a Python file and returns a dict mapping each function or method to its (start_lineno, end_lineno). Parameters: ['file_path: str'] Returns: Dict[str, Tuple[int, int]]
scripts.refactor.refactor_guard¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | RefactorGuard: analyse refactors and (optionally) enrich the results with line‑coverage |
information coming from a .coverage SQLite DB or a JSON export produced by Coverage.py. |
|
Adds support for both .coverage and coverage.json formats. Automatically switches |
|
| parsers based on the extension. | |
| Args | — |
| Returns | — |
📦 Classes¶
AnalysisError¶
Raised when an error occurs during analysis. Returns: None
RefactorGuard¶
Analyse / validate Python refactors. Parameters: ['self: Any', 'config: Optional[Dict[str, Any]] | None'] Returns: None
🛠️ Functions¶
__init__¶
No description available. Parameters: ['self: Any', 'config: Optional[Dict[str, Any]] | None'] Returns: None
attach_coverage_hits¶
No description available. Parameters: ['self: Any', 'coverage_data: Dict[str, Dict[str, Any]]'] Returns: None
analyze_tests¶
No description available. Parameters: ['self: Any', 'refactored_path: str', 'test_file_path: Optional[str] | None'] Returns: List[Dict[str, str]]
analyze_module¶
No description available. Parameters: ['self: Any', 'original_path: Optional[str]', 'refactored_path: str', 'test_file_path: Optional[str]'] Returns: Dict[str, Any]
_simple_name¶
No description available. Parameters: ['qual: str'] Returns: str
analyze_directory_recursive¶
No description available. Parameters: ['self: Any', 'original_dir: str', 'refactored_dir: str', 'test_dir: Optional[str]'] Returns: Dict[str, Dict[str, Any]]
print_human_readable¶
Print a human-readable summary of the analysis results. Parameters: ['summary: Dict[str, Dict[str, Any]]', 'guard: RefactorGuard', 'args: Optional[argparse.Namespace]'] Returns: None
scripts.refactor.refactor_guard_cli¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | No module description available. |
| Args | — |
| Returns | — |
🛠️ Functions¶
_ensure_utf8_stdout¶
No description available. Returns: None
_parse_args¶
No description available. Returns: argparse.Namespace
_merge_coverage¶
No description available. Parameters: ['summary: dict', 'ref: str', 'args: argparse.Namespace'] Returns: None
handle_full_scan¶
No description available. Parameters: ['args: argparse.Namespace', 'guard: RefactorGuard'] Returns: Dict[str, Dict[str, Any]]
handle_single_file¶
No description available. Parameters: ['args: argparse.Namespace', 'guard: RefactorGuard'] Returns: Dict[str, Dict[str, Any]]
main¶
No description available. Returns: int
scripts.refactor.strictness_analyzer¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | Test Coverage Mapper (Strictness Report Version) |
| Author: Angelos Dimakos | |
| Version: 3.2.0 | |
| Loads precomputed strictness analysis and merges it with audit coverage data | |
| into a module-centric report with consistent schema handling. | |
| Usage: | |
| python test_coverage_mapper.py --test-report test_report.json --audit refactor_audit.json --output final_report.json | |
| Args | — |
| Returns | — |
📦 Classes¶
ComplexityMetrics¶
Model for storing code complexity and test coverage metrics for a single method. Returns: None
FileAudit¶
Model for storing audit data for a specific file. Returns: None
AuditReport¶
Top-level model for the audit report. Returns: None
StrictnessEntry¶
Model for storing test strictness evaluation data. Returns: None
StrictnessReport¶
Top-level model for the strictness report. Returns: None
MethodOutput¶
Standardized output model for method data in the final report. Returns: None
TestOutput¶
Standardized output model for test data in the final report. Returns: None
ModuleOutput¶
Standardized output model for module data in the final report. Returns: None
FinalReport¶
Top-level model for the final merged report. Returns: None
🛠️ Functions¶
weighted_coverage¶
Return overall coverage weighted by each function's lines-of-code. Parameters: ['func_dict: Dict[str, ComplexityMetrics]'] Returns: float
get_test_severity¶
Compute severity with implicit weighting from coverage. Parameters: ['test_entry: StrictnessEntry', 'coverage: Optional[float]', 'alpha: float'] Returns: float
load_audit_report¶
Load the audit report JSON into the Pydantic model. Parameters: ['audit_path: str'] Returns: AuditReport
load_test_report¶
Load the precomputed strictness analysis JSON. Parameters: ['test_report_path: str'] Returns: List[StrictnessEntry]
generate_module_report¶
No description available. Parameters: ['audit_model: AuditReport', 'strictness_entries: List[StrictnessEntry]', 'test_imports: Dict[str, List[str]]'] Returns: Dict[str, Any]
fuzzy_match¶
Fuzzy matching with partial ratio preference for looser matching. Parameters: ['a: str', 'b: str', 'threshold: int'] Returns: bool
validate_report_schema¶
No description available. Parameters: ['data: Dict[str, Any]', 'report_type: str'] Returns: bool
should_assign_test_to_module¶
Decide if a test should be assigned to a production module using strict matching. Prioritizes conventions and imports. Fuzzy matching is a last resort with a high bar. Parameters: ['prod_file_name: str', 'method_names: List[str]', 'test_entry: StrictnessEntry', 'test_imports: Dict[str, List[str]]', 'fuzzy_threshold: int'] Returns: bool
main¶
No description available. Parameters: ['test_report_path: str', 'audit_path: str', 'output_path: Optional[str]'] Returns: None