explain-repo 0.1.0__tar.gz

explain_repo-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Byte-compiled files and Python caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Packaging and build output
+build/
+dist/
+*.egg-info/
+.eggs/
+eggs/
+sdist/
+wheels/
+pip-wheel-metadata/
+
+# Test, coverage, and analysis caches
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+.mypy_cache/
+.pyright/
+.ruff_cache/
+.hypothesis/
+
+# Local environment and secrets
+.env
+.env.*
+!.env.example
+
+# Editor and operating-system files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Logs and temporary files
+*.log
+*.tmp

explain_repo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alintm4
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

explain_repo-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: explain-repo
+Version: 0.1.0
+Summary: Static-analysis guided onboarding reports for Python repositories
+Project-URL: Homepage, https://github.com/alintm4/explain-repo
+Project-URL: Repository, https://github.com/alintm4/explain-repo.git
+Project-URL: Issues, https://github.com/alintm4/explain-repo/issues
+Author-email: alintm4 <alintimilsana@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 alintm4
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: networkx>=3.2
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# explain-repo
+
+`explain-repo` statically analyzes a local Python repository and produces a
+guided onboarding report. It parses Python with the standard-library `ast`
+module, resolves internal imports, builds a NetworkX dependency graph, and ranks
+files without reading meaning into source text.
+
+## Installation
+
+After the package is published to PyPI, run it without installing it globally:
+
+```console
+uvx explain-repo ./path/to/repository
+```
+
+For local development:
+
+```console
+git clone <repository-url>
+cd explain-repo
+uv sync
+uv run pytest
+uvx --from . explain-repo ./path/to/repository
+```
+
+Python 3.11 or newer is required.
+
+## Usage
+
+```console
+explain-repo [OPTIONS] PATH
+
+Options:
+  --top INTEGER RANGE             Number of files to show. [default: 10]
+  --json                          Output structured JSON.
+  --rank-method [indegree|pagerank]
+											 Ranking algorithm. [default: pagerank]
+  --llm                           Add structure-only Anthropic descriptions.
+  --help                          Show help and exit.
+```
+
+Examples:
+
+```console
+uvx explain-repo . --top 5
+uvx explain-repo . --rank-method indegree
+uvx explain-repo . --json > report.json
+uvx --from 'explain-repo[llm]' explain-repo . --llm
+```
+
+Sample terminal output:
+
+```text
+Suggested Reading Order
+┏━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
+┃ # ┃ File               ┃ Why central               ┃ Dependencies     ┃
+┡━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
+│ 1 │ src/app/core.py    │ imported by 12 other files │ src/app/types.py │
+│ 2 │ src/app/service.py │ imported by 4 other files  │ src/app/core.py  │
+└───┴────────────────────┴───────────────────────────┴──────────────────┘
+
+Core Abstractions
+┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
+┃ File               ┃ Classes              ┃ Functions        ┃
+┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
+│ src/app/core.py    │ Repository (load)    │ create_app       │
+│ src/app/service.py │ AnalysisService (run)│ analyze          │
+└────────────────────┴──────────────────────┴──────────────────┘
+```
+
+Syntax-invalid files are skipped with a warning. Common generated directories,
+including `.git`, `.venv`, `venv`, `node_modules`, `__pycache__`, `build`, and
+`dist`, are excluded from scanning. Circular imports are represented as ordinary
+cycles in the graph and require no recursive traversal.
+
+## Optional Anthropic descriptions
+
+Install the `llm` extra and provide Anthropic credentials in the environment:
+
+```console
+export ANTHROPIC_API_KEY="..."
+uv sync --extra llm
+uv run explain-repo . --llm
+```
+
+The model receives only the file path and extracted imports, function names,
+class names, and method names. Full source content is never sent. Override the
+default model with `EXPLAIN_REPO_ANTHROPIC_MODEL`.
+
+## Publishing to PyPI
+
+The distribution name, Python requirement, runtime dependencies, build backend,
+and `[project.scripts]` entry point are defined in `pyproject.toml`. The script
+entry is what lets `uvx` install the distribution and invoke `explain-repo`.
+
+1. Choose the next semantic version and update both `project.version` in
+	`pyproject.toml` and `__version__` in `src/explain_repo/__init__.py`.
+2. Run `uv lock`, `uv sync`, `uv run pytest`, and
+	`uvx --from . explain-repo .`.
+3. Build clean wheel and source distributions with `uv build`.
+4. Check the release files with `uvx twine check dist/*`.
+5. Create a PyPI trusted publisher for the repository's release workflow, or
+	create a scoped PyPI API token.
+6. Publish interactively with `uv publish`; when prompted for token credentials,
+	use `__token__` as the username and the PyPI token as the password. In CI,
+	prefer PyPI trusted publishing instead of storing a long-lived token.
+7. Verify the published release with
+	`uvx --refresh --from explain-repo==<version> explain-repo --help`.
+
+PyPI makes the distribution globally discoverable. Before publication,
+`uvx --from . explain-repo PATH` is the correct local equivalent.

explain_repo-0.1.0/README.md

@@ -0,0 +1,111 @@
+# explain-repo
+
+`explain-repo` statically analyzes a local Python repository and produces a
+guided onboarding report. It parses Python with the standard-library `ast`
+module, resolves internal imports, builds a NetworkX dependency graph, and ranks
+files without reading meaning into source text.
+
+## Installation
+
+After the package is published to PyPI, run it without installing it globally:
+
+```console
+uvx explain-repo ./path/to/repository
+```
+
+For local development:
+
+```console
+git clone <repository-url>
+cd explain-repo
+uv sync
+uv run pytest
+uvx --from . explain-repo ./path/to/repository
+```
+
+Python 3.11 or newer is required.
+
+## Usage
+
+```console
+explain-repo [OPTIONS] PATH
+
+Options:
+  --top INTEGER RANGE             Number of files to show. [default: 10]
+  --json                          Output structured JSON.
+  --rank-method [indegree|pagerank]
+											 Ranking algorithm. [default: pagerank]
+  --llm                           Add structure-only Anthropic descriptions.
+  --help                          Show help and exit.
+```
+
+Examples:
+
+```console
+uvx explain-repo . --top 5
+uvx explain-repo . --rank-method indegree
+uvx explain-repo . --json > report.json
+uvx --from 'explain-repo[llm]' explain-repo . --llm
+```
+
+Sample terminal output:
+
+```text
+Suggested Reading Order
+┏━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
+┃ # ┃ File               ┃ Why central               ┃ Dependencies     ┃
+┡━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
+│ 1 │ src/app/core.py    │ imported by 12 other files │ src/app/types.py │
+│ 2 │ src/app/service.py │ imported by 4 other files  │ src/app/core.py  │
+└───┴────────────────────┴───────────────────────────┴──────────────────┘
+
+Core Abstractions
+┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
+┃ File               ┃ Classes              ┃ Functions        ┃
+┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
+│ src/app/core.py    │ Repository (load)    │ create_app       │
+│ src/app/service.py │ AnalysisService (run)│ analyze          │
+└────────────────────┴──────────────────────┴──────────────────┘
+```
+
+Syntax-invalid files are skipped with a warning. Common generated directories,
+including `.git`, `.venv`, `venv`, `node_modules`, `__pycache__`, `build`, and
+`dist`, are excluded from scanning. Circular imports are represented as ordinary
+cycles in the graph and require no recursive traversal.
+
+## Optional Anthropic descriptions
+
+Install the `llm` extra and provide Anthropic credentials in the environment:
+
+```console
+export ANTHROPIC_API_KEY="..."
+uv sync --extra llm
+uv run explain-repo . --llm
+```
+
+The model receives only the file path and extracted imports, function names,
+class names, and method names. Full source content is never sent. Override the
+default model with `EXPLAIN_REPO_ANTHROPIC_MODEL`.
+
+## Publishing to PyPI
+
+The distribution name, Python requirement, runtime dependencies, build backend,
+and `[project.scripts]` entry point are defined in `pyproject.toml`. The script
+entry is what lets `uvx` install the distribution and invoke `explain-repo`.
+
+1. Choose the next semantic version and update both `project.version` in
+	`pyproject.toml` and `__version__` in `src/explain_repo/__init__.py`.
+2. Run `uv lock`, `uv sync`, `uv run pytest`, and
+	`uvx --from . explain-repo .`.
+3. Build clean wheel and source distributions with `uv build`.
+4. Check the release files with `uvx twine check dist/*`.
+5. Create a PyPI trusted publisher for the repository's release workflow, or
+	create a scoped PyPI API token.
+6. Publish interactively with `uv publish`; when prompted for token credentials,
+	use `__token__` as the username and the PyPI token as the password. In CI,
+	prefer PyPI trusted publishing instead of storing a long-lived token.
+7. Verify the published release with
+	`uvx --refresh --from explain-repo==<version> explain-repo --help`.
+
+PyPI makes the distribution globally discoverable. Before publication,
+`uvx --from . explain-repo PATH` is the correct local equivalent.

explain_repo-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "explain-repo"
+version = "0.1.0"
+description = "Static-analysis guided onboarding reports for Python repositories"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "alintm4", email = "alintimilsana@gmail.com" }]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "click>=8.1",
+    "networkx>=3.2",
+    "rich>=13.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/alintm4/explain-repo"
+Repository = "https://github.com/alintm4/explain-repo.git"
+Issues = "https://github.com/alintm4/explain-repo/issues"
+
+[project.optional-dependencies]
+llm = ["anthropic>=0.40"]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+explain-repo = "explain_repo.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/explain_repo"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = ["pytest>=8.0"]

explain_repo-0.1.0/src/explain_repo/__init__.py

@@ -0,0 +1,3 @@
+"""Static-analysis tools for explaining Python repositories."""
+
+__version__ = "0.1.0"

explain_repo-0.1.0/src/explain_repo/cli.py

@@ -0,0 +1,143 @@
+"""Command-line interface for explain-repo."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+from .graph import build_dependency_graph, rank_files
+from .parser import FileInfo, parse_repository
+
+
+def _import_label(info: FileInfo) -> list[str]:
+    labels = []
+    for imported in info.imports:
+        prefix = "." * imported.level + (imported.module or "")
+        labels.append(prefix or ", ".join(imported.names))
+    return labels
+
+
+def _build_report(
+    root: Path, top: int, rank_method: str, include_llm: bool
+) -> dict[str, Any]:
+    files = parse_repository(root)
+    graph = build_dependency_graph(files)
+    ranked = rank_files(graph, rank_method)[:top]
+    entries = []
+    for path, score in ranked:
+        info = files[path]
+        imported_by = sorted(source.as_posix() for source in graph.predecessors(path))
+        dependencies = sorted(target.as_posix() for target in graph.successors(path))
+        entry: dict[str, Any] = {
+            "path": path.as_posix(),
+            "score": score,
+            "why_central": f"imported by {len(imported_by)} other file{'s' if len(imported_by) != 1 else ''}",
+            "imported_by": imported_by,
+            "dependencies": dependencies,
+            "imports": _import_label(info),
+            "functions": info.functions,
+            "classes": [
+                {"name": name, "methods": info.class_methods.get(name, [])}
+                for name in info.classes
+            ],
+        }
+        if include_llm:
+            from .llm import describe_file
+
+            entry["description"] = describe_file(info)
+        entries.append(entry)
+    return {
+        "repository": str(root),
+        "rank_method": rank_method,
+        "python_file_count": len(files),
+        "syntax_errors": [
+            {"path": path.as_posix(), "error": info.syntax_error}
+            for path, info in files.items()
+            if info.syntax_error
+        ],
+        "reading_order": entries,
+    }
+
+
+def _render_text(report: dict[str, Any], console: Console) -> None:
+    console.print("[bold]Suggested Reading Order[/bold]")
+    reading_table = Table(show_header=True, header_style="bold cyan")
+    reading_table.add_column("#", justify="right")
+    reading_table.add_column("File")
+    reading_table.add_column("Why central")
+    reading_table.add_column("Dependencies")
+    for index, entry in enumerate(report["reading_order"], start=1):
+        reading_table.add_row(
+            str(index),
+            entry["path"],
+            entry["why_central"],
+            ", ".join(entry["dependencies"]) or "None",
+        )
+        if entry.get("description"):
+            reading_table.add_row("", "[dim]Description[/dim]", entry["description"], "")
+    console.print(reading_table)
+
+    console.print("\n[bold]Core Abstractions[/bold]")
+    abstraction_table = Table(show_header=True, header_style="bold cyan")
+    abstraction_table.add_column("File")
+    abstraction_table.add_column("Classes")
+    abstraction_table.add_column("Functions")
+    for entry in report["reading_order"]:
+        classes = []
+        for class_info in entry["classes"]:
+            methods = ", ".join(class_info["methods"])
+            classes.append(f"{class_info['name']} ({methods})" if methods else class_info["name"])
+        abstraction_table.add_row(
+            entry["path"],
+            "\n".join(classes) or "None",
+            ", ".join(entry["functions"]) or "None",
+        )
+    console.print(abstraction_table)
+
+
+@click.command()
+@click.version_option(version=__version__, prog_name="explain-repo")
+@click.argument(
+    "path",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+)
+@click.option("--top", type=click.IntRange(min=1), default=10, show_default=True)
+@click.option("--json", "as_json", is_flag=True, help="Output structured JSON.")
+@click.option(
+    "--rank-method",
+    type=click.Choice(["indegree", "pagerank"]),
+    default="pagerank",
+    show_default=True,
+)
+@click.option("--llm", is_flag=True, help="Add Anthropic descriptions from extracted structure.")
+def main(path: Path, top: int, as_json: bool, rank_method: str, llm: bool) -> None:
+    """Analyze the Python repository at PATH and suggest a reading order."""
+    root = path.resolve()
+    try:
+        report = _build_report(root, top, rank_method, llm)
+    except RuntimeError as error:
+        raise click.ClickException(str(error)) from error
+    except Exception as error:
+        if llm:
+            raise click.ClickException(f"LLM request failed: {error}") from error
+        raise
+
+    for syntax_error in report["syntax_errors"]:
+        click.echo(
+            f"Warning: skipped {syntax_error['path']}: {syntax_error['error']}",
+            err=True,
+        )
+    if as_json:
+        click.echo(json.dumps(report, indent=2))
+    else:
+        _render_text(report, Console())
+
+
+if __name__ == "__main__":
+    main()

explain_repo-0.1.0/src/explain_repo/graph.py

@@ -0,0 +1,124 @@
+"""Build and rank a file-level Python dependency graph."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path, PurePosixPath
+
+import networkx as nx
+
+from .parser import FileInfo, ImportInfo
+
+
+def _module_name(path: Path) -> str:
+    pure_path = PurePosixPath(path.as_posix())
+    if pure_path.name == "__init__.py":
+        return ".".join(pure_path.parent.parts)
+    return ".".join(pure_path.with_suffix("").parts)
+
+
+def _module_index(paths: Iterable[Path]) -> dict[str, Path]:
+    index: dict[str, Path] = {}
+    for path in paths:
+        module = _module_name(path)
+        if module:
+            index[module] = path
+            if module.startswith("src."):
+                index[module.removeprefix("src.")] = path
+        elif path.name == "__init__.py":
+            index["__root__"] = path
+    return index
+
+
+def _package_parts(importer: Path) -> list[str]:
+    module_parts = _module_name(importer).split(".") if _module_name(importer) else []
+    if importer.name != "__init__.py":
+        module_parts = module_parts[:-1]
+    return module_parts
+
+
+def _import_candidates(importer: Path, imported: ImportInfo) -> list[str]:
+    if imported.level:
+        package = _package_parts(importer)
+        keep = max(0, len(package) - imported.level + 1)
+        base_parts = package[:keep]
+        if imported.module:
+            base_parts.extend(imported.module.split("."))
+        base = ".".join(base_parts)
+        if imported.module:
+            return [*(f"{base}.{name}" for name in imported.names), base]
+        return [".".join([*base_parts, name]) for name in imported.names]
+
+    if imported.module:
+        return [
+            *(f"{imported.module}.{name}" for name in imported.names),
+            imported.module,
+        ]
+    return list(imported.names)
+
+
+def resolve_import(
+    importer: Path, imported: ImportInfo, module_index: dict[str, Path]
+) -> set[Path]:
+    """Resolve an import to files indexed inside the analyzed repository."""
+    resolved: set[Path] = set()
+    for candidate in _import_candidates(importer, imported):
+        if candidate in module_index:
+            resolved.add(module_index[candidate])
+            continue
+
+        parts = candidate.split(".")
+        while len(parts) > 1:
+            parts.pop()
+            parent = ".".join(parts)
+            if parent in module_index:
+                resolved.add(module_index[parent])
+                break
+    return resolved
+
+
+def build_dependency_graph(files: dict[Path, FileInfo]) -> nx.DiGraph:
+    """Build a graph whose edges point from importers to imported files."""
+    graph = nx.DiGraph()
+    graph.add_nodes_from(files)
+    index = _module_index(files)
+    for path, info in files.items():
+        for imported in info.imports:
+            for dependency in resolve_import(path, imported, index):
+                if dependency != path:
+                    graph.add_edge(path, dependency)
+    return graph
+
+
+def _pagerank(graph: nx.DiGraph, damping: float = 0.85) -> dict[Path, float]:
+    if not graph:
+        return {}
+    node_count = len(graph)
+    scores = {node: 1.0 / node_count for node in graph}
+    base_score = (1.0 - damping) / node_count
+    for _ in range(100):
+        dangling_score = sum(scores[node] for node in graph if graph.out_degree(node) == 0)
+        updated = {}
+        for node in graph:
+            inbound_score = sum(
+                scores[source] / graph.out_degree(source)
+                for source in graph.predecessors(node)
+            )
+            updated[node] = base_score + damping * (
+                inbound_score + dangling_score / node_count
+            )
+        if sum(abs(updated[node] - scores[node]) for node in graph) < node_count * 1e-6:
+            return updated
+        scores = updated
+    return scores
+
+
+def rank_files(graph: nx.DiGraph, method: str = "pagerank") -> list[tuple[Path, float]]:
+    """Rank files by PageRank or in-degree centrality."""
+    if method == "pagerank":
+        scores = _pagerank(graph)
+    elif method == "indegree":
+        scores = nx.in_degree_centrality(graph) if len(graph) > 1 else {node: 0.0 for node in graph}
+    else:
+        raise ValueError(f"Unsupported rank method: {method}")
+    return sorted(scores.items(), key=lambda item: (-item[1], item[0].as_posix()))