Metadata-Version: 2.4
Name: dextora
Version: 0.1.0
Summary: A Python CLI toolkit for diagnosing project setup, dependencies, environment configuration, and common development issues.
License: MIT
Project-URL: Homepage, https://github.com/TanishJain13/Dextora
Project-URL: Repository, https://github.com/TanishJain13/Dextora
Project-URL: Issues, https://github.com/TanishJain13/Dextora/issues
Project-URL: Changelog, https://github.com/TanishJain13/Dextora/blob/main/CHANGELOG.md
Keywords: developer-tools,diagnostics,cli,linter,environment,doctor,dextora
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# Dextora

> **A Python CLI toolkit for diagnosing project setup, dependencies, environment configuration, and common development issues.**
>
> *Note: Dextora was formerly developed under the initial development name KLYRO.*

Dextora helps developers instantly answer three questions:
1. **What is wrong with my project setup?**
2. **Why is it happening?**
3. **How can I fix it?**

---

## Features & Core Capabilities

- **Intelligent Project & Framework Classification**:
  - Python: Recognizes **Django**, **FastAPI**, **Flask**, and standard Python projects based on declared dependencies and manifests.
  - JavaScript / TypeScript: Recognizes **Vue**, **Nuxt**, **Svelte**, **SvelteKit**, **Angular**, **Astro**, **Next.js**, **React**, and generic **Node.js** projects.
  - Fullstack Combinations: Identifies combined backend/frontend architectures (e.g. `Fullstack (FastAPI + Next.js)`, `Fullstack (Django + React)`).
  - Preserves base types for generic directories and unrecognized structures.
- **Root-Cause Analysis Engine**: Deterministically identifies causal relationships among diagnostic findings (e.g. merge conflicts causing parser errors, missing `.gitignore` causing tracked secrets) and groups them with clear confidence levels (`confirmed` vs `probable`) without deleting or altering underlying findings.
- **Context-Aware Remediation**: Provides exact, safe remediation commands tailored to the detected package manager (`pnpm`, `yarn`, `bun`, `npm`, `poetry`, `pipenv`, `pip`) and marks complex migrations as requiring manual review.
- **Python Environment Verification**: Detects standard virtual environments (`.venv`, `venv`, `env`), verifies interpreter executables, checks Python version compatibility (`requires-python`), and checks site-packages status.
- **Dependency Diagnostics**: Detects missing lockfiles (`Pipfile` without `Pipfile.lock`), orphaned lockfiles (`poetry.lock` without `pyproject.toml`), conflicting package managers, duplicate dependencies, and unpinned packages in `requirements.txt`.
- **Environment & Secret Safety**: Validates `.env` variables against `.env.example`/`.env.sample` templates **without ever reading, logging, or exposing secret values** in findings, remediations, or JSON outputs.
- **Version Control Diagnostics**: Detects Git status, `.gitignore` presence and coverage, unmerged Git conflict markers (`<<<<<<<`), and verifies whether sensitive files are tracked by Git.
- **JavaScript/TypeScript Diagnostics**: Detects `package.json` syntax errors, flags conflicting lockfiles (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`), and checks lockfile presence with packageManager field awareness.
- **Strict Read-Only Safety**: Diagnostic commands never modify scanned files, never execute arbitrary project scripts, never execute suggested remediation commands, and safely bypass ignored directories (`.git`, `node_modules`, `.venv`, `dist`, `build`, caches).

---

## Implemented Diagnostic Codes

| Code | Severity | Description |
|---|---|---|
| `STR000` | ERROR | Target path does not exist or is not a directory |
| `STR001` | WARNING | Scanned directory is empty |
| `STR002` | SUCCESS | Standard project manifest detected |
| `STR003` | INFO | Generic directory without standard manifest |
| `PY000` | SUCCESS | Active virtual environment located |
| `PY001` | WARNING | No Python virtual environment found in standard locations |
| `PY002` | WARNING | Incomplete or broken virtual environment |
| `PY003` | WARNING | Running Python version does not satisfy project requirement |
| `PY004` | INFO | Virtual environment exists but site-packages appears empty |
| `DEP001` | WARNING | `Pipfile` found without corresponding `Pipfile.lock` |
| `DEP002` | ERROR | Orphaned `poetry.lock` found without `pyproject.toml` |
| `DEP004` | WARNING | Conflicting dependency managers detected (Pipenv + Poetry) |
| `DEP005` | INFO | Multiple dependency definitions present (Pipfile + requirements.txt) |
| `DEP006` | ERROR | Malformed `pyproject.toml` TOML syntax |
| `DEP007` | WARNING | Malformed requirement or duplicate packages in `requirements.txt` |
| `DEP008` | INFO | Unpinned dependencies detected in `requirements.txt` |
| `DEP009` | WARNING | `pyproject.toml` lacks standard build-system or project tables |
| `ENV000` | SUCCESS | `.env` variables fully synchronized with template |
| `ENV001` | WARNING | `.env.example` template present but `.env` is missing |
| `ENV002` | WARNING | Missing environment variables declared in template |
| `ENV003` | WARNING | Malformed `.dextora.toml` syntax |
| `ENV004` | SUCCESS | Valid `.dextora.toml` loaded |
| `GIT000` | INFO | Target directory is not a Git repository |
| `GIT001` | WARNING | No `.gitignore` file found in Git repository |
| `GIT002` | WARNING | `.env` exists but is not listed in `.gitignore` |
| `GIT003` | ERROR | Sensitive file tracked in Git index |
| `GIT004` | INFO | Git author identity (`user.name`/`user.email`) not configured |
| `GIT005` | ERROR | Unresolved Git merge conflict markers detected |
| `JS000` | SUCCESS | Consistent JavaScript package manager lockfile detected |
| `JS001` | ERROR | Malformed `package.json` syntax |
| `JS002` | WARNING | Multiple conflicting JavaScript lockfiles detected |
| `JS003` | INFO | `package.json` has dependencies but no lockfile found |

---

## Installation & Setup

### Prerequisites

- Python 3.11 or newer

### Local Development Setup (Windows PowerShell)

```powershell
# 1. Clone or navigate to the repository
cd D:\KLYRO

# 2. Create a virtual environment
python -m venv .venv

# 3. Activate the virtual environment
.\.venv\Scripts\Activate.ps1

# 4. Install Dextora in editable mode with development dependencies
pip install -e ".[dev]"
```

Once installed, the `dextora` command is available in your shell. You can also run it directly via `python -m dextora`.

---

## CLI Usage & Commands

### `dextora --help`
Displays command overview, flags, and usage examples:
```powershell
dextora --help
```

### `dextora --version`
Displays installed Dextora version:
```powershell
dextora --version
```

### `dextora doctor`
Scans the current working directory:
```powershell
dextora doctor
```

### `dextora doctor <path>`
Scans a specific target project without modifying its contents:
```powershell
dextora doctor C:\Users\dev\my-app
```

### `dextora doctor [path] --json`
Outputs clean, machine-readable JSON (ideal for CI pipelines and scripts):
```powershell
dextora doctor --json
```

### `dextora doctor [path] --strict`
Exits with code `1` if any `WARNING` or `ERROR` findings are discovered (default exits `1` on `ERROR` only).
```powershell
dextora doctor --strict
```

### `dextora init [path]`
Initializes a minimal `.dextora.toml` configuration in the project. Refuses to overwrite existing configuration without `--force`:
```powershell
dextora init
# Or overwrite existing:
dextora init --force
```

---

## Sample Outputs

### Terminal Output (`dextora doctor`)

```
+------------------------------------------------+
| Dextora v0.1.0 - Developer Diagnostics Toolkit |
| Target:       D:\Projects\sample-app           |
| Project Type: Python                           |
| Checks Run:   6                                |
+------------------------------------------------+

>>> WARNINGS (2)
----------------------------------------
[PY001] No Python virtual environment detected
  Why:      Python projects should use an isolated virtual environment to prevent dependency pollution.
  Evidence: Looked for: .venv, venv, env in project root.
  Fix:      Create a virtual environment with 'python -m venv .venv' and activate it.

[ENV001] Environment template '.env.example' present but '.env' is missing (.env.example)
  Why:      The project provides '.env.example' as an environment template, but no local '.env' file was found.
  Evidence: Template: .env.example
  Fix:      Copy '.env.example' to '.env' and fill in the required local configuration values.

>>> SUCCESSES (1)
----------------------------------------
[STR002] Project manifest detected (pyproject.toml)
  Why:      Identified Python project configuration manifests.
  Evidence: pyproject.toml
  Fix:      No action required.

 Diagnostic Summary
  Severity    Count
  Errors          0
  Warnings        2
  Info            0
  Passed          1

[!] Scan completed with 2 warning(s). Review the suggestions above.
```

### Machine-Readable JSON Output (`dextora doctor --json`)

```json
{
  "version": "0.1.0",
  "target_path": "D:\\Projects\\sample-app",
  "project_type": "Python",
  "checks_run": 6,
  "summary": {
    "ERROR": 0,
    "WARNING": 2,
    "INFO": 0,
    "SUCCESS": 1
  },
  "findings": [
    {
      "code": "PY001",
      "severity": "WARNING",
      "title": "No Python virtual environment detected",
      "explanation": "Python projects should use an isolated virtual environment to prevent dependency pollution.",
      "evidence": "Looked for: .venv, venv, env in project root.",
      "fix": "Create a virtual environment with 'python -m venv .venv' and activate it.",
      "file_path": null
    },
    {
      "code": "ENV001",
      "severity": "WARNING",
      "title": "Environment template '.env.example' present but '.env' is missing",
      "explanation": "The project provides '.env.example' as an environment template, but no local '.env' file was found.",
      "evidence": "Template: .env.example",
      "fix": "Copy '.env.example' to '.env' and fill in the required local configuration values.",
      "file_path": ".env.example"
    },
    {
      "code": "STR002",
      "severity": "SUCCESS",
      "title": "Project manifest detected",
      "explanation": "Identified Python project configuration manifests.",
      "evidence": "pyproject.toml",
      "fix": "No action required.",
      "file_path": "pyproject.toml"
    }
  ]
}
```

---

## Supported Frameworks & Ecosystems

Dextora uses declared dependencies, manifests, and lockfiles to reliably classify projects:

| Ecosystem | Detected Types & Frameworks | Evidence Required |
|---|---|---|
| **Python** | Django | `django` in `pyproject.toml`, `requirements.txt`, or `Pipfile` |
| **Python** | FastAPI | `fastapi` in `pyproject.toml`, `requirements.txt`, or `Pipfile` |
| **Python** | Flask | `flask` in `pyproject.toml`, `requirements.txt`, or `Pipfile` |
| **Python** | Python (Generic) | `pyproject.toml`, `requirements.txt`, or `Pipfile` without specialized frameworks |
| **JavaScript / TypeScript** | Next.js | `next` dependency in `package.json` |
| **JavaScript / TypeScript** | React | `react` dependency in `package.json` |
| **JavaScript / TypeScript** | Nuxt | `nuxt` dependency in `package.json` |
| **JavaScript / TypeScript** | Vue | `vue` dependency in `package.json` |
| **JavaScript / TypeScript** | SvelteKit | `@sveltejs/kit` dependency in `package.json` |
| **JavaScript / TypeScript** | Svelte | `svelte` dependency in `package.json` |
| **JavaScript / TypeScript** | Angular | `@angular/core` dependency in `package.json` |
| **JavaScript / TypeScript** | Astro | `astro` dependency in `package.json` |
| **JavaScript / TypeScript** | Node.js (Generic) | `package.json` without frontend framework dependencies |
| **Fullstack** | Composite (e.g. `Fullstack (FastAPI + Next.js)`) | Both Python and JavaScript framework manifests present |
| **Other** | Rust, Go | `Cargo.toml`, `go.mod` manifests |
| **Generic** | Generic / Unknown | Directories without recognized manifests or empty directories |

---

## Known Limitations

- **Offline-Only Analysis**: Dextora performs static local analysis and does not connect to PyPI, npm, or external networks to resolve transitive dependency trees.
- **Root-Level Monorepos**: Dextora primarily targets the root project directory and immediate components. Deeply nested workspace packages (e.g., Turborepo or nested multi-package monorepos) are classified from their top-level manifest rather than traversed independently.
- **Static Pattern Matching**: Environment verification checks `.env` and `.env.example` keys; dynamic environment resolution injected at runtime by remote secret managers (e.g. AWS Secrets Manager, HashiCorp Vault) is outside Dextora's local static scope.

---

## Safety Model

1. **Read-Only**: Diagnostic commands (`doctor`) never alter project files or directory structure.
2. **Secret Privacy**: Secret values from `.env` files are never parsed into memory for display, logged, or included in diagnostic evidence. Only variable **names** are compared.
3. **No Execution**: Project scripts, hooks, or package installation commands are never executed during scanning.
4. **Filesystem Boundaries**: Directory traversal does not follow symlinks outside target root, and skips directories known to contain large generated files (`.git`, `node_modules`, `.venv`, caches).
5. **Deterministic**: Diagnostics produce predictable, deterministic findings based strictly on file presence and parsed content.

---

## Development & Testing

### Running Tests
Run the full pytest suite:

```powershell
.\.venv\Scripts\python.exe -m pytest -v
```

### Building the Package
To build source distribution (`sdist`) and binary wheel (`wheel`):

```powershell
.\.venv\Scripts\python.exe -m build
```

Artifacts are produced in the `dist/` directory.

---

## Community & Contributing

- **Contributing**: Please review [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflows and development setup.
- **Changelog**: See [CHANGELOG.md](CHANGELOG.md) for release notes.
- **Security Policy**: See [SECURITY.md](SECURITY.md) for vulnerability reporting procedures.
- **License**: MIT License. See [LICENSE](LICENSE) for details.
