@milo4jo/contextkit 0.5.6 → 0.5.7

package/README.md

@@ -118,6 +118,34 @@ They're storage. ContextKit adds the **intelligence layer** — scoring, budgeti
 
 ---
 
+## Performance
+
+Benchmarks on a MacBook Pro M4 (ContextKit's own codebase: 40 files, 166 chunks):
+
+| Operation | Time | Notes |
+|-----------|------|-------|
+| **Initial index** | ~14s | Includes embedding generation |
+| **Incremental index** | <1s | Only changed files |
+| **Query (cold)** | ~200ms | First query loads model |
+| **Query (warm)** | ~50ms | Subsequent queries |
+| **Query (cached)** | <5ms | Identical queries |
+
+Scaling (tested on larger codebases):
+
+| Codebase Size | Index Time | Query Time |
+|---------------|------------|------------|
+| 100 files | ~30s | ~60ms |
+| 500 files | ~2min | ~80ms |
+| 1000 files | ~4min | ~100ms |
+
+**Key optimizations:**
+- Incremental indexing (content hashing)
+- Query caching with automatic invalidation
+- Local embeddings (no API latency)
+- SQLite for fast reads
+
+---
+
 ## Commands
 
 ### `contextkit init`
@@ -352,6 +380,58 @@ settings:
 
 ---
 
+## Troubleshooting
+
+### Quick Diagnosis
+
+```bash
+contextkit doctor
+```
+
+This checks your setup and shows any issues:
+
+```
+🩺 ContextKit Doctor
+
+Running diagnostics...
+
+✓ Node.js version: v20.10.0
+✓ Configuration: 2 source(s) configured
+✓ Index database: 166 chunks, 40 files (12.5 MB)
+✓ Embeddings: 166/166 chunks (100%)
+✓ Query cache: 5 cached queries
+✓ Disk space: OK
+
+✓ All checks passed! ContextKit is ready to use.
+```
+
+### Common Issues
+
+**"Not initialized"**
+```bash
+contextkit init
+contextkit source add ./src
+contextkit index
+```
+
+**"No sources configured"**
+```bash
+contextkit source add ./src
+```
+
+**"No embeddings generated"**
+```bash
+contextkit index --force  # Re-index with embeddings
+```
+
+**Slow queries?**
+```bash
+contextkit cache clear    # Clear query cache
+contextkit index --force  # Rebuild index
+```
+
+---
+
 ## Technical Details
 
 ### How Selection Works
@@ -398,10 +478,12 @@ contextkit select "How does authentication work?"
 - [x] Multi-factor scoring algorithm
 - [x] Multiple output formats (markdown, XML, JSON, plain)
 - [x] **Import-aware scoring** — understands code dependencies
-- [ ] Function/class boundary awareness
-- [ ] VS Code extension
+- [x] **Doctor command** — diagnose setup issues
+- [ ] ~~Function/class boundary awareness~~ (done via AST chunking)
+- [x] **VS Code extension** — [in development](https://github.com/milo4jo/contextkit-vscode)
 - [ ] Cursor integration
 - [ ] Neovim plugin
+- [ ] Cloud sync for teams
 
 ---
 

package/dist/errors/index.d.ts

@@ -27,4 +27,19 @@ export declare class AlreadyInitializedError extends ContextKitError {
 export declare class InvalidUsageError extends ContextKitError {
     constructor(message: string);
 }
+export declare class IndexEmptyError extends ContextKitError {
+    constructor();
+}
+export declare class NoSourcesError extends ContextKitError {
+    constructor();
+}
+export declare class EmbeddingError extends ContextKitError {
+    constructor(detail?: string);
+}
+export declare class QueryError extends ContextKitError {
+    constructor(message: string);
+}
+export declare class DatabaseError extends ContextKitError {
+    constructor(operation: string, detail?: string);
+}
 //# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAElB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,UAAQ;CAM/D;AAED,qBAAa,mBAAoB,SAAQ,eAAe;IACtD,QAAQ,CAAC,UAAU,qBAAqB;;CAQzC;AAED,qBAAa,mBAAoB,SAAQ,eAAe;IACtD,QAAQ,CAAC,UAAU,4BAA4B;gBAEnC,IAAI,EAAE,MAAM;CAMzB;AAED,qBAAa,iBAAkB,SAAQ,eAAe;gBACxC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAM9C;AAED,qBAAa,iBAAkB,SAAQ,eAAe;gBACxC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM;CAOhD;AAED,qBAAa,uBAAwB,SAAQ,eAAe;;CAI3D;AAED,qBAAa,iBAAkB,SAAQ,eAAe;gBACxC,OAAO,EAAE,MAAM;CAG5B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAElB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,UAAQ;CAM/D;AAED,qBAAa,mBAAoB,SAAQ,eAAe;IACtD,QAAQ,CAAC,UAAU,qBAAqB;;CAQzC;AAED,qBAAa,mBAAoB,SAAQ,eAAe;IACtD,QAAQ,CAAC,UAAU,4BAA4B;gBAEnC,IAAI,EAAE,MAAM;CAMzB;AAED,qBAAa,iBAAkB,SAAQ,eAAe;gBACxC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAM9C;AAED,qBAAa,iBAAkB,SAAQ,eAAe;gBACxC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM;CAOhD;AAED,qBAAa,uBAAwB,SAAQ,eAAe;;CAI3D;AAED,qBAAa,iBAAkB,SAAQ,eAAe;gBACxC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,eAAgB,SAAQ,eAAe;;CAQnD;AAED,qBAAa,cAAe,SAAQ,eAAe;;CAQlD;AAED,qBAAa,cAAe,SAAQ,eAAe;gBACrC,MAAM,CAAC,EAAE,MAAM;CAM5B;AAED,qBAAa,UAAW,SAAQ,eAAe;gBACjC,OAAO,EAAE,MAAM;CAO5B;AAED,qBAAa,aAAc,SAAQ,eAAe;gBACpC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAM/C"}

package/dist/errors/index.js

@@ -48,4 +48,36 @@ export class InvalidUsageError extends ContextKitError {
         super(message, 'INVALID_USAGE');
     }
 }
+export class IndexEmptyError extends ContextKitError {
+    constructor() {
+        super('Index is empty. Run `contextkit index` after adding sources.', 'INDEX_EMPTY', true // recoverable
+        );
+    }
+}
+export class NoSourcesError extends ContextKitError {
+    constructor() {
+        super('No sources configured. Add sources with `contextkit source add ./src`', 'NO_SOURCES', true);
+    }
+}
+export class EmbeddingError extends ContextKitError {
+    constructor(detail) {
+        const msg = detail
+            ? `Embedding generation failed: ${detail}`
+            : 'Embedding generation failed. Try `contextkit index --force` to rebuild.';
+        super(msg, 'EMBEDDING_ERROR', true);
+    }
+}
+export class QueryError extends ContextKitError {
+    constructor(message) {
+        super(`Query failed: ${message}. Run \`contextkit doctor\` to diagnose.`, 'QUERY_ERROR', true);
+    }
+}
+export class DatabaseError extends ContextKitError {
+    constructor(operation, detail) {
+        const msg = detail
+            ? `Database ${operation} failed: ${detail}`
+            : `Database ${operation} failed. Try removing .contextkit/index.db and re-indexing.`;
+        super(msg, 'DATABASE_ERROR');
+    }
+}
 //# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAS;IACb,WAAW,CAAU;IAE9B,YAAY,OAAe,EAAE,IAAY,EAAE,WAAW,GAAG,KAAK;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,eAAe;IAC7C,UAAU,GAAG,iBAAiB,CAAC;IAExC;QACE,KAAK,CACH,gFAAgF,EAChF,iBAAiB,CAClB,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,eAAe;IAC7C,UAAU,GAAG,wBAAwB,CAAC;IAE/C,YAAY,IAAY;QACtB,KAAK,CACH,WAAW,IAAI,uEAAuE,EACtF,kBAAkB,CACnB,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IACpD,YAAY,IAAY,EAAE,UAAmB;QAC3C,MAAM,GAAG,GAAG,UAAU;YACpB,CAAC,CAAC,SAAS,IAAI,8BAA8B,UAAU,IAAI;YAC3D,CAAC,CAAC,SAAS,IAAI,cAAc,CAAC;QAChC,KAAK,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IACpD,YAAY,IAAY,EAAE,YAAqB;QAC7C,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,kBAAkB,YAAY,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,KAAK,CACH,WAAW,IAAI,oBAAoB,IAAI,4EAA4E,IAAI,KAAK,EAC5H,eAAe,CAChB,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,eAAe;IAC1D;QACE,KAAK,CAAC,mDAAmD,EAAE,qBAAqB,CAAC,CAAC;IACpF,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IACpD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAClC,CAAC;CACF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAS;IACb,WAAW,CAAU;IAE9B,YAAY,OAAe,EAAE,IAAY,EAAE,WAAW,GAAG,KAAK;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,eAAe;IAC7C,UAAU,GAAG,iBAAiB,CAAC;IAExC;QACE,KAAK,CACH,gFAAgF,EAChF,iBAAiB,CAClB,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,eAAe;IAC7C,UAAU,GAAG,wBAAwB,CAAC;IAE/C,YAAY,IAAY;QACtB,KAAK,CACH,WAAW,IAAI,uEAAuE,EACtF,kBAAkB,CACnB,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IACpD,YAAY,IAAY,EAAE,UAAmB;QAC3C,MAAM,GAAG,GAAG,UAAU;YACpB,CAAC,CAAC,SAAS,IAAI,8BAA8B,UAAU,IAAI;YAC3D,CAAC,CAAC,SAAS,IAAI,cAAc,CAAC;QAChC,KAAK,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IACpD,YAAY,IAAY,EAAE,YAAqB;QAC7C,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,kBAAkB,YAAY,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,KAAK,CACH,WAAW,IAAI,oBAAoB,IAAI,4EAA4E,IAAI,KAAK,EAC5H,eAAe,CAChB,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,eAAe;IAC1D;QACE,KAAK,CAAC,mDAAmD,EAAE,qBAAqB,CAAC,CAAC;IACpF,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IACpD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAClC,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,eAAe;IAClD;QACE,KAAK,CACH,8DAA8D,EAC9D,aAAa,EACb,IAAI,CAAC,cAAc;SACpB,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,eAAe;IACjD;QACE,KAAK,CACH,uEAAuE,EACvE,YAAY,EACZ,IAAI,CACL,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,eAAe;IACjD,YAAY,MAAe;QACzB,MAAM,GAAG,GAAG,MAAM;YAChB,CAAC,CAAC,gCAAgC,MAAM,EAAE;YAC1C,CAAC,CAAC,yEAAyE,CAAC;QAC9E,KAAK,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;CACF;AAED,MAAM,OAAO,UAAW,SAAQ,eAAe;IAC7C,YAAY,OAAe;QACzB,KAAK,CACH,iBAAiB,OAAO,0CAA0C,EAClE,aAAa,EACb,IAAI,CACL,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,eAAe;IAChD,YAAY,SAAiB,EAAE,MAAe;QAC5C,MAAM,GAAG,GAAG,MAAM;YAChB,CAAC,CAAC,YAAY,SAAS,YAAY,MAAM,EAAE;YAC3C,CAAC,CAAC,YAAY,SAAS,6DAA6D,CAAC;QACvF,KAAK,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milo4jo/contextkit",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Intelligent context selection for LLM applications",
   "author": "Milo <milo4jo@outlook.de>",
   "license": "MIT",