seu-claude 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -5,26 +5,72 @@ 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).
 
+## [1.0.2] - 2026-01-16
+
+### Added
+
+- **Incremental Indexing** - New `FileIndex` class tracks file hashes and mtimes to skip unchanged files during re-indexing
+- **Progress Reporting** - Callback-based progress reporting during indexing with phase tracking (crawling, analyzing, embedding, saving)
+- CLI now shows real-time progress during `seu-claude index` command
+- `IndexResult` now includes `filesSkipped`, `filesUpdated`, and `filesDeleted` counts
+
+### Changed
+
+- `index_codebase` MCP tool output now shows incremental statistics
+- Improved indexing performance by only processing changed files
+- Better memory efficiency during large codebase indexing
+
+### Technical Details
+
+- **Test Coverage**: 301 tests passing
+- **New Classes**: `FileIndex` for persistent file tracking
+- **New Types**: `IndexProgress`, `IndexPhase`, `ProgressCallback`
+
+## [1.0.1] - 2026-01-15
+
+### Changed
+
+- 📚 Updated documentation to reflect complete v1.0 feature set
+- Updated README roadmap with completed feature indicators
+- Updated FEATURE_AUDIT with `search_xrefs` tool documentation
+- Added cross-reference tracking and git-aware indexing sections
+- Corrected test counts and coverage metrics across all docs
+- Applied Prettier formatting to all markdown files
+
+### Fixed
+
+- Fixed project structure in README to include `search-xrefs.ts`
+- Corrected tool count from 3 to 4 in documentation
+
 ## [1.0.0] - 2026-01-15
 
 ### Added
+
 - 🎉 Initial stable release
 - **MCP Server** - Full Model Context Protocol implementation for Claude Code/Desktop
 - **Semantic Indexing** - AST-based code chunking using Tree-sitter
 - **Vector Search** - LanceDB-powered similarity search with 384-dimension embeddings
 - **Multi-language Support** - TypeScript, JavaScript, Python, Java, C/C++, Go, Rust
-- **Three MCP Tools**:
+- **Cross-Reference Tracking** - Callers/callees graph powered by AST analysis
+- **Git-Aware Indexing** - Track file changes and prioritize recent modifications
+- **Four MCP Tools**:
   - `index_codebase` - Index entire codebase with incremental updates
   - `search_codebase` - Semantic search across indexed code
   - `read_semantic_context` - Read code with AST-aware context
+  - `search_xrefs` - Query cross-references (who calls this? what does this call?)
+- **CLI Commands**:
+  - `seu-claude doctor` - Diagnose environment and index health
+  - `seu-claude-setup` - Configure MCP settings
 
 ### Technical Details
+
 - **Embedding Model**: `Xenova/all-MiniLM-L6-v2` (no authentication required)
 - **Vector Dimensions**: 384
-- **Test Coverage**: 72.72% (214 tests passing)
+- **Test Coverage**: 78%+ (285 tests)
 - **Memory Usage**: ~100MB idle, ~500MB during indexing
 
 ### Performance
+
 - Indexed 26-file TypeScript project in 5.39 seconds
 - Created 359 semantic chunks
 - Query latency ~50ms
@@ -32,6 +78,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.1.0] - 2026-01-14
 
 ### Added
+
 - Initial development release
 - Core indexing and search functionality
 - Basic MCP integration

package/README.md

@@ -4,12 +4,17 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/seu-claude.svg)](https://www.npmjs.com/package/seu-claude)
+[![CI Status](https://github.com/jardhel/seu-claude/workflows/CI/badge.svg)](https://github.com/jardhel/seu-claude/actions)
+[![GitHub issues](https://img.shields.io/github/issues/jardhel/seu-claude)](https://github.com/jardhel/seu-claude/issues)
+[![GitHub stars](https://img.shields.io/github/stars/jardhel/seu-claude)](https://github.com/jardhel/seu-claude/stargazers)
 
 > Give Claude Code deep, proactive understanding of your entire codebase - not just the files it has touched.
 
 ## The Problem
 
 Current memory plugins for Claude Code suffer from "goldfish memory":
+
 - They only remember files the AI has explicitly accessed
 - Heavy resource usage (35GB+ RAM with in-memory vector databases)
 - Complex Python dependencies that conflict with your environment
@@ -34,11 +39,38 @@ Current memory plugins for Claude Code suffer from "goldfish memory":
 # Install globally
 npm install -g seu-claude
 
-# Or use npx
+# Or use npx directly
 npx seu-claude
 ```
 
-### Configuration
+### Automatic Configuration
+
+After installing, run the setup command from your project directory:
+
+```bash
+# With npx (recommended)
+npx seu-claude setup
+
+# Or if installed globally
+seu-claude setup
+```
+
+This will automatically:
+
+- Detect your project root
+- Create `.claude/settings.json` for Claude Code
+- Configure `claude_desktop_config.json` for Claude Desktop
+- Set up the MCP server connection
+
+### Verify Installation
+
+Check if everything is configured correctly:
+
+```bash
+npx seu-claude doctor
+```
+
+### Manual Configuration
 
 #### Claude Code
 
@@ -78,19 +110,26 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 
 ### First Run
 
-Once configured, Claude will have access to three new tools:
+Once configured, Claude will have access to four powerful tools:
 
 1. **Index your codebase** (run once, then incremental):
+
    > "Index this codebase for semantic search"
 
 2. **Search semantically**:
+
    > "Where is the user authentication logic?"
    > "Find all database connection handling code"
    > "Show me how API rate limiting is implemented"
 
 3. **Read with context**:
+
    > "Read the AuthService.login method with its surrounding context"
 
+4. **Search cross-references** (find callers/callees):
+   > "Who calls the validateUser function?"
+   > "What functions does processOrder call?"
+
 ## How It Works
 
 ### Architecture
@@ -123,21 +162,21 @@ Once configured, Claude will have access to three new tools:
 
 Unlike naive text splitting that breaks code mid-function, seu-claude uses Abstract Syntax Tree analysis to create semantically meaningful chunks:
 
-| Code Structure | Chunking Logic | Metadata |
-|----------------|----------------|----------|
-| Function | Complete function with signature | Type, Name, Scope |
-| Class | Header + methods as separate chunks | Type, Name, Methods |
-| Interface | Complete definition | Type, Module |
-| Method | Full body with context | Parent Class, Signature |
+| Code Structure | Chunking Logic                      | Metadata                |
+| -------------- | ----------------------------------- | ----------------------- |
+| Function       | Complete function with signature    | Type, Name, Scope       |
+| Class          | Header + methods as separate chunks | Type, Name, Methods     |
+| Interface      | Complete definition                 | Type, Module            |
+| Method         | Full body with context              | Parent Class, Signature |
 
 ### Technology Stack
 
-| Component | Technology | Why |
-|-----------|------------|-----|
-| Runtime | Node.js 20+ | Native MCP compatibility |
-| Parser | web-tree-sitter | WASM-based, multi-language |
-| Vector DB | LanceDB | Disk-based, <100MB RAM |
-| Embeddings | Transformers.js | Local, GPU-accelerated |
+| Component  | Technology      | Why                        |
+| ---------- | --------------- | -------------------------- |
+| Runtime    | Node.js 20+     | Native MCP compatibility   |
+| Parser     | web-tree-sitter | WASM-based, multi-language |
+| Vector DB  | LanceDB         | Disk-based, <100MB RAM     |
+| Embeddings | Transformers.js | Local, GPU-accelerated     |
 
 ## MCP Tools
 
@@ -177,17 +216,35 @@ Read code with AST-aware context.
 }
 ```
 
+### `search_xrefs`
+
+Find callers and callees of functions/methods. Understand code dependencies and call graphs.
+
+```typescript
+{
+  symbol: string;           // Function/method name to search for
+  direction?: string;       // "callers" | "callees" | "both" (default)
+  max_results?: number;     // Max results (default: 20)
+}
+```
+
+**Example prompts:**
+
+> "Who calls the authenticate function?"
+> "What does processPayment call?"
+> "Show me the cross-references for handleRequest"
+
 ## Configuration
 
 ### Environment Variables
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PROJECT_ROOT` | Current directory | Root of codebase to index |
-| `DATA_DIR` | `~/.seu-claude` | Where to store index data |
-| `EMBEDDING_MODEL` | `Xenova/all-MiniLM-L6-v2` | HuggingFace model |
-| `EMBEDDING_DIMENSIONS` | `384` | Vector dimensions |
-| `LOG_LEVEL` | `info` | debug, info, warn, error |
+| Variable               | Default                   | Description               |
+| ---------------------- | ------------------------- | ------------------------- |
+| `PROJECT_ROOT`         | Current directory         | Root of codebase to index |
+| `DATA_DIR`             | `~/.seu-claude`           | Where to store index data |
+| `EMBEDDING_MODEL`      | `Xenova/all-MiniLM-L6-v2` | HuggingFace model         |
+| `EMBEDDING_DIMENSIONS` | `384`                     | Vector dimensions         |
+| `LOG_LEVEL`            | `info`                    | debug, info, warn, error  |
 
 ### Ignore Patterns
 
@@ -206,27 +263,43 @@ path/to/large/file.ts
 
 ## Performance
 
-### Benchmark Results (seu-claude codebase - 26 TypeScript files)
+### Token Savings Benchmark
+
+seu-claude dramatically reduces token consumption by returning only semantically relevant code chunks instead of entire files.
+
+| Metric           | Without seu-claude | With seu-claude | Savings |
+| ---------------- | ------------------ | --------------- | ------- |
+| Tokens per query | ~22,000            | ~1,500          | **91%** |
+| Cost per session | $0.52              | $0.05           | **91%** |
+| Context accuracy | N/A                | 95%+            | -       |
+
+Run the benchmark yourself:
 
-| Metric | Result |
-|--------|--------|
-| Indexing time | 5.39s |
-| Files processed | 26 |
-| Chunks created | 359 |
-| Memory (idle) | ~100MB |
+```bash
+npx tsx scripts/benchmark-tokens.ts
+```
+
+### Indexing Performance (seu-claude codebase - 34 files)
+
+| Metric            | Result |
+| ----------------- | ------ |
+| Indexing time     | ~6s    |
+| Files processed   | 34     |
+| Chunks created    | 406    |
+| Memory (idle)     | ~100MB |
 | Memory (indexing) | ~500MB |
-| Query latency | ~50ms |
+| Query latency     | ~5ms   |
 
 ### Comparison
 
-| Metric | seu-claude | Traditional RAG |
-|--------|------------|-----------------|
-| RAM (idle) | ~100MB | 35GB+ |
-| RAM (indexing) | ~500MB | N/A |
-| Index time (26 files) | ~5s | Minutes |
-| Query latency | ~50ms | <10ms |
-| Startup time | <2s | 30s+ |
-| Dependencies | Node.js only | Python + CUDA |
+| Metric                | seu-claude   | Traditional RAG |
+| --------------------- | ------------ | --------------- |
+| RAM (idle)            | ~100MB       | 35GB+           |
+| RAM (indexing)        | ~500MB       | N/A             |
+| Index time (26 files) | ~5s          | Minutes         |
+| Query latency         | ~50ms        | <10ms           |
+| Startup time          | <2s          | 30s+            |
+| Dependencies          | Node.js only | Python + CUDA   |
 
 ## Development
 
@@ -256,7 +329,8 @@ seu-claude/
 │   └── tools/
 │       ├── index-codebase.ts
 │       ├── search-codebase.ts
-│       └── read-context.ts
+│       ├── read-context.ts
+│       └── search-xrefs.ts
 ├── languages/                # Tree-sitter WASM grammars
 └── models/                   # Downloaded embedding models
 ```
@@ -270,14 +344,37 @@ npm test
 ## Roadmap
 
 - [ ] Language Server Protocol integration for better symbol resolution
-- [ ] Git-aware indexing (prioritize recent changes)
-- [ ] Cross-reference graph (callers/callees)
+- [x] Git-aware indexing (prioritize recent changes)
+- [x] Cross-reference graph (callers/callees) - via `search_xrefs` tool
 - [ ] VSCode extension for index management
 - [ ] Support for more languages (Kotlin, Swift, PHP)
 
+See [ROADMAP.md](ROADMAP.md) for detailed plans.
+
 ## Contributing
 
-Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting PRs.
+We welcome contributions! Please see:
+
+- [Contributing Guidelines](CONTRIBUTING.md) - How to contribute code
+- [Code of Conduct](CODE_OF_CONDUCT.md) - Community standards
+- [Support](.github/SUPPORT.md) - Getting help
+- [GitHub Discussions](https://github.com/jardhel/seu-claude/discussions) - Ask questions
+
+### Quick Start for Contributors
+
+```bash
+git clone https://github.com/jardhel/seu-claude.git
+cd seu-claude
+npm install
+npm run build
+npm test
+```
+
+## Community
+
+- 💬 [GitHub Discussions](https://github.com/jardhel/seu-claude/discussions) - Ask questions, share ideas
+- 🐛 [Issue Tracker](https://github.com/jardhel/seu-claude/issues) - Report bugs or request features
+- 🌟 [Star the repo](https://github.com/jardhel/seu-claude) - Show your support!
 
 ## License
 

package/dist/__tests__/chunker.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=chunker.test.d.ts.map

package/dist/__tests__/chunker.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/chunker.test.ts"],"names":[],"mappings":""}