Skip to content

Commit c9cdcf0

Browse files
Raghava00001Raghava00001
committed
v1.0.0: Public release — dashboard, impact analysis, architecture, deployment packaging
0 parents  commit c9cdcf0

78 files changed

Lines changed: 13695 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.env.example‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
DATABASE_URL="postgresql://repo_doctor:repo_doctor@localhost:5432/repo_doctor?schema=public"
2+
REDIS_URL="redis://localhost:6379"
3+
JWT_SECRET="replace-with-a-long-random-secret"
4+
OPENAI_API_KEY=""
5+
GITHUB_APP_ID=""
6+
GITHUB_APP_PRIVATE_KEY=""
7+
GITHUB_WEBHOOK_SECRET=""
8+
GITHUB_TOKEN=""
9+
LOG_LEVEL="info"
10+
API_PORT="4000"
11+
WEB_ORIGIN="http://localhost:5173"
12+
VITE_API_URL="http://localhost:4000"

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
name: Bug Report
3+
about: Report a bug or unexpected behavior in Repo Doctor
4+
title: "[BUG] "
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
## Describe the Bug
10+
A clear and concise description of what the bug is.
11+
12+
## Steps to Reproduce
13+
1. Go to '...'
14+
2. Click on '...'
15+
3. Scroll down to '...'
16+
4. See error
17+
18+
## Expected Behavior
19+
What you expected to happen.
20+
21+
## Actual Behavior
22+
What actually happened.
23+
24+
## Screenshots
25+
If applicable, add screenshots to help explain the problem.
26+
27+
## Environment
28+
- **OS**: [e.g. Windows 11, macOS 15, Ubuntu 24.04]
29+
- **Browser**: [e.g. Chrome 126, Firefox 128]
30+
- **Node.js version**: [e.g. 20.19]
31+
- **Docker version** (if applicable): [e.g. 27.0]
32+
33+
## Console Errors
34+
Paste any browser console or server terminal errors here:
35+
```
36+
(paste errors)
37+
```
38+
39+
## Additional Context
40+
Add any other context about the problem here.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
name: Feature Request
3+
about: Suggest a new feature or improvement for Repo Doctor
4+
title: "[FEATURE] "
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
## Problem Statement
10+
What problem does this feature solve? Describe the pain point clearly.
11+
12+
## Proposed Solution
13+
A clear description of what you want to happen.
14+
15+
## Alternatives Considered
16+
Any alternative solutions or features you've considered.
17+
18+
## Use Case
19+
Describe a specific scenario where this feature would be useful:
20+
1. As a [type of user]...
21+
2. I want to [action]...
22+
3. So that [outcome]...
23+
24+
## Priority
25+
How important is this to your workflow?
26+
- [ ] Critical — blocks my use of the product
27+
- [ ] High — significant improvement to daily use
28+
- [ ] Medium — nice to have
29+
- [ ] Low — minor convenience
30+
31+
## Additional Context
32+
Add any mockups, screenshots, or references here.

‎.github/workflows/ci.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
jobs:
9+
validate:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-node@v4
14+
with:
15+
node-version: 20
16+
cache: npm
17+
- run: npm ci
18+
- run: npm run typecheck
19+
- run: npm run build
20+

‎.gitignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
node_modules/
2+
dist/
3+
coverage/
4+
.env
5+
.env.local
6+
.DS_Store
7+
*.log
8+
*.err
9+
.npm-cache/
10+
.tools/
11+
apps/api/prisma/migrations/
12+
apps/web/.vite/
13+
14+

‎CHANGELOG.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Changelog
2+
3+
All notable changes to the **Repo Doctor** project are documented here. Repo Doctor adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
4+
5+
---
6+
7+
## [1.0.0] - 2026-06-08
8+
9+
### 🚀 Public Release & Deployment Ready
10+
11+
Repo Doctor is now feature-complete, hardened, and ready for public v1.0 release on GitHub! This version transforms unfamiliar monorepos into actionable developer onboarding playbooks in minutes.
12+
13+
#### 🩺 Problem Statement Solved
14+
* Resolves developer cognitive overload when entering new repositories.
15+
* Answers **"Where do I start reading?"**, **"What will break if I edit this file?"**, and **"How does the request flow work?"** without requiring heavy force-directed graph diagrams.
16+
17+
---
18+
19+
### ✨ Feature Set
20+
21+
#### 1. Action-First Onboarding Dashboard
22+
* **Metrics panel**: Instantly monitors computed **Technical Debt Score**, number of **Fragile Modules**, and codebase **Stack Confidence**.
23+
* **Read-First Actions**: A sequenced reading checklist telling new developers exactly *why* each file is critical.
24+
* **Fix-First Actions**: Highlight checklist mapping highest-debt, volatile modules that require immediate refactoring.
25+
26+
#### 2. Interactive Codebase Maps (`WorkspaceTrees`)
27+
* Located prominently below URL ingestion, presenting three navigable views:
28+
* **Repository Directory**: Recursive directory folder tree highlighting entry points (star icon) and package manifests (pkg tag).
29+
* **Domain Modules**: Interactive cards grouping files by domain responsibility and outlining their structural purpose.
30+
* **Dependency Paths**: Inbound imports and outbound dependents lists calculated heuristically.
31+
* **Click-to-Audit link**: Click any node to focus-glow highlight that file and slide open the Impact Analysis panel.
32+
33+
#### 3. Transitive Impact Analysis
34+
* Calculates direct caller networks, transitive impact radius, and breakage risk score (0-100).
35+
* Maps nearby unit tests and generates a plain-English summary explaining what changes when a file is modified.
36+
37+
#### 4. Senior Engineer Explanation Mode
38+
* Synthesizes repository summary and request-data flow steps from endpoints to storage.
39+
* Identifies complex configuration, tooling, and boilerplate directories that new contributors can safely ignore at first.
40+
41+
#### 5. Guided Onboarding Tour & Guide Panels
42+
* **5-step Guided Stepper**: Modal overlay tour for new users explaining dashboard inputs, trees, actions list, and architecture views. State is saved to `localStorage` to avoid disrupting returning users.
43+
* **"How to Read" Guide Banner**: Dismissible grid panel summarizing metrics scan steps.
44+
45+
---
46+
47+
### 🛡️ Reliability & Resilience
48+
49+
* **Multi-Provider AI Client**: Resolves API requests by checking for `GEMINI_API_KEY` (Gemini 2.5 Flash), falling back to `OPENAI_API_KEY` (GPT-4o-Mini), and falling back to a deterministic markdown report template if offline.
50+
* **Octokit Rate-Limit Resilience**: Ingestion scanner tracks GitHub API rate-limit headers and triggers automatic backoffs before retrying large codebases.
51+
* **Redis Cache Fallback**: If Redis cache is offline, indexers gracefully fall back to in-memory maps, avoiding application crashes.
52+
* **Database optional Demo Mode**: Web dashboard boots instantly into Demo Mode utilizing 3 built-in indexed workspaces (TypeScript Payments, Rust Ledger, Python FastAPI) without local PostgreSQL or Redis database setup.
53+
54+
---
55+
56+
### 📦 Production Deployment Packaging
57+
58+
* **Backend Dockerfile** (`apps/api/Dockerfile`): Multi-stage node Alpine builder compiling TypeScript, running migrations, and caching Prisma client binaries.
59+
* **Frontend Dockerfile** (`apps/web/Dockerfile`): Builds Vite static production bundles and mounts them into a lightweight Alpine Nginx server.
60+
* **Nginx Configuration** (`apps/web/nginx.conf`): SPA routing rules and optimized cache-control headers.
61+
* **Production Orchestration** (`docker-compose.prod.yml`): Spin up Postgres database, Redis cache, API container, and Web Nginx server in a single launch command.

‎CONTRIBUTING.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Contributing to Repo Doctor
2+
3+
Thank you for your interest in contributing to Repo Doctor! This document outlines the process for contributing to this project.
4+
5+
---
6+
7+
## Development Setup
8+
9+
### Prerequisites
10+
- Node.js ≥ 20.11
11+
- Docker & Docker Compose (for PostgreSQL and Redis)
12+
- npm (ships with Node.js)
13+
14+
### Local Environment
15+
```bash
16+
# Clone the repository
17+
git clone https://github.com/your-org/repo-doctor.git
18+
cd repo-doctor
19+
20+
# Start databases
21+
docker compose up -d
22+
23+
# Install dependencies
24+
npm install
25+
26+
# Generate Prisma client
27+
npm run db:generate
28+
29+
# Run migrations
30+
npm run db:migrate
31+
32+
# Start dev servers (API + Web concurrently)
33+
npm run dev
34+
```
35+
36+
The frontend runs at `http://localhost:5173` and the API at `http://localhost:4000`.
37+
38+
---
39+
40+
## Branch Naming
41+
42+
Use descriptive branch names with a category prefix:
43+
44+
| Prefix | Purpose |
45+
|--------|---------|
46+
| `fix/` | Bug fixes |
47+
| `docs/` | Documentation changes |
48+
| `refactor/` | Code cleanup without behavior change |
49+
| `chore/` | Tooling, CI, dependency updates |
50+
| `test/` | Adding or improving tests |
51+
52+
Example: `fix/redis-cache-fallback-timeout`
53+
54+
---
55+
56+
## Pull Request Checklist
57+
58+
Before submitting a PR, verify:
59+
60+
- [ ] All tests pass: `npm test`
61+
- [ ] TypeScript compiles: `npm run build`
62+
- [ ] No new lint warnings
63+
- [ ] Changes are documented if user-facing
64+
- [ ] Commit messages are clear and descriptive
65+
- [ ] Screenshots included for any UI changes
66+
67+
---
68+
69+
## Code Standards
70+
71+
- **TypeScript**: Strict mode enabled. No `any` types unless wrapped with explicit casts and documented.
72+
- **Styling**: Vanilla CSS in `styles.css`. Dark-mode-first. No Tailwind.
73+
- **Components**: React functional components with hooks. No class components.
74+
- **Testing**: Vitest for unit and integration tests. Tests live alongside source files (`*.test.ts`).
75+
- **Architecture rule**: Deterministic analysis is the source of truth. AI is used only for explanation, never for scoring or risk calculation.
76+
77+
---
78+
79+
## Reporting Issues
80+
81+
- **Bugs**: Use the [Bug Report](/.github/ISSUE_TEMPLATE/bug_report.md) template.
82+
- **Features**: Use the [Feature Request](/.github/ISSUE_TEMPLATE/feature_request.md) template.
83+
84+
---
85+
86+
## Code of Conduct
87+
88+
Be respectful, constructive, and inclusive. We follow the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) code of conduct.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Repo Doctor Contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)