Metadata-Version: 2.4
Name: ai-code-watchdog
Version: 0.1.0
Summary: AI code quality gate: catches AI-slop, complexity spikes, placeholder tests, unsafe shortcuts, and baseline regressions.
Author: Hermes Agent
License-Expression: MIT
Project-URL: Homepage, https://github.com/erikadamil-max/ai-code-guard
Project-URL: Repository, https://github.com/erikadamil-max/ai-code-guard
Project-URL: Issues, https://github.com/erikadamil-max/ai-code-guard/issues
Keywords: ai,code-quality,guardrails,audit,security,technical-debt,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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 :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=5.1
Dynamic: license-file

# ai-code-guard

**AI code quality gate**: catches AI-slop, complexity spikes, placeholder tests, unsafe shortcuts, and baseline regressions.

Built for teams using Cursor, Copilot, Claude Code, Codex, and other AI coding assistants. AI writes code faster than humans can review it; this tool helps close the gap.

## Status

Beta v0.1. The CLI is usable, covered by smoke tests, and has been validated on one large local mixed Python/JS project. More real-world repository validation is still needed before calling this production hardened.

For production-grade security analysis, use it alongside Semgrep, Snyk, GitGuardian, or similar tools. ai-code-guard focuses on AI-specific code quality risks and baseline regressions; it does not find every vulnerability.

## Install

From a local checkout:

```bash
git clone https://github.com/erikadamil-max/ai-code-guard.git
cd ai-code-guard
pip install -e .
ai-code-guard self-test
```

After the first PyPI release, installation will be:

```bash
pip install ai-code-watchdog
ai-code-guard self-test
```

The PyPI distribution is `ai-code-watchdog`; the CLI command is still `ai-code-guard`.

## Quickstart

```bash
cd /path/to/your/project

# Create .codeguard/rules.yaml
ai-code-guard init .

# Run a full audit and create a baseline
ai-code-guard audit .

# Check current git changes before commit
ai-code-guard guard .

# Compare current state against the saved baseline
ai-code-guard monitor .
```

## Commands

```text
ai-code-guard audit [path]           Full project audit; scans entire codebase
ai-code-guard guard [path]           Pre-commit guard; checks git diff only
ai-code-guard monitor [path]         Delta vs baseline; reports regressions only
ai-code-guard init [path]            Create .codeguard/rules.yaml from template
ai-code-guard self-test              Run smoke tests
```

## Flags

```text
audit:
  --json               Output JSON instead of text report
  --rules PATH         Path to custom rules.yaml
  --no-baseline        Skip saving baseline

guard:
  --json               Output JSON
  --skip-tests         Skip test suite (faster, security-only)
  --include-untracked  Scan untracked files too
  --diff-cmd CMD       Custom git diff command

monitor:
  --json               Output JSON
  --update-baseline    Update baseline after reporting
  --rules PATH         Path to custom rules.yaml

init:
  --force              Overwrite existing rules.yaml
```

## What It Catches

Security:

- Hardcoded secrets
- SQL injection patterns
- Shell injection patterns
- Dangerous Python `eval` / `exec`
- JavaScript `eval()` and `new Function()`
- Unsafe deserialization
- DOM XSS sinks such as `innerHTML` as warning by default

AI anti-patterns:

- Silent exception swallowing
- Bare `except` blocks
- Missing error handling on network calls
- N+1 query patterns
- Long functions
- Commented-out code blocks
- Debug leftovers
- Mixed naming conventions

Testing and complexity:

- Placeholder tests such as `assert True` or `pass`-only tests
- Test-to-source file ratio
- Functions above `max_function_length`
- Baseline regressions in monitor mode

## Configuration

`ai-code-guard init .` creates `.codeguard/rules.yaml`.

```yaml
security:
  block_on_secrets: true
  block_on_sql_injection: true

complexity:
  max_function_length: 50
  hotspots_warning_threshold: 10

anti_patterns:
  warning_increase_percent: 20

testing:
  min_test_ratio: 0.15

javascript:
  dom_xss:
    enabled: true
    block_on_innerHTML: false

guard_mode:
  block_commit_on_critical: true
  max_fix_cycles: 2

allowlist:
  - scripts/smoke_test.py

exclude:
  - "**/vendor/**"
  - "**/generated/**"
```

## Exit Codes

| Command | 0 | 1 | 2 |
|---|---|---|---|
| `audit` | Success | Error | - |
| `guard` | Safe to commit | Issues found | Could not run |
| `monitor` | No regressions | Regressions found | No baseline |
| `self-test` | All tests passed | Tests failed | - |

## GitHub Actions

Until this repository is published and tagged, install from source in CI:

```yaml
name: AI Code Guard
on: [push, pull_request]

jobs:
  guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - run: pip install -e .
      - run: ai-code-guard guard . --skip-tests
      - run: ai-code-guard audit . --no-baseline --json > guard-report.json
        if: always()
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: ai-code-guard-report
          path: guard-report.json
```

After the repository is public and tagged, the composite action can be consumed as:

```yaml
- uses: erikadamil-max/ai-code-guard@v0.1.0
  with:
    mode: guard
    skip-tests: "true"
```

## pre-commit

Local hook configuration. This requires the package to be installed in the environment first:

```bash
pip install ai-code-watchdog
```

```yaml
repos:
  - repo: local
    hooks:
      - id: ai-code-guard
        name: AI Code Guard
        entry: ai-code-guard guard
        language: system
        pass_filenames: false
        args: ["--skip-tests"]
```

## Roadmap

Currently available as free open-source core:

- CLI: `audit`, `guard`, `monitor`, `init`, `self-test`
- Local project rules
- Local baseline and JSON reports
- GitHub Action
- pre-commit hook

Potential hosted layer later:

- Team dashboard
- Trend charts across repositories
- PR history and analytics
- Team policy packs
- Slack or Teams alerts
- Organization-wide baselines

## License

MIT
