confdoc/README.md

# ConfDoc - Configuration Validation and Documentation Generator

A CLI tool that validates JSON/YAML/TOML configuration files against a schema and auto-generates human-readable documentation. It provides schema validation with clear error messages and generates markdown documentation from the schema itself, solving configuration management challenges for developers and DevOps teams.

## Features

- **Multi-format Support**: Parse and validate JSON, YAML, and TOML configuration files
- **Schema Validation**: Validate configs against JSON Schema with detailed, actionable error messages
- **Documentation Generation**: Auto-generate markdown documentation from your schemas
- **Environment Profiles**: Built-in development, staging, and production profiles
- **Type Checking**: Extract and validate types from schemas with default values

## Installation

```bash
pip install confdoc
```

Or from source:

```bash
pip install -e .
```

## Quick Start

### Validate a Configuration File

```bash
# Validate a config file against a schema
confdoc validate config.json --schema schema.json

# Specify format explicitly
confdoc validate config.yaml --schema schema.json --format yaml

# Apply a profile
confdoc validate config.json --schema schema.json --profile production

# JSON output
confdoc validate config.json --schema schema.json --output json
```

### Generate Documentation

```bash
# Generate documentation from a schema
confdoc doc schema.json

# Write to a file
confdoc doc schema.json --output CONFIG.md

# Custom title
confdoc doc schema.json --title "My App Configuration"
```

### Initialize a Schema

```bash
# Create a starter schema
confdoc init schema.json

# Generate schema from existing config
confdoc init schema.json --config config.json
```

## Usage

### Commands

| Command | Description |
|---------|-------------|
| `confdoc validate <config>` | Validate a configuration file |
| `confdoc doc <schema>` | Generate documentation from schema |
| `confdoc init [output]` | Initialize a new schema file |

### Options

#### Validate Command

| Option | Description |
|--------|-------------|
| `--schema, -s` | Path to schema file (default: schema.json) |
| `--format, -f` | Config format: json, yaml, toml, auto |
| `--profile, -p` | Profile to apply: development, staging, production |
| `--output, -o` | Output format: text, json |

#### Doc Command

| Option | Description |
|--------|-------------|
| `--output, -o` | Output file path |
| `--title, -t` | Document title |
| `--format, -f` | Output format (default: markdown) |

#### Init Command

| Option | Description |
|--------|-------------|
| `--config, -c` | Generate schema from existing config file |

## Examples

### Example Configuration (JSON)

```json
{
  "app": {
    "name": "myapp",
    "version": "1.0.0",
    "debug": true
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "mydb"
  }
}
```

### Example Schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Application Configuration",
  "type": "object",
  "properties": {
    "app": {
      "type": "object",
      "properties": {
        "name": {"type": "string", "description": "Application name"},
        "version": {"type": "string", "description": "Version"},
        "debug": {"type": "boolean", "description": "Debug mode", "default": false}
      },
      "required": ["name"]
    },
    "database": {
      "type": "object",
      "properties": {
        "host": {"type": "string"},
        "port": {"type": "integer", "minimum": 1, "maximum": 65535}
      }
    }
  },
  "required": ["app"]
}
```

### Error Output

When validation fails, ConfDoc provides clear, actionable error messages:

```
✗ Configuration validation failed
  - 'port' is not of type 'string' in app.database
    → Expected type string, but got integer.
```

## Configuration

### Environment Variables

| Variable | Description |
|----------|-------------|
| `CONFDOC_CONFIG_PATH` | Default config path |
| `CONFDOC_DEFAULT_SCHEMA` | Default schema file |

### Configuration Files

ConfDoc looks for configuration in:
1. `confdoc.yaml`
2. `.confdocrc`
3. `pyproject.toml` section `[tool.confdoc]`

## Profiles

ConfDoc includes built-in profiles for different environments:

### Development
- Relaxed validation (additionalProperties allowed)
- Debug mode enabled by default
- DEBUG log level

### Staging
- Strict validation
- Debug disabled
- INFO log level

### Production
- Strict validation
- Debug disabled
- WARNING log level

Create custom profiles:

```python
from confdoc.profiles import ProfileManager

manager = ProfileManager()
manager.save_profile("custom", {
    "name": "Custom",
    "validation": {"strict": True},
    "overrides": {"custom_key": "value"}
})
```

## Schema Reference

ConfDoc supports JSON Schema draft-07 with these commonly used keywords:

| Keyword | Description |
|---------|-------------|
| `type` | Value type (string, integer, boolean, object, array) |
| `required` | Array of required property names |
| `properties` | Object property definitions |
| `description` | Property description for docs |
| `default` | Default value |
| `enum` | Allowed values |
| `minimum` | Minimum value (numbers) |
| `maximum` | Maximum value (numbers) |
| `minLength` | Minimum string length |
| `maxLength` | Maximum string length |
| `pattern` | Regex pattern |

## Testing

```bash
# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/confdoc --cov-report=term-missing

# Run specific test file
pytest tests/test_parsers.py -v
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add your changes
4. Write tests
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.