ubs

UBS - Ultimate Bug Scanner

Static analysis tool built for AI coding workflows. Catches bugs that AI agents commonly introduce: null safety, async/await issues, security holes, memory leaks. Scans JS/TS, Python, Go, Rust, Java, C++, Ruby, Swift in 3-5 seconds.

Why This Exists

AI agents move fast. Bugs move faster. You're shipping features in minutes, but:

• Null pointer crashes slip through
• Missing await causes silent failures
• XSS vulnerabilities reach production
• Memory leaks accumulate

UBS is the quality gate: scan before commit, fix before merge.

Golden Rule

ubs <changed-files> --fail-on-warning

Exit 0 = safe to commit. Exit 1 = fix and re-run.

Essential Commands

Quick Scans (Use These)

ubs file.ts file2.py                    # Specific files (< 1s)
ubs $(git diff --name-only --cached)    # Staged files
ubs --staged                            # Same, cleaner syntax
ubs --diff                              # Working tree vs HEAD

Full Project Scans

ubs .                                   # Current directory
ubs /path/to/project                    # Specific path
ubs --only=js,python src/               # Language filter (faster)

CI/CD Mode

ubs --ci --fail-on-warning .            # Strict mode for CI
ubs --format=json .                     # Machine-readable
ubs --format=sarif .                    # GitHub code scanning

Output Format

⚠️  Category (N errors)
    file.ts:42:5 – Issue description
    💡 Suggested fix
Exit code: 1

Parse: file:line:col → location | 💡 → how to fix | Exit 0/1 → pass/fail

The 18 Detection Categories

Critical (Always Fix)

| Category | What It Catches | |----------|-----------------| | Null Safety | Unguarded property access, missing null checks | | Security | XSS, injection, prototype pollution, hardcoded secrets | | Async/Await | Missing await, unhandled rejections, race conditions | | Memory Leaks | Event listeners without cleanup, timer leaks | | Type Coercion | == vs ===, parseInt without radix, NaN comparison |

Important (Production Risk)

| Category | What It Catches | |----------|-----------------| | Division Safety | Division without zero check | | Resource Lifecycle | Unclosed files, connections, context managers | | Error Handling | Empty catch blocks, swallowed errors | | Promise Chains | .then() without .catch() | | Array Mutations | Mutating during iteration |

Code Quality (Contextual)

| Category | What It Catches | |----------|-----------------| | Debug Code | console.log, debugger, print() statements | | TODO Markers | TODO, FIXME, HACK comments | | Type Safety | TypeScript any usage | | Readability | Complex ternaries, deep nesting |

Language-Specific Detection

| Language | Key Patterns | |----------|-------------| | JavaScript/TypeScript | innerHTML XSS, eval(), missing await, React hooks deps | | Python | eval(), open() without with, missing encoding=, None checks | | Go | Nil pointer, goroutine leaks, defer symmetry, context cancel | | Rust | .unwrap() panics, unsafe blocks, Option handling | | Java | Resource leaks (try-with-resources), null checks, JDBC | | C/C++ | Buffer overflows, strcpy(), memory leaks, use-after-free | | Ruby | eval(), send(), instance_variable_set | | Swift | Force unwrap (!), ObjC bridging issues |

Profiles

ubs --profile=strict .    # Fail on warnings, enforce high standards
ubs --profile=loose .     # Skip TODO/debug nits when prototyping

Category Packs (Focused Scans)

ubs --category=resource-lifecycle .    # Python/Go/Java resource hygiene

Narrows scan to relevant languages and suppresses unrelated categories.

Comparison Mode (Regression Detection)

# Capture baseline
ubs --ci --report-json .ubs/baseline.json .

# Compare against baseline
ubs --ci --comparison .ubs/baseline.json --report-json .ubs/latest.json .

Useful for CI to detect regressions vs. main branch.

Output Formats

| Format | Flag | Use Case | |--------|------|----------| | text | (default) | Human-readable terminal output | | json | --format=json | Machine parsing, scripting | | jsonl | --format=jsonl | Line-delimited, streaming | | sarif | --format=sarif | GitHub code scanning | | html | --html-report=file.html | PR attachments, dashboards |

Inline Suppression

When a finding is intentional:

eval(trustedCode);  // ubs:ignore

// ubs:ignore-next-line
dangerousOperation();

Exit Codes

| Code | Meaning | |------|---------| | 0 | No critical issues (safe to commit) | | 1 | Critical issues or warnings (with --fail-on-warning) | | 2 | Environment error (missing ast-grep, etc.) |

Doctor Command

ubs doctor                # Check environment
ubs doctor --fix          # Auto-fix missing dependencies

Checks: curl/wget, ast-grep, ripgrep, jq, typos, Node.js + TypeScript.

Agent Integration

UBS auto-configures hooks for coding agents during install:

| Agent | Hook Location | |-------|---------------| | Claude Code | .claude/hooks/on-file-write.sh | | Cursor | .cursor/rules | | Codex CLI | .codex/rules/ubs.md | | Gemini | .gemini/rules | | Windsurf | .windsurf/rules | | Cline | .cline/rules |

Claude Code Hook Pattern

#!/bin/bash
# .claude/hooks/on-file-write.sh
if [[ "$FILE_PATH" =~ \.(js|jsx|ts|tsx|py|go|rs|java|rb)$ ]]; then
  echo "🔬 Quality check running..."
  if ubs "${PROJECT_DIR}" --ci 2>&1 | head -30; then
    echo "✅ No critical issues"
  else
    echo "⚠️  Issues detected - review above"
  fi
fi

Git Pre-Commit Hook

#!/bin/bash
# .git/hooks/pre-commit
echo "🔬 Running bug scanner..."
if ! ubs . --fail-on-warning 2>&1 | tail -30; then
  echo "❌ Critical issues found. Fix or: git commit --no-verify"
  exit 1
fi
echo "✅ Quality check passed"

Performance

Small (5K lines):     0.8 seconds
Medium (50K lines):   3.2 seconds
Large (200K lines):   12 seconds
Huge (1M lines):      58 seconds

10,000+ lines per second. Use --jobs=N to control parallelism.

Speed Tips

1. Scope to changed files: ubs src/file.ts (< 1s) vs ubs . (30s)
2. Use --staged or --diff: Only scan what you're committing
3. Language filter: --only=js,python skips irrelevant scanners
4. Skip categories: --skip=11,14 to skip debug/TODO markers

Fix Workflow

1. Read finding → category + fix suggestion
2. Navigate file:line:col → view context
3. Verify real issue (not false positive)
4. Fix root cause (not symptom)
5. Re-run ubs <file> → exit 0
6. Commit

Bug Severity Guide

• Critical (always fix): Null safety, XSS/injection, async/await, memory leaks
• Important (production): Type narrowing, division-by-zero, resource leaks
• Contextual (judgment): TODO/FIXME, console logs

Common Anti-Patterns

| Don't | Do | |-------|-----| | Ignore findings | Investigate each | | Full scan per edit | Scope to changed files | | Fix symptom (if (x) { x.y }) | Fix root cause (x?.y) | | Suppress without understanding | Verify false positive first |

Installation

# One-liner (recommended)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" | bash -s -- --easy-mode

# Manual
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/ubs \
  -o /usr/local/bin/ubs && chmod +x /usr/local/bin/ubs

Custom AST Rules

mkdir -p ~/.config/ubs/rules

cat > ~/.config/ubs/rules/no-console.yml <<'EOF'
id: custom.no-console
language: javascript
rule:
  pattern: console.log($$$)
severity: warning
message: "Remove console.log before production"
EOF

ubs . --rules=~/.config/ubs/rules

Excluding Paths

ubs . --exclude=legacy,generated,vendor

Auto-ignored: node_modules, .venv, dist, build, target, editor caches.

Session Logs

ubs sessions --entries 1    # View latest install session

Integration with Flywheel

| Tool | Integration | |------|-------------| | BV | --beads-jsonl=out.jsonl exports findings for Beads | | CASS | Search past sessions for similar bug patterns | | CM | Extract rules from UBS findings | | Agent Mail | Notify agents of scan results | | DCG | UBS runs inside DCG protection |

Troubleshooting

| Error | Fix | |-------|-----| | "Environment error" (exit 2) | ubs doctor --fix | | "ast-grep not found" | brew install ast-grep or cargo install ast-grep | | Too many false positives | Use --skip=N or // ubs:ignore | | Slow scans | Scope to files: ubs <file> not ubs . |