Metadata-Version: 2.4
Name: saturnday
Version: 0.2.0
Summary: AI-specific governance for code generated by Claude, Cursor, Copilot, and other AI coding tools
License-Expression: MIT
Project-URL: Homepage, https://github.com/honouralexwill/saturnday
Project-URL: Repository, https://github.com/honouralexwill/saturnday
Keywords: ai,governance,security,code-review,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Security
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"

# Saturnday

AI-specific governance for code generated by Claude, Cursor, Copilot, and other AI coding tools.

Your team already uses AI coding tools. Saturnday makes sure what they produce is safe to ship.

## What it does

Saturnday runs 18+ automated checks on every PR, catching the things AI gets wrong that humans miss:

- **Hallucinated imports** — packages that don't exist on npm or PyPI
- **Fake tests** — `assert True`, empty test bodies, tests that test nothing
- **Leaked secrets** — API keys, passwords, tokens hardcoded in generated code
- **Syntax errors** — code that won't parse (Python and TypeScript/JavaScript)
- **Placeholder code** — TODO stubs, `pass`-only functions, `NotImplementedError` bodies
- **Typosquat dependencies** — suspicious package names that look like popular libraries
- **Prompt injection** — system prompt leakage in generated code
- **Security vulnerabilities** — via Bandit static analysis
- **Shell script issues** — via ShellCheck integration
- **API version mismatches** — calling methods that don't exist on the installed library version

## Install

```bash
pip install saturnday
```

## Usage

### Check a PR diff

```bash
saturnday check --repo . --diff HEAD~1..HEAD
```

### Scan an OpenClaw skill

```bash
saturnday scan --skill ./skills/my-skill/ --output ./results
```

### Scan an entire skills corpus

```bash
saturnday scan --openclaw ./openclaw-skills/ --output ./results --format json
```

## GitHub Action

Add this to `.github/workflows/saturnday.yml` in your repo:

```yaml
name: Saturnday Governance
on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  pull-requests: write

jobs:
  governance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - uses: honouralexwill/saturnday/.github/actions/saturnday-check@master
```

Every PR gets scanned. Findings are posted as a PR comment. The check fails if the disposition is FAIL.

## Policy configuration

Create a `saturnday-policy.yaml` in your repo root to customise check severity:

```yaml
schema_version: "1.0.0"

checks:
  secrets: error
  hallucinated_imports: error
  fake_tests: warning
  placeholders: info
  syntax: error

scope:
  denied_paths:
    - "vendor/**"
    - "node_modules/**"
```

## How it works

Saturnday treats AI-generated code as untrusted input. Every diff goes through deterministic verification — no LLM calls in the governance pipeline. The checks are fast, reproducible, and auditable.

Results are written to structured evidence packs that can be stored for compliance and audit purposes.

## License

MIT
