RepoPulse-Public/README.md

RepoPulse

Explain repository health, maintenance risk and release readiness from local, deterministic evidence.

RepoPulse is a self-hosted Gitea repository intelligence dashboard. It scans exact revisions, keeps findings and history, and helps prioritize the next maintenance action. Source code is analyzed locally without sending it to an external model.

flowchart LR
  A[Gitea catalog / local path] --> B[Exact revision acquisition]
  B --> C[Bounded deterministic scan]
  C --> D[Findings and explainable scores]
  D --> E[Portfolio / remediation / history]

Capabilities

• Read-only Gitea repository discovery, default-branch reconciliation and optional signed push webhooks.
• Durable SQLite job queue, revision deduplication, lease recovery and detached scan worktrees.
• Repository portfolio, triage, quick switch, architecture, hotspots, findings and history views.
• Language/LOC inventory, test/CI signals, dependency and lockfile analysis across common ecosystems.
• TODO debt, bounded churn, local import graphs and explainable hotspot ranking.
• Redacted credential-assignment warnings and backend-owned remediation guidance.
• Transparent scan budgets and truncation metadata instead of overstating scan coverage.
• Accepted-risk policies, release gates, finding deltas and standalone HTML/JSON reports.

Interface preview

These screenshots show the deterministic browser-test fixture: fictional Alpha/Beta/Gamma repositories, not a private or live repository inventory.

Deploy

git clone https://gitea.itworx.tech/Jens/RepoPulse-Public.git
cd RepoPulse-Public
cp .env.example .env
# Select the intended repository directory and configure your Gitea connector.
docker compose up --build

Open http://localhost:1254. Compose runs a Python API and React frontend. REPOPULSE_SOURCE_ROOT defaults to the parent directory and is mounted read-only at /scan; narrow it to the repository collection you intend to inspect. The Advanced path flow accepts paths inside that boundary.

REPOPULSE_DATA_ROOT=./data in the local template retains SQLite history, queue and repository mirrors. If unset, Compose uses the named repopulse_data volume. Keep persisted data outside a replaceable checkout and back it up before upgrades. The durable queue intentionally runs one active scan worker.

Connect Gitea

Configure these values on the server, never in the frontend:

REPOPULSE_GITEA_URL=https://gitea.example.test
REPOPULSE_GITEA_TOKEN=<repository-read-token>
REPOPULSE_OPERATOR_TOKEN=<independent-operator-token>

Use only the repository-read permissions needed for the intended catalog and revisions. An optional REPOPULSE_GITEA_WEBHOOK_SECRET authenticates push notifications. RepoPulse discovers repositories, resolves revisions, queues stale work, scans exact SHAs and retains results by revision. Incomplete or failed discovery preserves existing evidence rather than silently declaring missing repositories unavailable.

Protect deployment with an authenticated proxy or configure REPOPULSE_OPERATOR_TOKEN; the mutation API uses X-RepoPulse-Token. Limit network access and the scan mount. Direct development without REPOPULSE_SCAN_ROOT can read any path accessible to that process.

Interpret results

Findings are deterministic observations with locations and severity. Health scores reflect documented deductions; release gates report READY, READY WITH WARNINGS or BLOCKED under repository policy. Remediation guidance explains confidence, priority and a suggested first action. RepoPulse never edits external repositories automatically.

Heuristics are engineering guidance, not a substitute for review, runtime tests or specialized security audits. Truncated scans expose their limits. Credential warnings redact values but still require human investigation. Repository history and retained reports contain source-derived metadata, so treat the persisted store as sensitive.

Development

python -m venv .venv
# Activate .venv for your shell.
pip install -r requirements.txt
uvicorn app.main:app --app-dir backend --reload --port 8000

In another terminal:

npm --prefix frontend ci
npm --prefix frontend run dev

Run python -m pytest, npm --prefix frontend test, npm --prefix frontend run typecheck and npm --prefix frontend run build. The browser test fixture uses deterministic API responses; it is not a live production portfolio. See architecture for implementation detail.

Source distribution and licensing

This is the curated public source edition of RepoPulse 1.5.0. Reviewed updates flow from the private canonical repository after merges to main, without private history, repository inventories, runtime stores or internal CI/deployment workflows. Configure the generic deployment templates for your own environment.

No project-wide license is included. Public visibility does not grant reuse or redistribution rights; obtain the owner's terms and review third-party dependencies before redistribution.