codegraph-brain 0.6.0__tar.gz

codegraph_brain-0.6.0/.github/workflows/autodoc.yml

@@ -0,0 +1,84 @@
+name: Self-Documenting Architecture Sync
+
+on:
+  push:
+    branches: [ main ]
+    paths-ignore:
+      - 'docs/**'
+      - 'README.md'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync-architecture-docs:
+    name: Regenerate architecture graph & MCP reference
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install CGIS
+        run: uv sync
+
+      - name: Self-ingest core engine
+        run: uv run cgis ingest ./src --output /tmp/self_graph.db
+
+      - name: Generate pipeline flow diagram
+        run: |
+          mkdir -p docs/architecture/diagrams
+          uv run cgis trace "cgis.pipeline.IngestionPipeline.run" \
+            --db /tmp/self_graph.db \
+            --depth 1 \
+            --format mermaid \
+            --internal-only \
+            > docs/architecture/diagrams/pipeline_flow.mermaid
+
+      - name: Compute graph health badge
+        run: uv run python scripts/generate_health.py --db /tmp/self_graph.db
+
+      - name: Inject graph into README.md
+        run: |
+          uv run python scripts/inject_readme_graph.py \
+            --db /tmp/self_graph.db \
+            --fqn "cgis.pipeline.IngestionPipeline.run" \
+            --depth 1 \
+            --path-prefix "src/"
+
+      - name: Generate MCP reference manual
+        run: uv run python scripts/generate_mcp_ref.py
+
+      - name: Sync schema docs from source
+        run: uv run python scripts/generate_schema_docs.py
+
+      - name: Open PR with generated docs
+        uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676  # v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "docs: auto-sync architecture graph and MCP reference"
+          branch: docs/auto-sync
+          delete-branch: true
+          title: "docs: auto-sync architecture graph and MCP reference"
+          body: |
+            Auto-generated by the [Self-Documenting Architecture Sync](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) workflow.
+
+            Updates:
+            - Pipeline flow diagram (`docs/architecture/diagrams/pipeline_flow.mermaid`)
+            - Graph health badge (`docs/architecture/health_badge.json`)
+            - Schema docs (`docs/architecture/HOW_IT_WORKS.md`)
+            - MCP reference (`docs/how-to/MCP_REFERENCE.md`)
+            - README diagram injection
+          labels: "docs,automated"
+          add-paths: |
+            README.md
+            docs/

codegraph_brain-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: Continuous Integration
+
+on:
+  push:
+    branches: [ main, dev, "feat/**", "fix/**", "docs/**" ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  python-ci:
+    name: Python Verification
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install Dependencies
+        run: uv sync --group dev
+
+      - name: Ruff Format Check
+        run: uv run ruff format --check .
+
+      - name: Ruff Lint
+        run: uv run ruff check .
+
+      - name: Interrogate (≥90% docstring coverage)
+        run: uv run interrogate -v --fail-under 90 src/cgis
+
+      - name: Mypy (strict)
+        run: uv run mypy src
+
+      - name: Pytest
+        run: uv run pytest --cov=cgis --cov-report=term-missing

codegraph_brain-0.6.0/.github/workflows/guardian.yml

@@ -0,0 +1,235 @@
+name: Guardian Review
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions: {}
+
+jobs:
+  review:
+    # job-level if: uses GitHub expression engine, not shell — safe for comment.body comparison
+    if: |
+      github.event.issue.pull_request != null &&
+      github.event.comment.body == '/guardian review'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+
+    steps:
+      - name: Check commenter has write access
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea  # v7
+        with:
+          script: |
+            const { data: perm } = await github.rest.repos.getCollaboratorPermissionLevel({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              username: context.payload.comment.user.login,
+            });
+            const allowed = ['admin', 'write'];
+            if (!allowed.includes(perm.permission)) {
+              core.setFailed(`@${context.payload.comment.user.login} needs write access to trigger Guardian Review (has: ${perm.permission})`);
+            }
+
+      - name: React to trigger comment
+        env:
+          GH_TOKEN: ${{ github.token }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+        run: |
+          gh api repos/$GITHUB_REPOSITORY/issues/comments/$COMMENT_ID/reactions \
+            -X POST -f content=eyes
+
+      - name: Validate PR number and get base branch
+        env:
+          PR_NUMBER: ${{ github.event.issue.number }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if ! [[ "$PR_NUMBER" =~ ^[0-9]+$ ]]; then
+            echo "Invalid PR number: $PR_NUMBER" && exit 1
+          fi
+          echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
+          BASE_BRANCH=$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json baseRefName --jq '.baseRefName')
+          echo "BASE_BRANCH=$BASE_BRANCH" >> $GITHUB_ENV
+
+      - name: Checkout PR branch
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          # PR_NUMBER validated as digits-only in previous step
+          ref: refs/pull/${{ env.PR_NUMBER }}/head
+          fetch-depth: 0
+
+      - name: Fetch base branch for diff
+        run: git fetch origin "$BASE_BRANCH"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+
+      - name: Install dependencies
+        run: uv sync --group guardian
+
+      - name: Build code graph
+        run: uv run cgis ingest ./src --output graph.db
+
+      - name: Restore metrics from data branch
+        run: |
+          git fetch origin data/guardian-metrics 2>/dev/null && \
+            git show origin/data/guardian-metrics:guardian_metrics.jsonl \
+              > guardian_metrics.jsonl 2>/dev/null || true
+
+      - name: Run Guardian Review
+        id: guardian
+        env:
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+          MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
+          GUARDIAN_PROVIDER: ${{ vars.GUARDIAN_PROVIDER }}
+          GUARDIAN_MODEL: ${{ vars.GUARDIAN_MODEL }}
+          GH_TOKEN: ${{ github.token }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          GUARDIAN_FEATURES: ${{ vars.GUARDIAN_FEATURES }}
+          GUARDIAN_SKEPTIC: ${{ vars.GUARDIAN_SKEPTIC }}
+          GUARDIAN_SKEPTIC_MODEL: ${{ vars.GUARDIAN_SKEPTIC_MODEL }}
+        run: |
+          uv run python scripts/guardian_review.py \
+            --output guardian_report.md \
+            --db graph.db \
+            --pr "$PR_NUMBER" \
+            --metrics guardian_metrics.jsonl \
+            --record-finder guardian_finder.json \
+            --inline \
+            --base-branch "$BASE_BRANCH"
+
+      - name: Upload metrics artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: guardian-metrics-${{ env.PR_NUMBER }}
+          path: guardian_metrics.jsonl
+          retention-days: 7
+
+      - name: Upload finder recording artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: guardian-finder-${{ env.PR_NUMBER }}
+          path: guardian_finder.json
+          retention-days: 7
+
+      - name: Post review as PR comment
+        if: steps.guardian.outputs.posted_inline != 'true'
+        uses: peter-evans/create-or-update-comment@a111a2c3bacd7be7898ee22d0d71d9aec2bb972c  # v4
+        with:
+          issue-number: ${{ env.PR_NUMBER }}
+          body-path: guardian_report.md
+
+  save-metrics:
+    needs: review
+    runs-on: ubuntu-latest
+    # contents: write is scoped to this job only — no PR code runs here
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Download metrics artifact
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: guardian-metrics-${{ github.event.issue.number }}
+
+      - name: Push metrics to data branch
+        env:
+          PR_NUMBER: ${{ github.event.issue.number }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          if git ls-remote --exit-code origin data/guardian-metrics > /dev/null 2>&1; then
+            git worktree add /tmp/metrics origin/data/guardian-metrics
+          else
+            git worktree add --orphan -b data/guardian-metrics /tmp/metrics
+          fi
+          cp guardian_metrics.jsonl /tmp/metrics/
+          git -C /tmp/metrics add guardian_metrics.jsonl
+          git -C /tmp/metrics diff --cached --quiet || \
+            git -C /tmp/metrics commit -m "metrics: guardian review PR #${PR_NUMBER} [skip ci]"
+          git -C /tmp/metrics push origin HEAD:data/guardian-metrics
+
+  rate:
+    # Triggered by: /guardian rate <applied> in a PR comment
+    # Example: /guardian rate 2
+    if: |
+      github.event.issue.pull_request != null &&
+      startsWith(github.event.comment.body, '/guardian rate ')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: read
+
+    steps:
+      - name: Check commenter has write access
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea  # v7
+        with:
+          script: |
+            const { data: perm } = await github.rest.repos.getCollaboratorPermissionLevel({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              username: context.payload.comment.user.login,
+            });
+            const allowed = ['admin', 'write'];
+            if (!allowed.includes(perm.permission)) {
+              core.setFailed(`@${context.payload.comment.user.login} needs write access (has: ${perm.permission})`);
+            }
+
+      - name: Parse rate command
+        env:
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          PR_NUMBER: ${{ github.event.issue.number }}
+        run: |
+          if ! [[ "$PR_NUMBER" =~ ^[0-9]+$ ]]; then
+            echo "Invalid PR number: $PR_NUMBER" && exit 1
+          fi
+          APPLIED=$(echo "$COMMENT_BODY" | sed -n 's|^/guardian rate \([0-9]*\).*|\1|p')
+          if ! [[ "$APPLIED" =~ ^[0-9]+$ ]]; then
+            echo "Invalid applied count in comment: '$COMMENT_BODY'" && exit 1
+          fi
+          echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
+          echo "APPLIED=$APPLIED" >> $GITHUB_ENV
+
+      - name: Checkout main
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Rate review and push metrics
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          git fetch origin data/guardian-metrics
+          git show origin/data/guardian-metrics:guardian_metrics.jsonl \
+            > guardian_metrics.jsonl
+
+          uv run cgis guardian-rate "$PR_NUMBER" "$APPLIED" \
+            --metrics guardian_metrics.jsonl
+
+          if git ls-remote --exit-code origin data/guardian-metrics > /dev/null 2>&1; then
+            git worktree add /tmp/metrics origin/data/guardian-metrics
+          else
+            git worktree add --orphan -b data/guardian-metrics /tmp/metrics
+          fi
+          cp guardian_metrics.jsonl /tmp/metrics/
+          git -C /tmp/metrics add guardian_metrics.jsonl
+          git -C /tmp/metrics diff --cached --quiet || \
+            git -C /tmp/metrics commit \
+              -m "metrics: rate PR #${PR_NUMBER} applied=${APPLIED} [skip ci]"
+          git -C /tmp/metrics push origin HEAD:data/guardian-metrics

codegraph_brain-0.6.0/.github/workflows/release-please.yml

@@ -0,0 +1,77 @@
+name: Release Please
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  release-please:
+    name: Release Please
+    runs-on: ubuntu-latest
+    permissions:
+      # Scoped to this job only: the publish job below must never inherit
+      # write access to the repository.
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - name: Run release-please
+        id: release
+        uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071  # v4.4.1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    name: Publish to PyPI
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/codegraph-brain
+    permissions:
+      # Mints the short-lived OIDC token PyPI exchanges for an upload token.
+      # This is the whole point of trusted publishing: no API token in secrets.
+      id-token: write
+      # Lets the publish action attach PEP 740 provenance attestations.
+      attestations: write
+      contents: read
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Verify metadata
+        # Pinned and wheel-only: this job holds publish rights, so the tooling
+        # it pulls in must not be a floating version that can run setup scripts.
+        run: uvx --no-build --from "twine==7.0.0" twine check dist/*
+
+      - name: Verify version matches the tag
+        env:
+          TAG_NAME: ${{ needs.release-please.outputs.tag_name }}
+        run: |
+          set -euo pipefail
+          built=$(ls dist/*.whl | sed -E 's/.*-([0-9][^-]*)-py3.*/\1/')
+          echo "tag=$TAG_NAME built=$built"
+          case "$TAG_NAME" in
+            *"$built") ;;
+            *) echo "::error::tag $TAG_NAME does not match built version $built"; exit 1 ;;
+          esac
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2

codegraph_brain-0.6.0/.gitignore

@@ -0,0 +1,231 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# Superpowers planning artifacts
+docs/superpowers/
+.superpowers/
+.claude/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+graph.json
+*.db
+ui/
+guardian_metrics.jsonl
+
+# SQLite WAL/SHM sidecars
+*.db-wal
+*.db-shm

codegraph_brain-0.6.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.16
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.1.0
+    hooks:
+      - id: mypy
+        args: [--config-file=pyproject.toml]
+        files: ^src/
+        additional_dependencies:
+          - httpx>=0.27  # imported directly by guardian/providers/base.py (#275)
+          - pydantic>=2.13.4
+          - structlog>=25.5.0
+          - types-pyyaml>=6.0.12.20260518
+          - rich>=15.0.0
+          - typer>=0.26.7
+          - tree-sitter>=0.25.2
+          - tree-sitter-python>=0.25.0
+          - tree-sitter-typescript>=0.23.2
+          - pytest>=9.0.3
+          - "mcp[cli]>=2"  # must match the pyproject bound
+          - duckdb>=1.1.0

codegraph_brain-0.6.0/.python-version

@@ -0,0 +1 @@
+3.12

codegraph_brain-0.6.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.6.0"
+}