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

pip install repolens-core

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

Usage

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:

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:

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:

[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.

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.