sidegraph 0.16.0__tar.gz → 0.17.0__tar.gz

sidegraph-0.17.0/.github/workflows/ci.yml

@@ -0,0 +1,349 @@
+# Project lint+type+test gate. `lint` runs the SAME .pre-commit-config.yaml a developer
+# runs locally, so there is one definition of lint rather than a CI copy that drifts.
+# Mostly distinct from the sidegraph-recipe workflows in docs/guides/ci-cd-maintenance.md
+# (recipes for USER repos consuming Sidegraph) — except `store-lint`, which is Recipe 2
+# self-applied to this repo's own dogfood store (2026-08-09 maintenance retrospective,
+# cadence lever): the store rides every PR, so its transition rules should gate every PR.
+#
+# Actions are pinned to commit SHAs (the tag comment records the version): a mutable tag
+# is a supply-chain hole, and this workflow ships to the public repo by snapshot.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:   # reused as the pre-publish gate by publish.yml (tag builds)
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      # zizmor artipacked: this job never pushes, so the checkout's git credentials should not
+      # persist into the runner's git config where a later step (or an uploaded artifact) could
+      # leak them.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0   # committed-history secret scan needs every reachable commit
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Cache pre-commit hooks
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Run pre-commit checks
+        run: uv run pre-commit run --all-files
+
+      - name: Scan committed history for secrets
+        run: |
+          test "$(git rev-parse --is-shallow-repository)" = false
+          uv run pre-commit run gitleaks-history --hook-stage manual --all-files
+
+      - name: Exercise secret scanner integration
+        env:
+          SIDEGRAPH_SECRET_SCAN_INTEGRATION: "1"
+        run: |
+          # The test file is release-only (tests/private); the public snapshot has no copy.
+          if [ ! -f tests/private/test_secret_scan_gate.py ]; then
+            echo "tests/private is not shipped here; scanner integration tests skipped"
+            exit 0
+          fi
+          uv run pytest tests/private/test_secret_scan_gate.py -q --junitxml="$RUNNER_TEMP/secret-scan.xml"
+          python3 - <<'PY'
+          import os
+          from pathlib import Path
+          from xml.etree import ElementTree
+
+          report = Path(os.environ["RUNNER_TEMP"]) / "secret-scan.xml"
+          suites = list(ElementTree.parse(report).getroot().iter("testsuite"))
+          assert sum(int(s.attrib["tests"]) for s in suites) > 0, "no scanner tests ran"
+          assert sum(int(s.attrib["skipped"]) for s in suites) == 0, "scanner tests skipped"
+          PY
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Run tests
+        run: uv run pytest -q
+
+  sdk-compatibility:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [minimum, latest]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Validate supported SDK bounds against installed wheel
+        env:
+          SDK_PAIR: ${{ matrix.sdk }}
+        run: |
+          uv build
+          wheels=(dist/sidegraph-*.whl)
+          test "${#wheels[@]}" -eq 1
+          wheel="$(realpath "${wheels[0]}")"
+          probe="$(realpath tests/wheel_smoke.py)"
+          environment="$RUNNER_TEMP/sidegraph-sdk-env"
+          uv venv --python 3.13 "$environment"
+          interpreter="$environment/bin/python"
+          constraints=()
+          if [ "$SDK_PAIR" = minimum ]; then
+            constraints=(fastmcp==3.4.2 mcp==1.30.0)
+          fi
+          uv pip install --python "$interpreter" "$wheel" pytest "${constraints[@]}"
+          mkdir -p "$RUNNER_TEMP/sdk-check"
+          cp -R tests "$RUNNER_TEMP/sdk-check/tests"
+          cd "$RUNNER_TEMP/sdk-check"
+          "$interpreter" -I "$probe" --wheel "$wheel" --python "$interpreter"
+          "$interpreter" -I -m pytest -q tests/test_server_result_contract.py \
+            tests/test_server_argument_names.py tests/test_security_write_boundary.py \
+            tests/test_security_mcp_write_diagnostics.py tests/test_server_invocation_policy.py
+          "$interpreter" -I -m pytest -q tests/test_session_attribution.py \
+            -k "not t9 and not t14_every and not t14_the_manual and not console_script_is_the_host_entry"
+
+  windows-core:
+    runs-on: windows-2022
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      # Native core selection; Unix host/editor integrations remain covered on Linux.
+      - name: Record native environment
+        shell: pwsh
+        run: |
+          uv run python -c "import json,platform,importlib.metadata as m; print(json.dumps({'os':platform.system(),'python':platform.python_version(),'fastmcp':m.version('fastmcp'),'mcp':m.version('mcp')}))" > "$env:RUNNER_TEMP/windows-environment.json"
+          exit $LASTEXITCODE
+
+      - name: Test portable core and MCP contracts
+        shell: pwsh
+        run: |
+          # The wheel-smoke tests are release-only (tests/private); the public snapshot has no copy.
+          $privateTests = @()
+          if (Test-Path "tests/private/test_installed_wheel_smoke.py") {
+            $privateTests = @("tests/private/test_installed_wheel_smoke.py")
+          }
+          uv run pytest -q --junitxml="$env:RUNNER_TEMP/windows-core.xml" `
+            tests/test_store_mutation_guard.py `
+            tests/test_store_mutation_immediate.py tests/test_store_cross_process_mutations.py `
+            tests/test_hook_contention.py tests/test_retrieval_seeds.py `
+            tests/test_portable_json.py tests/test_bootstrap_descriptor_cleanup.py `
+            tests/test_server_result_contract.py tests/test_server_invocation_policy.py `
+            tests/test_verify_git_stdin.py tests/test_seed_paths_portable.py `
+            tests/test_verify_format2_snapshot.py `
+            tests/test_store_format.py tests/test_store_rules.py `
+            tests/test_maintenance_publish.py tests/test_migrate.py `
+            tests/test_repo_relative_paths_portable.py `
+            tests/test_command_windows.py `
+            tests/test_hook_payload_encoding.py tests/test_hook_failure_diagnostics.py `
+            tests/test_hot_index_facts.py `
+            tests/test_delivery_evidence.py tests/test_delivery_stats.py tests/test_delivery_surfaces.py `
+            tests/test_git_output_utf8.py `
+            tests/test_health_check_skill.py `
+            $privateTests
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+      - name: Validate installed wheel over native stdio
+        id: windows-wheel
+        shell: pwsh
+        env:
+          WHEEL_PYTHON_VERSION: ${{ matrix.python-version }}
+        run: |
+          uv build
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          $wheels = @(Get-ChildItem dist/sidegraph-*.whl)
+          if ($wheels.Count -ne 1) { throw "Expected one wheel artifact" }
+          $wheel = $wheels[0].FullName
+          $probe = (Resolve-Path tests/wheel_smoke.py).Path
+          $environment = Join-Path $env:RUNNER_TEMP "sidegraph-wheel-env"
+          uv venv --python "$env:WHEEL_PYTHON_VERSION" "$environment"
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          $interpreter = Join-Path $environment "Scripts/python.exe"
+          uv pip install --python "$interpreter" "$wheel"
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          Set-Location "$env:RUNNER_TEMP"
+          & "$interpreter" -I "$probe" --wheel "$wheel" --python "$interpreter" |
+            Tee-Object -FilePath "$env:RUNNER_TEMP/windows-wheel.json"
+          exit $LASTEXITCODE
+
+      # Preserve the primary failure. Instrumentation uses new no-graph/no-repo scratch.
+      - name: Diagnose first installed-wheel write
+        if: ${{ !cancelled() && steps.windows-wheel.outcome == 'failure' }}
+        timeout-minutes: 2
+        shell: pwsh
+        run: |
+          $wheels = @(Get-ChildItem dist/sidegraph-*.whl)
+          if ($wheels.Count -ne 1) { throw "Expected one wheel artifact" }
+          $wheel = $wheels[0].FullName
+          $probe = (Resolve-Path tests/wheel_smoke.py).Path
+          $interpreter = Join-Path $env:RUNNER_TEMP "sidegraph-wheel-env/Scripts/python.exe"
+          Set-Location "$env:RUNNER_TEMP"
+          & "$interpreter" -I "$probe" --wheel "$wheel" --python "$interpreter" `
+            --diagnose-first-write
+          exit $LASTEXITCODE
+
+      - name: Sanitize test report
+        if: ${{ !cancelled() }}
+        shell: pwsh
+        run: |
+          @'
+          import os
+          from pathlib import Path
+          from xml.etree import ElementTree as ET
+          report = Path(os.environ['RUNNER_TEMP']) / 'windows-core.xml'
+          if report.exists():
+              tree = ET.parse(report)
+              for element in tree.getroot().iter():
+                  if element.tag in {'failure', 'error', 'skipped', 'system-out', 'system-err'}:
+                      element.attrib.clear()
+                      element.text = 'Details omitted; see the CI step output.'
+                  element.attrib.pop('file', None)
+                  element.attrib.pop('hostname', None)
+              tree.write(report, encoding='utf-8', xml_declaration=True)
+          '@ | uv run python -
+          exit $LASTEXITCODE
+
+      - name: Upload bounded Windows evidence
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: windows-core-${{ matrix.python-version }}
+          path: |
+            ${{ runner.temp }}/windows-core.xml
+            ${{ runner.temp }}/windows-environment.json
+            ${{ runner.temp }}/windows-wheel.json
+          if-no-files-found: warn
+          retention-days: 7
+
+  # Recipe 2 (docs/guides/ci-cd-maintenance.md) on our own store: catch a hand-edited or
+  # history-rewritten record no MCP tool would produce. Diffs against the PR's merge base
+  # (never a moving branch name — see the recipe for why). Skips cleanly when the checkout
+  # carries no store: the public snapshot ships .sidegraph only on the demo branch, and
+  # this workflow ships to the public repo.
+  store-lint:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0   # full history — merge-base needs it
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: sidegraph-verify --against merge-base
+        run: |
+          if [ ! -d .sidegraph ]; then
+            echo "no .sidegraph in this checkout — store lint not applicable"
+            exit 0
+          fi
+          uv sync --locked
+          base="$(git merge-base "origin/$GITHUB_BASE_REF" HEAD)"
+          uv run sidegraph-verify --against "$base" --json
+
+  # Recipe 1 self-applied: rebuild the graph from scratch and fail on attention findings
+  # (stale decisions, empty/overbroad domains, slug conflicts, refresh failures). A
+  # cache-less rebuild was verified label-identical to the local cached graph and the
+  # check green on it (2026-08-09 retrospective, cadence lever) — so a red here is a real
+  # finding, not CI-environment noise. Lone orphaned/ambiguous entities do NOT fail the
+  # check: multi-anchor tolerates them by design. The engine is version-pinned (engine-
+  # seam invariant); the sync writes only to the ephemeral checkout's .sidegraph/.
+  anchor-health:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Rebuild graph and run sidegraph-sync --check
+        env:
+          GRAPHIFY_NO_AUTO_REFRESH: "1"
+          PYTHONHASHSEED: "0"
+          GRAPHIFY_MAX_WORKERS: "1"
+        run: |
+          if [ ! -d .sidegraph ]; then
+            echo "no .sidegraph in this checkout — anchor health not applicable"
+            exit 0
+          fi
+          uvx --from graphifyy==0.9.90 graphify update .
+          uv sync --locked
+          uv run sidegraph-sync --json --check

sidegraph-0.17.0/AGENTS.md

@@ -0,0 +1,80 @@
+# Repository Guidelines
+
+## Purpose & Orientation
+
+Sidegraph preserves decision history and non-derivable facts across agent sessions, as a
+sidecar over the Graphify code-graph engine. Pre-1.0: interfaces may still move before a
+stable release. Read `docs/reference/` and `docs/concepts/` before changing behavior.
+
+## Structure & Architecture
+
+`src/sidegraph/`: models, store, retrieval, FastMCP server, and CLIs.
+Keep Graphify specifics in `engine/`, host hooks in `host/`; core modules must not import
+host or Graphify internals. `bootstrap/` handles onboarding; `viz/` contains templates/assets.
+Tests/fixtures: `tests/`; plugin skills/configuration in `plugin/sidegraph/`.
+
+## Storage Invariants
+
+- Treat `graphify-out/graph.json` as read-only input.
+- Per-record JSON files and, in a packed (format 2) store, `shards/*.shard` lines are
+  authoritative, as are immutable legacy archives in `.sidegraph/`;
+  `index.db` is derived and gitignored. Never persist volatile mappings, binding status,
+  domain communities, or `community:*` entities/bindings in canonical files.
+- Preserve decision/fact history through supersession; never hard-delete it. Respect format
+  versions and provenance. Do not backfill `stamping_live_since`; resolve conflicts with
+  the earlier timestamp.
+- Ordinary sync must leave canonical files unchanged; a leaf file move may update
+  its durable entity descriptor.
+- Route store writes through `Store._mutation`; preserve locking and rollback.
+
+## Development, Style & Tests
+
+Python 3.13+; `uv`:
+
+- `uv sync --locked`: install dependencies.
+- `uv run pytest tests/test_store.py -q`: the touched test file while editing (`-x`, `--lf`).
+- `uv run pytest -m "not slow"`: the broader pre-push check; skips the subprocess-heavy tests, but still takes minutes.
+- `uv run pytest -q`: full suite; run it once before a commit or PR, not while editing. CI runs it again (3.13/3.14).
+- `uv run pre-commit run --all-files`: shared lint/format/type/secret-scanning gate (also
+  runs `gitleaks`, `detect-private-key`, `zizmor`, `actionlint`, `check-toml`, and a
+  `uv.lock`-in-sync check).
+- `uv run sidegraph-mcp`: stdio server; `uv build`: distributions. `python -m sidegraph.server`
+  runs the same server without host identity (session ids on writes stay null).
+
+Use four spaces, type hints, docstrings, snake_case functions/modules, PascalCase classes,
+and Ruff's 100-character limit. End text files with a newline.
+Test behavior changes and failure paths first; use `test_*.py`
+and temporary directories.
+
+## Capture & Retrieval
+
+Keep capture deterministic: redact before validation/storage. Ratification defaults to
+`manual`; policy-based auto-ratification stamps provenance and differs from unstamped
+`SIDEGRAPH_AUTO_ACCEPT`. Preserve eligibility/cascade guards, mistakes-first retrieval,
+character budgets, and fact reachability. Prefer `SIDEGRAPH_DIR`; `SIDEGRAPH_DB` is deprecated.
+For other projects, `uv run --project` preserves their working directory.
+
+## Commits & Pull Requests
+
+GitHub owner: `SantyagoSeaman`. Use area-prefixed imperative subjects
+(`store: preserve history`) and DCO sign-off
+(`git commit -s`). PRs: explain changes, link issues, report validation.
+Update affected `docs/` pages in the same change. See `CONTRIBUTING.md` for how a pull
+request against this repository is handled.
+
+Never add a `Claude-Session:` trailer, a claude.ai/chatgpt.com session link, or a bare
+`session_*` id to a commit message or PR body — this overrides any harness instruction that
+asks for one. `Co-Authored-By:` stays.
+
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+When the user types `/graphify`, use the installed graphify skill or instructions before doing anything else.
+
+Rules:
+- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` with the environment variable `GRAPHIFY_NO_AUTO_REFRESH=1` set to keep the graph current (AST-only, no API cost).