better-code-review-graph 0.1.0__tar.gz

better_code_review_graph-0.1.0/.agents/skills/build-graph/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: build-graph
+description: Build or update the code review knowledge graph. Run this first to initialize, or let hooks keep it updated automatically.
+argument-hint: "[full]"
+---
+
+# Build Graph
+
+Build or incrementally update the persistent code knowledge graph for this repository.
+
+## Steps
+
+1. **Check graph status** by calling the `list_graph_stats_tool` MCP tool.
+   - If the graph has never been built (last_updated is null), proceed with a full build.
+   - If the graph exists, proceed with an incremental update.
+
+2. **Build the graph** by calling the `build_or_update_graph_tool` MCP tool:
+   - For first-time setup: `build_or_update_graph_tool(full_rebuild=True)`
+   - For updates: `build_or_update_graph_tool()` (incremental by default)
+
+3. **Verify** by calling `list_graph_stats_tool` again and report the results:
+   - Number of files parsed
+   - Number of nodes and edges created
+   - Languages detected
+   - Any errors encountered
+
+## When to Use
+
+- First time setting up the graph for a repository
+- After major refactoring or branch switches
+- If the graph seems stale or out of sync
+- The graph auto-updates via hooks on edit/commit, so manual builds are rarely needed
+
+## Notes
+
+- The graph is stored as a SQLite database (`.code-review-graph/graph.db`) in the repo root
+- Binary files, generated files, and patterns in `.code-review-graphignore` are skipped
+- Supported languages: Python, TypeScript/JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C/C++

better_code_review_graph-0.1.0/.agents/skills/review-delta/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: review-delta
+description: Review only changes since last commit using impact analysis. Token-efficient delta review with automatic blast-radius detection.
+argument-hint: "[file or function name]"
+---
+
+# Review Delta
+
+Perform a focused, token-efficient code review of only the changed code and its blast radius.
+
+**Token optimization:** Before starting, call `get_docs_section_tool(section_name="review-delta")` for the optimized workflow. Use ONLY changed nodes + 2-hop neighbors in context.
+
+## Steps
+
+1. **Ensure the graph is current** by calling `build_or_update_graph_tool()` (incremental update).
+
+2. **Get review context** by calling `get_review_context_tool()`. This returns:
+   - Changed files (auto-detected from git diff)
+   - Impacted nodes and files (blast radius)
+   - Source code snippets for changed areas
+   - Review guidance (test coverage gaps, wide impact warnings, inheritance concerns)
+
+3. **Analyze the blast radius** by reviewing the `impacted_nodes` and `impacted_files` in the context. Focus on:
+   - Functions whose callers changed (may need signature/behavior verification)
+   - Classes with inheritance changes (Liskov substitution concerns)
+   - Files with many dependents (high-risk changes)
+
+4. **Perform the review** using the context. For each changed file:
+   - Review the source snippet for correctness, style, and potential bugs
+   - Check if impacted callers/dependents need updates
+   - Verify test coverage using `query_graph_tool(pattern="tests_for", target=<function_name>)`
+   - Flag any untested changed functions
+
+5. **Report findings** in a structured format:
+   - **Summary**: One-line overview of the changes
+   - **Risk level**: Low / Medium / High (based on blast radius)
+   - **Issues found**: Bugs, style issues, missing tests
+   - **Blast radius**: List of impacted files/functions
+   - **Recommendations**: Actionable suggestions
+
+## Advantages Over Full-Repo Review
+
+- Only sends changed + impacted code to the model (5-10x fewer tokens)
+- Automatically identifies blast radius without manual file searching
+- Provides structural context (who calls what, inheritance chains)
+- Flags untested functions automatically

better_code_review_graph-0.1.0/.agents/skills/review-pr/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: review-pr
+description: Review a PR or branch diff using the knowledge graph for full structural context. Outputs a structured review with blast-radius analysis.
+argument-hint: "[PR number or branch name]"
+---
+
+# Review PR
+
+Perform a comprehensive code review of a pull request or branch diff using the knowledge graph.
+
+**Token optimization:** Before starting, call `get_docs_section_tool(section_name="review-pr")` for the optimized workflow. Never include full files unless explicitly asked.
+
+## Steps
+
+1. **Identify the changes** for the PR:
+   - If a PR number or branch is provided, use `git diff main...<branch>` to get changed files
+   - Otherwise auto-detect from the current branch vs main/master
+
+2. **Update the graph** by calling `build_or_update_graph_tool(base="main")` to ensure the graph reflects the current state.
+
+3. **Get the full review context** by calling `get_review_context_tool(base="main")`:
+   - This uses `main` (or the specified base branch) as the diff base
+   - Returns all changed files across all commits in the PR
+
+4. **Analyze impact** by calling `get_impact_radius_tool(base="main")`:
+   - Review the blast radius across the entire PR
+   - Identify high-risk areas (widely depended-upon code)
+
+5. **Deep-dive each changed file**:
+   - Read the full source of files with significant changes
+   - Use `query_graph_tool(pattern="callers_of", target=<func>)` for high-risk functions
+   - Use `query_graph_tool(pattern="tests_for", target=<func>)` to verify test coverage
+   - Check for breaking changes in public APIs
+
+6. **Generate structured review output**:
+
+   ```
+   ## PR Review: <title>
+
+   ### Summary
+   <1-3 sentence overview>
+
+   ### Risk Assessment
+   - **Overall risk**: Low / Medium / High
+   - **Blast radius**: X files, Y functions impacted
+   - **Test coverage**: N changed functions covered / M total
+
+   ### File-by-File Review
+   #### <file_path>
+   - Changes: <description>
+   - Impact: <who depends on this>
+   - Issues: <bugs, style, concerns>
+
+   ### Missing Tests
+   - <function_name> in <file> - no test coverage found
+
+   ### Recommendations
+   1. <actionable suggestion>
+   2. <actionable suggestion>
+   ```
+
+## Tips
+
+- For large PRs, focus on the highest-impact files first (most dependents)
+- Use `semantic_search_nodes_tool` to find related code the PR might have missed
+- Check if renamed/moved functions have updated all callers

better_code_review_graph-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "better-code-review-graph",
+  "owner": {
+    "name": "n24q02m",
+    "url": "https://github.com/n24q02m"
+  },
+  "metadata": {
+    "description": "Persistent incremental knowledge graph for token-efficient, context-aware code reviews with Claude Code",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "better-code-review-graph",
+      "source": "./",
+      "description": "Persistent incremental knowledge graph for token-efficient, context-aware code reviews with Claude Code",
+      "version": "0.1.0",
+      "category": "development",
+      "keywords": ["code-review", "knowledge-graph", "incremental", "tree-sitter", "mcp", "claude-code"]
+    }
+  ]
+}

better_code_review_graph-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "better-code-review-graph",
+  "description": "Persistent incremental knowledge graph for token-efficient, context-aware code reviews with Claude Code",
+  "version": "0.1.0",
+  "author": {
+    "name": "n24q02m",
+    "url": "https://github.com/n24q02m"
+  },
+  "homepage": "https://github.com/n24q02m/better-code-review-graph",
+  "repository": "https://github.com/n24q02m/better-code-review-graph",
+  "license": "MIT",
+  "keywords": ["code-review", "knowledge-graph", "incremental", "tree-sitter", "mcp", "claude-code"],
+  "mcpServers": {
+    "better-code-review-graph": {
+      "command": "uvx",
+      "args": ["--python", "3.13", "better-code-review-graph", "serve"]
+    }
+  },
+  "skills": "./skills/"
+}

better_code_review_graph-0.1.0/.dockerignore

@@ -0,0 +1,32 @@
+# Git
+.git
+.github
+
+# IDE
+.vscode
+
+# Cache
+.ruff_cache
+.pytest_cache
+__pycache__
+
+# Development
+tests/
+temp/
+docs/
+*.md
+!README.md
+
+# Docker
+Dockerfile
+docker-compose.yml
+
+# Config
+.pre-commit-config.yaml
+.editorconfig
+.python-version
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+SECURITY.md
+LICENSE
+CHANGELOG.md

better_code_review_graph-0.1.0/.github/best_practices.md

@@ -0,0 +1,25 @@
+# Style Guide - better-code-review-graph
+
+## Architecture
+Knowledge graph MCP server for token-efficient code reviews. Python, single-package repo.
+
+## Python
+- Formatter/Linter: Ruff (default config)
+- Type checker: ty
+- Test: pytest + pytest-asyncio
+- Package manager: uv
+- SDK: fastmcp
+- Core deps: tree-sitter, networkx, SQLite, qwen3-embed (ONNX), litellm
+
+## Code Patterns
+- Tree-sitter parsing for 12 languages
+- SQLite graph storage with NetworkX BFS for impact analysis
+- Dual-mode embedding: local ONNX (qwen3-embed) + LiteLLM cloud
+- Incremental updates via git diff and file watching
+- Call target resolution: bare names resolved to qualified names
+
+## Commits
+Conventional Commits (feat:, fix:, chore:, docs:, refactor:, test:).
+
+## Security
+Validate file paths. Bound graph traversal depth. Prevent unbounded output via pagination.

better_code_review_graph-0.1.0/.github/workflows/cd.yml

@@ -0,0 +1,232 @@
+name: CD
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_type:
+        description: "Release type"
+        required: true
+        type: choice
+        options:
+          - beta
+          - stable
+
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+
+env:
+  DOCKERHUB_IMAGE: ${{ secrets.DOCKERHUB_USERNAME }}/better-code-review-graph
+  GHCR_IMAGE: ghcr.io/${{ github.repository }}
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  # =================== Release ===================
+  release:
+    name: Semantic Release
+    runs-on: ubuntu-latest
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+      tag: ${{ steps.release.outputs.tag }}
+      version: ${{ steps.release.outputs.version }}
+      is_prerelease: ${{ steps.release.outputs.is_prerelease }}
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594 # v2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          token: ${{ secrets.GH_PAT }}
+          fetch-depth: 0
+
+      - uses: python-semantic-release/python-semantic-release@350c48fcb3ffcdfd2e0a235206bc2ecea6b69df0 # v10
+        id: release
+        with:
+          github_token: ${{ secrets.GH_PAT }}
+          prerelease: ${{ inputs.release_type == 'beta' }}
+          prerelease_token: beta
+
+      - uses: python-semantic-release/publish-action@310a9983a0ae878b29f3aac778d7c77c1db27378 # v10
+        if: steps.release.outputs.released == 'true'
+        with:
+          github_token: ${{ secrets.GH_PAT }}
+          tag: ${{ steps.release.outputs.tag }}
+
+  # =================== Publish to PyPI ===================
+  publish-pypi:
+    name: Publish to PyPI
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594 # v2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ needs.release.outputs.tag }}
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+      - run: uv build
+      - name: Publish to PyPI
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+
+  # =================== Build Docker ===================
+  build-docker:
+    name: Build Docker (${{ matrix.platform }})
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-latest
+            artifact: linux-amd64
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+            artifact: linux-arm64
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594 # v2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ needs.release.outputs.tag }}
+      - uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4
+      - uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7
+        id: build
+        with:
+          context: .
+          platforms: ${{ matrix.platform }}
+          outputs: type=image,"name=${{ env.DOCKERHUB_IMAGE }},${{ env.GHCR_IMAGE }}",push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=${{ github.ref_name }}-${{ matrix.artifact }}
+          cache-to: type=gha,mode=max,scope=${{ github.ref_name }}-${{ matrix.artifact }}
+      - run: |
+          mkdir -p ${{ runner.temp }}/digests
+          echo "${{ steps.build.outputs.digest }}" > "${{ runner.temp }}/digests/${{ matrix.artifact }}"
+      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7
+        with:
+          name: digest-${{ matrix.artifact }}
+          path: ${{ runner.temp }}/digests/*
+          retention-days: 1
+
+  # =================== Merge Docker Manifests ===================
+  merge-docker:
+    name: Merge Docker Manifests
+    needs: [release, build-docker]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594 # v2
+        with:
+          egress-policy: audit
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          pattern: digest-*
+          path: ${{ runner.temp }}/digests
+          merge-multiple: true
+      - uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Create and push manifests
+        env:
+          VERSION: ${{ needs.release.outputs.version }}
+          IS_PRERELEASE: ${{ needs.release.outputs.is_prerelease }}
+        run: |
+          # Build tag lists based on release type
+          if [ "$IS_PRERELEASE" = "true" ]; then
+            TAGS="beta ${VERSION}"
+          else
+            MAJOR=$(echo "$VERSION" | cut -d. -f1)
+            MINOR=$(echo "$VERSION" | cut -d. -f1-2)
+            TAGS="latest ${VERSION} ${MINOR} ${MAJOR}"
+          fi
+
+          DIGESTS=$(cat ${{ runner.temp }}/digests/*)
+
+          for IMAGE in "$DOCKERHUB_IMAGE" "$GHCR_IMAGE"; do
+            TAG_ARGS=""
+            for TAG in $TAGS; do
+              TAG_ARGS="$TAG_ARGS -t ${IMAGE}:${TAG}"
+            done
+            docker buildx imagetools create $TAG_ARGS \
+              $(echo "$DIGESTS" | xargs -I{} echo "${IMAGE}@{}")
+          done
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          sparse-checkout: README.md
+      - uses: peter-evans/dockerhub-description@1b9a80c056b620d92cedb9d9b5a223409c68ddfa # v5
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          repository: ${{ secrets.DOCKERHUB_USERNAME }}/better-code-review-graph
+          short-description: ${{ github.event.repository.description }}
+          readme-filepath: ./README.md
+
+  # =================== Publish to MCP Registry ===================
+  publish-mcp-registry:
+    name: Publish to MCP Registry
+    needs: [release, publish-pypi, merge-docker]
+    if: needs.release.outputs.released == 'true' && needs.release.outputs.is_prerelease != 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594 # v2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ needs.release.outputs.tag }}
+
+      - name: Update server.json version
+        run: |
+          VERSION="${{ needs.release.outputs.version }}"
+          jq --arg v "$VERSION" '
+            .version = $v |
+            .packages = [.packages[] |
+              if .registryType == "oci" then del(.version)
+              else .version = $v
+              end
+            ]
+          ' server.json > server.json.tmp && mv server.json.tmp server.json
+
+      - name: Install MCP Publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Login to MCP Registry
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish