ubs

UBS - Ultimate Bug Scanner

AI コーディングワークフロー向けに構築された静的解析ツールです。AI エージェントがよく引き起こすバグ、つまり null 安全性、async/await の問題、セキュリティホール、メモリーリークを検出します。JS/TS、Python、Go、Rust、Java、C++、Ruby、Swift を 3～5 秒でスキャンします。

これが必要な理由

AI エージェントは速く動きます。バグはさらに速く発生します。数分で機能をリリースする一方で、次の問題が起こり得ます。

• Null ポインターによるクラッシュを見逃す
• await の欠落によって、気付かないうちに失敗する
• XSS の脆弱性が本番環境に到達する
• メモリーリークが蓄積する

UBS は品質ゲートです。コミット前にスキャンし、マージ前に修正します。

基本ルール

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

終了コード 0 = 安全にコミットできます。終了コード 1 = 修正して再実行してください。

基本コマンド

クイックスキャン（こちらを使用）

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

プロジェクト全体のスキャン

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

CI/CD モード

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

出力形式

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

解析方法：file:line:col → 場所 | 💡 → 修正方法 | 終了コード 0/1 → 合格／不合格

18 の検出カテゴリ

重大（必ず修正）

カテゴリ	検出する内容
Null 安全性	ガードされていないプロパティアクセス、null チェックの欠落
セキュリティ	XSS、インジェクション、プロトタイプ汚染、ハードコードされたシークレット
Async/Await	await の欠落、未処理の拒否、競合状態
メモリーリーク	クリーンアップされないイベントリスナー、タイマーリーク
型強制	== と === の違い、基数を指定しない parseInt、NaN の比較

重要（本番環境でのリスク）

カテゴリ	検出する内容
除算の安全性	0 チェックのない除算
リソースのライフサイクル	閉じられていないファイルや接続、コンテキストマネージャー
エラー処理	空の catch ブロック、握りつぶされたエラー
Promise チェーン	.catch() のない .then()
配列の変更	反復処理中の変更

コード品質（状況による）

カテゴリ	検出する内容
デバッグコード	console.log、debugger、print() 文
TODO マーカー	TODO、FIXME、HACK コメント
型安全性	TypeScript での any の使用
可読性	複雑な三項演算子、深いネスト

言語別の検出

言語	主なパターン
JavaScript/TypeScript	innerHTML による XSS、eval()、await の欠落、React フックの依存関係
Python	eval()、with を使わない open()、encoding= の欠落、None チェック
Go	Nil ポインター、ゴルーチンリーク、defer の対称性、コンテキストのキャンセル
Rust	.unwrap() によるパニック、unsafe ブロック、Option の処理
Java	リソースリーク（try-with-resources）、null チェック、JDBC
C/C++	バッファーオーバーフロー、strcpy()、メモリーリーク、解放後使用
Ruby	eval()、send()、instance_variable_set
Swift	強制アンラップ（!）、Objective-C ブリッジングの問題

プロファイル

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

カテゴリパック（対象を絞ったスキャン）

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

関連する言語にスキャン対象を絞り、無関係なカテゴリを除外します。

比較モード（リグレッション検出）

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

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

CI で main ブランチと比較してリグレッションを検出するのに便利です。

出力形式

形式	フラグ	用途
text	（デフォルト）	人が読みやすいターミナル出力
json	--format=json	機械処理、スクリプト
jsonl	--format=jsonl	行区切り、ストリーミング
sarif	--format=sarif	GitHub のコードスキャン
html	--html-report=file.html	PR の添付ファイル、ダッシュボード

インライン抑制

検出結果が意図的なものである場合：

eval(trustedCode);  // ubs:ignore

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

終了コード

コード	意味
0	重大な問題なし（安全にコミットできます）
1	重大な問題または警告あり（--fail-on-warning を指定した場合）
2	環境エラー（ast-grep がない場合など）

Doctor コマンド

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

チェック対象：curl/wget、ast-grep、ripgrep、jq、typos、Node.js + TypeScript。

エージェントとの連携

UBS はインストール時に、コーディングエージェント用のフックを自動設定します。

エージェント	フックの場所
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 のフックパターン

#!/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 のコミット前フック

#!/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"

パフォーマンス

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

1 秒あたり 10,000 行以上を処理します。--jobs=N を使って並列処理数を制御します。

速度を上げるヒント

1. 変更したファイルに対象を絞る：ubs src/file.ts（1 秒未満）と ubs .（30 秒）
2. --staged または --diff を使う：コミットする内容だけをスキャンします
3. 言語で絞り込む：--only=js,python を指定すると、無関係なスキャナーをスキップできます
4. カテゴリをスキップする：--skip=11,14 でデバッグ／TODO マーカーをスキップします

修正ワークフロー

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

バグの重大度ガイド

• 重大（必ず修正）：ヌル安全性、XSS／インジェクション、async／await、メモリーリーク
• 重要（本番環境向け）：型の絞り込み、ゼロ除算、リソースリーク
• 状況による（判断が必要）：TODO／FIXME、コンソールログ

よくあるアンチパターン

避けること	推奨すること
指摘を無視する	それぞれ調査する
編集のたびに全体をスキャンする	変更したファイルに対象を絞る
症状を修正する（if (x) { x.y }）	根本原因を修正する（x?.y）
理解せずに抑制する	まず誤検知かどうか確認する

インストール

# 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

カスタム AST ルール

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

パスの除外

ubs . --exclude=legacy,generated,vendor

自動的に無視されるパス：node_modules、.venv、dist、build、target、エディターのキャッシュ。

セッションログ

ubs sessions --entries 1    # View latest install session

Flywheel との連携

ツール	連携方法
BV	--beads-jsonl=out.jsonl で Beads 用に指摘をエクスポートします
CASS	過去のセッションから類似するバグパターンを検索します
CM	UBS の指摘からルールを抽出します
Agent Mail	スキャン結果をエージェントに通知します
DCG	UBS は DCG の保護下で実行されます

トラブルシューティング

エラー	対処方法
"Environment error"（終了コード 2）	ubs doctor --fix
"ast-grep not found"	brew install ast-grep または cargo install ast-grep
誤検知が多すぎる	--skip=N または // ubs:ignore を使います
スキャンが遅い	ubs . ではなく、ubs <file> のようにファイルに対象を絞ります