refactrail 0.3.1a0__py3-none-any.whl

refactrail/__init__.py

@@ -0,0 +1,32 @@
+"""RefacTrail: check and safely refactor Python against a rule profile."""
+
+from refactrail._version import __version__
+from refactrail.config import load_settings
+from refactrail.correctness import check_correctness_list
+from refactrail.engine import check_paths_list, check_text_list
+from refactrail.formatting import (
+    FormatPlan, format_source_str, plan_format, write_format_none,
+)
+from refactrail.models import Finding, Settings
+from refactrail.lexical import analyze_lexical_dict
+from refactrail.project_index import analyze_project_dict
+from refactrail.rename import plan_rename_dict
+from refactrail.correctness_batch import check_correctness_paths_list
+
+__all__ = [
+    "analyze_lexical_dict",
+    "analyze_project_dict",
+    "plan_rename_dict",
+    "check_correctness_paths_list",
+    "Finding",
+    "FormatPlan",
+    "Settings",
+    "__version__",
+    "check_paths_list",
+    "check_text_list",
+    "load_settings",
+    "check_correctness_list",
+    "format_source_str",
+    "plan_format",
+    "write_format_none",
+]

refactrail/__main__.py

@@ -0,0 +1,6 @@
+"""Allow python -m refactrail."""
+
+from refactrail.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

refactrail/_version.py

@@ -0,0 +1,3 @@
+"""RefacTrail version."""
+
+__version__ = "0.3.1a0"

refactrail/analysis_cli.py

@@ -0,0 +1,82 @@
+"""Thin interfaces for partial scope, project and local rename evidence."""
+
+import argparse
+from hashlib import sha256
+import json
+from pathlib import Path
+import sys
+
+from refactrail.lexical import analyze_lexical_dict
+from refactrail.project_index import analyze_project_dict
+from refactrail.rename import plan_rename_dict
+from refactrail.source import decode_source_text
+
+
+def add_analysis_commands_none(commands_info: argparse._SubParsersAction
+                                ) -> None:
+    """Register source-linked analysis and read-only rename commands.
+
+    Args:
+        commands_info (argparse._SubParsersAction): Main command registry.
+    Returns:
+        None: Adds scope, index and rename subcommands.
+    Warnings:
+        The rename command produces a review proposal without applying it.
+    """
+    scope_parser = commands_info.add_parser(
+        "scope", help="Inspect lexical evidence")
+    scope_parser.add_argument("path")
+    index_parser = commands_info.add_parser(
+        "index", help="Inspect project import impact")
+    index_parser.add_argument(
+        "root", help="Directory used as Python import root")
+    index_parser.add_argument("--changed", action="append", default=[])
+    rename_parser = commands_info.add_parser(
+        "rename", help="Preview a local variable rename")
+    rename_parser.add_argument("path")
+    rename_parser.add_argument("--function", required=True)
+    rename_parser.add_argument("--old", required=True)
+    rename_parser.add_argument("--new", required=True)
+
+
+def read_scope_report_dict(path_str: str) -> dict:
+    """Read compiler evidence with an original-source fingerprint.
+
+    Args:
+        path_str (str): Regular Python source path.
+    Returns:
+        dict: Versioned partial scope report.
+    Warnings:
+        Notebook kernel state and unsupported encodings are not inferred.
+    """
+    path_info = Path(path_str)
+    if path_info.is_symlink() or path_info.is_junction():
+        raise ValueError("Linked scope inputs are unsupported")
+    raw_bytes = path_info.read_bytes()
+    text_str = decode_source_text(raw_bytes)
+    if text_str is None:
+        raise ValueError("Scope input must be UTF-8 Python source")
+    report_dict = analyze_lexical_dict(text_str, path_str)
+    return {"schema_version": "refactrail-scope-1", "path": path_str,
+        "source_sha256": sha256(raw_bytes).hexdigest(), **report_dict}
+
+
+def run_analysis_int(arguments: argparse.Namespace) -> int:
+    """Render exactly one JSON document from the selected analysis API.
+
+    Args:
+        arguments (argparse.Namespace): Parsed source and query options.
+    Returns:
+        int: Zero for completed partial analysis; errors propagate.
+    Warnings:
+        Coverage and unresolved semantics are explicit report fields.
+    """
+    if arguments.command == "scope":
+        report_dict = read_scope_report_dict(arguments.path)
+    elif arguments.command == "index":
+        report_dict = analyze_project_dict(arguments.root, arguments.changed)
+    else:
+        report_dict = plan_rename_dict(arguments.path, arguments.function,
+                                       arguments.old, arguments.new)
+    sys.stdout.write(json.dumps(report_dict, indent=2) + "\n")
+    return 0

refactrail/cli.py

@@ -0,0 +1,227 @@
+"""Command line: refactrail check / rules / version."""
+
+import argparse
+from pathlib import Path
+import sys
+
+from refactrail._version import __version__
+from refactrail.analysis_cli import (
+    add_analysis_commands_none, run_analysis_int,
+)
+from refactrail.config import PROFILES_TUPLE, load_settings
+from refactrail.correctness import CORRECTNESS_TITLES_DICT
+from refactrail.discovery import discover_python_files_list
+from refactrail.engine import (
+    CACHE_FOLDER_STR, ENGINES_TUPLE, check_paths_list,
+)
+from refactrail.fixing import fix_file, render_diff_str, write_fix_none
+from refactrail.general_cli import (
+    add_general_commands_none, run_format_int, run_lint_int,
+)
+from refactrail.report import (
+    OUTPUT_FORMATS_TUPLE, render_github_str, render_json_str,
+    render_statistics_str, render_text_str,
+)
+from refactrail.rules import RULE_TITLES_DICT
+from refactrail.sarif import render_sarif_str
+
+
+QUICK_START_STR = """\
+RefacTrail - the Python refactorizer. Paths default to the current folder.
+
+  refactrail lint
+      find likely bugs (comparisons with None, duplicate keys, ...)
+  refactrail format --diff
+      show formatting changes; use --write to apply them
+  refactrail check
+      check structure, naming, type hints and docstrings
+  refactrail fix --diff
+      preview safe fixes; run without --diff to apply them
+  refactrail rules
+      list every rule code
+
+Run "refactrail COMMAND --help" for options or "refactrail --help" for all
+commands.
+"""
+
+
+def add_settings_options_none(parser: argparse.ArgumentParser) -> None:
+    """Add the paths and settings options shared by check and fix.
+
+    Args:
+        parser (argparse.ArgumentParser): Sub-command parser.
+    Returns:
+        None: Adds arguments in place.
+    Warnings:
+        None.
+    """
+    parser.add_argument("paths", nargs="*", default=["."])
+    parser.add_argument("--profile", choices=PROFILES_TUPLE)
+    parser.add_argument("--line-length", type=int)
+    parser.add_argument("--select", help="Comma-separated codes")
+    parser.add_argument("--ignore", help="Comma-separated codes")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Define the command-line interface.
+
+    Args:
+        None: The interface is fixed for this version.
+    Returns:
+        argparse.ArgumentParser: Parser with the check and rules commands.
+    Warnings:
+        Option names follow Ruff where the meaning is the same.
+    """
+    parser = argparse.ArgumentParser(
+        prog="refactrail", description="Check Python code against a "
+        "refactoring rule profile.")
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    check_parser = commands.add_parser("check", help="Report findings")
+    add_settings_options_none(check_parser)
+    check_parser.add_argument("--output-format", default="text",
+                              choices=OUTPUT_FORMATS_TUPLE)
+    check_parser.add_argument("--statistics", action="store_true")
+    check_parser.add_argument("--exit-zero", action="store_true")
+    check_parser.add_argument("--no-cache", action="store_true")
+    check_parser.add_argument("--jobs", type=int, default=0,
+                              help="Worker processes (0: one per core)")
+    check_parser.add_argument("--engine", default="auto",
+                              choices=ENGINES_TUPLE,
+                              help="auto uses Rust when installed")
+    fix_parser = commands.add_parser(
+        "fix", help="Apply bounded refactoring edits")
+    add_settings_options_none(fix_parser)
+    fix_parser.add_argument("--diff", action="store_true",
+                            help="Show the fixes; do not write files")
+    commands.add_parser("rules", help="List RT style and RC correctness codes")
+    add_general_commands_none(commands)
+    add_analysis_commands_none(commands)
+    return parser
+
+
+def run_fix_int(arguments: argparse.Namespace) -> int:
+    """Run the fix command: write fixes, or print them with --diff.
+
+    Args:
+        arguments (argparse.Namespace): Parsed options.
+    Returns:
+        int: With --diff, 1 when changes are pending; otherwise 1 when
+            findings remain after fixing, else 0.
+    Warnings:
+        Files are changed in place unless --diff is given.
+    """
+    if getattr(arguments, "jobs", 0) < 0:
+        raise ValueError("jobs must be nonnegative")
+    settings_info = load_settings(Path(arguments.paths[0]), {
+        "profile": arguments.profile, "line_length": arguments.line_length,
+        "select": split_codes_tuple(arguments.select),
+        "ignore": split_codes_tuple(arguments.ignore)})
+    files_list = discover_python_files_list(arguments.paths, settings_info)
+    fixes_list = [fix_file(path_str, settings_info)
+                  for path_str in files_list]
+    for file_fix in fixes_list:
+        if file_fix.skip_reason:
+            sys.stderr.write(f"{file_fix.path}: skipped: "
+                             f"{file_fix.skip_reason}\n")
+        elif arguments.diff:
+            sys.stdout.write(render_diff_str(file_fix))
+        elif file_fix.changed_bool:
+            write_fix_none(file_fix)
+            sys.stdout.write("".join(f"{file_fix.path}: {line_str}\n" for
+                                     line_str in file_fix.outcome.applied))
+    changed_int = sum(file_fix.changed_bool for file_fix in fixes_list)
+    skipped_bool = any(fix_info.skip_reason for fix_info in fixes_list)
+    if arguments.diff:
+        sys.stdout.write(f"{changed_int} file(s) would be changed.\n")
+        return int(bool(changed_int) or skipped_bool)
+    remaining_list = check_paths_list(files_list, settings_info)
+    sys.stdout.write(f"Fixed {changed_int} file(s); {len(remaining_list)} "
+                     "finding(s) remain for the selected rules (run "
+                     "'refactrail check').\n")
+    return int(bool(remaining_list) or skipped_bool)
+
+
+def split_codes_tuple(codes_str: str | None) -> tuple[str, ...] | None:
+    """Turn "RT1,RT201" into a tuple of codes.
+
+    Args:
+        codes_str (str | None): Comma-separated codes, or None.
+    Returns:
+        tuple[str, ...] | None: Codes, or None when not given.
+    Warnings:
+        Codes are upper-cased.
+    """
+    if codes_str is None:
+        return None
+    return tuple(code_str.strip().upper() for code_str in codes_str.split(",")
+                 if code_str.strip())
+
+
+def run_check_int(arguments: argparse.Namespace) -> int:
+    """Run the check command and print its report.
+
+    Args:
+        arguments (argparse.Namespace): Parsed options.
+    Returns:
+        int: 0 without findings (or with --exit-zero), 1 with findings.
+    Warnings:
+        Settings come from the pyproject.toml nearest the first path.
+    """
+    if getattr(arguments, "jobs", 0) < 0:
+        raise ValueError("jobs must be nonnegative")
+    settings_info = load_settings(Path(arguments.paths[0]), {
+        "profile": arguments.profile, "line_length": arguments.line_length,
+        "select": split_codes_tuple(arguments.select),
+        "ignore": split_codes_tuple(arguments.ignore)})
+    files_list = discover_python_files_list(arguments.paths, settings_info)
+    cache_path = None if arguments.no_cache else (
+        Path.cwd() / CACHE_FOLDER_STR / "results-v1.json")
+    findings_list = check_paths_list(files_list, settings_info,
+                                     arguments.jobs, cache_path,
+                                     arguments.engine)
+    renderers_dict = {
+        "text": lambda: render_text_str(findings_list, len(files_list)),
+        "json": lambda: render_json_str(findings_list),
+        "github": lambda: render_github_str(findings_list),
+        "sarif": lambda: render_sarif_str(findings_list),
+    }
+    sys.stdout.write(renderers_dict[arguments.output_format]())
+    if arguments.statistics:
+        sys.stderr.write(render_statistics_str(findings_list))
+    return 0 if arguments.exit_zero or not findings_list else 1
+
+
+def main(argv_list: list[str] | None = None) -> int:
+    """Run the command line and return the exit status.
+
+    Args:
+        argv_list (list[str] | None): Arguments; None reads sys.argv.
+    Returns:
+        int: 0 success, 1 findings, 2 usage or configuration error.
+    Warnings:
+        Configuration and path errors are printed, not raised.
+    """
+    if not (sys.argv[1:] if argv_list is None else argv_list):
+        sys.stdout.write(QUICK_START_STR)
+        return 0
+    arguments = build_parser().parse_args(argv_list)
+    try:
+        if arguments.command in ("scope", "index", "rename"):
+            return run_analysis_int(arguments)
+        if arguments.command == "lint":
+            return run_lint_int(arguments)
+        if arguments.command == "format":
+            return run_format_int(arguments)
+        if arguments.command == "fix":
+            return run_fix_int(arguments)
+        if arguments.command == "rules":
+            sys.stdout.write("".join(f"{code_str}  {title_str}\n" for
+                                     code_str, title_str in
+                                     {**RULE_TITLES_DICT,
+                                      **CORRECTNESS_TITLES_DICT}.items()))
+            return 0
+        return run_check_int(arguments)
+    except (ValueError, OSError, SyntaxError) as error:
+        sys.stderr.write(f"refactrail: error: {error}\n")
+        return 2

refactrail/config.py

@@ -0,0 +1,136 @@
+"""Load RefacTrail settings from pyproject.toml and command-line options."""
+
+from dataclasses import fields, replace
+from pathlib import Path
+import tomllib
+
+from refactrail.models import Settings
+
+PROFILES_TUPLE = ("standard", "strict")
+INTEGER_KEYS_TUPLE = (
+    "line_length", "function_preferred_lines", "function_max_lines",
+    "main_max_lines",
+)
+LIST_KEYS_TUPLE = ("select", "ignore", "exclude")
+
+
+def find_pyproject_path(start_path: Path) -> Path | None:
+    """Find the nearest pyproject.toml at or above a folder.
+
+    Args:
+        start_path (Path): File or folder where the search begins.
+    Returns:
+        Path | None: The configuration file, or None when there is none.
+    Warnings:
+        The search stops at the file system root.
+    """
+    folder_path = start_path.resolve()
+    if folder_path.is_file():
+        folder_path = folder_path.parent
+    for candidate_path in (folder_path, *folder_path.parents):
+        pyproject_path = candidate_path / "pyproject.toml"
+        if pyproject_path.is_file():
+            return pyproject_path
+    return None
+
+
+def read_tool_table_dict(pyproject_path: Path | None) -> dict:
+    """Read the [tool.refactrail] table of a pyproject.toml file.
+
+    Args:
+        pyproject_path (Path | None): File to read, or None.
+    Returns:
+        dict: Table with dashes turned into underscores; empty if absent.
+    Warnings:
+        Invalid TOML raises ValueError with the file name.
+    """
+    if pyproject_path is None:
+        return {}
+    try:
+        document_dict = tomllib.loads(
+            pyproject_path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as error:
+        raise ValueError(f"{pyproject_path}: invalid TOML: {error}") from error
+    table_dict = document_dict.get("tool", {}).get("refactrail", {})
+    if not isinstance(table_dict, dict):
+        raise ValueError("tool.refactrail must be a table")
+    return {key_str.replace("-", "_"): setting_value
+            for key_str, setting_value in table_dict.items()}
+
+
+def build_settings(
+    table_dict: dict, overrides_dict: dict | None = None,
+) -> Settings:
+    """Validate configuration values and build Settings.
+    Args:
+        table_dict (dict): Values from pyproject.toml.
+        overrides_dict (dict | None): Command-line values, which win.
+    Returns:
+        Settings: Validated settings.
+    Warnings:
+        Unknown keys and invalid values raise ValueError naming them.
+    """
+    given_dict = {key_str: setting_value for key_str, setting_value
+                  in (overrides_dict or {}).items()
+                  if setting_value is not None}
+    merged_dict = {**table_dict, **given_dict}
+    known_set = {field_info.name for field_info in fields(Settings)}
+    unknown_list = sorted(set(merged_dict) - known_set)
+    if unknown_list:
+        raise ValueError(f"Unknown setting(s): {', '.join(unknown_list)}")
+    if merged_dict.get("profile", "standard") not in PROFILES_TUPLE:
+        raise ValueError(f"Profile must be one of {PROFILES_TUPLE}")
+    for key_str in INTEGER_KEYS_TUPLE:
+        setting_value = merged_dict.get(key_str)
+        if setting_value is not None and (
+            not isinstance(setting_value, int)
+            or isinstance(setting_value, bool) or setting_value < 1
+        ):
+            raise ValueError(f"{key_str} must be a positive integer")
+    validate_limits_none(merged_dict)
+    for key_str in LIST_KEYS_TUPLE:
+        if key_str in merged_dict:
+            values_list = merged_dict[key_str]
+            if not isinstance(values_list, (list, tuple)) or not all(
+                isinstance(entry_str, str) and entry_str.strip()
+                for entry_str in values_list
+            ):
+                raise ValueError(f"{key_str} must be a list of strings")
+            merged_dict[key_str] = tuple(values_list)
+    return replace(Settings(), **merged_dict)
+
+
+def load_settings(
+    start_path: Path, overrides_dict: dict | None = None,
+) -> Settings:
+    """Load settings for a path from its nearest pyproject.toml.
+
+    Args:
+        start_path (Path): File or folder being checked.
+        overrides_dict (dict | None): Command-line values.
+    Returns:
+        Settings: Validated settings.
+    Warnings:
+        Command-line values override the file.
+    """
+    return build_settings(
+        read_tool_table_dict(find_pyproject_path(start_path)),
+        overrides_dict)
+
+
+def validate_limits_none(settings_dict: dict) -> None:
+    """Validate related size limits before constructing settings.
+
+    Args:
+        settings_dict (dict): Validated integer settings.
+    Returns:
+        None: Raises ValueError for inconsistent limits.
+    Warnings:
+        Width matches the FuncLoom API used by the fix command.
+    """
+    if not 40 <= settings_dict.get("line_length", 79) <= 200:
+        raise ValueError("line_length must be from 40 to 200")
+    if settings_dict.get("function_preferred_lines", 40) > (
+        settings_dict.get("function_max_lines", 50)
+    ):
+        raise ValueError("Preferred function size exceeds maximum")

refactrail/correctness.py

@@ -0,0 +1,94 @@
+"""General correctness analysis independent of RefacTrail style profiles."""
+
+import ast
+
+from refactrail.correctness_checks import (
+    FUNCTION_NODES_TUPLE, check_comparison_none, check_defaults_none,
+    check_dictionary_none, check_finally_none, check_statement_lists_none,
+    report_node_none,
+)
+from refactrail.engine import parse_quietly_node
+from refactrail.models import Finding, Settings
+from refactrail.lexical import check_lexical_none
+from refactrail.rules.context import RuleContext
+from refactrail.source import build_source_file, decode_source_text
+
+CORRECTNESS_TITLES_DICT = {
+    "RC201": "Unresolved lexical name",
+    "RC202": "Import without lexical use",
+    "RC101": "Mutable default argument",
+    "RC102": "Duplicate literal dictionary key",
+    "RC103": "Identity comparison with a non-singleton literal",
+    "RC104": "Bare except handler",
+    "RC105": "Unreachable statement after a direct terminator",
+    "RC106": "Nonempty tuple assertion",
+    "RC107": "Control-flow exit from finally",
+}
+
+
+def check_node_none(context_info: RuleContext, node: ast.AST) -> None:
+    """Dispatch independent checks during a shared syntax traversal.
+
+    Args:
+        context_info (RuleContext): Findings and suppression state.
+        node (ast.AST): Current syntax node.
+    Returns:
+        None: Adds applicable RC observations.
+    Warnings:
+        Checks are syntax evidence, not whole-program proofs.
+    """
+    if isinstance(node, FUNCTION_NODES_TUPLE):
+        check_defaults_none(context_info, node)
+    if isinstance(node, ast.Dict):
+        check_dictionary_none(context_info, node)
+    if isinstance(node, ast.Compare):
+        check_comparison_none(context_info, node)
+    if isinstance(node, ast.ExceptHandler) and node.type is None:
+        report_node_none(context_info, node, "RC104",
+                         "Bare except also catches process-control "
+                         "exceptions such as KeyboardInterrupt.")
+    if isinstance(node, ast.Assert) and isinstance(node.test, ast.Tuple):
+        if node.test.elts and not any(isinstance(element, ast.Starred)
+                                     for element in node.test.elts):
+            report_node_none(context_info, node.test, "RC106",
+                             "A nonempty tuple assertion tests the tuple's "
+                             "truthiness, not its first element.")
+    if isinstance(node, (ast.Try, ast.TryStar)):
+        check_finally_none(context_info, node)
+    check_statement_lists_none(context_info, node)
+
+
+def check_correctness_list(
+    path_str: str, raw_bytes: bytes,
+    select_tuple: tuple[str, ...] = ("RC",),
+    ignore_tuple: tuple[str, ...] = (),
+) -> list[Finding]:
+    """Check general correctness without importing or executing the source.
+
+    Args:
+        path_str (str): Source label for findings.
+        raw_bytes (bytes): Original UTF-8 source, optionally with a BOM.
+        select_tuple (tuple[str, ...]): Enabled rule prefixes.
+        ignore_tuple (tuple[str, ...]): Disabled ordinary rule prefixes.
+    Returns:
+        list[Finding]: Sorted observations or an unsuppressible input error.
+    Warnings:
+        This independent engine does not infer domain intent or runtime types.
+    """
+    settings_info = Settings(select=select_tuple, ignore=ignore_tuple)
+    text_str = decode_source_text(raw_bytes)
+    if text_str is None:
+        return [Finding(path_str, 1, 1, "RT002", "error",
+                        "File is not UTF-8 or declares another encoding.")]
+    try:
+        tree_node = parse_quietly_node(text_str, path_str)
+    except (SyntaxError, ValueError) as error:
+        return [Finding(path_str, getattr(error, "lineno", None) or 1,
+                        getattr(error, "offset", None) or 1, "RT001",
+                        "error", f"Syntax error: {error}")]
+    context_info = RuleContext(build_source_file(path_str, text_str),
+                               tree_node, settings_info)
+    for node in ast.walk(tree_node):
+        check_node_none(context_info, node)
+    check_lexical_none(context_info)
+    return sorted(set(context_info.findings_list))