codebase-context 1.2.2 → 1.5.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 PatrickSys
-
-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.
+MIT License
+
+Copyright (c) 2025 PatrickSys
+
+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.

package/README.md

@@ -1,87 +1,144 @@
-# codebase-context
-
-**AI coding agents don't know your codebase. This MCP fixes that.**
-
-Your team has internal libraries, naming conventions, and patterns that external AI models have never seen. This MCP server gives AI assistants real-time visibility into your codebase: which libraries your team actually uses, how often, and where to find canonical examples.
-
-## Quick Start
-
-Add this to your MCP client config (Claude Desktop, VS Code, Cursor, etc.).
-
-```json
-"mcpServers": {
-  "codebase-context": {
-    "command": "npx",
-    "args": ["codebase-context", "/path/to/your/project"]
-  }
-}
-```
-
-## What You Get
-
-- **Internal library discovery** → `@mycompany/ui-toolkit`: 847 uses vs `primeng`: 3 uses
-- **Pattern frequencies** → `inject()`: 97%, `constructor()`: 3%
-- **Pattern momentum** → `Signals`: Rising (last used 2 days ago) vs `RxJS`: Declining (180+ days)
-- **Golden file examples** → Real implementations showing all patterns together
-- **Testing conventions** → `Jest`: 74%, `Playwright`: 6%
-- **Framework patterns** → Angular signals, standalone components, etc.
-- **Circular dependency detection** → Find toxic import cycles between files
-
-
-## How It Works
-
-When generating code, the agent checks your patterns first:
-
-| Without MCP | With MCP |
-|-------------|----------|
-| Uses `constructor(private svc: Service)` | Uses `inject()` (97% team adoption) |
-| Suggests `primeng/button` directly | Uses `@codeblue/prime` wrapper |
-| Generic Jest setup | Your team's actual test utilities |
-
-### Tip: Auto-invoke in your rules
-
-Add this to your `.cursorrules`, `CLAUDE.md`, or `AGENTS.md`:
-
-```
-When generating or reviewing code, use codebase-context tools to check team patterns first.
-```
-
-Now the agent checks patterns automatically instead of waiting for you to ask.
-
-## Tools
-
-| Tool | Purpose |
-|------|---------|
-| `search_codebase` | Semantic + keyword hybrid search |
-| `get_component_usage` | Find where a library/component is used |
-| `get_team_patterns` | Pattern frequencies + canonical examples |
-| `get_codebase_metadata` | Project structure overview |
-| `get_style_guide` | Query style guide rules |
-| `detect_circular_dependencies` | Find import cycles between files |
-| `refresh_index` | Re-index the codebase |
-
-
-## Configuration
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `EMBEDDING_PROVIDER` | `transformers` | `openai` (fast, cloud) or `transformers` (local, private) |
-| `OPENAI_API_KEY` | - | Required if provider is `openai` |
-| `CODEBASE_CONTEXT_DEBUG` | - | Set to `1` to enable verbose logging (startup messages, analyzer registration) |
-
-## Performance Note
-
-This tool runs **locally** on your machine using your hardware.
-- **Initial Indexing**: The first run works hard. It may take several minutes (e.g., ~2-5 mins for 30k files) to compute embeddings for your entire codebase.
-- **Caching**: Subsequent queries are instant (milliseconds).
-- **Updates**: Currently, `refresh_index` re-scans the codebase. True incremental indexing (processing only changed files) is on the roadmap.
-
-## Links
-
-- 📄 [Motivation](./MOTIVATION.md) — Why this exists, research, learnings
-- 📋 [Changelog](./CHANGELOG.md) — Version history
-- 🤝 [Contributing](./CONTRIBUTING.md) — How to add analyzers
-
-## License
-
-MIT
+# codebase-context
+
+**AI coding agents don't know your codebase. This MCP fixes that.**
+
+Your team has internal libraries, naming conventions, and patterns that external AI models have never seen. This MCP server gives AI assistants real-time visibility into your codebase: which libraries your team actually uses, how often, and where to find canonical examples.
+
+## Quick Start
+
+Add this to your MCP client config (Claude Desktop, VS Code, Cursor, etc.).
+
+```json
+"mcpServers": {
+  "codebase-context": {
+    "command": "npx",
+    "args": ["codebase-context", "/path/to/your/project"]
+  }
+}
+```
+
+If your environment prompts on first run, use `npx --yes ...` (or `npx -y ...`) to auto-confirm.
+
+## What You Get
+
+- **Internal library discovery** → `@mycompany/ui-toolkit`: 847 uses vs `primeng`: 3 uses
+- **Pattern frequencies** → `inject()`: 97%, `constructor()`: 3%
+- **Pattern momentum** → `Signals`: Rising (last used 2 days ago) vs `RxJS`: Declining (180+ days)
+- **Golden file examples** → Real implementations showing all patterns together
+- **Testing conventions** → `Jest`: 74%, `Playwright`: 6%
+- **Framework patterns** → Angular signals, standalone components, etc.
+- **Circular dependency detection** → Find toxic import cycles between files
+- **Memory system** → Record "why" behind choices so AI doesn't repeat mistakes
+
+## How It Works
+
+When generating code, the agent checks your patterns first:
+
+| Without MCP                              | With MCP                             |
+| ---------------------------------------- | ------------------------------------ |
+| Uses `constructor(private svc: Service)` | Uses `inject()` (97% team adoption)  |
+| Suggests `primeng/button` directly       | Uses `@mycompany/ui-toolkit` wrapper |
+| Generic Jest setup                       | Your team's actual test utilities    |
+
+### Tip: Auto-invoke in your rules
+
+Add this to your `.cursorrules`, `CLAUDE.md`, or `AGENTS.md`:
+
+```
+## Codebase Context
+
+**At start of each task:** Call `get_memory` to load team conventions.
+
+**CRITICAL:** When user says "remember this" or "record this":
+- STOP immediately and call `remember` tool FIRST
+- DO NOT proceed with other actions until memory is recorded
+- This is a blocking requirement, not optional
+```
+
+Now the agent checks patterns automatically instead of waiting for you to ask.
+
+## Tools
+
+| Tool                           | Purpose                                       |
+| ------------------------------ | --------------------------------------------- |
+| `search_codebase`              | Semantic + keyword hybrid search              |
+| `get_component_usage`          | Find where a library/component is used        |
+| `get_team_patterns`            | Pattern frequencies + canonical examples      |
+| `get_codebase_metadata`        | Project structure overview                    |
+| `get_indexing_status`          | Indexing progress + last stats                |
+| `get_style_guide`              | Query style guide rules                       |
+| `detect_circular_dependencies` | Find import cycles between files              |
+| `remember`                     | Record memory (conventions/decisions/gotchas) |
+| `get_memory`                   | Query recorded memory by category/keyword     |
+| `refresh_index`                | Re-index the codebase                         |
+
+## File Structure
+
+The MCP creates the following structure in your project:
+
+```
+.codebase-context/
+  ├── memory.json         # Team knowledge (commit this)
+  ├── intelligence.json   # Pattern analysis (generated)
+  ├── index.json          # Keyword index (generated)
+  └── index/              # Vector database (generated)
+```
+
+**Recommended `.gitignore`:** The vector database and generated files can be large. Add this to your `.gitignore` to keep them local while sharing team memory:
+
+```gitignore
+# Codebase Context MCP - ignore generated files, keep memory
+.codebase-context/*
+!.codebase-context/memory.json
+```
+
+### Memory System
+
+Patterns tell you _what_ the team does ("97% use inject"), but not _why_ ("standalone compatibility"). Use `remember` to capture rationale that prevents repeated mistakes:
+
+```typescript
+// AI won't change this again after recording the decision
+remember({
+  type: 'decision',
+  category: 'dependencies',
+  memory: 'Use node-linker: hoisted, not isolated',
+  reason:
+    "Some packages don't declare transitive deps. Isolated forces manual package.json additions."
+});
+```
+
+Memories surface automatically in `search_codebase` results and `get_team_patterns` responses.
+
+**Early baseline — known quirks:**
+
+- Agents may bundle multiple things into one entry
+- Duplicates can happen if you record the same thing twice
+- Edit `.codebase-context/memory.json` directly to clean up
+- Be explicit: "Remember this: use X not Y"
+
+## Configuration
+
+| Variable                 | Default        | Description                                                                    |
+| ------------------------ | -------------- | ------------------------------------------------------------------------------ |
+| `EMBEDDING_PROVIDER`     | `transformers` | `openai` (fast, cloud) or `transformers` (local, private)                      |
+| `OPENAI_API_KEY`         | -              | Required if provider is `openai`                                               |
+| `CODEBASE_ROOT`          | -              | Project root to index (CLI arg takes precedence)                               |
+| `CODEBASE_CONTEXT_DEBUG` | -              | Set to `1` to enable verbose logging (startup messages, analyzer registration) |
+
+## Performance Note
+
+This tool runs **locally** on your machine using your hardware.
+
+- **Initial Indexing**: The first run works hard. It may take several minutes (e.g., ~2-5 mins for 30k files) to compute embeddings for your entire codebase.
+- **Caching**: Subsequent queries are instant (milliseconds).
+- **Updates**: Currently, `refresh_index` re-scans the codebase. True incremental indexing (processing only changed files) is on the roadmap.
+
+## Links
+
+- 📄 [Motivation](./MOTIVATION.md) — Why this exists, research, learnings
+- 📋 [Changelog](./CHANGELOG.md) — Version history
+- 🤝 [Contributing](./CONTRIBUTING.md) — How to add analyzers
+
+## License
+
+MIT

package/dist/analyzers/angular/index.d.ts

@@ -3,7 +3,7 @@
  * Understands components, services, directives, pipes, modules, guards, interceptors, etc.
  * Detects state management patterns, architectural layers, and Angular-specific patterns
  */
-import { FrameworkAnalyzer, AnalysisResult, CodebaseMetadata, CodeChunk } from "../../types/index.js";
+import { FrameworkAnalyzer, AnalysisResult, CodebaseMetadata, CodeChunk } from '../../types/index.js';
 export declare class AngularAnalyzer implements FrameworkAnalyzer {
     readonly name = "angular";
     readonly version = "1.0.0";

package/dist/analyzers/angular/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/analyzers/angular/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,SAAS,EAOV,MAAM,sBAAsB,CAAC;AAI9B,qBAAa,eAAgB,YAAW,iBAAiB;IACvD,QAAQ,CAAC,IAAI,aAAa;IAC1B,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,mBAAmB,WAQ1B;IACF,QAAQ,CAAC,QAAQ,OAAO;IAExB,OAAO,CAAC,eAAe,CAarB;IAEF,OAAO,CAAC,uBAAuB,CAO7B;IAEF,OAAO,CAAC,qBAAqB,CAa3B;IAEF,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO;IAuBjD,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;YA0B3D,qBAAqB;IA+NnC;;OAEG;IACH,OAAO,CAAC,2BAA2B;YAcrB,uBAAuB;IAsHrC,OAAO,CAAC,wBAAwB;IAgChC,OAAO,CAAC,qBAAqB;IA2B7B,OAAO,CAAC,uBAAuB;IA0B/B,OAAO,CAAC,aAAa;IA8CrB,OAAO,CAAC,cAAc;YA6CR,mBAAmB;YAyCnB,gBAAgB;IA8B9B,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,cAAc;IAkEtB,OAAO,CAAC,oBAAoB;IAmCtB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmKzE;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM;IAkFnC,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,gBAAgB;CAMzB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/analyzers/angular/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,SAAS,EAKV,MAAM,sBAAsB,CAAC;AAQ9B,qBAAa,eAAgB,YAAW,iBAAiB;IACvD,QAAQ,CAAC,IAAI,aAAa;IAC1B,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,mBAAmB,WAA8D;IAC1F,QAAQ,CAAC,QAAQ,OAAO;IAExB,OAAO,CAAC,eAAe,CAYrB;IAEF,OAAO,CAAC,uBAAuB,CAM7B;IAEF,OAAO,CAAC,qBAAqB,CAa3B;IAEF,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO;IAqBjD,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;YA0B3D,qBAAqB;IAuNnC;;OAEG;IACH,OAAO,CAAC,2BAA2B;YAYrB,uBAAuB;IA+GrC,OAAO,CAAC,wBAAwB;IAgChC,OAAO,CAAC,qBAAqB;IA2B7B,OAAO,CAAC,uBAAuB;IAqB/B,OAAO,CAAC,aAAa;IA4CrB,OAAO,CAAC,cAAc;YAyCR,mBAAmB;YAiCnB,gBAAgB;IAwB9B,OAAO,CAAC,qBAAqB;IAS7B,OAAO,CAAC,cAAc;IA0DtB,OAAO,CAAC,oBAAoB;IA2BtB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwJzE;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM;IA2FnC,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,gBAAgB;CAMzB"}