flake8-stepdown 0.1.0__tar.gz

flake8_stepdown-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run ty check .
+      - run: uv run pytest

flake8_stepdown-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,16 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

flake8_stepdown-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.log
+*.swp
+*~
+.DS_Store
+.coverage
+.coverage.*
+htmlcov/
+specs.md
+CLAUDE.md
+AGENTS.md

flake8_stepdown-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty type checker
+        entry: uvx ty check .
+        language: system
+        pass_filenames: false
+        types: [python]
+      - id: pytest
+        name: pytest
+        entry: uv run pytest
+        language: system
+        pass_filenames: false
+        types: [python]

flake8_stepdown-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,11 @@
+- id: flake8-stepdown-check
+  name: flake8-stepdown (check)
+  entry: stepdown check
+  language: python
+  types: [python]
+
+- id: flake8-stepdown-fix
+  name: flake8-stepdown (fix)
+  entry: stepdown fix
+  language: python
+  types: [python]

flake8_stepdown-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

flake8_stepdown-0.1.0/.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+    "[python]": {
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": "explicit"
+        }
+    }
+}

flake8_stepdown-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing
+
+## Code style
+
+Ruff enforces many rules automatically.
+Run `./lint.sh` to auto-fix and format.
+
+## Commands reference
+
+| Task | Command |
+|------|---------|
+| Install deps | `uv sync` |
+| Lint + format | `./lint.sh` |
+| Type check | `uvx ty check .` |
+| Run tests | `uv run pytest` |
+| Pre-commit (manual) | `uv run pre-commit run --all-files` |

flake8_stepdown-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: flake8-stepdown
+Version: 0.1.0
+Summary: Enforce top-down / newspaper-style function ordering in Python
+Project-URL: Homepage, https://github.com/<owner>/<project-name>
+Project-URL: Repository, https://github.com/<owner>/<project-name>
+Project-URL: Issues, https://github.com/<owner>/<project-name>/issues
+Author-email: Didier Marin <mail@didiermarin.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: libcst>=1.1.0
+Provides-Extra: flake8
+Requires-Dist: flake8>=6.0; extra == 'flake8'
+Description-Content-Type: text/markdown
+
+# flake8-stepdown
+
+![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
+
+A [flake8](https://flake8.pycqa.org/) plugin that enforces **top-down (newspaper-style) function ordering** in Python modules.
+
+This is inspired by Robert C. Martin's "Clean Code" stepdown rule: High-level logic first, details later. When reading a module, callers should appear before callees, so you can read the code from top to bottom like a newspaper article.
+
+## Violation codes
+
+| Code | Meaning |
+|---------|---------|
+| TDP001 | Function is defined in the wrong order (should appear after another function) |
+
+## Installation
+
+```bash
+pip install flake8-stepdown
+```
+
+The plugin registers itself with flake8 automatically. Verify it's installed:
+
+```bash
+flake8 --version
+```
+
+You should see `flake8-stepdown` in the list of installed plugins.
+
+## Usage
+
+### As a flake8 plugin
+
+Just run flake8 as usual, the plugin will report `TDP001` violations:
+
+```bash
+flake8 your_module.py
+```
+
+### Standalone CLI
+
+The package also provides a `stepdown` command with three subcommands:
+
+```bash
+# Report violations
+stepdown check your_module.py
+
+# Show a unified diff of the proposed reordering
+stepdown diff your_module.py
+
+# Rewrite files in place
+stepdown fix your_module.py
+```
+
+Use `-v` / `--verbose` to show mutual recursion info on stderr.
+
+## Development
+
+### Prerequisites
+
+- [UV](https://docs.astral.sh/uv/) (Python package manager)
+
+### Setup
+
+```bash
+uv sync
+```
+
+### Linting
+
+```bash
+./lint.sh
+```
+
+### Testing
+
+```bash
+uv run pytest
+```
+
+Tests are organized by pipeline stage (`test_parser.py`, `test_graph.py`, `test_rewriter.py`, etc.). The rewriter uses **snapshot testing**: `tests/fixtures/` contains input Python files exercising various scenarios (bottom-up ordering, mutual recursion, decorators, etc.), and `tests/snapshots/` contains the expected output after rewriting. The test suite asserts correctness against snapshots, idempotency, and syntax validity.
+
+### Pre-commit hooks
+
+Pre-commit hooks are installed automatically. To run manually:
+
+```bash
+uv run pre-commit run --all-files
+```
+
+## CI
+
+GitHub Actions runs linting, type checking, and tests on every push to `main` and on pull requests.
+
+## Publishing to PyPI
+
+This project uses [trusted publishing](https://docs.pypi.org/trusted-publishers/) via GitHub Actions.
+
+To publish a new version:
+
+1. Bump the version with `uv version --bump patch` (or `minor`/`major`)
+2. Create a GitHub release with a tag matching the version (e.g., `v0.1.0`)
+3. The publish workflow will automatically build and upload to PyPI
+
+> **First-time setup:** Configure a trusted publisher on PyPI under your project's settings (Publishing tab). Use `publish.yml` as the workflow name and `publish` as the environment name.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for code style, conventions, and development workflow.

flake8_stepdown-0.1.0/README.md

@@ -0,0 +1,108 @@
+# flake8-stepdown
+
+![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
+
+A [flake8](https://flake8.pycqa.org/) plugin that enforces **top-down (newspaper-style) function ordering** in Python modules.
+
+This is inspired by Robert C. Martin's "Clean Code" stepdown rule: High-level logic first, details later. When reading a module, callers should appear before callees, so you can read the code from top to bottom like a newspaper article.
+
+## Violation codes
+
+| Code | Meaning |
+|---------|---------|
+| TDP001 | Function is defined in the wrong order (should appear after another function) |
+
+## Installation
+
+```bash
+pip install flake8-stepdown
+```
+
+The plugin registers itself with flake8 automatically. Verify it's installed:
+
+```bash
+flake8 --version
+```
+
+You should see `flake8-stepdown` in the list of installed plugins.
+
+## Usage
+
+### As a flake8 plugin
+
+Just run flake8 as usual, the plugin will report `TDP001` violations:
+
+```bash
+flake8 your_module.py
+```
+
+### Standalone CLI
+
+The package also provides a `stepdown` command with three subcommands:
+
+```bash
+# Report violations
+stepdown check your_module.py
+
+# Show a unified diff of the proposed reordering
+stepdown diff your_module.py
+
+# Rewrite files in place
+stepdown fix your_module.py
+```
+
+Use `-v` / `--verbose` to show mutual recursion info on stderr.
+
+## Development
+
+### Prerequisites
+
+- [UV](https://docs.astral.sh/uv/) (Python package manager)
+
+### Setup
+
+```bash
+uv sync
+```
+
+### Linting
+
+```bash
+./lint.sh
+```
+
+### Testing
+
+```bash
+uv run pytest
+```
+
+Tests are organized by pipeline stage (`test_parser.py`, `test_graph.py`, `test_rewriter.py`, etc.). The rewriter uses **snapshot testing**: `tests/fixtures/` contains input Python files exercising various scenarios (bottom-up ordering, mutual recursion, decorators, etc.), and `tests/snapshots/` contains the expected output after rewriting. The test suite asserts correctness against snapshots, idempotency, and syntax validity.
+
+### Pre-commit hooks
+
+Pre-commit hooks are installed automatically. To run manually:
+
+```bash
+uv run pre-commit run --all-files
+```
+
+## CI
+
+GitHub Actions runs linting, type checking, and tests on every push to `main` and on pull requests.
+
+## Publishing to PyPI
+
+This project uses [trusted publishing](https://docs.pypi.org/trusted-publishers/) via GitHub Actions.
+
+To publish a new version:
+
+1. Bump the version with `uv version --bump patch` (or `minor`/`major`)
+2. Create a GitHub release with a tag matching the version (e.g., `v0.1.0`)
+3. The publish workflow will automatically build and upload to PyPI
+
+> **First-time setup:** Configure a trusted publisher on PyPI under your project's settings (Publishing tab). Use `publish.yml` as the workflow name and `publish` as the environment name.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for code style, conventions, and development workflow.

flake8_stepdown-0.1.0/flake8_stepdown/__init__.py

@@ -0,0 +1,5 @@
+"""flake8-stepdown: enforce top-down function ordering in Python."""
+
+__version__ = "0.1.0"
+
+from flake8_stepdown.core.ordering import order_module

flake8_stepdown-0.1.0/flake8_stepdown/cli.py

@@ -0,0 +1,168 @@
+"""CLI entry point for flake8-stepdown."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from fnmatch import fnmatch
+from pathlib import Path
+
+from flake8_stepdown.core.ordering import order_module
+from flake8_stepdown.reporter import format_diff, format_violations
+
+EXIT_OK = 0
+EXIT_VIOLATIONS = 1
+EXIT_ERROR = 2
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point.
+
+    Returns:
+        Exit code: 0 (clean), 1 (violations/changes), 2 (error).
+
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    # Handle stdin
+    if args.stdin_filename:
+        source = sys.stdin.read()
+        code, output = _process_source(source, args.stdin_filename, args)
+        if output:
+            _write_output(output)
+        return code
+
+    if not args.files:
+        sys.stderr.write("Error: no files specified\n")
+        return EXIT_ERROR
+
+    filepaths = _resolve_paths(args.files, args.exclude)
+    if not filepaths:
+        return EXIT_OK
+
+    exit_code = EXIT_OK
+    for filepath in filepaths:
+        code = _process_file(filepath, args)
+        if code == EXIT_ERROR:
+            return EXIT_ERROR
+        exit_code = max(exit_code, code)
+
+    return exit_code
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="stepdown",
+        description="Enforce top-down function ordering in Python",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("files", nargs="*", help="Files or directories to check")
+    common.add_argument("--exclude", action="append", default=[], help="Glob patterns to exclude")
+    common.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Show debug info (mutual recursion info on stderr)",
+    )
+    common.add_argument(
+        "--stdin-filename",
+        help="Read from stdin, use this filename for output",
+    )
+
+    check_parser = subparsers.add_parser("check", parents=[common], help="Report violations")
+    check_parser.add_argument(
+        "--format",
+        dest="fmt",
+        choices=["text", "json"],
+        default="text",
+        help="Output format",
+    )
+
+    subparsers.add_parser("diff", parents=[common], help="Show unified diff")
+    subparsers.add_parser("fix", parents=[common], help="Rewrite files in place")
+
+    return parser
+
+
+def _resolve_paths(paths: list[str], exclude: list[str]) -> list[str]:
+    """Expand directories to .py files and apply exclude patterns."""
+    resolved: list[str] = []
+    for entry in paths:
+        p = Path(entry)
+        if p.is_dir():
+            for py_file in sorted(p.rglob("*.py")):
+                filepath = str(py_file)
+                if not any(fnmatch(filepath, pat) for pat in exclude):
+                    resolved.append(filepath)
+        elif not any(fnmatch(entry, pat) for pat in exclude):
+            resolved.append(entry)
+    return resolved
+
+
+def _process_file(filepath: str, args: argparse.Namespace) -> int:
+    """Process a single file and handle output."""
+    path = Path(filepath)
+    if not path.exists():
+        sys.stderr.write(f"Error: {filepath} not found\n")
+        return EXIT_ERROR
+
+    try:
+        source = path.read_text()
+    except (OSError, UnicodeDecodeError) as e:
+        sys.stderr.write(f"Error reading {filepath}: {e}\n")
+        return EXIT_ERROR
+
+    code, output = _process_source(source, filepath, args)
+
+    if args.command == "fix" and code == EXIT_VIOLATIONS and output:
+        path.write_text(output)
+    elif output:
+        _write_output(output)
+
+    return code
+
+
+def _process_source(
+    source: str,
+    filename: str,
+    args: argparse.Namespace,
+) -> tuple[int, str]:
+    """Process a single source file and return (exit_code, output)."""
+    compute_rewrite = args.command != "check"
+    result = order_module(source, compute_rewrite=compute_rewrite)
+
+    if args.verbose and result.mutual_recursion_groups:
+        for group in result.mutual_recursion_groups:
+            sys.stderr.write(
+                f"{filename}: mutual recursion between {', '.join(group)}; original order preserved\n"
+            )
+
+    if args.command == "check":
+        output = format_violations(result.violations, filename=filename, fmt=args.fmt)
+        return (EXIT_VIOLATIONS if result.violations else EXIT_OK), output
+
+    if args.command == "diff":
+        if result.reordered_source is not None:
+            output = format_diff(source, result.reordered_source, filename=filename)
+            return EXIT_VIOLATIONS, output
+        return EXIT_OK, ""
+
+    # fix command
+    if result.reordered_source is not None:
+        return EXIT_VIOLATIONS, result.reordered_source
+    return EXIT_OK, ""
+
+
+def _write_output(output: str) -> None:
+    """Write output to stdout with trailing newline if needed."""
+    sys.stdout.write(output)
+    if not output.endswith("\n"):
+        sys.stdout.write("\n")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

flake8_stepdown-0.1.0/flake8_stepdown/core/__init__.py

@@ -0,0 +1 @@
+"""Core analysis modules for flake8-stepdown."""

flake8_stepdown-0.1.0/flake8_stepdown/core/bindings.py

@@ -0,0 +1,148 @@
+"""Extract bindings (defined names) from module-level statements."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import libcst as cst
+import libcst.matchers as m
+
+from flake8_stepdown.types import Statement
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+def extract_bindings(
+    statements: list[cst.CSTNode],
+    positions: Mapping[cst.CSTNode, cst.metadata.CodeRange],
+) -> list[Statement]:
+    """Extract bindings from module-level statements.
+
+    Args:
+        statements: The module-level CST nodes to analyze (functions, classes,
+            and assignments from the reorderable zone between preamble and postamble).
+        positions: Position mapping from MetadataWrapper.resolve(PositionProvider).
+
+    Groups consecutive @overload stubs with their implementation into a single Statement.
+    Returns Statement objects with empty refs (to be populated by references module).
+
+    """
+    result: list[Statement] = []
+    i = 0
+    nodes = list(statements)
+
+    while i < len(nodes):
+        node = nodes[i]
+
+        # Check for @overload grouping
+        if isinstance(node, cst.FunctionDef) and _has_overload_decorator(node):
+            func_name = node.name.value
+            group_nodes: list[cst.CSTNode] = [node]
+
+            # Collect consecutive same-name functions
+            j = i + 1
+            while j < len(nodes):
+                next_node = nodes[j]
+                if isinstance(next_node, cst.FunctionDef) and next_node.name.value == func_name:
+                    group_nodes.append(next_node)
+                    if not _has_overload_decorator(next_node):
+                        j += 1
+                        break
+                    j += 1
+                else:
+                    break
+
+            # Merge if stubs + implementation (>1 node and last is not overload)
+            last_node = group_nodes[-1]
+            if (
+                len(group_nodes) > 1
+                and isinstance(last_node, cst.FunctionDef)
+                and not _has_overload_decorator(last_node)
+            ):
+                first_pos = positions.get(group_nodes[0])
+                last_pos = positions.get(last_node)
+                result.append(
+                    Statement(
+                        node=last_node,
+                        start_line=first_pos.start.line if first_pos else 0,
+                        end_line=last_pos.end.line if last_pos else 0,
+                        bindings=frozenset({func_name}),
+                        immediate_refs=frozenset(),
+                        deferred_refs=frozenset(),
+                        is_overload_group=True,
+                    ),
+                )
+                i = j
+                continue
+
+            # Not a complete overload group — fall through to normal handling
+
+        # Normal statement
+        pos = positions.get(node)
+        start_line = pos.start.line if pos else 0
+        end_line = pos.end.line if pos else 0
+
+        bindings = (
+            _extract_binding_names(node) if isinstance(node, cst.BaseStatement) else frozenset()
+        )
+        result.append(
+            Statement(
+                node=node,
+                start_line=start_line,
+                end_line=end_line,
+                bindings=bindings,
+                immediate_refs=frozenset(),
+                deferred_refs=frozenset(),
+                is_overload_group=False,
+            ),
+        )
+        i += 1
+
+    return result
+
+
+def _extract_binding_names(node: cst.BaseStatement) -> frozenset[str]:
+    """Extract the names defined by a single statement."""
+    if isinstance(node, cst.FunctionDef):
+        return frozenset({node.name.value})
+
+    if isinstance(node, cst.ClassDef):
+        return frozenset({node.name.value})
+
+    if isinstance(node, cst.SimpleStatementLine):
+        names: set[str] = set()
+        for stmt in node.body:
+            if isinstance(stmt, cst.Assign):
+                for target in stmt.targets:
+                    names |= _collect_names(target.target)
+            elif isinstance(stmt, cst.AnnAssign) and stmt.value is not None:
+                names |= _collect_names(stmt.target)
+        return frozenset(names)
+
+    return frozenset()
+
+
+def _collect_names(target: cst.BaseExpression) -> set[str]:
+    """Recursively collect all Name identifiers from an assignment target."""
+    if isinstance(target, cst.Name):
+        return {target.value}
+    if isinstance(target, cst.Tuple):
+        names: set[str] = set()
+        for element in target.elements:
+            names |= _collect_names(element.value)
+        return names
+    if isinstance(target, cst.StarredElement):
+        return _collect_names(target.value)
+    return set()
+
+
+def _has_overload_decorator(node: cst.FunctionDef) -> bool:
+    """Check if a FunctionDef has @typing.overload or @overload."""
+    for decorator in node.decorators:
+        dec = decorator.decorator
+        if m.matches(dec, m.Name("overload")):
+            return True
+        if m.matches(dec, m.Attribute(value=m.Name("typing"), attr=m.Name("overload"))):
+            return True
+    return False