Metadata-Version: 2.4
Name: pyproject-lens
Version: 0.4.2
Summary: A small health scanner for Python projects.
Author: Sam
License-Expression: MIT
Project-URL: Homepage, https://github.com/Sam3360/pyproject-lens
Project-URL: Repository, https://github.com/Sam3360/pyproject-lens
Project-URL: Issues, https://github.com/Sam3360/pyproject-lens/issues
Keywords: python,cli,project,pyproject,health
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli; python_version < "3.11"
Dynamic: license-file

# pyproject-lens

A small, free health scanner for Python projects. Point it at a folder and it checks the basics: packaging metadata, imports versus declared dependencies, Python-version claims, project layout, tests, obvious security footguns, documentation, and Git hygiene.

It is built for the first ten seconds of project review — not to replace Ruff, pytest, Bandit, or a human code review.

## Install

```bash
pip install pyproject-lens
```

## Use it

```bash
pyproject-lens .
pyproject-lens ./another-project --json report.json
pyproject-lens . --markdown report.md
pyproject-lens . --html report.html
pyproject-lens . --ci --minimum-score 75
```

You can also use it in Python:

```python
from pyproject_lens import analyze

report = analyze(".")
print(report.score)
print(report.to_json())
```

## What the score means

Each section starts at 100. Detected issues reduce only the relevant section, and the project score is the rounded average. The rules are deliberately simple and visible in `src/pyproject_lens/analyzers.py`; it is a conversation starter, not a grade.

## What it checks

- Packaging: `pyproject.toml`, project name, Python version, README
- Dependencies: direct source imports compared with `project.dependencies`
- Compatibility: detects `match/case` used with a Python claim below 3.10
- Structure: `src/`, packages, root modules, and tests directory
- Testing: test file presence and a rough source-to-test-file signal — not coverage
- Security: possible hard-coded secrets, `eval`/`exec`, and `shell=True`
- Documentation: README, install/usage wording, license, and contribution guide
- Repository hygiene: `.gitignore` and uncommitted changes
- Reports: terminal, JSON, Markdown, and a standalone HTML file

Everything is free and open source under the MIT license.

## Development

```bash
python -m pip install -e .
python -m unittest discover -s tests
```

Contributions are welcome. Please keep checks practical, explain what they found, and avoid claiming certainty when static analysis cannot prove something.
