zwischen 0.1.0

data/TESTING.md

@@ -0,0 +1,374 @@
+# Zwischen End-to-End Testing
+
+This guide verifies Zwischen as an installed Ruby gem, not from source. The installed-gem path matters because end users run the generated executable and packaged files.
+
+Run the tests from a temporary directory outside the repository, such as `/tmp/zwischen-test-*`.
+
+## Install the Gem Under Test
+
+```bash
+cd /path/to/zwischen
+./scripts/test_as_gem.sh
+
+export PATH="$HOME/.local/share/gem/ruby/$(ruby -e 'puts RUBY_VERSION[/\d+\.\d+/]')/bin:$PATH"
+
+which zwischen
+zwischen --help
+```
+
+Expected:
+
+- `which zwischen` points at the user gem bin path, not this repository's `bin/zwischen`.
+- `zwischen --help` lists `doctor`, `init`, `scan`, and `uninstall`.
+
+## Test Suite 1: Installation and Init
+
+### Test 1.1: Gem Installation
+
+```bash
+gem list zwischen
+gem which zwischen
+zwischen --help
+```
+
+Expected:
+
+- `gem list zwischen` includes the version under test.
+- `gem which zwischen` resolves to the installed gem.
+- Help exits successfully without opening a pager.
+
+### Test 1.2: Init in a Git Repository
+
+```bash
+TEST_DIR=$(mktemp -d -t zwischen-test-XXXXXX)
+cd "$TEST_DIR"
+mkdir test-repo && cd test-repo
+git init
+git config user.email test@example.com
+git config user.name "Zwischen Test"
+printf "# Test\n" > README.md
+git add README.md
+git commit -m "Initial"
+zwischen init
+```
+
+Expected:
+
+- `.zwischen.yml` exists.
+- `.git/hooks/pre-push` exists and is executable.
+- The hook contains `Zwischen pre-push hook`.
+- `~/.zwischen/bin/gitleaks` exists when auto-install succeeds, or `zwischen init` prints the manual install command when it cannot auto-install.
+- `~/.zwischen/credentials` is created only when `ANTHROPIC_API_KEY` was set before running `zwischen init`.
+
+### Test 1.3: Config Structure
+
+```bash
+ruby -ryaml -e 'p YAML.safe_load(File.read(".zwischen.yml")).keys'
+zwischen doctor
+```
+
+Expected:
+
+- Config includes `ai`, `blocking`, `scanners`, and `ignore`.
+- `zwischen doctor` reports Gitleaks status and Semgrep status without crashing.
+
+## Test Suite 2: Pre-Push Hook
+
+### Test 2.1: Clean Push Path
+
+```bash
+printf "def hello():\n    pass\n" > test.py
+git add test.py
+git commit -m "Add clean file"
+.git/hooks/pre-push
+echo $?
+```
+
+Expected:
+
+- Hook exits `0`.
+- Hook is silent when no changed files or no blocking findings are detected.
+
+### Test 2.2: Blocking Finding
+
+```bash
+cat > config.env <<'EOF'
+AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+EOF
+git add config.env
+git commit -m "Add secret"
+.git/hooks/pre-push
+echo $?
+```
+
+Expected:
+
+- Hook exits `1` when Gitleaks maps the finding to `high` or `critical`.
+- Compact output starts with `Zwischen:` and lists severity, file, line, and message.
+- Output includes the push-blocked guidance.
+
+### Test 2.3: Bypass Mechanisms
+
+Expected:
+
+- `git push --no-verify` bypasses Git hooks.
+- `ZWISCHEN_SKIP=1 .git/hooks/pre-push` exits `0`.
+
+## Test Suite 3: Manual Scan Commands
+
+### Test 3.1: Standard Scan
+
+```bash
+zwischen scan
+echo $?
+```
+
+Expected:
+
+- Prints the scanning banner and full terminal report when findings exist.
+- Exits `1` when findings meet the configured blocking severity.
+- Exits `0` when no blocking findings exist.
+
+### Test 3.2: JSON Output
+
+```bash
+zwischen scan --format json
+```
+
+Expected:
+
+- Prints valid JSON with `summary` and `findings`.
+- Exit code still reflects configured blocking behavior.
+
+### Test 3.3: Scanner Selection
+
+```bash
+zwischen scan --only secrets
+zwischen scan --only sast
+zwischen scan --only secrets,sast
+```
+
+Expected:
+
+- `secrets` selects Gitleaks.
+- `sast` selects Semgrep.
+- Missing scanners are skipped with a warning outside pre-push mode.
+
+### Test 3.4: Changed Files Filtering
+
+```bash
+cat > changed.env <<'EOF'
+AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+EOF
+git add changed.env
+git commit -m "Add changed secret"
+
+cat > uncommitted.env <<'EOF'
+AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+EOF
+zwischen scan --pre-push
+```
+
+Expected:
+
+- Pre-push mode only reports findings from files returned by `GitDiff.changed_files`.
+- Uncommitted files outside that diff are not reported.
+
+## Test Suite 4: Blocking Configuration
+
+### Test 4.1: Default Blocking
+
+```yaml
+blocking:
+  severity: high
+```
+
+Expected:
+
+- `critical` and `high` findings block.
+- `medium`, `low`, and `info` findings do not block.
+
+### Test 4.2: Critical Only
+
+```yaml
+blocking:
+  severity: critical
+```
+
+Expected:
+
+- `critical` findings block.
+- `high` findings do not block.
+
+### Test 4.3: No Blocking
+
+```yaml
+blocking:
+  severity: none
+```
+
+Expected:
+
+- Findings may be reported.
+- Scan exits `0`.
+- Pre-push hook allows the push.
+
+## Test Suite 5: Uninstall
+
+### Test 5.1: Remove Zwischen Hook
+
+```bash
+zwischen uninstall
+# Answer y for hook removal.
+# Answer n for config removal unless testing config deletion.
+# Answer n for credentials removal unless testing credentials deletion.
+```
+
+Expected:
+
+- Zwischen hook is removed.
+- `.zwischen.yml` is preserved when answering `n`.
+- `~/.zwischen/credentials` is preserved when answering `n`.
+
+### Test 5.2: Preserve Non-Zwischen Hook
+
+```bash
+printf "#!/bin/sh\nprintf 'custom hook\\n'\n" > .git/hooks/pre-push
+chmod +x .git/hooks/pre-push
+zwischen uninstall
+```
+
+Expected:
+
+- Custom hook remains because it does not contain the Zwischen marker.
+- Uninstall reports that no Zwischen hook was found.
+
+## Test Suite 6: Edge Cases
+
+### Test 6.1: No Git Repository
+
+```bash
+NO_GIT_DIR=$(mktemp -d -t zwischen-no-git-XXXXXX)
+cd "$NO_GIT_DIR"
+zwischen init
+```
+
+Expected:
+
+- Config is created.
+- Hook installation is skipped with a warning.
+
+### Test 6.2: Existing Pre-Push Hook
+
+```bash
+cd "$TEST_DIR/test-repo"
+printf "#!/bin/sh\nprintf 'existing hook\\n'\n" > .git/hooks/pre-push
+chmod +x .git/hooks/pre-push
+zwischen init
+```
+
+Expected for the current Ruby implementation:
+
+- Existing hook is copied to `.git/hooks/pre-push.zwischen.backup` or a timestamped variant.
+- New Zwischen hook replaces `.git/hooks/pre-push`.
+
+
+### Test 6.3: Default Branch Detection
+
+Expected:
+
+- Remote `origin` HEAD is preferred when available.
+- Local `main` is used before local `master`.
+- `HEAD` is the final fallback.
+
+## Test Suite 7: AI Integration
+
+### Test 7.1: Claude
+
+```bash
+ANTHROPIC_API_KEY=... zwischen scan --ai claude
+```
+
+Expected:
+
+- AI analysis runs after scanner findings are aggregated.
+- Findings may include fix suggestions and risk explanations.
+- AI failures fall back to original findings without aborting the scan.
+
+### Test 7.2: Ollama
+
+```bash
+ollama pull llama3
+ollama serve
+zwischen scan --ai ollama
+```
+
+Expected:
+
+- Ollama analysis runs against the configured local URL.
+- If Ollama is not running, scan continues without AI and prints an AI warning outside pre-push mode.
+
+### Test 7.3: AI Disabled for Pre-Push
+
+```yaml
+ai:
+  enabled: true
+  pre_push_enabled: false
+```
+
+Expected:
+
+- Manual `zwischen scan` can use AI.
+- `zwischen scan --pre-push` does not use AI unless `pre_push_enabled` is `true`.
+
+## Report Template
+
+```markdown
+# Zwischen Test Report
+
+## Environment
+- Ruby version:
+- Gem location:
+- Test directory:
+- Gitleaks version:
+- Semgrep version:
+
+## Results
+- Test 1.1:
+- Test 1.2:
+- Test 1.3:
+- Test 2.1:
+- Test 2.2:
+- Test 2.3:
+- Test 3.1:
+- Test 3.2:
+- Test 3.3:
+- Test 3.4:
+- Test 4.1:
+- Test 4.2:
+- Test 4.3:
+- Test 5.1:
+- Test 5.2:
+- Test 6.1:
+- Test 6.2:
+- Test 6.3:
+- Test 7.1:
+- Test 7.2:
+- Test 7.3:
+
+## Failures
+
+## Notes
+
+## Overall Status
+```
+
+## Cleanup
+
+```bash
+gem uninstall zwischen --user-install
+rm -rf /tmp/zwischen-test-* /tmp/zwischen-no-git-*
+```

data/bin/zwischen

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "zwischen"
+
+# Always start CLI when this file is loaded (works for both direct execution and gem wrapper)
+Zwischen::CLI.start(ARGV)

data/lib/zwischen/ai/analyzer.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "anthropic_client"
+require_relative "ollama_client"
+require_relative "openai_client"
+require_relative "../finding/finding"
+
+module Zwischen
+  module AI
+    class Analyzer
+      def initialize(provider: "claude", api_key: nil, config: {}, project_context: {})
+        @project_context = project_context
+        
+        client_class = case provider.to_s.downcase
+                       when "claude", "anthropic" then AnthropicClient
+                       when "ollama" then OllamaClient
+                       when "openai" then OpenAIClient
+                       else
+                         # Fallback or error
+                         AnthropicClient
+                       end
+
+        @client = client_class.new(api_key: api_key, config: config)
+      end
+
+      def analyze(findings)
+        return findings if findings.empty?
+
+        prompt = build_prompt(findings)
+        response = @client.analyze(prompt)
+
+        enhance_findings(findings, response)
+      rescue AI::Error => e
+        warn "AI analysis failed: #{e.message}. Returning original findings."
+        findings
+      rescue StandardError => e
+        warn "AI analysis failed: #{e.message}. Returning original findings."
+        findings
+      end
+
+      private
+
+      def build_prompt(findings)
+        project_info = "Project type: #{@project_context[:primary_type] || 'unknown'}, Language: #{@project_context[:language] || 'unknown'}"
+
+        findings_text = findings.map.with_index(1) do |finding, idx|
+          <<~FINDING
+            #{idx}. [#{finding.severity.upcase}] #{finding.file}:#{finding.line}
+               Rule: #{finding.rule_id}
+               Message: #{finding.message}
+           #{finding.code_snippet ? "   Code:\n   #{finding.code_snippet.split("\n").map { |l| "   #{l}" }.join("\n")}" : ""}
+          FINDING
+        end.join("\n")
+
+        <<~PROMPT
+          You are a senior security engineer reviewing security scan findings. Analyze the following findings and provide:
+
+          1. Prioritization: Which findings are most critical and should be addressed first?
+          2. False positives: Are any of these false positives that can be safely ignored?
+          3. Fix suggestions: For each real finding, provide a clear, actionable fix suggestion.
+
+          #{project_info}
+
+          Findings:
+          #{findings_text}
+
+          Please respond in the following JSON format for each finding (by index number):
+          {
+            "1": {
+              "priority": "high|medium|low",
+              "is_false_positive": false,
+              "fix_suggestion": "Clear explanation of how to fix this issue",
+              "risk_explanation": "Why this is a security risk"
+            },
+            ...
+          }
+
+          If a finding is a false positive, set is_false_positive to true and explain why.
+        PROMPT
+      end
+
+      def enhance_findings(findings, ai_response)
+        # Try to parse JSON from the response
+        # Look for JSON object in the response
+        json_match = ai_response.match(/\{[\s\S]*\}/m)
+        return findings unless json_match
+
+        ai_analysis = JSON.parse(json_match[0])
+
+        findings.map.with_index(1) do |finding, idx|
+          analysis = ai_analysis[idx.to_s]
+          next finding unless analysis
+
+          # Add AI insights to raw_data
+          enhanced_data = finding.raw_data.merge(
+            "ai_priority" => analysis["priority"],
+            "ai_false_positive" => analysis["is_false_positive"] || false,
+            "ai_fix_suggestion" => analysis["fix_suggestion"],
+            "ai_risk_explanation" => analysis["risk_explanation"]
+          )
+
+          # Create new finding with enhanced data
+          Zwischen::Finding::Finding.new(
+            type: finding.type,
+            scanner: finding.scanner,
+            severity: finding.severity,
+            file: finding.file,
+            line: finding.line,
+            message: finding.message,
+            rule_id: finding.rule_id,
+            code_snippet: finding.code_snippet,
+            raw_data: enhanced_data
+          )
+        end
+      rescue JSON::ParserError => e
+        warn "Failed to parse AI response: #{e.message}"
+        findings
+      end
+    end
+  end
+end

data/lib/zwischen/ai/anthropic_client.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require_relative "base_client"
+
+module Zwischen
+  module AI
+    class AnthropicClient < BaseClient
+      API_BASE_URL = "https://api.anthropic.com/v1/"
+      API_VERSION = "2023-06-01"
+
+      def initialize(api_key: nil, config: {})
+        super
+        raise Error, "Claude API key not found." unless @api_key
+
+        @client = Faraday.new(url: API_BASE_URL) do |conn|
+          conn.request :json
+          conn.response :json, content_type: /\bjson$/
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def analyze(prompt)
+        model = @config["model"] || "claude-3-5-sonnet-20241022"
+
+        # Relative path: a leading slash would discard the /v1 prefix of the base URL
+        response = @client.post("messages") do |req|
+          req.headers["x-api-key"] = @api_key
+          req.headers["anthropic-version"] = API_VERSION
+          req.body = {
+            model: model,
+            max_tokens: 4096,
+            messages: [
+              {
+                role: "user",
+                content: prompt
+              }
+            ]
+          }
+        end
+
+        body = response.body
+        body = JSON.parse(body) if body.is_a?(String)
+
+        if response.success?
+          body.dig("content", 0, "text")
+        else
+          error_message = body.dig("error", "message") rescue body
+          raise Error, "Claude API error: #{error_message}"
+        end
+      rescue Faraday::Error => e
+        raise Error, "Network error: #{e.message}"
+      rescue JSON::ParserError => e
+        raise Error, "Invalid JSON response: #{e.message}"
+      end
+    end
+  end
+end

data/lib/zwischen/ai/base_client.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Zwischen
+  module AI
+    class Error < StandardError; end
+
+    class BaseClient
+      attr_reader :api_key, :config
+
+      def initialize(api_key: nil, config: {})
+        @api_key = api_key
+        @config = config
+        validate_config!
+      end
+
+      def analyze(prompt)
+        raise NotImplementedError, "#{self.class.name} must implement #analyze"
+      end
+
+      protected
+
+      def validate_config!
+        # Hook for subclasses
+      end
+    end
+  end
+end

data/lib/zwischen/ai/ollama_client.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require_relative "base_client"
+
+module Zwischen
+  module AI
+    class OllamaClient < BaseClient
+      def initialize(api_key: nil, config: {})
+        super
+        # Ollama usually doesn't need an API key, but we accept it if provided
+        
+        base_url = @config["url"] || "http://localhost:11434"
+        # Ensure base URL doesn't end with /api/chat if user provided full path
+        base_url = base_url.sub(/\/api\/chat\/?$/, "")
+
+        @client = Faraday.new(url: base_url) do |conn|
+          conn.request :json
+          conn.response :json, content_type: /\bjson$/
+          # Local models can take a while to load and generate; default 60s
+          # is too tight for larger models.
+          conn.options.timeout = (@config["timeout"] || 180).to_i
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def analyze(prompt)
+        model = @config["model"] || "llama3"
+
+        response = @client.post("/api/chat") do |req|
+          req.body = {
+            model: model,
+            messages: [
+              {
+                role: "user",
+                content: prompt
+              }
+            ],
+            stream: false
+          }
+        end
+
+        if response.success?
+          content = response.body.dig("message", "content")
+          unless content
+            raise Error, "Unexpected Ollama response format: #{response.body}"
+          end
+          content
+        else
+          error_message = response.body.dig("error") || "Unknown error"
+          raise Error, "Ollama API error: #{error_message}"
+        end
+      rescue Faraday::Error => e
+        raise Error, "Ollama connection error: #{e.message}. Is Ollama running?"
+      end
+    end
+  end
+end

data/lib/zwischen/ai/openai_client.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require_relative "base_client"
+
+module Zwischen
+  module AI
+    class OpenAIClient < BaseClient
+      API_BASE_URL = "https://api.openai.com/v1/"
+
+      def initialize(api_key: nil, config: {})
+        super
+        raise Error, "OpenAI API key not found." unless @api_key
+
+        @client = Faraday.new(url: API_BASE_URL) do |conn|
+          conn.request :json
+          conn.response :json, content_type: /\bjson$/
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def analyze(prompt)
+        model = @config["model"] || "gpt-4"
+
+        # Relative path: a leading slash would discard the /v1 prefix of the base URL
+        response = @client.post("chat/completions") do |req|
+          req.headers["Authorization"] = "Bearer #{@api_key}"
+          req.body = {
+            model: model,
+            messages: [
+              {
+                role: "user",
+                content: prompt
+              }
+            ]
+          }
+        end
+
+        body = response.body
+        body = JSON.parse(body) if body.is_a?(String)
+
+        if response.success?
+          body.dig("choices", 0, "message", "content")
+        else
+          error_message = body.dig("error", "message") rescue body
+          raise Error, "OpenAI API error: #{error_message}"
+        end
+      rescue Faraday::Error => e
+        raise Error, "Network error: #{e.message}"
+      rescue JSON::ParserError => e
+        raise Error, "Invalid JSON response: #{e.message}"
+      end
+    end
+  end
+end