Metadata-Version: 2.4
Name: stablestack
Version: 0.3.6
Summary: Your AI-generated code, double-checked. Catches subtle bugs that AI assistants often introduce.
Project-URL: Homepage, https://github.com/stablestack/stablestack
Project-URL: Documentation, https://github.com/stablestack/stablestack#readme
Project-URL: Repository, https://github.com/stablestack/stablestack
Author: vibecheck contributors
License: StableStack Proprietary License
        
        Copyright (c) 2026 StableStack. All Rights Reserved.
        
        NOTICE: This software and associated documentation files (the "Software")
        are proprietary and confidential. The Software is protected by copyright
        law and international treaties.
        
        LICENSE GRANT
        
        Subject to payment of applicable license fees and compliance with this
        agreement, you are granted a limited, non-exclusive, non-transferable
        license to:
        
        1. Install and use the Software on systems you own or control
        2. Use the Software for your internal business purposes
        3. Make a reasonable number of backup copies for archival purposes
        
        FREE TIER
        
        The free tier of the Software (including security checks SEC001-SEC004)
        may be used without a paid license, subject to the restrictions below.
        
        RESTRICTIONS
        
        You may NOT:
        
        1. Redistribute, sell, lease, sublicense, or otherwise transfer the
           Software to any third party without prior written consent
        2. Modify, adapt, translate, reverse engineer, decompile, disassemble,
           or create derivative works based on the Software
        3. Remove or alter any proprietary notices, labels, or marks on the
           Software
        4. Use the Software to provide services to third parties (SaaS) without
           a separate commercial agreement
        5. Share license keys or authentication credentials with unauthorized
           users
        6. Publish or disclose any benchmark or performance results without
           prior written consent
        
        COMMERCIAL USE
        
        Full access to all checks requires a valid paid license. For pricing
        and licensing inquiries, contact: licensing@stablestack.ai
        
        WARRANTY DISCLAIMER
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
        OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
        THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
        DEALINGS IN THE SOFTWARE.
        
        LIMITATION OF LIABILITY
        
        IN NO EVENT SHALL STABLESTACK BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
        SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING BUT NOT LIMITED
        TO LOSS OF PROFITS, DATA, OR BUSINESS INTERRUPTION) HOWEVER CAUSED,
        WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT, EVEN IF ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGE.
        
        TERMINATION
        
        This license is effective until terminated. Your rights under this license
        will terminate automatically without notice if you fail to comply with any
        of its terms. Upon termination, you must destroy all copies of the Software
        in your possession.
        
        GOVERNING LAW
        
        This agreement shall be governed by and construed in accordance with the
        laws of the United States, without regard to conflict of law principles.
        
        For licensing inquiries: licensing@stablestack.ai
License-File: LICENSE
Keywords: ai-generated-code,code-quality,determinism,linter,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.7
Requires-Dist: click>=8.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: build
Requires-Dist: build>=1.0; extra == 'build'
Requires-Dist: cython>=3.0; extra == 'build'
Requires-Dist: setuptools>=65.0; extra == 'build'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: watch
Requires-Dist: watchdog>=3.0; extra == 'watch'
Description-Content-Type: text/markdown

# vibecheck

**Your AI-generated code, double-checked.**

A lightweight linter that catches subtle bugs AI assistants often introduce. 71 rules across 19 categories, focused on issues that existing linters miss.

## Installation

```bash
pip install vibecheck
```

Or install from source:

```bash
git clone https://github.com/pfrank8/vibecheck
cd vibecheck
pip install -e .
```

## Quick Start

```bash
# Check your source directory
vibecheck src/

# Check specific files
vibecheck app.py utils.py

# CI mode (exit code 1 if errors found)
vibecheck src/ --ci

# JSON output for CI/CD
vibecheck src/ --format json > results.json
```

## Repository Structure

| Directory | Description |
|-----------|-------------|
| `/site` | Marketing website (Next.js) - the primary deployed application at stablestack.ai |
| `/stablestack` | Core product code - the vibecheck CLI and analysis engine |
| `/` | Root contains shared configs, documentation, and Python package setup |

To run the marketing site locally:

```bash
cd site
npm install
npm run dev
```

### Stripe Configuration (Optional)

The site includes Stripe Checkout for paid subscriptions. To enable payments:

1. Create a [Stripe account](https://stripe.com) and get your API keys
2. Create subscription products/prices in Stripe Dashboard
3. Set the following environment variables:

```bash
# Required for checkout to work
STRIPE_SECRET_KEY=sk_live_...           # or sk_test_... for testing
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...  # or pk_test_... for testing

# Price IDs from your Stripe Dashboard
NEXT_PUBLIC_STRIPE_PRICE_INDIE=price_...
NEXT_PUBLIC_STRIPE_PRICE_ENTERPRISE=price_...
```

If these variables are not set, the pricing page will display a notice and checkout buttons will show an error. The site builds and runs normally without Stripe configured.

## What It Catches

**71 rules** across **19 categories**. See [CHECKERS.md](CHECKERS.md) for complete documentation.

### Determinism Issues (DET001-DET008)

Non-deterministic code breaks LLM caching and causes flaky tests:

| Rule | Issue | Impact |
|------|-------|--------|
| DET001 | Unsorted dict iteration | Cache misses, flaky tests |
| DET002 | Unsorted set iteration | Random ordering |
| DET003 | Missing sort tiebreaker | Unstable ordering |
| DET004 | list(set()) deduplication | Order scrambling |
| DET005 | Random without seed | Non-reproducible results |
| DET006 | datetime.now() usage | Time-dependent bugs |
| DET007 | Unsorted directory listing | Platform-dependent order |
| DET008 | Hashing unsorted collections | Inconsistent cache keys |

### Security Issues (SEC001-SEC011)

Catch vulnerabilities before they reach production:

| Rule | Issue | Risk |
|------|-------|------|
| SEC001 | Hardcoded secrets | Credential leaks |
| SEC002 | SQL injection | Database compromise |
| SEC003 | eval() usage | Code execution |
| SEC004 | Insecure random | Predictable tokens |
| SEC005 | innerHTML XSS | Script injection |
| SEC006 | Webhook bypass | Forged webhooks |
| SEC007 | OAuth state missing | CSRF attacks |
| SEC008 | Plaintext tokens | Data breach exposure |
| SEC009 | Email header injection | Email spoofing |
| SEC010 | CSV formula injection | Code execution |
| SEC011 | Unsanitized HTML | XSS attacks |

### Quality Issues (QUAL001-QUAL008)

Code quality problems that cause production bugs:

| Rule | Issue |
|------|-------|
| QUAL001 | Swallowed exceptions (Python + JS/TS) |
| QUAL002 | Unnamed threads |
| QUAL003 | Complex tuple types |
| QUAL004 | Mutable default arguments |
| QUAL005 | Print statements |
| QUAL006 | TODO/FIXME comments |
| QUAL007 | Broad exception catching |
| QUAL008 | Magic numbers |

### API Issues (API001-API004)

Frontend-backend integration problems:

| Rule | Issue |
|------|-------|
| API001 | Unhandled API errors |
| API002 | Inconsistent naming (snake_case vs camelCase) |
| API003 | Missing Content-Type headers |
| API004 | Hardcoded API URLs |

### Async Issues (ASYNC001-ASYNC004)

Common async/await mistakes:

| Rule | Issue |
|------|-------|
| ASYNC001 | Missing await on async calls |
| ASYNC002 | Blocking calls in async functions |
| ASYNC003 | Fire-and-forget tasks |
| ASYNC004 | Silent .catch() handlers |

### Concurrency Issues (CONC001)

Race conditions and thread safety:

| Rule | Issue |
|------|-------|
| CONC001 | Check-then-act race conditions |

### Type Safety Issues (TYPE001-TYPE010)

Type safety beyond basic linting:

| Rule | Issue |
|------|-------|
| ASYNC001 | Missing await on async calls |
| ASYNC002 | Blocking calls in async functions |
| ASYNC003 | Fire-and-forget tasks without error handling |

### Performance Issues (PERF001)

| Rule | Issue |
|------|-------|
| PERF001 | N+1 queries in loops |

### Project Issues (PROJ001-PROJ003)

Project setup and configuration checks:

| Rule | Issue |
|------|-------|
| PROJ001 | Missing CLAUDE.md file for AI context |
| PROJ002 | Not using git version control |
| PROJ003 | Missing pyright configuration |

### Structure Issues (STRUCT001-STRUCT010)

Code organization problems:

| Rule | Issue |
|------|-------|
| STRUCT001 | Multiple classes in one file |
| STRUCT003 | Imports inside functions |
| STRUCT004 | sys.path manipulation |
| STRUCT005 | Relative imports |
| STRUCT006 | hasattr/getattr on typed fields |
| STRUCT009 | Class name doesn't match filename |
| STRUCT010 | Mixed frontend/backend code |

### Type Safety Issues (TYPE001-TYPE009)

Type annotation problems:

| Rule | Issue |
|------|-------|
| TYPE001 | Weak typing (Dict[str, Any]) |
| TYPE002 | Naked dict for structured data |
| TYPE004 | Missing type hints |
| TYPE006 | Inline type definitions |
| TYPE007 | Duplicate type definitions |
| TYPE008 | TypeScript 'any' usage |
| TYPE009 | Env var non-null assertions |

### Testing Issues (TEST001-TEST004)

Test quality problems:

| Rule | Issue |
|------|-------|
| TEST001 | Skipped tests |
| TEST003 | Async mock issues |
| TEST004 | Duplicate test helpers |

### Session Issues (SESS001)

Database session problems:

| Rule | Issue |
|------|-------|
| SESS001 | DB session passed to background tasks |

### Datetime Issues (DATE002-DATE003)

Timezone problems:

| Rule | Issue |
|------|-------|
| DATE002 | Naive datetime (no timezone) |
| DATE003 | DB datetime used without timezone check |

### Kubernetes Issues (KUBE001)

Container compatibility:

| Rule | Issue |
|------|-------|
| KUBE001 | Local filesystem for app data |

### Import Issues (IMPORT001)

Import problems:

| Rule | Issue |
|------|-------|
| IMPORT001 | Imports shadowing builtins |

### Rate Limiting Issues (RATE001)

API protection:

| Rule | Issue |
|------|-------|
| RATE001 | Missing rate limiting on endpoints |

### Frontend Issues (FRONT002-FRONT003)

React/Next.js issues:

| Rule | Issue |
|------|-------|
| FRONT002 | window/document without SSR check |
| FRONT003 | Inline arrow functions in JSX |

## Example Output

```
src/cache.py

  ⚠ Line 42: Looping through 'config.items()' without sorting. This may produce different results on different runs.

    Problem:
      for key, value in config.items():

    Fix:
      for key, value in sorted(config.items()):

    Why? Dictionary order isn't guaranteed to be the same every time your program runs.
    This can cause tests to pass sometimes and fail other times, and can break caching
    systems that depend on consistent output.

────────────────────────────────────────────────────────────
Found 1 warning in 1 file
```

## Configuration

Configure vibecheck in your `pyproject.toml`:

```toml
[tool.vibecheck]
# Enable only specific rules
enable = ["DET001", "DET002", "SEC001", "SEC002"]

# Or disable specific rules
disable = ["QUAL005", "QUAL006"]

# Path patterns
include = ["src/**/*.py"]
exclude = ["**/migrations/**", "**/test_*.py"]

# Override severity for specific rules
[tool.vibecheck.rules.DET001]
severity = "info"  # Downgrade from warning to info
```

## CLI Options

```
Usage: vibecheck [OPTIONS] [PATHS]...

Options:
  -f, --format [text|json]  Output format (default: text)
  -c, --config PATH         Path to pyproject.toml config file
  --enable TEXT             Comma-separated list of rule IDs to enable
  --disable TEXT            Comma-separated list of rule IDs to disable
  --ci                      CI mode: exit with code 1 if any errors found
  --no-color                Disable colored output
  --no-why                  Don't show 'why this matters' explanations
  -v, --version             Show version and exit
  --help                    Show this message and exit
```

## Why vibecheck?

AI coding assistants are amazing, but they sometimes generate code with subtle issues:

- **Non-deterministic patterns** that work during development but break LLM caching and cause flaky tests
- **Security vulnerabilities** like hardcoded secrets and SQL injection
- **Silent failures** that hide bugs until production
- **Async mistakes** like missing await that cause hard-to-debug issues
- **Type safety issues** that bypass IDE checking
- **Kubernetes-hostile patterns** that break in containers

vibecheck catches these patterns that traditional linters miss.

**Key benefits:**
- Improve LLM cache hit rates from 30% to 95%+
- Eliminate flaky tests caused by non-determinism
- Catch security issues before they reach git history
- Beginner-friendly explanations for every issue
- Sensible pyright configuration recommendations

## Language Support

- **Python** (.py) - All 71 rules
- **TypeScript/JavaScript** (.ts, .tsx, .js, .jsx) - 29 rules:
  - DET: Random without seed, datetime.now() usage
  - QUAL: Exception swallowing, file length
  - API: Unhandled errors, naming, headers, URLs
  - SEC: Secrets, SQL injection, eval, insecure random, XSS, webhooks
  - ASYNC: Missing await, blocking calls (fs.readFileSync, execSync, etc.)
  - TYPE: TypeScript any, env non-null assertions, unsafe JSON parsing
  - FRONT: SSR safety, inline JSX handlers
  - TEST: Skipped tests (Jest, Vitest, Playwright, Mocha)
  - PERF: N+1 queries (Prisma, TypeORM, Sequelize, Mongoose, Drizzle)
  - RATE: Missing rate limiting on endpoints
  - KUBE: Local filesystem data storage
- **Project-level** - PROJ rules check any directory

## Documentation

- [CHECKERS.md](CHECKERS.md) - Complete reference for all 71 rules
- [MARKETING.md](MARKETING.md) - Value propositions and ROI analysis

## Development Setup

### Secrets Management

This project uses [Doppler](https://doppler.com) for secrets management:

```bash
# Install Doppler CLI
brew install dopplerhq/cli/doppler

# Login (creates scoped credentials for this directory)
doppler login --scope /path/to/vibecheck

# Setup the project (uses doppler.yaml config)
doppler setup

# Run commands with secrets injected
doppler run -- python -m pytest
doppler run -- vibecheck src/
```

Ask a team member to invite you to the CTS workspace in Doppler.

## Contributing

Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

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