Metadata-Version: 2.5
Name: project-mapper
Version: 0.1.1
Summary: Understand what a Python file depends on — without running the code.
Project-URL: Homepage, https://github.com/Yashjindal11/projectmap
Project-URL: Repository, https://github.com/Yashjindal11/projectmap
Project-URL: Issues, https://github.com/Yashjindal11/projectmap/issues
Author: Yash Jindal
License: MIT
License-File: LICENSE
Keywords: ast,dependencies,dependency-graph,imports,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# project-mapper

**Understand what a Python file depends on — without running the code.**

`project-mapper` is a static analysis tool for Python. Point it at an entry-point
file and it maps every local file that entry point reaches, classifies its
imports, detects environment-variable *names*, and produces a polished,
self-contained HTML report.

It never executes the code it analyzes. It makes no network calls. It sends no
telemetry. Everything runs locally.

```bash
project-mapper main.py
```

```text
Project Mapper

Analyzing
  /Users/yash/projects/example/main.py

Scanning dependencies...

✓ Entry point parsed
✓ 8 Python files analyzed
✓ 13 local dependencies found
✓ 5 third-party imports found
✓ 11 standard-library imports found
✓ 4 environment variables found

Generating HTML report...

✓ Report generated
  ./project-mapper-report.html
```

## How it works

```text
Entry point
    ↓
AST analysis          (Python's ast module — never executed)
    ↓
Local dependency resolution
    ↓
Recursive traversal
    ↓
HTML report
```

## Installation

```bash
pip install project-mapper
```

Or from source:

```bash
git clone https://github.com/Yashjindal11/projectmap
cd projectmap
pip install -e ".[dev]"
```

Requires **Python 3.10+**.

> **Naming:** the PyPI distribution and CLI command are both **`project-mapper`**,
> and the Python import package is **`project_map`**.

## Usage

### CLI

```bash
project-mapper main.py                      # writes ./project-mapper-report.html
project-mapper ./main.py --output map.html  # custom output
project-mapper main.py -o map.html --open   # open in default browser
project-mapper main.py --verbose            # extra diagnostics
project-mapper --help
```

### Python API

```python
from project_map import analyze
from project_map.report import generate_html

result = analyze("main.py")
generate_html(result, "project-mapper-report.html")

print(result.third_party_imports)     # ['pandas', 'requests']
print(result.environment_variables)   # ['API_KEY', 'DATABASE_URL']
```

## Example

Given:

```text
my-project/
├── main.py
├── config.py
├── services/
│   └── customer.py
└── utils/
    └── helpers.py
```

```bash
project-mapper main.py
```

The report shows the dependency structure:

```text
main.py
├── config.py
└── services/customer.py
    └── utils/helpers.py
```

plus:

```text
Third Party
    requests

Standard Library
    os
    logging

Environment Variables
    API_KEY
```

## Features

- **Static Python analysis** — parses the AST; never runs your code.
- **Recursive local dependency mapping** — follows reachable local imports.
- **Import classification** — local, standard library, third-party, unresolved.
- **Environment-variable detection** — reports *names* only, never values.
- **Standalone HTML report** — inline CSS/SVG, works offline via `file://`.
- **CLI and Python API.**
- **No code execution. No network. No telemetry.**

## Privacy & safety

- The analyzed code is treated as **untrusted input** and is never imported,
  executed, or evaluated (no `eval`, no `exec`, no subprocesses).
- `.env` files are **never** read. Only environment-variable *names* that
  appear literally in the source are reported — never their values.
- No network requests are made by the analyzer.

## Limitations

Static analysis cannot perfectly resolve every import. In particular:

- Dynamic imports such as `importlib.import_module(name)` or
  `__import__(name)` cannot be followed.
- Third-party import names are not guaranteed PyPI package names — for example,
  `import cv2` corresponds to the PyPI package `opencv-python`. They are
  labelled as *third-party imports*, not package names.
- V1 targets common, predictable project layouts. Exotic import machinery,
  namespace packages, and sys.path manipulation may not resolve.

Where resolution is uncertain, the import is reported honestly as
**Unresolved** rather than guessed.

## License

MIT — see [LICENSE](LICENSE).
