hedwig-cg 0.9.0__tar.gz

hedwig_cg-0.9.0/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "hedwig_cg/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/ci.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "hedwig_cg/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/ci.yml"
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check hedwig_cg/
+
+      - name: Run tests
+        run: pytest --tb=short -q
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Verify wheel contents
+        run: |
+          pip install dist/*.whl
+          hedwig-cg --version
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+

hedwig_cg-0.9.0/.github/workflows/release.yml

@@ -0,0 +1,117 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version (e.g. v0.1.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check hedwig_cg/
+
+      - name: Test
+        run: pytest --tb=short -q
+
+  release:
+    runs-on: ubuntu-latest
+    needs: test
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Validate version format
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          if [[ ! "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Version must match vX.Y.Z format (e.g. v0.1.0)"
+            exit 1
+          fi
+
+      - name: Check tag does not already exist
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          if git rev-parse "$VERSION" >/dev/null 2>&1; then
+            echo "::error::Tag $VERSION already exists"
+            exit 1
+          fi
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Verify wheel
+        run: |
+          pip install dist/*.whl
+          hedwig-cg --version
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Generate changelog
+        env:
+          VERSION: ${{ inputs.version }}
+          REPO: ${{ github.repository }}
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+
+          if [ -z "$PREV_TAG" ]; then
+            COMMITS=$(git log --pretty=format:"- %s (%h)" --no-merges)
+            COMPARE_BASE=$(git rev-list --max-parents=0 HEAD | head -1)
+          else
+            COMMITS=$(git log "${PREV_TAG}..HEAD" --pretty=format:"- %s (%h)" --no-merges)
+            COMPARE_BASE="$PREV_TAG"
+          fi
+
+          {
+            echo "## What's Changed"
+            echo ""
+            echo "$COMMITS"
+            echo ""
+            echo "**Full Changelog**: https://github.com/${REPO}/compare/${COMPARE_BASE}...${VERSION}"
+          } > release_notes.md
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ inputs.version }}
+          SHA: ${{ github.sha }}
+        run: |
+          gh release create "$VERSION" dist/* \
+            --title "$VERSION" \
+            --notes-file release_notes.md \
+            --target "$SHA"

hedwig_cg-0.9.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# hedwig-cg databases (generated)
+.hedwig-cg/
+.hedwig-cb/
+
+# Claude Code
+.claude/
+CLAUDE.md
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+
+# Internal review feedback (not for public repo)
+feedbacks/
+
+# Generated integration files (from hedwig-cg install commands)
+.cursor/
+.windsurf/
+.codex/
+AGENTS.md
+GEMINI.md
+CONVENTIONS.md
+.aider.conf.yml
+
+# OMC state
+.omc/

hedwig_cg-0.9.0/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-04-11
+
+### Added
+- **Cursor IDE integration** (`hedwig-cg cursor install/uninstall`): Creates `.cursor/rules/hedwig-cg.mdc` with alwaysApply rules
+- **Windsurf IDE integration** (`hedwig-cg windsurf install/uninstall`): Creates `.windsurf/rules/hedwig-cg.md` for Cascade
+- **Cline (VS Code extension) integration** as 8th supported AI agent
+- **`hedwig-cg doctor` command**: 21-point installation health check (Python version, deps, tree-sitter parsers, MCP, embedding models, DB integrity, FAISS indexes)
+- **MCP tool descriptions optimized for AI agents**: `search` marked as PRIMARY tool, `communities` marked as "rarely needed", `instructions` guide agents to start with search
+- **AI Agent Interface Design Principle** documented in CLAUDE.md: minimal interface philosophy to prevent hallucination
+- **Weighted Reciprocal Rank Fusion**: Per-signal weights (code_vec=1.0, text_vec=1.0, graph=0.8, keyword=1.5, community=0.7) tuned for optimal search quality
+- **Stopword filtering**: 80+ common English stopwords removed from keyword/community search terms for improved FTS5 precision
+- **LRU search result cache** (128 entries): Instant return for repeated queries, auto-cleared on graph rebuild
+- **Query embedding LRU cache** (256 entries): Eliminates re-encoding for identical queries (291ms → 0ms)
+- `extract_search_terms()` public API for reusable stopword-filtered term extraction
+- `clear_search_cache()` and `clear_query_cache()` public APIs
+- `weights` parameter on `hybrid_search()` for runtime signal weight tuning
+- **Weight-aware graph expansion**: BFS traversal now uses edge weights (semantic similarity + confidence + proximity) and relation-type weights (`calls`/`inherits`=1.0, `imports`=0.7, `defines`=0.5, `contains`=0.3) instead of uniform hop distance
+- `RELATION_WEIGHTS` dictionary for configurable per-relation expansion priority
+- **Parent class context in embeddings**: Method/constructor/property nodes now include "method of ClassName" in embedding text for better class-membership queries
+- **Query-relevant snippets**: Search results now show the most query-term-dense region of source code instead of blind truncation from the start
+- **MCP Server** (`hedwig-cg mcp`): Model Context Protocol server exposing 5 tools (search, node, stats, communities, build) over stdio transport for universal AI agent integration
+- **Search signal explainability**: Each result now includes per-signal RRF contribution breakdown (code_vector, text_vector, graph, keyword, community) in CLI table and MCP output
+- **JS/TS call graph extraction**: Tree-sitter now extracts function/method calls in JavaScript and TypeScript (previously only Python had call tracking), with JS builtin filtering
+- **Pipeline stage timing**: Build command now displays per-stage wall-clock timing breakdown (detect, extract, build, pagerank, embed, cluster, analyze, store) with total elapsed time
+- **Incremental embedding**: `--incremental` builds now skip re-embedding unchanged nodes by checking existing embeddings in DB, reducing rebuild time by up to 95% (8.7s → 0.4s when no files changed)
+- **Fast search mode**: `--fast` flag uses text model only, skipping code model loading for lower cold-start latency; available in CLI, REPL, and MCP server
+- **REPL model preloading**: `hedwig-cg query` REPL now preloads embedding models in a background thread so first search is faster
+- **Python decorator extraction**: Decorators (`@dataclass`, `@cli.command()`, `@staticmethod`, etc.) are now extracted and stored as node attributes, enriching embeddings for decorator-aware search
+- **Search result line numbers**: Results now include `start_line`/`end_line` in CLI (`file.py:42`), MCP server (`file.py:42-67`), and SearchResult API — enabling AI agents to navigate directly to code
+
+### Changed
+- README updated with real benchmarks (9.5s full build, 0.4s incremental, 0.08s warm search), new features (fast search, line numbers, decorator extraction, incremental embedding), and revised optimizations list
+- FAISS index loading now uses `IO_FLAG_MMAP` for lower RSS and faster cold starts on large indices (with automatic fallback)
+- Pipeline automatically clears search result and query embedding caches after rebuild
+- RRF keyword weight boosted from 1.0 → 1.5 so exact-match code entities rank higher
+- Graph expansion seeds increased from top-5 to top-8 for broader graph signal coverage
+
+### Fixed
+- **CI failure**: Added `mcp>=1.0` to dev dependencies and `pytest.importorskip("mcp")` guard for graceful skip
+- **MCP stats tool**: Fixed `compute_god_nodes` (non-existent) → `analyze()` from analyze module returning `AnalysisResult.god_nodes`
+- **Fast mode variable shadowing**: `code_vector_hits` was incorrectly overwritten with text-model results
+
+### Performance
+- Search performance improved ~46% (5.9s → 3.2s) via FAISS disk persistence and graph expansion caching
+- Query embedding cache hit: 291ms → 0ms (3M+ speedup for repeated queries)
+- FAISS mmap loading reduces memory footprint for large indices
+- Warm search: 0.02s, cached search: 0.006s (986 nodes / 2091 edges)
+
+## [0.1.2] - 2026-04-11
+
+### Added
+- **Chinese (简体中文) README** (`docs/README_zh.md`)
+- **German (Deutsch) README** (`docs/README_de.md`)
+- Cross-language navigation links across all 5 README variants (en, ko, ja, zh, de)
+
+### Fixed
+- Correct HybridRAG signal count from "6-signal" to "5-signal" across all documentation, code comments, and CLAUDE.md (actual RRF receives 5 ranked lists: code vector, text vector, graph, keyword, community)
+- Clarify `hedwig-cg search` as the single primary HybridRAG entry point in skill rules and PreToolUse hook
+
+## [Unreleased]
+
+### Added
+- **Community-aware HybridRAG**: 5-signal search (code vector + text vector + graph + keyword + community)
+- **Community summaries**: Auto-generated keyword-rich text from node labels, kinds, docstrings, and file paths
+- **`hedwig-cg communities` CLI command**: List, filter by level, and search communities
+- **Markdown document extraction**: Headings become section nodes with hierarchy, internal links become reference edges
+- **Incremental build** (`--incremental`): SHA-256 content hashing skips unchanged files for fast rebuilds
+- **Embedding download UX**: Rich console message on first model download (~80MB)
+- `community_search()` method in KnowledgeStore for summary-based community lookup
+- **D3.js export format** (`--format d3`): Force-directed graph JSON with PageRank-based sizing and kind-based grouping
+- **`hedwig-cg visualize` CLI command**: Self-contained interactive HTML visualization with zoom, search, tooltips, and drag
+- **`hedwig-cg clean` CLI command**: Remove .hedwig-cg/ database directory with confirmation prompt
+- **Graph quality metrics in `stats`**: Density, connected components, average clustering coefficient
+- Comprehensive CLI command tests (communities, search, d3 export, visualize, clean)
+- Comprehensive JavaScript tree-sitter extraction tests (17 tests)
+- **`hedwig-cg query` REPL**: Interactive search session with `:node`, `:stats`, `:quit` commands
+- **`--offline` flag for `visualize`**: Inlines D3.js (~280KB) for airgapped/offline environments
+- **TypeScript-specific extraction**: Interfaces (with extends/method signatures), type aliases, enums with member extraction
+- E2E integration tests for full pipeline (build → store → search → incremental → export → clean)
+- TypeScript-specific tree-sitter extraction tests (12 tests)
+- 160 tests with 87% code coverage (up from 61 tests)
+- **PyPI classifiers expansion**: Python 3.10/3.11/3.12, AI/NLP topics, `Typing :: Typed`, OS Independent
+- **GitHub Actions PyPI publish**: Automated deployment on GitHub Release via `pypa/gh-action-pypi-publish`
+
+### Fixed
+- **Critical**: `dependencies` in pyproject.toml was under `[project.urls]` TOML section, causing wheel to declare zero dependencies
+- Resolved all 27 ruff lint errors (import sorting, unused variables, line length)
+- Removed legacy ignore-file backward compatibility reference
+- Removed stale `build_hnsw_index` backward-compat alias from store.py
+- Fixed `try_to_load_from_cache` return value check in embeddings.py (operator precedence bug)
+- **Critical**: Incremental build second run returned empty graph — fixed by merging unchanged files from DB via `nx.compose()`
+
+### Changed
+- Updated CLAUDE.md and Claude Code skill docs with new commands and features
+- Updated CHANGELOG.md to reflect all iterations
+
+## [0.1.0] - 2026-04-11
+
+### Added
+- Core pipeline: detect → extract → build → embed → cluster → analyze → store
+- HybridRAG search engine combining vector similarity, graph traversal, and FTS5 keyword matching with RRF fusion
+- Tree-sitter AST extraction for Python, JavaScript, TypeScript with regex fallback
+- Hierarchical Leiden community detection at multiple resolutions (0.25, 0.5, 1.0, 2.0)
+- Local embeddings via sentence-transformers (nomic-ai/nomic-embed-code)
+- FAISS vector index for cosine similarity search
+- SQLite + FTS5 full-text search with BM25 ranking
+- CLI commands: `build`, `search`, `stats`, `node`, `export`
+- Graph analysis: PageRank, god node detection, hub analysis, quality metrics
+- File detection for 20+ programming languages
+- `.hedwig-cg-ignore` for excluding files from analysis
+- Privacy-first design: 100% local, no cloud services
+- Claude Code skill documentation for AI tool integration
+- Multi-language README (English, Korean, Japanese)
+- GitHub Actions CI (Python 3.10-3.12, Ubuntu + macOS)
+- CONTRIBUTING.md with development guide
+
+[Unreleased]: https://github.com/hedwig-ai/hedwig-code-graph/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/hedwig-ai/hedwig-code-graph/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/hedwig-ai/hedwig-code-graph/compare/v0.1.0...v0.1.2
+[0.1.0]: https://github.com/hedwig-ai/hedwig-code-graph/releases/tag/v0.1.0

hedwig_cg-0.9.0/CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributing to hedwig-cg
+
+Thank you for your interest in contributing to hedwig-cg! This guide will help you get started.
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/hedwig-ai/hedwig-code-graph.git
+cd hedwig-code-graph
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Linux/macOS
+# .venv\Scripts\activate   # Windows
+
+# Install in development mode with dev dependencies
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+# Run all tests with coverage
+pytest
+
+# Run a specific test file
+pytest tests/test_store.py
+
+# Run with verbose output
+pytest -v
+```
+
+## Code Style
+
+We use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+# Check for issues
+ruff check .
+
+# Auto-fix issues
+ruff check --fix .
+
+# Format code
+ruff format .
+```
+
+**Key conventions:**
+- Line length: 100 characters
+- Target Python: 3.10+
+- Import sorting: isort-compatible (handled by Ruff)
+
+## Project Structure
+
+```
+hedwig_cg/
+├── cli/          # Click-based CLI interface
+├── core/         # Pipeline stages (detect, extract, build, cluster, analyze)
+├── query/        # Hybrid search engine (vector + graph + keyword + RRF)
+└── storage/      # SQLite + FAISS storage layer
+```
+
+## Making Changes
+
+1. **Fork** the repository and create a feature branch from `main`.
+2. **Write tests** for any new functionality in `tests/`.
+3. **Run the test suite** to ensure nothing is broken.
+4. **Follow the existing code style** — Ruff will help enforce this.
+5. **Keep commits focused** — one logical change per commit.
+
+## Pull Request Guidelines
+
+- Keep PRs focused on a single change.
+- Include a clear description of what the PR does and why.
+- Ensure all tests pass before submitting.
+- Update documentation if you change public APIs or CLI commands.
+
+## Architecture Notes
+
+The pipeline follows a linear flow:
+
+```
+detect → extract → build → embed → cluster → analyze → store
+```
+
+- **detect**: Scans directories, classifies files by language.
+- **extract**: Tree-sitter AST extraction with regex fallback.
+- **build**: Assembles a NetworkX DiGraph with deduplication.
+- **embed**: Generates sentence-transformer embeddings locally.
+- **cluster**: Hierarchical Leiden community detection.
+- **analyze**: Structural analysis (god nodes, hubs, quality metrics).
+- **store**: SQLite + FTS5 + FAISS vector index, all in a single file.
+
+## Reporting Issues
+
+- Use [GitHub Issues](https://github.com/hedwig-ai/hedwig-code-graph/issues) for bug reports and feature requests.
+- Include reproduction steps for bugs.
+- Mention your Python version and OS.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

hedwig_cg-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hedwig AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.