devdoctor-cli 0.1.0__py3-none-any.whl

devdoctor_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,382 @@
+Metadata-Version: 2.4
+Name: devdoctor-cli
+Version: 0.1.0
+Summary: Deterministic developer machine and project diagnostic doctor.
+Author: Souran Jash
+License-Expression: MIT
+Keywords: developer-tools,diagnostics,cli,linting,debugging,environment
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0.0
+Requires-Dist: packaging>=21.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# DevDoctor 🩺
+
+> **Deterministic developer machine & project diagnostic doctor.**  
+> *Scan your machine/project → Run diagnostic checks → Identify problems → Explain WHY → Give a safe FIX → Generate reports.*
+
+DevDoctor is a CLI-first, deterministic Python tool that inspects your development environment, detects misconfigurations, explains the root cause with evidence, and provides safe, actionable remediations. **No AI chatbot guesswork, no hallucinations—purely deterministic diagnostics.**
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Install via pip
+pip install devdoctor
+
+# Or install locally in editable mode
+git clone https://github.com/your-org/devdoctor.git
+cd devdoctor
+pip install -e .
+```
+
+### Run DevDoctor
+
+```bash
+# Scan current directory / project
+devdoctor
+
+# Or explicitly
+devdoctor scan
+```
+
+---
+
+## 📺 Example Output
+
+```text
+$ devdoctor scan
+
+DevDoctor 0.1.0
+Project: Django + PostgreSQL + Docker
+────────────────────────────
+
+✓ Python 3.12.10
+✓ pip 25.0.1
+✓ Git 2.55.0
+
+❌ Virtual environment
+   Current shell is not using a virtual environment.
+
+   Active interpreter is global: C:\Program Files\Python312\python.exe
+
+   Fix:
+   Windows:
+     .venv\Scripts\activate
+
+⚠ Port 8000
+   Port is already occupied.
+
+   Process: python.exe
+   PID: 18420
+
+   Fix:
+     devdoctor port free 8000
+
+❌ Environment variable
+   DATABASE_URL is required but missing.
+
+   Found in:
+     settings.py (line 24)
+
+   Fix:
+     Add DATABASE_URL to .env
+
+Score: 72/100
+
+3 problems found.
+```
+
+---
+
+## 🧠 Diagnostic Structure
+
+Every single DevDoctor diagnostic follows a strict, high-signal structure:
+
+```text
+PROBLEM
+    ↓
+WHY IT HAPPENED
+    ↓
+EVIDENCE
+    ↓
+SAFE FIX
+    ↓
+COMMAND
+```
+
+Run with `--verbose` to view the comprehensive breakdown:
+
+```text
+$ devdoctor scan --verbose
+
+❌ Pydantic installation problem
+
+PROBLEM:
+Incompatible version of pydantic-core installed for Python runtime.
+
+WHY:
+Your Python version is 3.13 and requires a compatible wheel.
+
+EVIDENCE:
+pydantic-core does not have a compatible wheel for your current environment.
+
+SAFE FIX:
+Use Python 3.12 for this project.
+
+COMMAND:
+py -3.12 -m venv .venv
+
+Confidence: HIGH
+```
+
+---
+
+## 🛠️ The First 10 Diagnostic Checks
+
+| # | Check | Description |
+|---|---|---|
+| **1** | **Python Version** | Validates active interpreter against `pyproject.toml` (`requires-python`), `.python-version`, or `runtime.txt`. |
+| **2** | **pip Availability** | Validates pip installation, version, and bootstrap status. |
+| **3** | **Virtual Environment** | Confirms whether shell is operating inside an active venv; provides exact platform activation command. |
+| **4** | **Git Availability** | Verifies Git CLI is installed and in PATH. |
+| **5** | **Git Configuration** | Checks `user.name` and `user.email`; audits `.gitignore` to ensure `.env` and sensitive files are not committed. |
+| **6** | **Required Environment Variables** | Uses Python AST to detect unfulfilled `os.environ[...]` lookups without defaults. |
+| **7** | **.env vs .env.example** | Diffs template keys against your `.env` to prevent runtime configuration crashes. |
+| **8** | **Port Conflicts** | Scans web dev ports (8000, 3000, 5000, 5173, etc.); maps occupied ports to process name & PID. |
+| **9** | **Broken Python Imports** | Scans Python code using AST and flags uninstalled third-party packages in site-packages. |
+| **10** | **Dependency Conflicts** | Runs deterministic graph checks and `pip check` to detect version conflicts (e.g., `fastapi` vs `pydantic<3`). |
+
+---
+
+## 🔍 Project Understanding (Phase 3)
+
+DevDoctor inspects your repository and automatically determines its stack without requiring AI:
+
+- Detects `manage.py` → **Django**
+- Detects `fastapi` in dependencies or code → **FastAPI**
+- Detects `flask` in dependencies or code → **Flask**
+- Detects `Dockerfile` / `docker-compose.yml` → **Docker**
+- Detects PostgreSQL connection strings / psycopg → **PostgreSQL**
+- Detects Redis configuration / compose service → **Redis**
+- Detects `package.json` → **Node.js**
+
+```bash
+$ devdoctor project
+
+Project Profile: my-web-app
+──────────────────────────────────────────
+Detected Type:      Django
+Stack Summary:      Django + PostgreSQL + Redis + Docker
+Technologies:       Python, Django, PostgreSQL, Redis, Docker
+Frameworks:         Django
+Config Files:       pyproject.toml, docker-compose.yml, .env
+Dependencies:       24 declared
+```
+
+---
+
+## ⚡ Framework-Specific Diagnostics (Phase 4)
+
+DevDoctor includes dedicated diagnostic suites for major frameworks:
+
+```bash
+# Django diagnostics: DEBUG mode, insecure SECRET_KEY, empty ALLOWED_HOSTS, unapplied migrations
+devdoctor django
+
+# FastAPI diagnostics: Uvicorn status, default port 8000, reload flag, CORS wildcard check
+devdoctor fastapi
+
+# Docker diagnostics: daemon accessibility, exited container error codes, compose port collisions
+devdoctor docker
+
+# PostgreSQL diagnostics: port 5432 status, connection string format
+devdoctor postgres
+
+# Redis diagnostics: port 6379 status, RESP PING response test
+devdoctor redis
+```
+
+---
+
+## 🧰 The Killer Feature: `devdoctor fix` (Phase 5)
+
+Never blindly modify a developer's machine. DevDoctor clearly separates **Safe automatic fixes** from **Action-required fixes**.
+
+### Interactive Fix Prompt
+
+```bash
+$ devdoctor fix
+
+Found 3 problem(s) with available fixes:
+
+ 1. [SAFE] Add .env to .gitignore
+    Command: echo .env >> .gitignore
+ 2. [SAFE] Copy .env.example to .env
+    Command: copy .env.example .env
+ 3. [ACTION] Kill process python.exe (PID: 18420) on port 8000
+    Command: devdoctor port free 8000
+
+Apply fixes? [Y/n]: Y
+
+Applying fixes...
+
+✓ Fixed: Add .env to .gitignore
+✓ Fixed: Copy .env.example to .env
+✓ Fixed: Kill process python.exe (PID: 18420) on port 8000
+
+Completed: 3 applied, 0 failed.
+```
+
+### Safe-Only Automation (CI / Scripts)
+
+Apply only safe, non-destructive fixes without touching running processes or external installations:
+
+```bash
+devdoctor fix --safe
+```
+
+### Dry Run
+
+Preview all proposed remediations without executing anything:
+
+```bash
+devdoctor fix --dry-run
+```
+
+### Standalone Port Free Utility
+
+Easily free up an occupied port with PID and process name resolution:
+
+```bash
+devdoctor port free 8000 --yes
+```
+
+---
+
+## 🔌 Extensible Plugin Engine (Phase 6)
+
+DevDoctor can be extended with custom checks via the `@check` decorator or Python entry points (`devdoctor.checks`).
+
+### Writing a Custom Check
+
+Create a Python file in your project under `.devdoctor/checks/my_check.py` or inside an installable package:
+
+```python
+from devdoctor import check, Diagnostic, ScanContext, Severity
+
+@check(name="internal_api", title="Internal API Gateway", category="network")
+def check_internal_api(context: ScanContext) -> Diagnostic | None:
+    api_url = context.env_vars.get("INTERNAL_API_URL")
+    if not api_url:
+        return Diagnostic(
+            title="Internal API Gateway",
+            severity=Severity.ERROR,
+            message="INTERNAL_API_URL is missing in environment.",
+            why="Microservices require INTERNAL_API_URL to reach the auth cluster.",
+            fix="Add INTERNAL_API_URL=https://api.internal to .env",
+            command="echo INTERNAL_API_URL=https://api.internal >> .env",
+        )
+    return Diagnostic(
+        title="Internal API Gateway",
+        severity=Severity.OK,
+        message=f"Configured: {api_url}",
+    )
+```
+
+DevDoctor will automatically discover and execute your custom check!
+
+---
+
+## 🐍 Python API
+
+Integrate DevDoctor diagnostics directly into your Python scripts, pytest test suites, or tooling:
+
+```python
+from devdoctor import DevDoctor
+
+doctor = DevDoctor(project_path=".")
+
+# Run scan
+report = doctor.scan()
+
+print(f"Health Score: {report.score}/100")
+print(f"Total Problems: {report.total_problems}")
+
+for problem in report.problems:
+    print(f"[{problem.severity.value}] {problem.title}: {problem.message}")
+
+# Apply safe fixes automatically
+if not report.is_healthy:
+    doctor.fix(safe_only=True)
+```
+
+---
+
+## 🤖 CI/CD Integration & Reporting
+
+Export machine-readable JSON or GitHub-flavored Markdown for CI/CD checks:
+
+```bash
+# Output JSON for pipeline evaluation
+devdoctor scan --json
+
+# Fail build if errors or warnings exist
+devdoctor scan --strict
+
+# Export Markdown report for PR comment
+devdoctor report --format markdown -o report.md
+```
+
+---
+
+## 📋 CLI Reference
+
+```text
+devdoctor [scan] [PATH]           Scan machine and project (default command)
+  --json                          Output report in JSON format
+  --markdown                      Output report in Markdown format
+  -v, --verbose                   Show detailed WHY/EVIDENCE/FIX/COMMAND breakdown
+  -o, --output FILE               Save report to file
+  --strict                        Exit with code 1 on warnings or errors
+  --checks-dir DIR                Load custom check plugins from directory
+
+devdoctor fix [PATH]              Apply fixes for identified issues
+  --safe                          Apply only safe non-destructive fixes
+  --dry-run                       Show planned fixes without applying changes
+  -y, --yes                       Confirm all fixes non-interactively
+
+devdoctor dependencies [PATH]     Check dependency conflicts and broken imports
+devdoctor port free <PORT> [-y]   Kill process listening on specified port
+devdoctor project [PATH]          Inspect detected project profile and tech stack
+devdoctor report [PATH]           Export diagnostic report (terminal/markdown/json)
+devdoctor django [PATH]           Run Django-specific diagnostics
+devdoctor fastapi [PATH]          Run FastAPI-specific diagnostics
+devdoctor docker [PATH]           Run Docker-specific diagnostics
+devdoctor postgres [PATH]         Run PostgreSQL-specific diagnostics
+devdoctor redis [PATH]            Run Redis-specific diagnostics
+```
+
+---
+
+## 📄 License
+
+MIT License. See [LICENSE](LICENSE) for details.

devdoctor_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+devdoctor/__init__.py,sha256=xbnqWvtUw864v7Fz1sJ5NxHrSOuQ4F7Id4yk3ZhSZmo,906
+devdoctor/__main__.py,sha256=aOaylG-TuVvKY6OArZhYUA1eTJds2fDLhbQROrkisgc,156
+devdoctor/api.py,sha256=0swi86ZahcO9CtaizW6xqU-wBIFeAdDDVru4PS3IieU,2908
+devdoctor/cli.py,sha256=5Ru-cJbg81kKmnmuRBmn-ufsqxVRZDJ2VcFTIJcUY-s,13096
+devdoctor/fixer.py,sha256=vOD774wM8lvgCRWHvW34T6oYh2FzZess5YhatLnAdYw,5994
+devdoctor/models.py,sha256=Xq3PRO5tCrMA0QS_M3rsmhXQG9Hu1yTbpSfhToADGwE,8700
+devdoctor/plugin.py,sha256=ythkIu1rSjDqHxnuZWnSvjhlUdosVJ_9kDmgNqfsn0U,3117
+devdoctor/project.py,sha256=l3G6Es7M-9n9Ea04PoOqmlNvH1MqJn3-1LA5l4Unyj4,7279
+devdoctor/reporter.py,sha256=5DmMdHJpa1Og9lK3xP5sDt13VGO3Pf-oRn-U9HBX8pU,7842
+devdoctor/scanner.py,sha256=H6HpBIHUSCKKgzPZujJIz-QgZ3H-KbxKZ7WuL4TvJ9w,4214
+devdoctor/checks/__init__.py,sha256=6SlkF4OkwNd3zX2DRyTDjqwBl7anfVvn2oWyaD5srQU,1286
+devdoctor/checks/base.py,sha256=lsCSGxMWLU4Iv4yRRXIoHsQdof1kGNqk1DYMV12YF48,2299
+devdoctor/checks/dependencies.py,sha256=BcLkHGq7rJt90rrJVGavUzqTxk7Qg7RcBYeGJtNMfpE,6036
+devdoctor/checks/django.py,sha256=gcAoBliTjE7shWMKolOeBQJMTljx7i5eUcPydmMUgzQ,6159
+devdoctor/checks/docker.py,sha256=27ZH3fSCLfDllPr42y-sjWCao-cspXN5jrLxEJRbvbw,5771
+devdoctor/checks/environment.py,sha256=o8pmKDL-6yWK-EwPNNrgURugWA40GjuEOP9DgVs2-J8,6517
+devdoctor/checks/fastapi.py,sha256=QPNCFNjTxlxkcGsltij6y0q5KGrlobClK7gINHXkh80,4164
+devdoctor/checks/filesystem.py,sha256=fPN0OnrttySMJ4dth8noSV35emFTlSqObV1vqTKjHvU,3043
+devdoctor/checks/git.py,sha256=tjPcCzB1SDmCRHyawP2Qy5uE_W6ia8DmY2CCwVB0EVU,7132
+devdoctor/checks/imports.py,sha256=jHfbRUsrUHq6tW4nq-oDbP2jgaBmUx5EG0qUqHcwDJs,1924
+devdoctor/checks/pip.py,sha256=cYQf_r59q7Dkw59TZVmh1jas4CProww_o8Q9u98PDLE,2755
+devdoctor/checks/ports.py,sha256=wA1Wxe0DMzFlUqlPkYxhXVJ_KogDyNXjvFWIl5ZTtIQ,3564
+devdoctor/checks/postgres.py,sha256=4LGofF9c9V4le8bTy4CvOeVdOsPNT_KnKGJ9lyNAjJo,2866
+devdoctor/checks/python.py,sha256=qcc8Uc6QzR8UHNRSB0XeqxHmN76MgOBfneZVuVK1PoE,4455
+devdoctor/checks/redis.py,sha256=e7d1M4ora7Iv1g2uEdhSxYKQKUV26EdfHkFm2RmooHg,2637
+devdoctor/checks/virtualenv.py,sha256=6RFFfpKoAPH4Dvjtwijz_xXaakN-TkFVfQeimfWs8Qw,2954
+devdoctor/utils/__init__.py,sha256=YrU3Mr0p9k7VUbTHPqCbtsR-aQnbUY3_mB6N6McnHGI,37
+devdoctor/utils/ast_imports.py,sha256=2xNBiiSpsGi9_IxnuN1ldlKXk05fPokLM5lxTSxUjAk,7703
+devdoctor/utils/env_parser.py,sha256=ujZs7NbmiJdho0M9tjlaM4HjFBr7GUg2X0e3A4gbbkI,1967
+devdoctor/utils/platform_info.py,sha256=FDmhRhMQV3I5CsQ_HqwrXmF41JPWGPji98d_li_rx0M,2525
+devdoctor/utils/process_utils.py,sha256=cOTFkeVdNqO0iIDDsqhlMy-qaLYUo6BcThP9zmV0w_E,5680
+devdoctor_cli-0.1.0.dist-info/licenses/LICENSE,sha256=aUnJ2ckD0vO08wkntOzdZ9Dt5yX-4ic_UwQhwcJdqNE,1067
+devdoctor_cli-0.1.0.dist-info/METADATA,sha256=-elzGyrC_Rulaq_zwb7rP_K1EiOL2EsoKc7qAFlz_F0,11487
+devdoctor_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+devdoctor_cli-0.1.0.dist-info/entry_points.txt,sha256=39PIHelOZ6Hxkvsn93byTVD-gwpmKCqwKgWrcKXDFFY,49
+devdoctor_cli-0.1.0.dist-info/top_level.txt,sha256=3nH0Vv5-Arsjb8AS6nFK6Q3-BXKQRKu0cmTHW6T0Hlo,10
+devdoctor_cli-0.1.0.dist-info/RECORD,,

devdoctor_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

devdoctor_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+devdoctor = devdoctor.cli:main

devdoctor_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Souran Jash
+
+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.

devdoctor_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+devdoctor