MergeGuard v1.0.0

MergeGuard v1.0.0

Detect cross-PR conflicts before they reach your merge queue.

First stable release. MergeGuard analyzes open pull requests and finds conflicts between them while you're still developing, not at merge time.

Highlights

• 6 conflict types detected with AST-level analysis across 165+ languages
• Multi-platform: GitHub (Cloud + Enterprise), GitLab, Bitbucket
• Benchmarked: 59-82% false positive reduction on FastAPI vs pre-release
• 19 security fixes (SSRF, XSS, injection, token leakage)
• 695+ tests, 72% coverage with CI enforcement

Install

pip install py-mergeguard
mergeguard analyze --pr 42

What Changed Since v0.5

Accuracy

• Transitive conflict detection overhauled (59-82% false positive reduction)
• Multi-line Python import parsing fixed
• Go import regex scoped to import blocks
• CODEOWNERS ** glob matching fixed

Scope

• Secret scanning disabled by default (opt-in via --secrets)
• README rewritten with focused pitch and comparison table

Security (19 critical/high findings resolved)

• Git argument injection, ReDoS, SSRF, XSS, markdown injection, LLM prompt injection, token leakage, path traversal

Reliability

• SQLite thread safety, rate limiter crash guard, AST RecursionError handling, CLI resource leaks, queue shutdown

See CHANGELOG.md for full details.

v0.1.2 — Extras fix & repo cleanup

MergeGuard v0.1.2

Patch release fixing the optional [llm] extra dependency, CLI version detection, and organizing the repository.

Fixes

• py-mergeguard[llm] extras — pip install py-mergeguard[llm] now resolves correctly (was referencing old package name mergeguard[llm])
• --version flag — mergeguard --version now works correctly with the renamed package
• Version test — no longer hardcodes a specific version string

Repo Cleanup

• Moved example reports to examples/reports/:
  • mlflow_pr21273.json — mlflow analysis (post symbol-fix)
  • mlflow_pr21273_before_fix.json — mlflow analysis (pre symbol-fix, showing the misattribution bug)
  • django_pr20826.json — django/django E2E test (fork PR, 92 open PRs scanned)
  • langchain_pr35457.json — langchain E2E test
• Added *.log to .gitignore
• Removed temp files from repo root

Install

pip install py-mergeguard==0.1.2

# With LLM support
pip install py-mergeguard[llm]==0.1.2

Full Changelog: v0.1.1...v0.1.2

v0.1.1 — Documentation & metadata update

MergeGuard v0.1.1

Patch release to update PyPI metadata, README, and documentation to reflect the actual implementation status.

Changes

• README: Added PyPI badge, corrected install command to pip install py-mergeguard, fixed GitHub repo URLs
• Docs: Updated test count from 214 → 256 across all documentation
• Docs: Marked Gap #12 (transitive conflict detection) and Gap #15 (PR auto-detection) as implemented — both were fully working but docs still listed them as deferred
• Docs: Checked off all release checklist items
• Docs: Fixed GitHub Action references to Vansh2795/mergeguard@v0.1

No code changes — this release only updates documentation and package metadata.

Install

pip install py-mergeguard==0.1.1

Full Changelog: v0.1.0...v0.1.1

v0.1.0 — Initial Release

MergeGuard v0.1.0 — Initial Release

Cross-PR conflict detection for the agentic coding era. MergeGuard analyzes open pull requests to detect conflicts that traditional CI misses — before they reach main.

Install

pip install py-mergeguard

Usage

# Analyze a specific PR
export GITHUB_TOKEN=ghp_...
mergeguard analyze --repo owner/repo --pr 123

# Collision map of all open PRs
mergeguard map --repo owner/repo

# Risk dashboard
mergeguard dashboard --repo owner/repo

---

Changelog

Core Analysis Engine

• Cross-PR conflict detection — compares every open PR pairwise to detect overlapping changes
• AST-level symbol extraction via Tree-sitter with support for Python, TypeScript, JavaScript, Go, Rust, Java, and Ruby
• Intra-file call graph — tracks caller/callee relationships within files for smarter conflict classification
• Three-way symbol classification — correctly identifies added, removed, and modified symbols by comparing BASE vs HEAD branches
• Dependency graph traversal — detects transitive conflicts through import chains (BFS with deduplication)
• AI attribution detection — flags PRs authored by Copilot, Cursor, Claude, Devin, etc.

Conflict Types

Type	Description
Hard	Same lines modified differently across PRs
Interface	Function signature changed without updating callers in other PRs
Behavioral	Same logic modified incompatibly in separate PRs
Duplication	Same feature implemented independently in two PRs
Transitive	Breakage through dependency chains (A imports B, both modified)
Regression	PR reverts a recently merged deliberate change
Guardrail	Custom rule violations defined in .mergeguard.yml

Risk Scoring

• Composite risk score (0–100) based on:
  • Conflict severity and type
  • Blast radius (number of conflicting PRs)
  • Code churn (additions + deletions, normalized)
  • Dependency depth (transitive import chain length)
  • Pattern deviation (novel symbol names vs existing codebase)
  • AI attribution penalty
• Diminishing returns for multiple conflicts against the same PR
• Test file severity downgrade (test conflicts scored lower than source conflicts)
• Comment-only change detection and skip

Output Formats

• Terminal — rich tables with color-coded severity
• JSON — structured report for programmatic consumption
• Markdown — formatted for documentation or comments
• GitHub PR comments — post results directly on PRs via --post-comment

Performance

• Parallel PR enrichment (8 workers, 300s timeout)
• Content cache with LRU eviction (500 entries max)
• Analysis cache keyed by (repo, pr_number, head_sha) — skips re-analysis on unchanged PRs
• Single-pass Tree-sitter parsing (symbols + call graph extracted together)
• O(N) collision map via reverse file-to-PR index
• Pre-compiled fnmatch patterns for path filtering
• Jaccard similarity pre-filter before expensive SequenceMatcher
• Benchmarked: ~25–40s single PR analysis on large repos (mlflow, langchain)

Security

• 38/44 code audit issues resolved (all critical, high, and medium severity)
• Atomic cache writes with file locking and symlink rejection
• Token isolation — credentials never appear in HTTP headers
• CLI input validation (PR number range, repo format pattern)
• Binary file detection (null byte check in first 8KB)
• File size limits (500KB) and diff size limits (50K lines)
• YAML config parser with key validation

GitHub Action

# .github/workflows/mergeguard.yml
name: MergeGuard
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Vansh2795/mergeguard@v0.1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

CLI Features

• mergeguard analyze — analyze a single PR for cross-PR conflicts
• mergeguard map — collision map of all open PRs
• mergeguard dashboard — risk dashboard for all open PRs
• Auto-detection of repo from git remote and PR from current branch
• --llm flag for optional AI-powered semantic conflict analysis (requires Anthropic API key)
• --format flag for terminal, JSON, or markdown output
• --max-prs and --max-pr-age overrides for large repos

Test Coverage

• 256 tests — all passing
• Unit tests for every core module (engine, conflict, AST parser, diff parser, risk scorer, dependency graph, similarity, config, CLI)
• Integration tests (full pipeline E2E, GitHub client, cache wiring, guardrails, regression detection, LLM analysis)
• Edge case tests (empty PRs, binary files, deleted files, ignored paths, empty content)
• Concurrency tests (thread-safe symbol index, content cache, parallel enrichment)
• Error recovery tests (corrupt cache, API timeouts, disk full)

---

Bug Fixes

• Fixed symbol misattribution on insertion — when a new function is inserted before an existing one, the existing function was incorrectly reported as modified_body. Now uses three-way BASE/HEAD classification to correctly identify the new function as added and skip displaced-but-unchanged functions.
• Fixed guardrail conflict type (was REGRESSION, now correctly GUARDRAIL)
• Fixed UnicodeDecodeError in AST parser for files with invalid UTF-8
• Fixed Windows path separator issue in module resolution (now uses PurePosixPath)
• Fixed unbounded content cache (now LRU-evicted at 500 entries)
• Fixed double Tree-sitter parsing (merged into single pass)

Known Limitations

• GitLab support is stub-only (NotImplementedError)
• MCP server tools return not_implemented
• No Docker image yet
• 6 low-impact audit issues intentionally deferred (cosmetic and low-risk)

---

Full Changelog: https://github.com/Vansh2795/mergeguard/commits/v0.1.0