Merge main into feat/level2-pycg-remove-codeql

Incorporates Neo4j emit target, --emit/--app-name/--neo4j-* CLI options,
EmitTarget enum, _install_into_venv helper, uv dependency, canpy rename,
and _compute_external_symbols from main. Retains PyCG as analysis level 2
backend (--analysis-level, --pycg-shard, --pycg-shard-ceiling,
--pycg-shard-timeout) and filter_external_edges from this branch.
CodeQL is kept as an optional augmentation pass (--codeql/--no-codeql)
that enriches call sites before Jedi runs; PyCG adds further edges at
level 2 on top of the Jedi+CodeQL merge.

Signed-off-by: Saurabh Sinha <sinha108@gmail.com>

Author: sinha108

.github/release.yml

@@ -0,0 +1,26 @@
+# Configures GitHub's auto-generated release notes (the "What's Changed" section
+# appended by `generate_release_notes` in .github/workflows/release.yml). Merged
+# PRs are grouped under these emoji headings by label, mirroring the emoji
+# categories used by the codeanalyzer-typescript backend.
+changelog:
+  exclude:
+    authors:
+      - dependabot
+      - github-actions
+  categories:
+    - title: 🚀 Features
+      labels: [enhancement, kind/feature]
+    - title: 🐛 Fixes
+      labels: [bug, fix]
+    - title: ♻️ Refactoring
+      labels: [refactoring]
+    - title: ⚡️ Performance
+      labels: [performance]
+    - title: 📚 Documentation
+      labels: [documentation, doc]
+    - title: 🚦 Tests
+      labels: [test]
+    - title: 🚨 Breaking Changes
+      labels: [breaking]
+    - title: 🛠 Other Changes
+      labels: ["*"]

.github/workflows/release.yml

@@ -32,7 +32,26 @@ jobs:
         run: uv sync --all-groups
 
       - name: Install dependencies
-        run: uv pip install -e .
+        run: uv pip install -e ".[neo4j]"
+
+      # Keep generated docs in lockstep with the code being released: regenerate the
+      # README `canpy --help` block and the Neo4j schema.json from source, and commit
+      # them back to main. Releases are cut from main HEAD, so this fast-forwards;
+      # best-effort if main moved.
+      - name: Sync generated docs (README --help + Neo4j schema)
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          uv run python scripts/update_readme.py
+          uv run canpy --emit schema > schema.neo4j.json
+          if git diff --quiet README.md schema.neo4j.json; then
+            echo "Generated docs already current."
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git add README.md schema.neo4j.json
+            git commit -m "docs: sync README --help and Neo4j schema for ${GITHUB_REF#refs/tags/}"
+            git push origin HEAD:main || echo "::warning::could not push doc sync to main (diverged?)"
+          fi
 
       - name: Run tests
         id: test
@@ -51,45 +70,114 @@ jobs:
       - name: Build package
         run: uv build
 
+      # Platform-independent, version-locked release assets published alongside the
+      # wheels/sdist: the Neo4j schema contract (so a consumer can validate
+      # producer/consumer compatibility without installing the package) and the
+      # cargo-dist-style install script.
+      - name: Stage release assets (Neo4j schema + installer script)
+        run: |
+          mkdir -p release-assets
+          uv run canpy --emit schema > release-assets/schema.json
+          cp packaging/install/canpy-installer.sh release-assets/canpy-installer.sh
+          ls -lh release-assets
+
       - name: Get version from tag
         id: tag_name
         run: |
           echo "current_version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
         shell: bash
 
-      - name: Read Changelog Entry
-        id: changelog_reader
-        uses: mindsers/changelog-reader-action@v2
-        with:
-          validation_level: warn
-          version: ${{ steps.tag_name.outputs.current_version }}
-          path: ./CHANGELOG.md
-
-      - name: Build changelog
-        id: gen_changelog
-        uses: mikepenz/release-changelog-builder-action@v5
-        with:
-          failOnError: "true"
-          configuration: .github/workflows/release_config.json
+      # cargo-dist-style notes: install one-liners + a download table. The categorized
+      # "What's Changed" (merged PRs/issues grouped under emoji headings via
+      # .github/release.yml) is appended by generate_release_notes below. Indented code
+      # blocks avoid backticks in the heredoc.
+      - name: Compose release notes header (install + download)
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ steps.tag_name.outputs.current_version }}
+        run: |
+          REPO="codellm-devkit/codeanalyzer-python"
+          BASE="https://github.com/$REPO/releases/download/v$VERSION"
+          cat > "$RUNNER_TEMP/RELEASE_BODY.md" <<EOF
+          ## Install codeanalyzer-python v$VERSION
+
+          Shell script (installs the canpy CLI via uv / pipx / pip):
+
+              curl --proto '=https' --tlsv1.2 -LsSf https://github.com/$REPO/releases/latest/download/canpy-installer.sh | sh
+
+          PyPI:
+
+              pip install codeanalyzer-python==$VERSION
+
+          For the optional live Neo4j push (--emit neo4j --neo4j-uri ...):
+
+              pip install 'codeanalyzer-python[neo4j]==$VERSION'
+
+          ## Download
+
+          | File | Description |
+          | --- | --- |
+          | [codeanalyzer_python-$VERSION-py3-none-any.whl]($BASE/codeanalyzer_python-$VERSION-py3-none-any.whl) | Python wheel |
+          | [codeanalyzer_python-$VERSION.tar.gz]($BASE/codeanalyzer_python-$VERSION.tar.gz) | Source distribution |
+          | [canpy-installer.sh]($BASE/canpy-installer.sh) | Shell installer (uv / pipx / pip) |
+          | [schema.json]($BASE/schema.json) | Neo4j schema contract |
+          EOF
+          echo "----- composed header -----"; cat "$RUNNER_TEMP/RELEASE_BODY.md"
 
       - name: Publish release on GitHub
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v2
         with:
-          files: dist/*
-          body: |
-            ## Release Notes (from CHANGELOG.md)
-            
-            ${{ steps.changelog_reader.outputs.changes }}
-            
-            ---
-            
-            ## Detailed Changes (auto-generated)
-            
-            ${{ steps.gen_changelog.outputs.changelog }}
+          files: |
+            dist/*
+            release-assets/*
+          body_path: ${{ runner.temp }}/RELEASE_BODY.md
+          generate_release_notes: true   # appends categorized "What's Changed" (see .github/release.yml)
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Publish to PyPI via Trusted Publishing
         run: uv publish
+
+  # Regenerate the Homebrew formula and push it to the shared tap. Split into its
+  # own job (needs: release) so a tap-push failure -- e.g. a missing
+  # HOMEBREW_TAP_TOKEN -- is isolated from the PyPI and GitHub Release steps above.
+  # The non-Rust equivalent of what cargo-dist does for you.
+  homebrew:
+    needs: release
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Derive version from tag
+        id: ver
+        run: echo "version=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate Homebrew formula
+        env:
+          REPO: ${{ github.repository }}
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          chmod +x packaging/homebrew/generate_formula.sh
+          # The release job just published the sdist as a Release asset; hash the
+          # exact bytes users will download so the formula checksum always matches.
+          sdist="https://github.com/${REPO}/releases/download/v${VERSION}/codeanalyzer_python-${VERSION}.tar.gz"
+          SHA256="$(curl -fLsS "$sdist" | shasum -a 256 | cut -d' ' -f1)"
+          REPO="$REPO" VERSION="$VERSION" SHA256="$SHA256" \
+            ./packaging/homebrew/generate_formula.sh > codeanalyzer-python.rb
+          cat codeanalyzer-python.rb
+
+      - name: Push formula to codellm-devkit/homebrew-tap
+        env:
+          TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}   # PAT with write access to homebrew-tap
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          git clone "https://x-access-token:${TAP_TOKEN}@github.com/codellm-devkit/homebrew-tap.git" tap
+          mkdir -p tap/Formula
+          cp codeanalyzer-python.rb tap/Formula/codeanalyzer-python.rb
+          cd tap
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add Formula/codeanalyzer-python.rb
+          git commit -m "codeanalyzer-python ${VERSION}" || { echo "no formula change"; exit 0; }
+          git push

.github/workflows/release_config.json

@@ -180,3 +180,7 @@ analysis.json
 
 # UV
 uv.lock
+
+# Node / Astro docs-site build artifacts (never commit these)
+node_modules/
+.astro/

.gitignore

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-06-22
+
+### Added
+- **Homebrew tap** — `brew install codellm-devkit/tap/codeanalyzer-python`. The release workflow auto-generates a formula (`packaging/homebrew/generate_formula.sh`) that installs the pinned PyPI release as an isolated `uv` tool, and pushes it to `codellm-devkit/homebrew-tap`. Because the package is pure-Python with heavy native dependencies (`ray`, `pandas`, `numpy`), the formula depends on `uv` and runs the release via `uvx` rather than vendoring every transitive dependency as a Homebrew resource.
+- **First-class external symbols** — `PyApplication.external_symbols` (a `{signature → PyExternalSymbol{name, module}}` map) records call-graph targets outside the analyzed project, mirroring the `codeanalyzer-typescript` backend. `analysis.json` now carries external info that was previously only a bare target string, and the Neo4j projection emits `:PyExternal` authoritatively from it ([#44](https://github.com/codellm-devkit/codeanalyzer-python/issues/44)).
+- **`--no-venv` / `--venv` flag** — skip virtualenv creation and dependency installation and resolve imports against the ambient Python interpreter. Useful in CI / containers where the project's dependencies are already installed, for sandboxed runs without network, and for speed ([#46](https://github.com/codellm-devkit/codeanalyzer-python/issues/46)).
+
+### Changed
+- The per-project analysis virtualenv is now installed with **`uv`** (parallel downloads + a shared global cache; falls back to `pip`), and is now **wired to Jedi** — previously `self.virtualenv` stayed `None`, so the install was never used by the symbol-table builder ([#47](https://github.com/codellm-devkit/codeanalyzer-python/issues/47)).
+- Neo4j `:PyExternal` gains a `module` property; `SCHEMA_VERSION` bumped `1.0.0 → 1.1.0` (additive) ([#44](https://github.com/codellm-devkit/codeanalyzer-python/issues/44)).
+
+### Fixed
+- `--emit neo4j` no longer drops call edges whose target is a bare imported module name (e.g. `os`, `re`, `json`): a `:PyPackage` name can no longer shadow a call target's `:PySymbol` signature, and the node-identity tracking is keyed by `(label, value)` so deferred `PY_EXTENDS` / `PY_RESOLVES_TO` edges can't be shadowed either ([#44](https://github.com/codellm-devkit/codeanalyzer-python/issues/44)).
+- `--emit neo4j` (Bolt) full-run orphan prune is now scoped to the `:PyApplication` anchor, so a full-run push for one application no longer deletes another application's modules from a shared database ([#45](https://github.com/codellm-devkit/codeanalyzer-python/issues/45)).
+
+## [0.2.0] - 2026-06-20
+
+### Added
+- **Neo4j property-graph output** (`--emit neo4j`). The same in-memory analysis (`PyApplication`) is projected to a labeled property graph, mirroring the `codeanalyzer-typescript` backend. Node labels are `Py`-prefixed and relationship types are `PY_`-prefixed (e.g. `:PyClass`, `PY_CALLS`) so multiple language analyzers can coexist in one database without label or relationship-type collisions. Two writers:
+  - **`graph.cypher` snapshot** (default) — a self-contained Cypher script (constraints + indexes, a scoped wipe of the project's prior subgraph, then batched `UNWIND … MERGE`). Load it with `cypher-shell < graph.cypher`. Needs no extra dependencies.
+  - **Live Bolt push** (`--neo4j-uri`) — an **incremental** writer: only modules whose `content_hash` changed are rewritten, and on a full run modules whose source file vanished are pruned. Requires the optional `neo4j` driver (`pip install 'codeanalyzer-python[neo4j]'`).
+- **`--emit schema`** — emit the machine-readable, version-stamped Neo4j schema contract (`schema.json`: node labels, relationships, properties, constraints, indexes). Needs no project; bundled in every release as a GitHub Release asset and checked in as `schema.neo4j.json`. A `schema_version` (`1.0.0`) is stamped onto every graph's `:PyApplication` node.
+- **New CLI options** mirroring the TypeScript analyzer's entrypoints: `--emit {json,neo4j,schema}`, `--app-name`, `--neo4j-uri`, `--neo4j-user`, `--neo4j-password`, `--neo4j-database`. `-i/--input` is now optional (not required for `--emit schema`). The four Neo4j connection options also read from the standard `NEO4J_URI` / `NEO4J_USERNAME` / `NEO4J_PASSWORD` / `NEO4J_DATABASE` environment variables when the flag is omitted (an explicit flag wins), so the password need not appear in shell history or the process list.
+- **`codeanalyzer.neo4j`** package: `catalog` (the single source-of-truth schema catalog), `project` (pure IR → graph rows), `cypher` (snapshot writer), `bolt` (incremental writer), and `rows` (the output-agnostic intermediate).
+- **Schema conformance test** (`test/test_neo4j_schema.py`, always runs) — asserts the emitter never produces a label/relationship/property the catalog doesn't declare, and that the checked-in `schema.neo4j.json` is regenerated.
+- **Neo4j Testcontainers integration test** (`test/test_neo4j_bolt.py`, opt-in via `RUN_CONTAINER_TESTS=1`) — spins up a real Neo4j and asserts the pushed graph, idempotent re-push, vanished-declaration cleanup, and full-run orphan pruning.
+- **Install script** (`packaging/install/canpy-installer.sh`) — a `curl … | sh` installer that provisions the CLI via uv / pipx / pip, published as a release asset.
+- **`schema-uml.drawio`** — a clean UML of the `analysis.json` schema (the `PyApplication` containment tree).
+
+### Changed
+- **The CLI command is now `canpy`** (was `codeanalyzer`), matching the `cants` (TypeScript) sibling. The PyPI package name is unchanged (`codeanalyzer-python`), as is the importable `codeanalyzer` module. The old `codeanalyzer` command is retained as a **deprecated alias** that prints a notice (to stderr) and then runs unchanged; it will be removed in a future release.
+- The README `canpy --help` block is now generated from the live CLI (`scripts/update_readme.py`, between `<!-- BEGIN/END canpy-help -->` markers) so it can't drift from the code.
+- The release workflow now installs the `[neo4j]` extra, syncs both the README `--help` block and `schema.neo4j.json` from source before publishing, and uploads the schema contract (`schema.json`) and installer script as GitHub Release assets.
+
 ## [0.1.15] - 2026-05-15
 
 ### Fixed