Metadata-Version: 2.4
Name: gavlix-docs
Version: 0.1.0
Summary: Universal documentation engine for software repositories
Project-URL: Homepage, https://github.com/gavlix/gavlix-docs
Project-URL: Documentation, https://github.com/gavlix/gavlix-docs#readme
Project-URL: Repository, https://github.com/gavlix/gavlix-docs
Project-URL: Issues, https://github.com/gavlix/gavlix-docs/issues
Author-email: Gavlix <docs@gavlix.dev>
License: MIT
License-File: LICENSE
Keywords: architecture,cli,code-analysis,diagrams,documentation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.9
Requires-Dist: fastapi>=0.115.0
Requires-Dist: pydantic>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Gavlix Docs

Universal documentation engine for software repositories. Scans source files, understands structure, and generates architecture documentation, workflow diagrams, API notes, and developer guidance.

## 1. Overview

Gavlix Docs is a **universal CLI tool** that works on **any codebase** regardless of framework or structure. It behaves like `eslint`, `prettier`, and `black` — detecting patterns dynamically and generating complete documentation without hardcoding assumptions about Flask, Django, React, Next.js, or any specific framework.

### Problem It Solves

Understanding a new codebase is expensive. Gavlix Docs turns repository structure into clear documentation that developers, reviewers, and AI agents can consume without manually reading every file.

### Supported Languages

- **Python** (AST-based parsing)
- **JavaScript / TypeScript** (regex-based parsing)
- **HTML / CSS**
- **JSON / YAML**
- **SQL** (DDL parsing)
- **Markdown**

## 2. Features

- ✅ **Auto documentation** — Generates root README, module READMEs, and detailed docs
- ✅ **Architecture diagrams** — Mermaid diagrams for dependency, workflow, database, and architecture
- ✅ **Database analysis** — ORM detection (SQLAlchemy, Django, Tortoise, Peewee, Pony, SQLModel), table mapping, relationship detection
- ✅ **Plugin system** — Auto-registration, isolation, install/remove/list
- ✅ **Incremental analysis** — File hashing, change detection, cache reuse
- ✅ **Dry-run mode** — Preview changes without writing files
- ✅ **Error isolation** — Parse failures skip files safely, never crash
- ✅ **Strict validation** — Enforces completeness before finishing
- ✅ **VS Code integration** — Commands, sidebar, output panel
- ✅ **HTTP API** — FastAPI server for VS Code and web dashboard integration

## 3. Installation

### From PyPI

```bash
pip install gavlix-docs
```

### From Source

```bash
git clone https://github.com/gavlix/gavlix-docs.git
cd gavlix-docs
pip install -e ".[dev]"
```

### Verify Installation

```bash
gavlix-docs --version
```

## 4. Usage

### Generate Documentation

```bash
gavlix-docs generate .
```

Generate documentation for the current directory. Creates:
- `README.md` — Root system documentation
- `docs/` — Detailed documentation (architecture, database, security, deployment, API, workflows)
- `docs/adr/` — Architecture Decision Records
- `diagrams/` — Mermaid diagram source files
- `modules/<name>/README.md` — Per-module documentation

### Analyze Without Writing

```bash
gavlix-docs analyze .
```

Analyze repository structure without generating documentation files.

### Validate Documentation

```bash
gavlix-docs validate .
```

Validate that all required documentation files and sections exist.

### Watch Mode

```bash
gavlix-docs watch .
```

Monitor file changes and automatically update documentation.

### Dry Run

```bash
gavlix-docs generate . --dry-run
```

Preview what files would be written without actually writing them.

### Strict Mode

```bash
gavlix-docs generate . --strict
```

Fail if validation finds any missing documentation.

### Disable Cache

```bash
gavlix-docs generate . --no-cache
```

Force fresh analysis without using cached results.

### Start API Server

```bash
gavlix-docs serve
```

Start the FastAPI server for VS Code extension and web dashboard integration.

### Plugin Management

```bash
gavlix-docs plugin list
gavlix-docs plugin install <name>
gavlix-docs plugin remove <name>
```

## 5. Configuration

Create a `gavlix.config.yaml` in your project root:

```yaml
ignore:
  - node_modules
  - .git
  - dist
  - .next

entry_points:
  - app.py
  - main.ts

documentation:
  strict: true
  include_private: false

analysis:
  incremental: true

database:
  orm: auto-detect

diagrams:
  enabled: true
  format: mermaid

plugins:
  enabled: true
  directory: .gavlix/plugins
```

## 6. VS Code Extension

### Installation

1. Install the VS Code extension from the marketplace (search "Gavlix Docs")
2. Or build from source:

```bash
cd extensions/vscode-extension
npm install
npm run compile
vsce package
```

### Commands

| Command | Description |
|---------|-------------|
| `gavlix.generateDocs` | Generate documentation for the workspace |
| `gavlix.analyzeProject` | Analyze project structure |
| `gavlix.validateDocs` | Validate documentation completeness |
| `gavlix.watchDocs` | Watch and auto-update documentation |
| `gavlix.stopWatch` | Stop watch mode |

### Configuration

```json
{
  "gavlix.useApi": false,
  "gavlix.apiUrl": "http://127.0.0.1:8000",
  "gavlix.strict": false,
  "gavlix.outputDir": "docs_output"
}
```

## 7. Plugin Development

### Plugin Interface

```typescript
export interface GavlixPlugin {
  name: string;
  version: string;
  analyzers?: Analyzer[];
  generators?: Generator[];
}
```

### Python Plugin SDK

```python
from plugins.sdk import BasePlugin, PluginMetadata

class MyPlugin(BasePlugin):
    def __init__(self):
        super().__init__(PluginMetadata(
            name="my-plugin",
            version="1.0.0",
            description="Custom analyzer plugin",
            capabilities=["analyzer"],
        ))

    def run(self, context):
        # Custom analysis logic
        return {"status": "ok", "result": "custom analysis"}
```

### Install a Plugin

```bash
gavlix-docs plugin install my-plugin
```

## 8. Architecture Overview

### Pipeline Flow

```
Scan Project → Parse All Files → Build Code Model → Build Dependency Graph
    ↓
Detect Entry Points → Infer Workflows → Analyze Database Layer
    ↓
Analyze Security Layer → Analyze Deployment Layer
    ↓
Generate Diagrams → Generate Documentation → Validate Completeness
    ↓
Write Files
```

### Architecture Diagram

```mermaid
graph TB
    A[CLI / API / VS Code] --> B[GavlixOrchestrator]
    B --> C[ProjectAnalyzer]
    C --> D[ArchitectureMapper]
    D --> E[DependencyMapper]
    B --> F[DatabaseAnalyzer]
    B --> G[SecurityAnalyzer]
    B --> H[DeploymentAnalyzer]
    B --> I[WorkflowBuilder]
    B --> J[Generators]
    J --> K[ReadmeGenerator]
    J --> L[ModuleReadmeGenerator]
    J --> M[DiagramGenerator]
    J --> N[DocumentationBundle]
    B --> O[DocumentationValidator]
    O --> P[SafeWriter]
    P --> Q[Output Files]
```

### Why This Architecture

- **Modular**: Each analyzer, generator, and validator is independent
- **Scalable**: Incremental analysis with file hashing and caching
- **Language-agnostic**: Parsers are pluggable per file extension
- **Error-isolated**: Parse failures skip files, never crash the system
- **Extensible**: Plugin system with auto-registration and isolation

### Key Components

| Component | Purpose |
|-----------|---------|
| `gavlix_docs/cli.py` | CLI with isolated command handlers, exit codes, error handling |
| `gavlix_docs/orchestrator.py` | Coordinates the full pipeline |
| `gavlix_docs/analyzers/` | Project analysis and structure discovery |
| `gavlix_docs/generators/` | Markdown and Mermaid output generation |
| `gavlix_docs/validators/` | Output validation and completeness checks |
| `gavlix_docs/cache/` | Disk-based cache with file-level change detection |
| `gavlix_docs/config/` | Configuration loading and validation |
| `gavlix_docs/plugins.py` | Plugin registry with auto-registration and isolation |
| `gavlix_docs/api.py` | FastAPI server for VS Code and web integration |

## 9. API

The FastAPI server exposes:

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/health` | Health check |
| GET | `/status` | System status with validation result |
| POST | `/analyze` | Analyze a project |
| POST | `/generate` | Generate documentation |
| GET | `/api/overview` | Project overview with statistics |
| GET | `/api/modules` | List all modules |
| GET | `/api/graph` | Dependency graph |
| GET | `/api/workflows` | Inferred workflows |
| GET | `/api/database` | Database schema |
| GET | `/api/security` | Security findings |
| GET | `/api/deployment` | Deployment info |
| GET | `/api/metrics` | System metrics |

## 10. Testing

```bash
# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=gavlix_docs

# Run specific test file
pytest tests/test_cli.py
```

## 11. License

MIT License — see [LICENSE](LICENSE).
