reposcape 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. reposcape-0.1.0/.copier-answers.yml +21 -0
  2. reposcape-0.1.0/.github/FUNDING.yml +3 -0
  3. reposcape-0.1.0/.github/copilot-instructions.md +19 -0
  4. reposcape-0.1.0/.github/dependabot.yml +9 -0
  5. reposcape-0.1.0/.github/workflows/build.yml +88 -0
  6. reposcape-0.1.0/.github/workflows/documentation.yml +57 -0
  7. reposcape-0.1.0/.gitignore +32 -0
  8. reposcape-0.1.0/.pre-commit-config.yaml +48 -0
  9. reposcape-0.1.0/LICENSE +22 -0
  10. reposcape-0.1.0/PKG-INFO +350 -0
  11. reposcape-0.1.0/README.md +300 -0
  12. reposcape-0.1.0/docs/.empty +0 -0
  13. reposcape-0.1.0/duties.py +60 -0
  14. reposcape-0.1.0/mkdocs.yml +92 -0
  15. reposcape-0.1.0/overrides/_dummy.txt +1 -0
  16. reposcape-0.1.0/pyproject.toml +243 -0
  17. reposcape-0.1.0/src/reposcape/__init__.py +29 -0
  18. reposcape-0.1.0/src/reposcape/analyzers/__init__.py +9 -0
  19. reposcape-0.1.0/src/reposcape/analyzers/base.py +38 -0
  20. reposcape-0.1.0/src/reposcape/analyzers/python_ast.py +362 -0
  21. reposcape-0.1.0/src/reposcape/analyzers/text.py +107 -0
  22. reposcape-0.1.0/src/reposcape/importance/__init__.py +15 -0
  23. reposcape-0.1.0/src/reposcape/importance/base.py +121 -0
  24. reposcape-0.1.0/src/reposcape/importance/graph.py +70 -0
  25. reposcape-0.1.0/src/reposcape/importance/scoring.py +178 -0
  26. reposcape-0.1.0/src/reposcape/mapper.py +437 -0
  27. reposcape-0.1.0/src/reposcape/models/__init__.py +8 -0
  28. reposcape-0.1.0/src/reposcape/models/nodes.py +64 -0
  29. reposcape-0.1.0/src/reposcape/models/options.py +20 -0
  30. reposcape-0.1.0/src/reposcape/py.typed +0 -0
  31. reposcape-0.1.0/src/reposcape/serializers/__init__.py +10 -0
  32. reposcape-0.1.0/src/reposcape/serializers/base.py +225 -0
  33. reposcape-0.1.0/src/reposcape/serializers/compact.py +98 -0
  34. reposcape-0.1.0/src/reposcape/serializers/markdown.py +100 -0
  35. reposcape-0.1.0/src/reposcape/serializers/tree.py +105 -0
  36. reposcape-0.1.0/src/reposcape/utils/__init__.py +7 -0
  37. reposcape-0.1.0/src/reposcape/utils/tokens.py +18 -0
  38. reposcape-0.1.0/tests/__init__.py +3 -0
  39. reposcape-0.1.0/tests/analyzers/__init__.py +0 -0
  40. reposcape-0.1.0/tests/analyzers/test_python_ast.py +146 -0
  41. reposcape-0.1.0/tests/conftest.py +70 -0
  42. reposcape-0.1.0/tests/importance/__init__.py +0 -0
  43. reposcape-0.1.0/tests/importance/test_calculator.py +127 -0
  44. reposcape-0.1.0/tests/importance/test_graph.py +131 -0
  45. reposcape-0.1.0/tests/importance/test_scorer.py +108 -0
  46. reposcape-0.1.0/tests/test_mapper.py +207 -0
  47. reposcape-0.1.0/tests/test_node_types.py +46 -0
  48. reposcape-0.1.0/tests/test_references.py +28 -0
@@ -0,0 +1,21 @@
1
+ # Changes here will be overwritten by Copier
2
+ _commit: v1.8.0
3
+ _src_path: .\copier-phil65\
4
+ author_email: philipptemminghoff@googlemail.com
5
+ author_fullname: Philipp Temminghoff
6
+ author_username: phil65
7
+ copyright_date: '2024'
8
+ copyright_holder: Philipp Temminghoff
9
+ copyright_holder_email: philipptemminghoff@googlemail.com
10
+ libraries_use_pydantic: false
11
+ libraries_use_qt: false
12
+ project_description: Repository maps for LLMs
13
+ project_name: RepoScape
14
+ python_minimum_version: '3.12'
15
+ python_package_command_line_name: reposcape
16
+ python_package_distribution_name: reposcape
17
+ python_package_import_name: reposcape
18
+ repository_name: reposcape
19
+ repository_namespace: phil65
20
+ repository_provider: github.com
21
+
@@ -0,0 +1,3 @@
1
+ github: phil65
2
+ custom:
3
+ - https://www.paypal.me/phil65
@@ -0,0 +1,19 @@
1
+ ## Code style
2
+
3
+ You can assume Python 3.12.
4
+ Use newest language features if possible
5
+ Consider using pattern matching, walrus operators and other new syntax features.
6
+ Adhere to pep8.
7
+
8
+ ## Tests
9
+
10
+ Tests are written using PyTest. Dont put tests into a class.
11
+
12
+ ## DocStrings
13
+
14
+ DocStrings are written in google-style.
15
+ Dont add the types to the "Args" section.
16
+ Only add a Return section if a value is returned and the meaning of the returned value
17
+ is not obvious.
18
+ You can use markdown admonitions with python-markdown syntax if neccessary (!!! info, !!! note, !!! warning).
19
+ You can use markdown tables and markdown lists if neccessary.
@@ -0,0 +1,9 @@
1
+ # Set update schedule for GitHub Actions
2
+
3
+ version: 2
4
+ updates:
5
+ - package-ecosystem: "github-actions"
6
+ directory: "/"
7
+ schedule:
8
+ # Check for updates to GitHub Actions every week
9
+ interval: "weekly"
@@ -0,0 +1,88 @@
1
+ name: Build
2
+
3
+ on: [push, pull_request]
4
+
5
+ jobs:
6
+ test:
7
+ runs-on: ${{ matrix.os }}
8
+ continue-on-error: ${{ matrix.python_version == '3.14' }}
9
+ strategy:
10
+ matrix:
11
+ python_version: ["3.12", "3.13", "3.14"]
12
+ os: ["ubuntu-latest", "macos-latest", "windows-latest"]
13
+ steps:
14
+ - name: Check out repository
15
+ uses: actions/checkout@v4
16
+
17
+ - name: Set up Python ${{ matrix.python_version }}
18
+ uses: actions/setup-python@v5
19
+ with:
20
+ python-version: ${{ matrix.python_version }}
21
+ allow-prereleases: true
22
+
23
+ - name: Install uv
24
+ uses: astral-sh/setup-uv@v4
25
+ with:
26
+ enable-cache: true
27
+ cache-dependency-glob: pyproject.toml
28
+ cache-suffix: py${{ matrix.python_version }}
29
+
30
+ - name: Install dependencies (uv sync)
31
+ run: uv sync --all-extras --no-group docs
32
+
33
+ - name: Check for code issues (ruff check)
34
+ uses: astral-sh/ruff-action@v1
35
+
36
+ - name: Check code format (ruff format)
37
+ uses: astral-sh/ruff-action@v1
38
+ with:
39
+ args: "format --check"
40
+
41
+ - name: Static type checking (MyPy)
42
+ run: uv run --no-group docs mypy src/reposcape/
43
+
44
+ - name: Run tests
45
+ run: uv run --no-group docs pytest --cov-report=xml --cov=src/reposcape/ --cov-report=term-missing
46
+
47
+ - name: Upload test results to Codecov
48
+ uses: codecov/codecov-action@v5
49
+ with:
50
+ fail_ci_if_error: false
51
+ verbose: true
52
+
53
+ release:
54
+ runs-on: ubuntu-latest
55
+ needs: test
56
+ if: startsWith(github.ref, 'refs/tags/')
57
+ permissions:
58
+ # this permission is mandatory for trusted publishing
59
+ id-token: write
60
+ contents: write
61
+ steps:
62
+ - name: Check out repository
63
+ uses: actions/checkout@v4
64
+
65
+ - name: Set up Python
66
+ uses: actions/setup-python@v5
67
+ with:
68
+ python-version: "3.12"
69
+
70
+ - name: Install uv
71
+ uses: astral-sh/setup-uv@v4
72
+ with:
73
+ enable-cache: true
74
+ cache-dependency-glob: pyproject.toml
75
+ cache-suffix: py${{ matrix.python_version }}
76
+
77
+ - name: Build package
78
+ run: uv build
79
+
80
+ - name: Publish package distributions to PyPI
81
+ uses: pypa/gh-action-pypi-publish@release/v1
82
+
83
+ - name: Release package on GitHub
84
+ uses: ncipollo/release-action@v1
85
+ with:
86
+ body: ${{ github.event.head_commit.message }}
87
+ artifacts: dist/*.whl,dist/*.tar.gz
88
+ token: ${{ secrets.GITHUB_TOKEN }}
@@ -0,0 +1,57 @@
1
+ name: Build documentation
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main
7
+
8
+ # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
9
+ permissions:
10
+ contents: read
11
+ pages: write
12
+ id-token: write
13
+
14
+ # Allow one concurrent deployment
15
+ concurrency:
16
+ group: "pages"
17
+ cancel-in-progress: true
18
+
19
+ # Default to bash
20
+ defaults:
21
+ run:
22
+ shell: bash
23
+
24
+ jobs:
25
+ build:
26
+ runs-on: ubuntu-latest
27
+
28
+ steps:
29
+ - uses: actions/checkout@v4
30
+ with:
31
+ fetch-depth: 0
32
+ - name: Set up Python
33
+ uses: actions/setup-python@v5
34
+ with:
35
+ python-version: "3.12"
36
+ - name: Install uv
37
+ uses: astral-sh/setup-uv@v4
38
+ - name: Install dependencies
39
+ run: |
40
+ uv sync --all-extras
41
+ - name: Build
42
+ run: uv run mknodes build
43
+ - name: Upload artifact
44
+ uses: actions/upload-pages-artifact@v3
45
+ with:
46
+ path: ./site
47
+
48
+ deploy:
49
+ environment:
50
+ name: github-pages
51
+ url: ${{ steps.deployment.outputs.page_url }}
52
+ runs-on: ubuntu-latest
53
+ needs: build
54
+ steps:
55
+ - name: Deploy to GitHub Pages
56
+ id: deployment
57
+ uses: actions/deploy-pages@v4
@@ -0,0 +1,32 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[cod]
4
+ # Distribution / packaging
5
+ *.sublime-workspace
6
+ # Unit test / coverage reports
7
+ .coverage
8
+ coverage.xml
9
+ .cache
10
+ .hatch
11
+ .pytest_cache/
12
+ junit.xml
13
+ # Jupyter Notebook
14
+ .ipynb_checkpoints
15
+ # pyenv
16
+ .python-version
17
+ # dotenv
18
+ .env
19
+ # virtualenv
20
+ .venv
21
+ # mkdocs documentation
22
+ /site
23
+ # mypy
24
+ .mypy_cache/
25
+ # .vscode
26
+ .vscode/
27
+ # OS files
28
+ .DS_Store
29
+ # uv
30
+ uv.lock
31
+ # DiskCache cache file
32
+ ./model_cache
@@ -0,0 +1,48 @@
1
+ default_language_version:
2
+ python: python3.12
3
+ default_stages: [pre-commit]
4
+ repos:
5
+ - repo: local
6
+ hooks:
7
+ - id: pytest-check
8
+ name: pytest-check
9
+ entry: uv run pytest
10
+ language: system
11
+ # stages: [push]
12
+ types: [python]
13
+ pass_filenames: false
14
+ always_run: true
15
+
16
+ - repo: https://github.com/pre-commit/pre-commit-hooks
17
+ # https://pre-commit.com/hooks.html
18
+ rev: v5.0.0
19
+ hooks:
20
+ - id: check-added-large-files
21
+ - id: check-case-conflict
22
+ - id: check-merge-conflict
23
+ - id: check-toml
24
+ - id: check-json
25
+ - id: check-xml
26
+ - id: check-yaml
27
+ args: [--allow-multiple-documents, --unsafe]
28
+ - id: debug-statements
29
+ - id: detect-private-key
30
+
31
+ - repo: https://github.com/pre-commit/mirrors-mypy
32
+ rev: v1.13.0
33
+ hooks:
34
+ - id: mypy
35
+ additional_dependencies: [orjson]
36
+
37
+ - repo: https://github.com/charliermarsh/ruff-pre-commit
38
+ rev: v0.8.1
39
+ hooks:
40
+ - id: ruff
41
+ - id: ruff-format
42
+
43
+ - repo: https://github.com/commitizen-tools/commitizen
44
+ rev: v4.0.0
45
+ hooks:
46
+ - id: commitizen
47
+ stages: [commit-msg]
48
+ additional_dependencies: [typing-extensions]
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024, Philipp Temminghoff
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
@@ -0,0 +1,350 @@
1
+ Metadata-Version: 2.3
2
+ Name: reposcape
3
+ Version: 0.1.0
4
+ Summary: Repository maps for LLMs
5
+ Project-URL: Documentation, https://phil65.github.io/reposcape/
6
+ Project-URL: Source, https://github.com/phil65/reposcape
7
+ Project-URL: Issues, https://github.com/phil65/reposcape/issues
8
+ Project-URL: Discussions, https://github.com/phil65/reposcape/discussions
9
+ Project-URL: Code coverage, https://app.codecov.io/gh/phil65/reposcape
10
+ Author-email: Philipp Temminghoff <philipptemminghoff@googlemail.com>
11
+ License: MIT License
12
+
13
+ Copyright (c) 2024, Philipp Temminghoff
14
+
15
+ Permission is hereby granted, free of charge, to any person obtaining a copy
16
+ of this software and associated documentation files (the "Software"), to deal
17
+ in the Software without restriction, including without limitation the rights
18
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
19
+ copies of the Software, and to permit persons to whom the Software is
20
+ furnished to do so, subject to the following conditions:
21
+
22
+ The above copyright notice and this permission notice shall be included in all
23
+ copies or substantial portions of the Software.
24
+
25
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
26
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
27
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
28
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
29
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
30
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
31
+ SOFTWARE.
32
+
33
+ Classifier: Development Status :: 4 - Beta
34
+ Classifier: Intended Audience :: Developers
35
+ Classifier: Operating System :: OS Independent
36
+ Classifier: Programming Language :: Python :: 3
37
+ Classifier: Programming Language :: Python :: 3 :: Only
38
+ Classifier: Programming Language :: Python :: 3.12
39
+ Classifier: Programming Language :: Python :: 3.13
40
+ Classifier: Programming Language :: Python :: 3.14
41
+ Classifier: Topic :: Documentation
42
+ Classifier: Topic :: Software Development
43
+ Classifier: Topic :: Utilities
44
+ Classifier: Typing :: Typed
45
+ Requires-Python: >=3.12
46
+ Requires-Dist: rustworkx>=0.15.1
47
+ Requires-Dist: tiktoken>=0.8.0
48
+ Requires-Dist: universal-pathlib>=0.2.5
49
+ Description-Content-Type: text/markdown
50
+
51
+ # RepoScape
52
+
53
+ [![PyPI License](https://img.shields.io/pypi/l/reposcape.svg)](https://pypi.org/project/reposcape/)
54
+ [![Package status](https://img.shields.io/pypi/status/reposcape.svg)](https://pypi.org/project/reposcape/)
55
+ [![Daily downloads](https://img.shields.io/pypi/dd/reposcape.svg)](https://pypi.org/project/reposcape/)
56
+ [![Weekly downloads](https://img.shields.io/pypi/dw/reposcape.svg)](https://pypi.org/project/reposcape/)
57
+ [![Monthly downloads](https://img.shields.io/pypi/dm/reposcape.svg)](https://pypi.org/project/reposcape/)
58
+ [![Distribution format](https://img.shields.io/pypi/format/reposcape.svg)](https://pypi.org/project/reposcape/)
59
+ [![Wheel availability](https://img.shields.io/pypi/wheel/reposcape.svg)](https://pypi.org/project/reposcape/)
60
+ [![Python version](https://img.shields.io/pypi/pyversions/reposcape.svg)](https://pypi.org/project/reposcape/)
61
+ [![Implementation](https://img.shields.io/pypi/implementation/reposcape.svg)](https://pypi.org/project/reposcape/)
62
+ [![Releases](https://img.shields.io/github/downloads/phil65/reposcape/total.svg)](https://github.com/phil65/reposcape/releases)
63
+ [![Github Contributors](https://img.shields.io/github/contributors/phil65/reposcape)](https://github.com/phil65/reposcape/graphs/contributors)
64
+ [![Github Discussions](https://img.shields.io/github/discussions/phil65/reposcape)](https://github.com/phil65/reposcape/discussions)
65
+ [![Github Forks](https://img.shields.io/github/forks/phil65/reposcape)](https://github.com/phil65/reposcape/forks)
66
+ [![Github Issues](https://img.shields.io/github/issues/phil65/reposcape)](https://github.com/phil65/reposcape/issues)
67
+ [![Github Issues](https://img.shields.io/github/issues-pr/phil65/reposcape)](https://github.com/phil65/reposcape/pulls)
68
+ [![Github Watchers](https://img.shields.io/github/watchers/phil65/reposcape)](https://github.com/phil65/reposcape/watchers)
69
+ [![Github Stars](https://img.shields.io/github/stars/phil65/reposcape)](https://github.com/phil65/reposcape/stars)
70
+ [![Github Repository size](https://img.shields.io/github/repo-size/phil65/reposcape)](https://github.com/phil65/reposcape)
71
+ [![Github last commit](https://img.shields.io/github/last-commit/phil65/reposcape)](https://github.com/phil65/reposcape/commits)
72
+ [![Github release date](https://img.shields.io/github/release-date/phil65/reposcape)](https://github.com/phil65/reposcape/releases)
73
+ [![Github language count](https://img.shields.io/github/languages/count/phil65/reposcape)](https://github.com/phil65/reposcape)
74
+ [![Github commits this week](https://img.shields.io/github/commit-activity/w/phil65/reposcape)](https://github.com/phil65/reposcape)
75
+ [![Github commits this month](https://img.shields.io/github/commit-activity/m/phil65/reposcape)](https://github.com/phil65/reposcape)
76
+ [![Github commits this year](https://img.shields.io/github/commit-activity/y/phil65/reposcape)](https://github.com/phil65/reposcape)
77
+ [![Package status](https://codecov.io/gh/phil65/reposcape/branch/main/graph/badge.svg)](https://codecov.io/gh/phil65/reposcape/)
78
+ [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
79
+ [![PyUp](https://pyup.io/repos/github/phil65/reposcape/shield.svg)](https://pyup.io/repos/github/phil65/reposcape/)
80
+
81
+ [Read the documentation!](https://phil65.github.io/reposcape/)
82
+
83
+ # RepoScape
84
+
85
+ RepoScape is a Python library for mapping and analyzing repository structures with a focus on understanding code dependencies and importance. It parses code files, builds a graph representation, and helps identify important components through various scoring algorithms.
86
+
87
+ ## Installation
88
+
89
+ ```bash
90
+ pip install reposcape
91
+ ```
92
+
93
+ Requires Python 3.12 or higher.
94
+
95
+ ## Quick Start
96
+
97
+ ```python
98
+ from reposcape import RepoMapper, DetailLevel
99
+
100
+ # Create mapper with default settings
101
+ mapper = RepoMapper()
102
+
103
+ # Generate overview of entire repository
104
+ overview = mapper.create_overview(
105
+ repo_path="path/to/repo",
106
+ detail=DetailLevel.SIGNATURES,
107
+ token_limit=2000 # Optional token limit for output
108
+ )
109
+
110
+ # Generate focused view of specific files
111
+ focused = mapper.create_focused_view(
112
+ files=["main.py", "utils.py"],
113
+ repo_path="path/to/repo",
114
+ detail=DetailLevel.DOCSTRINGS
115
+ )
116
+ ```
117
+
118
+ ## Core Components
119
+
120
+ ### RepoMapper
121
+
122
+ The main entry point for repository analysis. Configurable with custom analyzers, scorers, and serializers.
123
+
124
+ ```python
125
+ class RepoMapper:
126
+ def __init__(
127
+ self,
128
+ *,
129
+ analyzers: Sequence[CodeAnalyzer] | None = None,
130
+ scorer: GraphScorer | None = None,
131
+ serializer: CodeSerializer | None = None,
132
+ ): ...
133
+
134
+ def create_overview(
135
+ self,
136
+ repo_path: str | PathLike[str],
137
+ *,
138
+ token_limit: int | None = None,
139
+ detail: DetailLevel = DetailLevel.SIGNATURES,
140
+ exclude_patterns: list[str] | None = None,
141
+ ) -> str: ...
142
+
143
+ def create_focused_view(
144
+ self,
145
+ files: Sequence[str | PathLike[str]],
146
+ repo_path: str | PathLike[str],
147
+ *,
148
+ token_limit: int | None = None,
149
+ detail: DetailLevel = DetailLevel.SIGNATURES,
150
+ exclude_patterns: list[str] | None = None,
151
+ ) -> str: ...
152
+ ```
153
+
154
+ ### Detail Levels
155
+
156
+ Control how much information is included in the output:
157
+
158
+ ```python
159
+ class DetailLevel(Enum):
160
+ STRUCTURE # Just names and hierarchy
161
+ SIGNATURES # Include function/class signatures
162
+ DOCSTRINGS # Include signatures + docstrings
163
+ FULL_CODE # Include complete implementations
164
+ ```
165
+
166
+ ## Code Analysis
167
+
168
+ RepoScape includes analyzers for different file types:
169
+
170
+ ### PythonAstAnalyzer
171
+
172
+ Analyzes Python files using AST parsing:
173
+ - Extracts classes, functions, methods, variables
174
+ - Tracks references between symbols
175
+ - Collects docstrings and signatures
176
+
177
+ ```python
178
+ analyzer = PythonAstAnalyzer()
179
+ nodes = analyzer.analyze_file("main.py")
180
+ ```
181
+
182
+ ### TextAnalyzer
183
+
184
+ Basic analyzer for text files:
185
+ - Handles .txt, .md, .rst files
186
+ - Extracts sections from markdown files
187
+ - Preserves file content and first paragraph as docstring
188
+
189
+ ## Importance Scoring
190
+
191
+ RepoScape offers different algorithms for calculating code importance:
192
+
193
+ ### ReferenceScorer
194
+
195
+ Simple reference-based scoring that considers:
196
+ - Number of incoming references (highest weight)
197
+ - Number of outgoing references (medium weight)
198
+ - Being referenced by important files (high boost)
199
+ - Distance from important files (decreasing boost)
200
+
201
+ ```python
202
+ from reposcape.importance import ReferenceScorer
203
+
204
+ scorer = ReferenceScorer(
205
+ ref_weight=1.0,
206
+ outref_weight=0.5,
207
+ important_ref_boost=2.0,
208
+ distance_decay=0.5,
209
+ )
210
+ ```
211
+
212
+ ### PageRankScorer
213
+
214
+ Uses the PageRank algorithm to score nodes based on the graph structure:
215
+ - Considers connection patterns
216
+ - Handles cycles in dependencies
217
+ - Supports personalization for focused analysis
218
+
219
+ ```python
220
+ from reposcape.importance import PageRankScorer
221
+
222
+ scorer = PageRankScorer()
223
+ ```
224
+
225
+ ## Output Serialization
226
+
227
+ Multiple serializers are available for different output formats:
228
+
229
+ ### MarkdownSerializer
230
+
231
+ Generates detailed markdown with:
232
+ - Hierarchical structure using headers
233
+ - Code blocks for signatures/implementations
234
+ - Emojis for different node types
235
+ - Optional details based on importance scores
236
+
237
+ ### CompactSerializer
238
+
239
+ Produces a compact, indented format:
240
+ - Single line per node
241
+ - Indentation shows hierarchy
242
+ - Abbreviated signatures
243
+ - Good for quick overviews
244
+
245
+ ### TreeSerializer
246
+
247
+ ASCII tree-style output:
248
+ - Uses box-drawing characters
249
+ - Shows clear parent-child relationships
250
+ - Similar to `tree` command output
251
+
252
+ Example usage:
253
+
254
+ ```python
255
+ from reposcape.serializers import MarkdownSerializer, CompactSerializer, TreeSerializer
256
+
257
+ # Create mapper with specific serializer
258
+ mapper = RepoMapper(serializer=TreeSerializer())
259
+ ```
260
+
261
+ ## Advanced Usage
262
+
263
+ ### Custom Analyzers
264
+
265
+ Implement `CodeAnalyzer` for custom file analysis:
266
+
267
+ ```python
268
+ class CustomAnalyzer(CodeAnalyzer):
269
+ def can_handle(self, path: str | PathLike[str]) -> bool:
270
+ return path.endswith(".custom")
271
+
272
+ def analyze_file(
273
+ self,
274
+ path: str | PathLike[str],
275
+ content: str | None = None
276
+ ) -> list[CodeNode]: ...
277
+ ```
278
+
279
+ ### Focused Analysis
280
+
281
+ Analyze specific files and their relationships:
282
+
283
+ ```python
284
+ mapper = RepoMapper()
285
+
286
+ # Focus on specific files
287
+ focused_view = mapper.create_focused_view(
288
+ files=["src/core.py", "src/utils.py"],
289
+ repo_path=".",
290
+ detail=DetailLevel.DOCSTRINGS,
291
+ exclude_patterns=["**/test_*.py", "**/__pycache__/*"]
292
+ )
293
+ ```
294
+
295
+ ### Token Limits
296
+
297
+ Control output size for large repositories:
298
+
299
+ ```python
300
+ # Limit output to approximately 2000 tokens
301
+ overview = mapper.create_overview(
302
+ repo_path=".",
303
+ token_limit=2000,
304
+ detail=DetailLevel.SIGNATURES
305
+ )
306
+ ```
307
+
308
+ ## Models
309
+
310
+ ### CodeNode
311
+
312
+ Immutable representation of code elements:
313
+
314
+ ```python
315
+ @dataclass(frozen=True)
316
+ class CodeNode:
317
+ name: str
318
+ node_type: NodeType
319
+ path: str
320
+ content: str | None = None
321
+ docstring: str | None = None
322
+ signature: str | None = None
323
+ children: Mapping[str, CodeNode] | None = None
324
+ references_to: Sequence[Reference] | None = None
325
+ referenced_by: Sequence[Reference] | None = None
326
+ importance: float = 0.0
327
+ ```
328
+
329
+ ### NodeType
330
+
331
+ Available node types:
332
+ - DIRECTORY
333
+ - FILE
334
+ - CLASS
335
+ - FUNCTION
336
+ - METHOD
337
+ - VARIABLE
338
+
339
+ ### Reference
340
+
341
+ Tracks symbol references:
342
+
343
+ ```python
344
+ @dataclass(frozen=True)
345
+ class Reference:
346
+ name: str
347
+ path: str
348
+ line: int
349
+ column: int
350
+ ```