Metadata-Version: 2.4
Name: analyze-project
Version: 0.1.1
Summary: Static Python codebase walkthrough generator for onboarding developers.
Author: aetsr
License-Expression: MIT
Keywords: analysis,ast,cli,codebase,onboarding,python,static-analysis,walkthrough
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.8
Requires-Dist: networkx>=3.2
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# analyze_project

`analyze-project` helps developers understand unfamiliar Python codebases by generating a step-by-step walkthrough, execution flow, decision tree, data flow summary, and dependency graphs.

It is designed for onboarding into a project without running the target codebase.

## What It Generates

Default runs produce human-readable onboarding reports and the existing technical artifacts:

- `walkthrough.md`: narrative walkthrough for a new developer
- `execution_flow.json`: structured entry point and execution-flow data
- `decision_tree.md`: important `if` / `else` / `try` branches
- `data_flow.md`: simple assignment-to-call data movement
- `project_analysis.json`: machine-readable structural analysis
- `project_analysis.png`: module dependency graph
- `project_call_graph.png`: cross-module call graph when available
- `project_hotspots.png`: most-called functions and methods when available

## Requirements

- Python 3.9+
- Runtime dependencies are installed automatically from package metadata

## Installation

```bash
pip install analyze-project
```

For isolated CLI installs, `pipx` is a good fit:

```bash
pipx install analyze-project
```

For a local checkout:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
```

## Usage

Analyze the current working directory:

```bash
analyze-project .
```

Analyze a specific project:

```bash
analyze-project /path/to/python-project
```

Only generate onboarding reports and skip graph/chart generation:

```bash
analyze-project /path/to/python-project --walkthrough-only
```

Focus on one entry point:

```bash
analyze-project /path/to/python-project --entry app.main::main
```

Only generate the backward-compatible JSON report:

```bash
analyze-project /path/to/python-project --json-only
```

Module execution is also supported:

```bash
python -m analyze_project /path/to/python-project
```

At the end of a normal run, the terminal prints the output directory and direct `walkthrough.md` path, for example:

```text
Output dir  : /repo/analysis_output/my_project
Walkthrough : /repo/analysis_output/my_project/walkthrough.md
```

## CLI

```text
analyze-project [target] [--output-dir PATH] [--depth N | --max-depth N] [--max-branches N] [--max-entry-trees N] [--hotspots N] [--non-recursive] [--include-glob PATTERN] [--exclude-dir NAME] [--entry ENTRYPOINT] [--show-unresolved] [--summary-only | --json-only | --walkthrough-only]
```

- `target`: Directory to analyze. Defaults to the current working directory.
- `--output-dir PATH`: Output directory for generated artifacts. Defaults to `./analysis_output/<project_name>/`.
- `--depth N`, `--max-depth N`: Maximum call tree and walkthrough depth.
- `--max-branches N`: Maximum call-tree branches per node.
- `--max-entry-trees N`: Maximum number of technical entry-point call trees printed.
- `--hotspots N`: Number of most-called callables to include.
- `--non-recursive`: Only analyze Python files in the top-level target directory.
- `--include-glob PATTERN`: Repeatable relative-path glob filter for `.py` files.
- `--exclude-dir NAME`: Repeatable directory name to exclude in addition to the built-in skip list.
- `--entry ENTRYPOINT`: Generate walkthrough details only for a matching entry point.
- `--show-unresolved`: Print unresolved call examples in the terminal summary.
- `--summary-only`: Print the technical terminal summary without writing artifacts.
- `--json-only`: Only write `project_analysis.json`; no walkthrough or Markdown files are written.
- `--walkthrough-only`: Only write `walkthrough.md`, `execution_flow.json`, `decision_tree.md`, and `data_flow.md`.

## Walkthrough Content

`walkthrough.md` includes:

- Project Purpose Guess
- How to Run
- Entry Points ranked by confidence and source
- Execution Walkthrough
- Decision Points
- Data Flow
- Side Effects
- Final Outcome
- Unknowns / Static Analysis Limits

The analyzer ranks entry points in this order:

1. `console_scripts` from package metadata
2. `if __name__ == "__main__"`
3. FastAPI or Flask app objects and route handlers
4. `main()`, `run()`, `start()`
5. `handler()` and `lambda_handler()`

## Static Analysis Limits

The target project is never executed. The analyzer uses Python AST parsing and metadata inspection, so some behavior cannot be known with certainty.

Known limitations:

- Dynamic imports, monkey patching, runtime dependency injection, and reflection may be missed.
- Deep data-flow and alias tracking are intentionally shallow.
- External library behavior is summarized as side effects instead of expanded into the local execution tree.
- Unknown object calls may appear as unresolved even when they are valid at runtime.
- Secrets are redacted from output, but avoid analyzing real `.env` files if you do not want their variable names listed.

## Security And Secrets

Values that look like tokens, passwords, API keys, credentials, or secrets are masked in generated reports.

Example:

```text
TELEGRAM_BOT_TOKEN=***
```

## Development

Install development dependencies and run checks:

```bash
pip install -e .[dev]
python -m py_compile analyze_project.py tests/test_cli.py
ruff check .
pytest
rm -rf dist build *.egg-info
python -m build
python -m twine check dist/*
```

## Publishing

Before publishing a new version to PyPI, bump `version` in `pyproject.toml`, clean old build artifacts, build, and upload:

```bash
rm -rf dist build *.egg-info
python -m build
python -m twine check dist/*
python -m twine upload dist/*
```

`0.1.0` cannot be uploaded again once published; use a new version such as `0.1.1`.

## License

MIT. See [`LICENSE`](LICENSE).
