ai-code-watchdog 0.1.0

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

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:

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:

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

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

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

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.

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:

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:

- 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:

pip install ai-code-watchdog

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