Skip to content

Commit 0177cb3

Browse files
MaybeBioMaybeBio
committed
Release v0.1.0
0 parents  commit 0177cb3

35 files changed

+7388
-0
lines changed

‎README.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Repo-Inspector
2+
3+
![MIT License](https://img.shields.io/badge/license-MIT-brightgreen.svg)
4+
[![PR's Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](http://makeapullrequest.com)
5+
6+
![](./icon.png)
7+
8+
🕵️ Repo-Inspector helps developers and reviewers quickly understand a `Python repository`. It produces a concise static analysis report and — optionally — deeper runtime inspection output by integrating with `LibInspector`.
9+
10+
Key outcomes:
11+
- A static Markdown report summarizing modules, APIs, and structure.
12+
- Per-file AST summaries for quick browsing.
13+
- Optional dynamic inspection (LibInspector) with per-target reports and a merged, deduplicated dynamic report (Markdown + optional HTML).
14+
15+
## Quick install
16+
17+
```bash
18+
# Clone the repository
19+
git clone https://github.com/MaybeBio/Repo-Inspector.git
20+
cd Repo-Inspector
21+
22+
# Install in editable mode (installs dependencies & CLI tool)
23+
pip install -e .
24+
```
25+
26+
## Help manual
27+
```bash
28+
❯ repo-inspector --help
29+
30+
Usage: repo-inspector [OPTIONS] PATH
31+
32+
Analyze a local Python project folder statically, with optional dynamic analysis bridge.
33+
34+
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
35+
│ * path TEXT Path to the local folder (or git cloned repo) [required] │
36+
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
37+
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
38+
│ --output -o TEXT Output Markdown file path [default: report.md] │
39+
│ --dynamic -d Enable dynamic analysis using LibInspector (requires installation). │
40+
│ --install-completion Install completion for the current shell. │
41+
│ --show-completion Show completion for the current shell, to copy it or customize the installation. │
42+
│ --help Show this message and exit. │
43+
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
44+
```
45+
We recommend writing outputs into a dedicated directory, for example `/path/PROJECT_REPORT_DIR/`.
46+
Pass the desired Markdown file path with `-o`; e.g. `-o /path/PROJECT_REPORT_DIR/project_report.md`.
47+
Repo-Inspector will create the output directory if it does not exist and will place generated artifacts under a `reports/` subfolder next to your output (you will find the main Markdown report and a `reports/` folder containing AST summaries and any dynamic outputs).
48+
49+
50+
## Quick usage
51+
52+
Generate a static report:
53+
54+
```bash
55+
repo-inspector /path/to/repo -o ./reports/project_report.md
56+
```
57+
58+
Run dynamic inspection (requires LibInspector):
59+
60+
```bash
61+
repo-inspector /path/to/repo -o ./reports/project_report.md -d
62+
```
63+
64+
What you get (when `-d` is used):
65+
- `reports/INDEX.md` — repository index and AST summaries
66+
- `reports/dynamic/` — per-target LibInspector reports (Markdown + HTML)
67+
- `reports/dynamic/<base>_merged_dynamic.md` — merged & deduplicated dynamic report
68+
- When LibInspector is importable, HTML renderings are produced alongside the Markdown files
69+
70+
## LibInspector (optional)
71+
72+
Dynamic analysis depends on LibInspector. Install it when you want runtime inspection:
73+
74+
```bash
75+
pip install git+https://github.com/MaybeBio/LibInspector.git
76+
```
77+
78+
or check my page for detailed installation guidance:
79+
[LibInspector](https://github.com/MaybeBio/LibInspector)
80+
81+
If LibInspector is not installed, Repo-Inspector will still produce the static report and AST summaries.
82+
83+
## Output & Links
84+
85+
The tool produces `three` primary artifacts: `the top-level Markdown` report (e.g. ./reports/project_report.md); `the INDEX.md inside a same-named folder` (e.g. ./reports/project_report/INDEX.md) containing the repo index and AST summaries; and `the merged dynamic report inside that folder’s dynamic/ subfolder` (e.g. ./reports/project_report/dynamic/project_report_merged_dynamic.md). The top-level report includes relative links to these files and their HTML renditions when available for quick review.
86+
87+
## Recommended workflow
88+
89+
1. Run the static scan to get a quick overview.
90+
2. Set "-d" parameter to run dynamic inspection for package entry-points, CLI scripts, examples or tests (these are auto-detected by Repo-Inspector). For optimal results, we strongly recommend `installing LibInspector` in advance and `installing the target package` directly from the repository you intend to inspect.
91+
3. Review the inspection markdown output with a focus on the three primary artifacts highlighted above (see `Output & Links` section). Alternatively, use the generated HTML report for a more intuitive, interactive viewing experience.
92+
93+
94+
## Test Case
95+
```bash
96+
❯ repo-inspector ../TensorVis/ -d -o ./test/Tensorvis.md
97+
98+
🔍 [Static] Scanning directory: ../TensorVis/ ...
99+
📊 [Static] Found 5 modules.
100+
✅ Report saved to: ./test/Tensorvis.md
101+
102+
🚀 [Dynamic] Initiating LibInspector Bridge...
103+
🔍 [Dynamic] Building repo index and AST summaries...
104+
🔍 [Dynamic] Detecting runtime targets (entry points, scripts, CLIs)...
105+
▶ [Dynamic] Running LibInspector on tensorvis (hint=module) -> test/Tensorvis/dynamic/Tensorvis_dynamic_1_module_tensorvis.md
106+
🔍 Target Resolution: Input='tensorvis' -> Import='tensorvis' (Type: module)
107+
108+
🔁 Running candidate 1/1: tensorvis -> output=./test/Tensorvis/dynamic/Tensorvis_dynamic_1_module_tensorvis_candidate_1_tensorvis.md
109+
🔍 Target Resolution: Input='tensorvis' -> Import='tensorvis' (Type: module)
110+
❌ Error: Unable to import any candidate modules for target 'tensorvis'.
111+
▶ [Dynamic] Running LibInspector on ../TensorVis/TensorVis/vis.py (hint=file) -> test/Tensorvis/dynamic/Tensorvis_dynamic_2_file_.._TensorVis_TensorVis_vis.py.md
112+
🔍 Target Resolution: Input='../TensorVis/TensorVis/vis.py' -> Import='vis' (Type: file)
113+
114+
🔁 Running candidate 1/3: TensorVis.vis -> output=./test/Tensorvis/dynamic/Tensorvis_dynamic_2_file_.._TensorVis_TensorVis_vis.py_candidate_1_TensorVis.vis.md
115+
🔍 Target Resolution: Input='TensorVis.vis' -> Import='TensorVis.vis' (Type: module)
116+
❌ Error: Unable to import any candidate modules for target 'TensorVis.vis'.
117+
118+
🔁 Running candidate 2/3: vis -> output=./test/Tensorvis/dynamic/Tensorvis_dynamic_2_file_.._TensorVis_TensorVis_vis.py_candidate_2_vis.md
119+
🔍 Target Resolution: Input='vis' -> Import='vis' (Type: module)
120+
❌ Error: Unable to import any candidate modules for target 'vis'.
121+
122+
🔁 Running candidate 3/3: /data2/TensorVis/TensorVis/vis.py -> output=./test/Tensorvis/dynamic/Tensorvis_dynamic_2_file_.._TensorVis_TensorVis_vis.py_candidate_3_vis.py.md
123+
🔍 Target Resolution: Input='/data2/TensorVis/TensorVis/vis.py' -> Import='vis' (Type: file)
124+
🔍 Analyzing dependencies for 'TensorVis.vis' (Network Analysis Phase)...
125+
✅ Markdown report saved to: /data2/Repo-Inspector/test/Tensorvis/dynamic/Tensorvis_dynamic_2_file_.._TensorVis_TensorVis_vis.py_candidate_3_vis.py.md
126+
📊 Interactive HTML report saved to: /data2/Repo-Inspector/test/Tensorvis/dynamic/Tensorvis_dynamic_2_file_.._TensorVis_TensorVis_vis.py_candidate_3_vis.py.html
127+
(Open the HTML file in your browser to see rendered charts)
128+
▶ [Dynamic] Running LibInspector on ../TensorVis/TensorVis/cli.py (hint=file) -> test/Tensorvis/dynamic/Tensorvis_dynamic_3_file_.._TensorVis_TensorVis_cli.py.md
129+
🔍 Target Resolution: Input='../TensorVis/TensorVis/cli.py' -> Import='cli' (Type: file)
130+
131+
🔁 Running candidate 1/3: TensorVis.cli -> output=./test/Tensorvis/dynamic/Tensorvis_dynamic_3_file_.._TensorVis_TensorVis_cli.py_candidate_1_TensorVis.cli.md
132+
🔍 Target Resolution: Input='TensorVis.cli' -> Import='TensorVis.cli' (Type: module)
133+
🔍 Analyzing dependencies for 'TensorVis.cli' (Network Analysis Phase)...
134+
✅ Markdown report saved to: /data2/Repo-Inspector/test/Tensorvis/dynamic/Tensorvis_dynamic_3_file_.._TensorVis_TensorVis_cli.py_candidate_1_TensorVis.cli.md
135+
📊 Interactive HTML report saved to: /data2/Repo-Inspector/test/Tensorvis/dynamic/Tensorvis_dynamic_3_file_.._TensorVis_TensorVis_cli.py_candidate_1_TensorVis.cli.html
136+
(Open the HTML file in your browser to see rendered charts)
137+
138+
🔁 Running candidate 2/3: cli -> output=./test/Tensorvis/dynamic/Tensorvis_dynamic_3_file_.._TensorVis_TensorVis_cli.py_candidate_2_cli.md
139+
🔍 Target Resolution: Input='cli' -> Import='cli' (Type: module)
140+
❌ Error: Unable to import any candidate modules for target 'cli'.
141+
142+
🔁 Running candidate 3/3: /data2/TensorVis/TensorVis/cli.py -> output=./test/Tensorvis/dynamic/Tensorvis_dynamic_3_file_.._TensorVis_TensorVis_cli.py_candidate_3_cli.py.md
143+
🔍 Target Resolution: Input='/data2/TensorVis/TensorVis/cli.py' -> Import='cli' (Type: file)
144+
🔍 Analyzing dependencies for 'TensorVis.cli' (Network Analysis Phase)...
145+
✅ Markdown report saved to: /data2/Repo-Inspector/test/Tensorvis/dynamic/Tensorvis_dynamic_3_file_.._TensorVis_TensorVis_cli.py_candidate_3_cli.py.md
146+
📊 Interactive HTML report saved to: /data2/Repo-Inspector/test/Tensorvis/dynamic/Tensorvis_dynamic_3_file_.._TensorVis_TensorVis_cli.py_candidate_3_cli.py.html
147+
(Open the HTML file in your browser to see rendered charts)
148+
▶ [Dynamic] Running LibInspector on ../TensorVis/TensorVis/op_viz.py (hint=file) -> test/Tensorvis/dynamic/Tensorvis_dynamic_4_file_.._TensorVis_TensorVis_op_viz.py.md
149+
🔍 Target Resolution: Input='../TensorVis/TensorVis/op_viz.py' -> Import='op_viz' (Type: file)
150+
151+
🔁 Running candidate 1/3: TensorVis.op_viz -> output=./test/Tensorvis/dynamic/Tensorvis_dynamic_4_file_.._TensorVis_TensorVis_op_viz.py_candidate_1_TensorVis.op_viz.md
152+
🔍 Target Resolution: Input='TensorVis.op_viz' -> Import='TensorVis.op_viz' (Type: module)
153+
🔍 Analyzing dependencies for 'TensorVis.op_viz' (Network Analysis Phase)...
154+
✅ Markdown report saved to: /data2/Repo-Inspector/test/Tensorvis/dynamic/Tensorvis_dynamic_4_file_.._TensorVis_TensorVis_op_viz.py_candidate_1_TensorVis.op_viz.md
155+
📊 Interactive HTML report saved to: /data2/Repo-Inspector/test/Tensorvis/dynamic/Tensorvis_dynamic_4_file_.._TensorVis_TensorVis_op_viz.py_candidate_1_TensorVis.op_viz.html
156+
(Open the HTML file in your browser to see rendered charts)
157+
158+
🔁 Running candidate 2/3: op_viz -> output=./test/Tensorvis/dynamic/Tensorvis_dynamic_4_file_.._TensorVis_TensorVis_op_viz.py_candidate_2_op_viz.md
159+
🔍 Target Resolution: Input='op_viz' -> Import='op_viz' (Type: module)
160+
🔍 Analyzing dependencies for 'op_viz' (Network Analysis Phase)...
161+
✅ Markdown report saved to: /data2/Repo-Inspector/test/Tensorvis/dynamic/Tensorvis_dynamic_4_file_.._TensorVis_TensorVis_op_viz.py_candidate_2_op_viz.md
162+
📊 Interactive HTML report saved to: /data2/Repo-Inspector/test/Tensorvis/dynamic/Tensorvis_dynamic_4_file_.._TensorVis_TensorVis_op_viz.py_candidate_2_op_viz.html
163+
(Open the HTML file in your browser to see rendered charts)
164+
165+
🔁 Running candidate 3/3: /data2/TensorVis/TensorVis/op_viz.py -> output=./test/Tensorvis/dynamic/Tensorvis_dynamic_4_file_.._TensorVis_TensorVis_op_viz.py_candidate_3_op_viz.py.md
166+
🔍 Target Resolution: Input='/data2/TensorVis/TensorVis/op_viz.py' -> Import='op_viz' (Type: file)
167+
🔍 Analyzing dependencies for 'TensorVis.op_viz' (Network Analysis Phase)...
168+
✅ Markdown report saved to: /data2/Repo-Inspector/test/Tensorvis/dynamic/Tensorvis_dynamic_4_file_.._TensorVis_TensorVis_op_viz.py_candidate_3_op_viz.py.md
169+
📊 Interactive HTML report saved to: /data2/Repo-Inspector/test/Tensorvis/dynamic/Tensorvis_dynamic_4_file_.._TensorVis_TensorVis_op_viz.py_candidate_3_op_viz.py.html
170+
(Open the HTML file in your browser to see rendered charts)
171+
🔍 [Dynamic] Merging and deduplicating dynamic reports...
172+
✅ Merged dynamic reports -> test/Tensorvis/dynamic/Tensorvis_merged_dynamic.md (6 files included)
173+
✅ Rendered HTML index -> test/Tensorvis/INDEX.html
174+
✅ Rendered merged dynamic HTML -> test/Tensorvis/dynamic/Tensorvis_merged_dynamic.html
175+
✅ Rendered main static HTML -> test/Tensorvis.html
176+
```
177+
178+
you can check the result in [Test case for Tensorvis repo](./test)
179+
180+
## References
181+
182+
- LibInspector: https://github.com/MaybeBio/LibInspector
183+
184+
## ToDos
185+
186+
- [ ] For LLM support, [DeepWiKi](https://github.com/AsyncFuncAI/deepwiki-open) is also a good choice

‎icon.png‎

5.37 MB
Loading

‎pyproject.toml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
[build-system]
2+
requires = ["setuptools>=61.0"]
3+
build-backend = "setuptools.build_meta"
4+
5+
[project]
6+
name = "repo-inspector"
7+
version = "0.1.0"
8+
description = "An analysis tool to inspect Python project structures from source code."
9+
readme = "README.md"
10+
license = "MIT"
11+
authors = [{name = "Joe Hoye Dow", email = "[email protected]"}]
12+
requires-python = ">=3.8"
13+
dependencies = [
14+
"typer>=0.20.0",
15+
"networkx>=3.6",
16+
]
17+
18+
[project.scripts]
19+
repo-inspector = "src.main:app"
20+
21+
[tool.setuptools.packages.find]
22+
where = ["."]
23+
24+

‎src/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
2+
3+

0 commit comments

Comments
 (0)