Metadata-Version: 2.4
Name: stablestack
Version: 0.3.29
Summary: Catch the subtle bugs AI assistants introduce. Linter for Python, JavaScript, TypeScript, and C# (including Unity).
Project-URL: Homepage, https://stablestack.ai
Project-URL: Documentation, https://stablestack.ai/docs
Project-URL: Repository, https://github.com/pfrank8/vibecheck
Author: StableStack
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,csharp,determinism,linter,static-analysis,typescript,unity
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.9
Requires-Dist: click>=8.0
Requires-Dist: libcst>=1.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: pdf
Requires-Dist: reportlab>=4.0; extra == 'pdf'
Provides-Extra: watch
Requires-Dist: watchdog>=3.0; extra == 'watch'
Description-Content-Type: text/markdown

# StableStack

**Catch the subtle bugs AI assistants introduce.**

A lightweight linter that catches issues traditional linters miss — non-determinism that breaks LLM caching, silent exception swallowing, async mistakes, SSR pitfalls, and more. **146 rules across 23 categories**, with first-class support for Python, JavaScript/TypeScript, and C# (including Unity).

<!-- Rule counts are generated from the checker registry — see stablestack/scripts/gen_check_counts.py (output: site/src/lib/checks-counts.json). -->


Marketing site: [stablestack.ai](https://stablestack.ai)

## Install

```bash
# Python (recommended)
pip install stablestack

# Node.js — thin wrapper around the pip package
npx stablestack
```

After upgrading, pin the version — pip caches aggressively:

```bash
pip install stablestack==0.3.26
```

## Quick Start

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

# Check specific files
stablestack app.py utils.py

# CI mode (exit 1 on errors)
stablestack src/ --ci

# JSON output
stablestack src/ --format json > results.json

# Only run critical rules
stablestack src/ --tier critical

# List every available rule
stablestack --list-rules

# Explain a specific rule
stablestack explain DET001
```

## Claude Code Integration

StableStack ships opt-in Claude Code slash commands. Run once per repo:

```bash
stablestack init                 # pyproject.toml + .stablestackignore + /check, /fix-production slash commands
stablestack init --minimal       # just pyproject.toml
stablestack init --no-commands   # skip the slash commands
```

After `init`, inside Claude Code you can use:

- **`/check`** — run StableStack and fix findings
- **`/fix-production`** — detect your CI/CD platform, monitor builds, and keep fixing until production is green

StableStack never writes files to your repo unless you run `init` explicitly.

## Workflow Blueprints

Beyond checking code, StableStack scaffolds the process around it:

```bash
stablestack add-ci           # CI + deploy pipelines, detected from your repo
stablestack add-playwright   # starter E2E suite with anti-flake rules baked in
```

`add-ci` reads the repo before it writes — package manager (with a
`--package-manager` override when multiple lockfiles make it ambiguous),
typecheck/test/lint scripts, Prisma, Python/pytest, your deploy platform
(Vercel, Amplify, Netlify, Render, Fly, Docker), and any CI that already
exists. It refuses to write GitHub Actions into a GitLab/Bitbucket/CircleCI
repo and leaves existing deploy workflows untouched. It generates:

- **`ci.yml`** — the PR gate: lint, typecheck, unit tests, the StableStack
  quality gate (baseline-aware, so legacy code adopts today), and E2E if a
  suite exists. Red blocks the merge.
- **`deploy-staging.yml`** — every push to `main` lands on staging; a polling
  health check verifies the *deployed* site (never just the deploy's exit
  code) and the Playwright suite runs against the deployed staging URL.
- **`deploy-production.yml`** — ships when the `production` branch advances.
  Promotion is a fast-forward (`git push origin main:production`), or
  automatic after green staging E2E with `--auto-promote`. Uses GitHub's
  `production` environment, so adding required reviewers gives an approval
  gate. Verifies the live site and tags every deploy.

Platforms that auto-deploy on push (Vercel & co.) get verify-only jobs
instead of duplicate deploys; anything else gets a deploy step that fails
loudly until you wire in your deploy command.

`add-playwright` writes a config plus three starter specs: every core page
renders with zero console errors, the sitemap contract, and a money-path
template. Setting `BASE_URL` points the same suite at a deployed
environment — that's what the staging E2E job does.

Both are one-shot generators: the output is plain YAML/TypeScript in your
repo, yours to edit.

## Language Support

| Language | Extensions | Notes |
|----------|------------|-------|
| Python | `.py` | Primary language, most checkers |
| TypeScript / JavaScript | `.ts`, `.tsx`, `.js`, `.jsx`, `.vue` | Frontend + backend (Next.js, tRPC, Prisma, React) |
| C# | `.cs` | .NET and Unity — includes 3 Unity-specific checkers (async void, Debug.Log in production, expensive lookups in Update loops) |
| Go, Rust, Ruby | `.go`, `.rs`, `.rb` | Partial coverage (hardcoded secrets, exception swallowing) |

## What It Catches

Full reference: `stablestack --list-rules`

| Category | Prefix | Rules | Example concerns |
|----------|--------|-------|------------------|
| Quality | QUAL | 19 | Exception swallowing, mutable defaults, magic numbers, complexity, print statements |
| Security | SEC | 16 | Hardcoded secrets, SQL injection, eval(), XSS, CSRF, email header injection |
| Type Safety | TYPE | 15 | Weak typing, `any`, env non-null assertions, unsafe JSON parsing |
| Frontend | FRONT | 13 | SSR-unsafe `window`, inline JSX handlers, stale time, unbounded AI output |
| Structure | STRUCT | 10 | Multiple classes per file, sys.path hacks, mixed frontend/backend code |
| Testing | TEST | 10 | Skipped tests, Playwright timing issues, duplicate test helpers |
| Determinism | DET | 9 | Unsorted iteration, `datetime.now()`, `random` without seed, uncached LLM calls |
| Project | PROJ | 8 | Missing CLAUDE.md, missing pyright config, beta dependencies, low test coverage |
| API | API | 7 | Unhandled errors, inconsistent naming, missing Content-Type, untyped responses |
| Performance | PERF | 7 | N+1 queries, render-blocking fonts, uninstrumented LLM calls |
| Memory | MEM | 4 | Unbounded queries, in-process accumulators, global singletons |
| Async | ASYNC | 4 | Missing await, blocking calls in async, fire-and-forget, silent `.catch()` |
| tRPC | TRPC | 4 | Procedures without input validation, inline Zod schemas |
| Datetime | DATE | 3 | Naive datetimes, DB timezone mismatches |
| C# | CS | 3 | `async void`, Debug.Log in production, expensive lookups in Unity Update |
| Concurrency | CONC | 2 | Check-then-act races, non-atomic read/write |
| Kubernetes | KUBE | 2 | Local filesystem storage, missing SSL redirect |
| Migrations | MIG | 2 | Alembic revision ids over VARCHAR(32), deploy scripts that mask migration failures |
| Rate Limiting | RATE | 2 | Missing rate limits, in-memory rate limiter |
| Schema | SCHEMA | 2 | Pydantic nullability, Pydantic/SQLAlchemy field mismatches |
| Session | SESS | 2 | DB session passed to background tasks, thread safety |
| Accessibility | A11Y | 1 | Button contrast |
| Imports | IMPORT | 1 | Imports shadowing builtins |

## Free vs. Paid Tiers

- **Free (24 rules)** — always available, no license required. Covers critical security, schema, project setup, quality, structure, async, API, and C# checkers.
- **Paid (122 rules)** — unlocked with `stablestack activate <license-key>`. Buy a license at [stablestack.ai](https://stablestack.ai).

Pricing and features: [stablestack.ai/pricing](https://stablestack.ai/pricing).

## 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 StableStack in your `pyproject.toml`:

```toml
[tool.stablestack]
# Enable only specific rules (empty = all enabled)
enable = []

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

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

# Override severity per rule
[tool.stablestack.rules.DET001]
severity = "info"
```

You can also add a `.stablestackignore` file (glob patterns, one per line) for paths the checker should skip.

## CLI Options (essentials)

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

Options:
  -f, --format [text|json|claude]  Output format (default: text)
  -c, --config PATH                Path to pyproject.toml config
  --enable TEXT                    Comma-separated rule IDs to enable
  --disable TEXT                   Comma-separated rule IDs to disable
  --ci                             Exit 1 if any errors found
  -t, --tier [critical|recommended|optional|preference]
                                   Run ONLY rules from this tier
  -u, --up-to [critical|recommended|optional|preference]
                                   Run rules up to and including this tier
  --list-rules                     List all available rules and exit
  --stats                          Show codebase statistics
  --baseline PATH                  Only report issues not in baseline
  --generate-baseline              Generate a baseline file
  --fix                            Automatically fix issues where possible
  --dry-run                        Show what --fix would do
  -w, --watch                      Watch for changes and re-run
  --top INTEGER                    Show only the top N findings
  --help                           Show full help

Subcommands:
  stablestack init       Install Claude Code commands and config files
  stablestack explain    Explain a specific rule (e.g. `stablestack explain DET001`)
  stablestack activate   Activate a paid license key
```

## Why StableStack?

AI coding assistants are fast, but they ship patterns traditional linters don't catch:

- **Non-determinism** that breaks LLM caching and causes flaky tests
- **Hardcoded secrets** that slip into git history before review
- **Silent exception swallowing** that hides production bugs
- **Missing `await`** on async calls that return without doing any work
- **SSR-unsafe code** that crashes in Next.js production builds
- **Unity anti-patterns** like `GameObject.Find` in `Update()` loops that kill frame rates
- **Weak types** (`any`, `Dict[str, Any]`) that bypass IDE checking

StableStack focuses specifically on the shape of bugs AI assistants generate.

## Repository Structure

| Directory | Description |
|-----------|-------------|
| `/stablestack` | Core product — the Python CLI and analysis engine (published to PyPI) |
| `/npm-package` | Thin Node.js wrapper that shells out to the Python CLI (`npx stablestack`) |
| `/nuget-package` | Prototype `dotnet tool` wrapper for .NET / Unity developers (not yet published) |
| `/site` | Marketing site at [stablestack.ai](https://stablestack.ai) (Next.js) |
| `/infrastructure/license-api` | AWS Lambda API for license validation + anonymous telemetry (Terraform) |

## Development Setup

### Running tests

```bash
cd stablestack
PYTHONPATH=src python -m pytest tests/ -v
```

### Running the site locally

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

### Secrets management

This project uses [Doppler](https://doppler.com) for secrets. Never commit `.env` files.

```bash
brew install dopplerhq/cli/doppler
doppler login --scope /path/to/vibecheck
doppler setup

# Run commands with secrets injected
doppler run -- stablestack src/
```

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

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT — see [LICENSE](LICENSE).
