ai-codeindex 0.23.0__tar.gz → 0.23.2__tar.gz

{ai_codeindex-0.23.0 → ai_codeindex-0.23.2}/.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
 
     - name: Run tests with coverage
       run: |
-        pytest -v --cov=src/codeindex --cov-report=term-missing --cov-report=xml
+        pytest -v --cov=src/codeindex --cov-report=term-missing --cov-report=xml --cov-fail-under=78
 
     - name: Upload coverage to Codecov (Ubuntu Python 3.11 only)
       if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
@@ -60,12 +60,16 @@ jobs:
       with:
         python-version: '3.11'
 
-    - name: Install ruff
-      run: pip install ruff
+    - name: Install lint tools
+      run: pip install ruff mypy
 
     - name: Run ruff check
       run: ruff check src/ tests/ test_generator/
 
+    - name: Run mypy type check (informational)
+      run: mypy src/codeindex/parser.py src/codeindex/scanner.py src/codeindex/config.py
+      continue-on-error: true
+
   build-check:
     runs-on: ubuntu-latest
     steps:

{ai_codeindex-0.23.0 → ai_codeindex-0.23.2}/.serena/project.yml

@@ -123,3 +123,8 @@ language_backend:
 # list of regex patterns which, when matched, mark a memory entry as read‑only.
 # Extends the list from the global configuration, merging the two lists.
 read_only_memory_patterns: []
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:

{ai_codeindex-0.23.0 → ai_codeindex-0.23.2}/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.2] - 2026-04-14
+
+### Changed
+
+- **Hook shebangs**: `#!/bin/zsh` → `#!/usr/bin/env bash` for cross-platform portability.
+- **Unified hook install**: `make install-hooks` now delegates to `codeindex hooks install --all`.
+- **Post-commit logging**: stderr redirected to `~/.codeindex/hooks/post-commit.log` instead of `/dev/null`.
+- **Debug detection**: Replaced ~50 lines of regex-based L2 check with ruff `T201`/`T100` rules.
+
+### Added
+
+- **`hook-common.sh` versioned**: Added to `scripts/hooks/` and auto-copied on `codeindex hooks install`.
+- **mypy**: Added as dev dependency with baseline config; CI runs informational type check on core modules.
+- **Coverage gate**: CI enforces `--cov-fail-under=78` to prevent coverage regression.
+- **`make typecheck`**: New Makefile target for mypy on core modules.
+
+## [0.23.1] - 2026-03-15
+
+### Added
+
+- **`codeindex claude-md update/status` CLI commands**: Manage codeindex section in project CLAUDE.md with version tracking.
+- **Startup version-outdated hint**: Every `codeindex` CLI invocation checks if CLAUDE.md section is outdated and prints a reminder.
+- **Unified `claude_md.py` module**: Single source of truth for CLAUDE.md injection, replacing fragmented hooks.py + init_wizard.py logic.
+
+### Changed
+
+- **CLAUDE.md template simplified**: 130 lines → 22 lines. Removed hardcoded paths, language support table, and verbose configuration examples.
+- **Unified marker format**: `<!-- codeindex:start v{version} -->` with backward compatibility for old markers without version.
+- **`init_wizard.py` injection**: Now delegates to `claude_md.py` module instead of inline template.
+
+### Fixed
+
+- **Dead code cleanup**: Removed `hooks.py` `post_install_update_guide()` (181 lines) that was never wired to pip entry points.
+- **Dead import fix**: `cli_config.py` referenced non-existent `install_hooks` from `hooks.py`, now uses correct `install_hook` from `cli_hooks.py`.
+
 ## [0.23.0] - 2026-03-12
 
 ### Added

ai_codeindex-0.23.2/CLAUDE.md

@@ -0,0 +1,186 @@
+# CLAUDE.md
+
+**For**: Claude Code working with this repository
+**Version**: v0.23.1
+
+---
+
+## Part 1: Understanding & Navigating
+
+### Code Navigation Priority
+
+1. `/README_AI.md` → Project overview
+2. Serena `find_symbol()` → Precise symbol location
+3. `/src/codeindex/README_AI.md` → Core module details
+4. Serena `find_referencing_symbols()` → Call relationships
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `README_AI.md` | AI-generated directory docs |
+| `PROJECT_SYMBOLS.md` | Global symbol index |
+| `.codeindex.yaml` | Scan configuration |
+| `CHANGELOG.md` | Version history |
+| `docs/planning/*.md` | Epic/Story design decisions |
+| `docs/architecture/design-philosophy.md` | Core design principles |
+
+### Serena MCP Quick Reference
+
+```python
+find_symbol(name_path_pattern="SmartWriter/write_readme")
+find_referencing_symbols(name_path="calculate_limit", relative_path="src/codeindex/adaptive_selector.py")
+get_symbols_overview(relative_path="src/codeindex/parser.py", depth=1)
+```
+
+---
+
+## Part 2: Development Workflow
+
+### Virtual Environment (REQUIRED)
+
+```bash
+source .venv/bin/activate
+which python3  # Must show .venv path
+pip install -e ".[dev,all]"
+```
+
+Without venv: pip fails (PEP 668), pre-push hooks fail (`ModuleNotFoundError`), `make release` fails.
+
+### Quick Start Commands
+
+```bash
+# Development
+pytest -v                          # Run tests
+ruff check src/                    # Lint
+pytest --cov=src/codeindex         # Coverage
+
+# codeindex usage
+codeindex scan-all --fallback      # Generate all indexes
+codeindex parse src/myfile.py      # Parse single file
+codeindex symbols                  # Global symbol index
+codeindex tech-debt ./src          # Code quality analysis
+codeindex hooks status             # Git hooks status
+```
+
+### Commit Message Format
+
+```
+feat(scope): add new feature
+fix(scope): fix bug
+docs(scope): update documentation
+test(scope): add tests
+refactor(scope): refactor code
+```
+
+### Documentation Update Rules
+
+| Change Type | Documents to Update |
+|-------------|---------------------|
+| New feature | CHANGELOG.md, README.md, relevant README_AI.md |
+| Bug fix | CHANGELOG.md |
+| Config change | .codeindex.yaml example, CHANGELOG.md |
+| Major release | CHANGELOG.md, RELEASE_NOTES_vX.X.X.md |
+
+After code changes: `codeindex scan-all --fallback`
+
+### Epic Completion Workflow
+
+1. Update `docs/planning/ROADMAP.md` (version + epic status)
+2. Archive: `docs/planning/active/ → docs/planning/completed/`
+3. Update `docs/planning/README.md` index
+
+---
+
+## Part 2.5: Design Philosophy
+
+Read `docs/architecture/design-philosophy.md` when:
+- Adding new language support
+- Implementing features involving ParseResult
+- Making architectural decisions (AI vs programmatic, parallelization)
+
+**Core principles**:
+- We extract structure (What), AI understands semantics (Why)
+- 3 layers: Structure Extraction (tree-sitter) → Automated Analysis → AI Enhancement
+- AI invocation is the bottleneck (99%), not parsing
+- ThreadPool for all languages (I/O bound)
+
+---
+
+## Part 3: Architecture Reference
+
+### Three-Repo Architecture
+
+> codeindex **sees** (AST parsing), LoomGraph **thinks** (pipeline + skills), LightRAG **remembers** (storage + retrieval)
+
+| Repo | Role | Local Path |
+|------|------|------------|
+| **codeindex** | AST parsing, Symbol/Call/Inheritance extraction | `/Users/dreamlinx/Projects/codeindex` |
+| **LoomGraph** | Pipeline dispatch, Embedding, CLI/Skill | `/Users/dreamlinx/Projects/LoomGraph` |
+| **LightRAG** | Graph storage, vector retrieval | `/Users/dreamlinx/Projects/LightRAG` |
+
+Data flow: `codeindex scan` → ParseResult → `LoomGraph embed/inject` → LightRAG API → PostgreSQL
+
+### Core Pipeline
+
+```
+Directory → Scanner → [files] → Parser (tree-sitter) → [ParseResult]
+  → SmartWriter → Writer → Invoker (AI CLI) → README_AI.md
+```
+
+### Key Data Types
+
+- `ScanResult`: path, files, subdirs
+- `ParseResult`: path, symbols, imports, module_docstring, error
+- `Symbol`: name, kind, signature, docstring, line_start, line_end
+- `Import`: module, names, is_from
+- `Config`: Loaded from `.codeindex.yaml`
+
+### Configuration
+
+```yaml
+version: 1
+ai_command: 'claude -p "{prompt}" --allowedTools "Read"'
+include: [src/]
+exclude: ["**/__pycache__/**"]
+languages: [python, php, java, typescript, javascript, swift, objc]
+output_file: README_AI.md
+
+symbols:
+  adaptive_symbols:
+    enabled: true
+```
+
+Full config: `examples/.codeindex.yaml` | Help: `codeindex config explain <param>`
+
+---
+
+## Part 4: Extension Development
+
+### Adding Language/Framework Support
+
+1. Write tests: `tests/extractors/test_myframework.py`
+2. Implement: `src/codeindex/extractors/myframework.py`
+3. Auto-registered via `extractors/__init__.py`
+
+Reference: `src/codeindex/extractors/thinkphp.py`
+
+### Git Hooks
+
+- pre-commit: lint + debug checks
+- post-commit: auto README updates
+- pre-push: test validation
+
+Management: `codeindex hooks install/uninstall/status`
+Guide: `docs/guides/git-hooks-integration.md`
+
+---
+
+## Common Mistakes
+
+1. **Directly modify README_AI.md** → It gets overwritten. Modify source docstrings instead.
+2. **Skip tests** → TDD required. Write tests first.
+3. **Glob/Grep for exploration** → Use Serena MCP tools.
+4. **Ignore README_AI.md** → Always read it first.
+5. **Commit to develop/master directly** → Use feature branches.
+6. **Forget venv** → Always `source .venv/bin/activate` first.

{ai_codeindex-0.23.0 → ai_codeindex-0.23.2}/Makefile

@@ -39,11 +39,9 @@ install:  ## Install package in editable mode
 install-dev:  ## Install with dev dependencies
 	pip install -e ".[dev,all]"
 
-install-hooks:  ## Install Git hooks (pre-commit, pre-push)
+install-hooks:  ## Install Git hooks via codeindex CLI
 	@echo "$(CYAN)Installing Git hooks...$(RESET)"
-	@mkdir -p .git/hooks
-	@cp scripts/hooks/pre-push .git/hooks/pre-push
-	@chmod +x .git/hooks/pre-push
+	@codeindex hooks install --all --force
 	@echo "$(GREEN)✓ Git hooks installed$(RESET)"
 
 # ============================================================================
@@ -65,6 +63,9 @@ lint:  ## Run linter (ruff)
 lint-fix:  ## Auto-fix linting issues
 	ruff check --fix src/ tests/
 
+typecheck:  ## Run mypy type check on core modules
+	mypy src/codeindex/parser.py src/codeindex/scanner.py src/codeindex/config.py
+
 format:  ## Format code with ruff
 	ruff format src/ tests/
 

{ai_codeindex-0.23.0 → ai_codeindex-0.23.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-codeindex
-Version: 0.23.0
+Version: 0.23.2
 Summary: AI-native code indexing tool for large codebases
 Project-URL: Homepage, https://github.com/dreamlx/codeindex
 Project-URL: Documentation, https://github.com/dreamlx/codeindex
@@ -32,6 +32,7 @@ Requires-Dist: tree-sitter-python>=0.21; extra == 'all'
 Requires-Dist: tree-sitter-swift>=0.0.1; extra == 'all'
 Requires-Dist: tree-sitter-typescript>=0.23.2; extra == 'all'
 Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
 Requires-Dist: pytest-bdd>=7.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
@@ -56,14 +57,16 @@ Description-Content-Type: text/markdown
 
 # codeindex
 
+[🇬🇧 English](README.md) | [🇨🇳 中文](README_zh.md)
+
 [![PyPI version](https://badge.fury.io/py/ai-codeindex.svg)](https://badge.fury.io/py/ai-codeindex)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Tests](https://github.com/dreamlx/codeindex/workflows/Tests/badge.svg)](https://github.com/dreamlx/codeindex/actions)
 
-**Enterprise-grade Code Intelligence Platform — Multi-language AST parser for AI-assisted development, code quality analysis, and knowledge graph integration.**
+**Enterprise-grade Code Intelligence Platform — Make AI agents understand your codebase through semantic navigation, not grep.**
 
-codeindex extracts symbols, inheritance relationships, call graphs, and imports from Python, PHP, Java, TypeScript, JavaScript, Swift, and Objective-C using tree-sitter. Designed for **enterprise environments** with intranet isolation, providing structured code data for AI tools, knowledge graphs, and code intelligence platforms.
+codeindex generates AI-readable documentation with **two-phase pipeline**: structural indexing (AST parsing via tree-sitter) + AI-powered module descriptions. AI agents can browse README_AI.md hierarchy, see module purposes at a glance, and navigate directly to the right code — across Python, PHP, Java, TypeScript, JavaScript, Swift, and Objective-C. Designed for **enterprise environments** with intranet isolation.
 
 **🏢 Enterprise Ready**: ✅ Intranet compatible ✅ Self-contained ✅ Version stable ✅ Data sovereignty
 
@@ -75,18 +78,28 @@ codeindex extracts symbols, inheritance relationships, call graphs, and imports
 
 ## Features
 
+### Core: Code Understanding for AI Agents
+
+- **Two-phase documentation pipeline** (v0.23.0) — Phase 1: structural README_AI.md via SmartWriter; Phase 2: AI generates one-line functional descriptions per module. AI agents can browse README_AI.md hierarchy and find the right module **without grep**.
+- **Smart indexing** — Tiered documentation (overview → navigation → detailed) optimized for AI agents, ≤50KB per file
+- **Auto-AI enrichment** — When `ai_command` is configured, `scan-all` automatically enables AI module descriptions. Use `--no-ai` to opt out
+- **Auto-update hooks** — Post-commit hook automatically regenerates README_AI.md for changed directories. Thin wrapper pattern: `pip upgrade` auto-updates hook logic
+
+### Parsing & Analysis
+
 - **Multi-language AST parsing** — Python, PHP, Java, TypeScript, JavaScript, Swift, Objective-C via tree-sitter (Go, Rust, C# planned)
-- **AI-powered documentation** — Generate README files using Claude, GPT, or any AI CLI
-- **Single file parse** — `codeindex parse <file>` with JSON output for tool integration
-- **Structured JSON output** — `--output json` for CI/CD, knowledge graphs, and downstream tools
 - **Call relationship extraction** — Function/method call graphs across Python, Java, PHP, TypeScript, JavaScript
 - **Inheritance extraction** — Class hierarchy and interface relationships
 - **Framework route extraction** — ThinkPHP and Spring Boot route tables (more planned)
-- **Technical debt analysis** — Detect large files, god classes, symbol overload
-- **Smart indexing** — Tiered documentation (overview → navigation → detailed) optimized for AI agents
+- **Technical debt analysis** — Detect large files, god classes, symbol overload, test smells
+- **Single file parse** — `codeindex parse <file>` with JSON output for tool integration
+- **Structured JSON output** — `--output json` for CI/CD, knowledge graphs, and downstream tools
+
+### Developer Experience
+
 - **Adaptive symbol extraction** — Dynamic 5–150 symbols per file based on size
-- **CLAUDE.md injection** — `codeindex init` auto-configures Claude Code integration (v0.17.0)
-- **Auto-update guide** — Post-install hook automatically updates `~/.claude/CLAUDE.md` after `pip upgrade` (v0.22.2)
+- **CLAUDE.md injection** — `codeindex init` auto-configures Claude Code integration
+- **Auto-update guide** — Post-install hook automatically updates `~/.claude/CLAUDE.md` after `pip upgrade`
 - **Template-based test generation** — YAML + Jinja2 for rapid language support (88–91% time savings)
 - **Parallel scanning** — Concurrent directory processing with configurable workers
 
@@ -101,18 +114,19 @@ codeindex extracts symbols, inheritance relationships, call graphs, and imports
 ```bash
 # Enterprise developer workflow
 git clone <internal-repo>
-codeindex scan-all --fallback       # Generate complete index
-# Read README_AI.md for architecture understanding
-# Check PROJECT_SYMBOLS.md for symbol lookup
+codeindex init                       # Configure project
+codeindex scan-all                   # Structural + AI descriptions (auto)
+# AI agent reads README_AI.md → sees module purposes → navigates directly
+# No grep needed for code discovery
 codeindex tech-debt src/ --output review.md  # Code quality analysis
 ```
 
 **Why enterprises choose codeindex**:
+- ✅ **Semantic navigation** — AI agents understand module purposes from README_AI.md hierarchy
 - ✅ **Intranet compatible** — no external dependencies, fully offline
 - ✅ **Self-contained** — no upstream MCP servers required
 - ✅ **Version stable** — enterprise-controlled release cycle
 - ✅ **Data sovereignty** — code never leaves internal network
-- ✅ **Customizable** — extensible for internal languages/frameworks
 
 ---
 
@@ -142,18 +156,18 @@ Without codeindex, LoomGraph cannot function. See [LoomGraph Integration Guide](
 
 **With Serena MCP**: For individual developers using Claude Code + Serena MCP, codeindex provides **complementary value**:
 
+- **codeindex** (build-time): Semantic architecture map (README_AI.md with module descriptions) + quality analysis
 - **Serena** (real-time): Precise symbol navigation (`find_symbol`, `find_referencing_symbols`)
-- **codeindex** (build-time): Architecture overview (README_AI.md) + quality analysis (tech-debt)
 
 ```bash
 # Personal developer workflow
 codeindex init                    # Setup CLAUDE.md integration
-codeindex scan-all --fallback     # Generate architecture docs
-# Claude Code reads README_AI.md first, then uses Serena for precise navigation
-codeindex tech-debt src/          # Detect technical debt
+codeindex scan-all                # Structural + AI descriptions (auto)
+codeindex hooks install post-commit  # Auto-update on commit
+# Claude Code reads README_AI.md → understands module purpose → uses Serena for details
 ```
 
-**Relationship**: codeindex and Serena are **not competitors** but **complementary tools** — codeindex provides the "map," Serena provides the "GPS navigation."
+**Relationship**: codeindex provides the "map with labels," Serena provides the "GPS navigation."
 
 ---
 
@@ -210,18 +224,17 @@ This creates:
 ### 2. Scan Your Codebase
 
 ```bash
-# Scan all directories (structural documentation, no AI needed)
+# Scan all directories
+# When ai_command is configured → auto Phase 1 (structural) + Phase 2 (AI descriptions)
+# Without ai_command → Phase 1 only (structural)
 codeindex scan-all
 
+# Structural only (skip AI enrichment)
+codeindex scan-all --no-ai
+
 # Scan a single directory
 codeindex scan ./src/auth
 
-# When ai_command is configured, auto-enables AI module descriptions
-codeindex scan-all
-
-# Disable AI enrichment (structural only)
-codeindex scan-all --no-ai
-
 # Full AI-generated README for a single directory
 codeindex scan ./src/auth --ai
 
@@ -388,17 +401,45 @@ codeindex debt-scan ./src --format json
 
 ## How It Works
 
-### Standalone Mode
+### Two-Phase Pipeline (v0.23.0)
 
 ```
-Directory → Scanner → Parser (tree-sitter) → Smart Writer → README_AI.md
+Phase 1 (Structural):
+  Directory → Scanner → Parser (tree-sitter) → SmartWriter → README_AI.md
+
+Phase 2 (AI Enrichment, automatic when ai_command configured):
+  README_AI.md → symbol names + file names → AI → one-line description → blockquote injection
 ```
 
+**Phase 1: Structural generation** (always runs)
 1. **Scanner** — walks directories, filters by config patterns
 2. **Parser** — extracts symbols (classes, functions, imports, calls, inheritance) via tree-sitter
-3. **Smart Writer** — generates tiered documentation with size limits (≤50KB)
+3. **SmartWriter** — generates tiered documentation with size limits (≤50KB)
 4. **Output** — `README_AI.md` optimized for AI consumption, or JSON for tool integration
 
+**Phase 2: AI enrichment** (auto-enabled when `ai_command` configured)
+- Generates a one-line functional description for each non-leaf module
+- Writes as blockquote: `> 会员等级管理、积分兑换、权益卡券`
+- ~200-400 tokens per directory, 10-20x cheaper than full AI generation
+- Parent directories read child descriptions for hierarchical navigation
+
+### Before vs After: Code Navigation
+
+```
+Before (structural only):
+  └── Application/
+      ├── Vip/           — 48 files | 386 symbols     ← AI agent cannot determine purpose
+      ├── Pay/           — 23 files | 178 symbols
+      └── SmallProgramApi/ — 31 files | 245 symbols
+
+After (structural + AI enrichment):
+  └── Application/
+      ├── Vip/           — 会员等级管理、积分兑换、权益卡券 | 48 files
+      ├── Pay/           — 支付网关（支付宝/微信/退款） | 23 files
+      └── SmallProgramApi/ — 小程序端API（登录、头像、商品） | 31 files
+                             ↑ AI agent can navigate directly
+```
+
 ### Three-Repo Architecture (Enterprise Knowledge Graph)
 
 ```
@@ -490,14 +531,14 @@ See [Release Automation Guide](docs/development/QUICK_START_RELEASE.md) for deta
 
 ## Roadmap
 
-**Current version**: v0.23.0
+**Current version**: v0.23.2
 
 **Recent milestones**:
+- v0.23.0 — **AI-Enhanced Module Descriptions**: two-phase pipeline, auto-AI enrichment, post-commit thin wrapper
 - v0.22.2 — Auto-update CLAUDE.md on `pip upgrade`, `/codeindex-update-guide` skill
 - v0.22.0 — Unified tech-debt + test smells analysis
 - v0.21.0 — Swift & Objective-C language support
 - v0.19.0 — TypeScript/JavaScript support with call extraction
-- v0.17.0 — CLAUDE.md injection via `codeindex init`
 
 **Next**:
 - Framework routes expansion: Express, Laravel, FastAPI, Django (Epic 17)