> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cirron.com/llms.txt
> Use this file to discover all available pages before exploring further.

# lint

> Validate project structure, config, and code quality.

# cirron lint

Comprehensive project validation and code quality checking for ML projects: analyzes structure, configuration, dependencies, and code to surface issues and best-practice violations.

## Usage

```bash theme={null}
cirron lint [options]
```

## Options

| Option           | Description                                | Default |
| ---------------- | ------------------------------------------ | ------- |
| `--config`       | Lint project configuration (`cirron.yaml`) | `false` |
| `--structure`    | Check project structure and files          | `false` |
| `--dependencies` | Validate `requirements.txt`                | `false` |
| `--code`         | Run code quality checks                    | `false` |
| `--all`          | Run all linting checks                     | `true`  |
| `--fix`          | Automatically fix fixable issues           | `false` |
| `--verbose`      | Show detailed suggestions                  | `false` |
| `--json`         | Output results in JSON format              | `false` |
| `--strict`       | Treat warnings as errors                   | `false` |

## Validation Rules

| Category     | Rule              | What it checks                                                                       | Severity |
| ------------ | ----------------- | ------------------------------------------------------------------------------------ | -------- |
| config       | Required fields   | `name`, `version`, `template` present in `cirron.yaml`                               | error    |
| config       | JSON syntax       | Valid JSON/YAML structure                                                            | error    |
| config       | Version format    | Semantic versioning compliance                                                       | warning  |
| config       | Framework config  | Framework-specific requirements (PyTorch needs Python version, TensorFlow GPU flags) | warning  |
| config       | Environment setup | Deployment environment configurations declared                                       | warning  |
| structure    | Required files    | `src/model.py`, `requirements.txt`, `Dockerfile` exist                               | error    |
| structure    | Optional files    | `src/inference.py`, `src/data_loader.py`, `tests/`                                   | info     |
| structure    | ML directories    | `models/`, `data/`, `checkpoints/`, `logs/` exist                                    | warning  |
| structure    | `.cirronignore`   | Ignore file present                                                                  | warning  |
| dependencies | requirements.txt  | File exists and is parseable                                                         | error    |
| dependencies | Version pinning   | Dependencies have version constraints                                                | warning  |
| dependencies | ML libraries      | Detects common ML libraries (torch, tensorflow, sklearn, numpy, pandas)              | info     |
| code         | TypeScript/JS     | Runs `npm run lint` (ESLint)                                                         | error    |
| code         | Python syntax     | `py_compile` on source files                                                         | error    |
| code         | Python style      | Lint via flake8/pylint if present                                                    | warning  |
| code         | ML patterns       | Model definition follows framework conventions                                       | warning  |

## Automatic Fixes

`--fix` resolves: missing ML directories (created), missing `.cirronignore` (generated from a template), ESLint auto-fixable code issues, and basic structural reorganization.

The generated `.cirronignore` template covers `.git/`, large data files (`data/raw/`, `*.csv`), model artifacts (`*.pth`, `*.pkl`), dev caches (`.vscode/`, `.idea/`, `__pycache__/`, `*.pyc`), logs, temp files, and build outputs.

## Examples

```bash theme={null}
# Run all checks
cirron lint

# Specific category
cirron lint --config
cirron lint --structure --dependencies

# Verbose mode with suggestions
cirron lint --verbose

# Apply fixes
cirron lint --fix

# Strict CI mode
cirron lint --all --strict

# Structured output
cirron lint --json
```

Example output:

```
Cirron Lint Results
==================================================

CONFIG:
  ℹ Project configuration is valid (cirron.yaml)

STRUCTURE:
  ⚠ ML directory not found: models/ (models/)
    → Create models/ directory for ML artifacts
  ⚠ No .cirronignore file found (.cirronignore)
    → Create .cirronignore to exclude unnecessary files from builds

DEPENDENCIES:
  ⚠ 3 dependencies without version constraints (requirements.txt)
    → Pin dependency versions for reproducible builds
  ℹ Found 8 dependencies (requirements.txt)

CODE:
  ℹ TypeScript code passes ESLint checks
  ℹ Python syntax is valid (src/model.py)

==================================================
0 errors, 2 warnings, 4 infos

✓ Linting passed

ℹ 2 issues can be automatically fixed with --fix
```

JSON output:

```json theme={null}
{
  "errors": 0,
  "warnings": 2,
  "infos": 4,
  "results": [
    {
      "category": "structure",
      "severity": "warning",
      "message": "ML directory not found: models/",
      "file": "models/",
      "fixable": true,
      "suggestion": "Create models/ directory for ML artifacts"
    }
  ]
}
```

## Recommended Project Structure

```
my-model/
├── src/
│   ├── model.py          # Required
│   ├── inference.py      # Optional
│   └── data_loader.py    # Optional
├── tests/                # Optional
├── models/               # ML artifacts
├── data/                 # Datasets
├── requirements.txt      # Required
├── Dockerfile            # Required
├── cirron.yaml           # Required
└── .cirronignore         # Recommended
```

## Integration

```yaml theme={null}
# GitHub Actions
- name: Lint Project
  run: |
    cirron lint --all --strict
    cirron lint --fix
```

```bash theme={null}
# .git/hooks/pre-commit
#!/bin/bash
cirron lint --all || { echo "Linting failed."; exit 1; }
```

## Troubleshooting

| Error                                 | Resolution                                                                                                 |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `npm run lint failed`                 | Install ESLint: `npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin` |
| `Python syntax error in src/model.py` | `python -m py_compile src/model.py`                                                                        |
| `Missing requirements.txt`            | `pip freeze > requirements.txt`                                                                            |

Use `.cirronignore` to exclude large data and model artifacts from linting. Pin dependency versions for reproducible builds and follow framework conventions in `src/model.py`.