Metadata-Version: 2.5
Name: repolens-core
Version: 0.1.0
Summary: Explainable repository best-practice scanner
Author: RepoLens contributors
License: MIT License
        
        Copyright (c) 2026 RepoLens contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: typer<1.0,>=0.16
Description-Content-Type: text/markdown

# RepoLens Core

RepoLens inspects a local repository and produces a deterministic, explainable
best-practice report. It reads files only; it never imports or executes code
from the repository and never accesses GitHub.

## Installation

```bash
pip install repolens-core
```

For development, install the project with its development dependencies using
your preferred PEP 517 workflow.

## Usage

```bash
repolens scan ./my-project
repolens scan ./my-project --output json
repolens scan ./my-project --output markdown --fail-below 70
```

The score is weighted across applicable rules. Each result includes a status,
evidence, and actionable guidance. JSON output is versioned by
`schema_version` and is stable for identical input.

The same scanner is available from Python:

```python
from pathlib import Path
from repolens.api import scan_repository
from repolens.reporting.json import render_json

report = scan_repository(Path("."))
print(report.score.value)
print(render_json(report))
```

Example terminal output:

```text
RepoLens: 52/100 (python)
[pass] README: README.md has meaningful content.
[fail] .gitignore: .gitignore was not detected.
```

## Configuration

An optional `repolens.toml` can customize safe directory exclusions, the source
file size threshold, and the default CI threshold:

```toml
[scanner]
max_source_file_lines = 500
excluded_directories = [".git", ".venv", "node_modules", "vendor"]
fail_below = 70
```

The scanner skips `.git`, binary files, inaccessible files, and symbolic links.
It reports relative evidence paths and does not modify the analyzed repository.

## Architecture

The package is split into immutable domain models, safe repository discovery,
an explicit rule registry, application orchestration, and terminal/JSON/Markdown
renderers. Architectural decisions are documented in [`docs/adr`](docs/adr).

## Limitations and next steps

Detection is intentionally conservative and marker-based; it does not parse
every build system or prove that a configuration is correct. Future work can
add language-specific rules, richer diagnostics, and additional report formats.
