QE Artifacts¶

SuperQode generates comprehensive artifacts from QE sessions, preserved in .superqode/qe-artifacts/.

Artifact Location¶

All artifacts are saved to:

.superqode/qe-artifacts/
├── manifest.json                # Index of saved artifacts
├── qr/
│   ├── qr-<date>-<session>.md   # Quality Report (Markdown)
│   └── qr-<date>-<session>.json # Quality Report (JSON)
├── patches/
│   ├── fix-<finding-id>.patch   # Suggested fix patches (when available)
│   └── ...
├── logs/
│   └── ...                       # Execution logs / work logs (if enabled)
├── evidence/
│   └── ...                       # Screenshots, traces, captured outputs
├── coverage/
│   └── ...                       # Coverage outputs (if generated)
└── generated-tests/
    ├── unit/
    ├── integration/
    ├── api/
    ├── fuzz/
    └── ...

Quality Report (QR)¶

The primary output is a JSON-formatted QR:

Structure¶

{
  "session": {
    "id": "qe-session-20240118-143022",
    "mode": "deep_qe",
    "duration_seconds": 1247.3,
    "started_at": "2024-01-18T14:30:22Z",
    "completed_at": "2024-01-18T14:51:09Z",
    "roles_executed": ["security_tester", "api_tester", "fullstack"],
    "workspace": {
      "method": "git_worktree",
      "base_commit": "abc123def",
      "reverted": true
    }
  },
  "findings": [...],
  "summary": {
    "total_findings": 6,
    "by_severity": {
      "critical": 1,
      "high": 2,
      "medium": 2,
      "low": 1
    },
    "production_ready": false,
    "blocking_issues": ["finding-001", "finding-002"]
  }
}

Finding Structure¶

{
  "id": "finding-001",
  "title": "SQL Injection in User Search",
  "severity": "critical",
  "category": "security",
  "subcategory": "injection",
  "confidence": 0.95,

  "location": {
    "file_path": "src/api/users.py",
    "line_number": 42,
    "function": "search_users"
  },

  "description": "User input is directly interpolated into SQL query...",

  "evidence": {
    "code_snippet": "query = f\"SELECT * FROM users WHERE name LIKE '%{search}%'\"",
    "test_input": "'; DROP TABLE users; --",
    "test_result": "SQL syntax error returned"
  },

  "reproduction": {
    "steps": [...],
    "automated_test": "tests/generated/test_sql_injection.py"
  },

  "root_cause": {
    "analysis": "String interpolation used instead of parameterized queries",
    "contributing_factors": [...]
  },

  "recommendation": {
    "summary": "Use parameterized queries or ORM methods",
    "fix_patch": "patches/fix-sql-injection.patch",
    "fix_verified": true
  },

  "metadata": {
    "detected_by": "security_tester",
    "detected_at": "2024-01-18T14:35:12Z",
    "cwe_id": "CWE-89",
    "owasp_category": "A03:2021 Injection"
  }
}

Viewing Artifacts¶

View QR in Terminal¶

# JSON format with jq
cat .superqode/qe-artifacts/qr/qr-*.json | jq

# Markdown report
cat .superqode/qe-artifacts/qr/qr-*.md

# Via CLI
superqe report

View in Browser¶

# Open dashboard for the latest QR
superqe dashboard

List All Artifacts¶

superqe artifacts

View Specific Artifact¶

superqe show <artifact-id>

Patches¶

Suggested fix patches are in unified diff format:

--- a/src/api/users.py
+++ b/src/api/users.py
@@ -40,7 +40,9 @@ def search_users(query: str):
     """Search for users by name."""
     conn = get_db_connection()
     cursor = conn.cursor()
-    sql = f"SELECT * FROM users WHERE name LIKE '%{query}%'"
+    sql = "SELECT * FROM users WHERE name LIKE ?"
+    params = (f"%{query}%",)
-    cursor.execute(sql)
+    cursor.execute(sql, params)
     return cursor.fetchall()

Applying Patches¶

# Preview
cat .superqode/qe-artifacts/patches/fix-sql-injection.patch

# Dry run
git apply --check .superqode/qe-artifacts/patches/fix-sql-injection.patch

# Apply
git apply .superqode/qe-artifacts/patches/fix-sql-injection.patch

# Or use SuperQode
superqode suggestions apply finding-001

Generated Tests¶

Regression tests are generated for verified findings:

# tests/generated/test_sql_injection.py
"""
Regression test for SQL Injection fix (finding-001)
Generated by SuperQode QE
"""

import pytest
from src.api.users import search_users

class TestSqlInjectionPrevention:
    """Tests that SQL injection is properly prevented."""

    def test_normal_search_works(self):
        """Normal search queries work correctly."""
        results = search_users("john")
        assert isinstance(results, list)

    def test_injection_attempt_neutralized(self):
        """SQL injection attempts are safely handled."""
        results = search_users("'; DROP TABLE users; --")
        assert isinstance(results, list)

    def test_special_chars_escaped(self):
        """Special characters are properly escaped."""
        results = search_users("O'Brien")
        assert isinstance(results, list)

Session Logs¶

Agent work logs capture the full investigation:

# View logs
superqe logs

# View logs for specific session
superqe logs qe-session-20240118-143022

Log Contents¶

Connection attempts and responses
Prompts sent to the AI agent
Analysis steps and reasoning
Tool calls and results
Finding extraction

Report Formats¶

Markdown Summary¶

Human-readable summary suitable for documentation:

# Quality Report

**Session**: qe-session-20240118-143022
**Duration**: 20m 47.3s
**Mode**: Deep QE

## Summary

| Severity | Count |
|----------|-------|
| Critical | 1 |
| High | 2 |
| Medium | 2 |
| Low | 1 |

**Production Ready**: No
**Blocking Issues**: 2

## Findings

### [CRITICAL] SQL Injection in User Search

**Location**: src/api/users.py:42
**Confidence**: 95%

User input is directly interpolated into SQL query...

HTML Report¶

Interactive HTML report with:

Finding cards with expandable details
Code snippets with syntax highlighting
Evidence viewer
Patch previewer
Severity filtering

JSON Export¶

Structured JSON for programmatic access:

superqe report --format json --output report.json

Artifact Retention¶

Default Behavior¶

Artifacts are preserved after each session
History is kept (configurable)
Old artifacts can be cleaned up

Configuration¶

qe:
  output:
    directory: ".superqode"
    keep_history: true

Cleanup¶

# Clean artifacts but keep QRs
superqe clean

# Remove everything
superqe clean --all

# Remove artifacts older than 7 days
superqe artifacts --clean --older-than 7d

CI/CD Integration¶

JSONL Streaming¶

Stream events for real-time processing:

superqe run . --jsonl | while read event; do
  TYPE=$(echo $event | jq -r '.type')
  case $TYPE in
    "finding.detected")
      echo "Found: $(echo $event | jq -r '.data.title')"
      ;;
    "qe.completed")
      echo "QE complete"
      ;;
  esac
done

JUnit XML¶

Export for test reporting tools:

superqe run . --junit results.xml

Quality Gates¶

# GitHub Actions example
- name: Run QE
  run: superqe run . --mode quick --junit results.xml

- name: Check for critical issues
  run: |
    CRITICAL=$(cat .superqode/qe-artifacts/qr-*.json | jq '.summary.by_severity.critical')
    if [ "$CRITICAL" -gt 0 ]; then
      echo "Critical issues found, blocking merge"
      exit 1
    fi

Next Steps¶

Test Generation - Generated test details
CI/CD Integration - Automated quality gates
QR Documentation - Report format details