@ulpi/codemap 0.1.0

package/LICENSE

@@ -0,0 +1,73 @@
+ULPI Codemap License
+
+Copyright (c) 2025-present ULPI Inc. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use
+the Software for local, non-commercial and commercial purposes on machines
+owned or controlled by the licensee, subject to the following conditions:
+
+1. GRANT OF USE
+
+   You may install, run, and use the Software on any number of machines you
+   own or control, for any purpose including personal, educational, and
+   commercial use.
+
+2. RESTRICTIONS
+
+   You may NOT:
+
+   a. Modify, adapt, translate, reverse engineer, decompile, disassemble,
+      or create derivative works based on the Software.
+
+   b. Redistribute, sublicense, sell, lease, rent, or otherwise transfer
+      the Software or any portion thereof to any third party, whether in
+      source code, binary, or any other form.
+
+   c. Remove, alter, or obscure any proprietary notices, labels, or marks
+      on the Software.
+
+   d. Use the Software to build a competing product or service that
+      replicates the core functionality of the Software.
+
+   e. Host, offer, or operate the Software as a service (SaaS) for third
+      parties, whether or not for compensation.
+
+3. INTELLECTUAL PROPERTY
+
+   The Software and all copies thereof are proprietary to ULPI Inc. and
+   title thereto remains in ULPI Inc. All rights in the Software not
+   specifically granted in this license are reserved to ULPI Inc.
+
+4. NO WARRANTY
+
+   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 ULPI INC. 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.
+
+5. TERMINATION
+
+   This license is effective until terminated. ULPI Inc. may terminate this
+   license at any time if you fail to comply with any term of this license.
+   Upon termination, you must destroy all copies of the Software in your
+   possession.
+
+6. CHANGES TO LICENSE TERMS
+
+   ULPI Inc. reserves the right to change the terms of this license in
+   future versions of the Software. Continued use of a version of the
+   Software is governed by the license terms that accompanied that version.
+   Updated license terms apply only to new versions released after the
+   change.
+
+7. GOVERNING LAW
+
+   This license shall be governed by and construed in accordance with the
+   laws of the State of Delaware, United States, without regard to its
+   conflict of laws provisions.
+
+For licensing inquiries, contact: legal@ulpi.dev

package/README.md

@@ -0,0 +1,386 @@
+# @ulpi/codemap
+
+Code intelligence CLI — hybrid vector + BM25 semantic search, dependency analysis, and PageRank for any codebase.
+
+[![npm version](https://img.shields.io/npm/v/@ulpi/codemap.svg)](https://www.npmjs.com/package/@ulpi/codemap) [![node](https://img.shields.io/node/v/@ulpi/codemap.svg)](https://nodejs.org)
+
+## Features
+
+- **Hybrid search** — combines vector similarity with BM25 keyword scoring for accurate code search
+- **Symbol lookup** — find functions, classes, types, and interfaces by name
+- **Dependency graph** — trace imports and dependents across your codebase
+- **PageRank** — identify the most important files by connectivity
+- **Cycle detection** — find circular dependencies automatically
+- **Coupling metrics** — measure afferent/efferent coupling and instability per file
+- **Real-time watching** — incremental re-indexing on file changes
+- **MCP server** — 12 tools for AI agent integration (Claude, Cursor, VS Code, etc.)
+- **Per-branch indexing** — separate indexes for each git branch
+- **Multiple providers** — works with Ollama (free, local), OpenAI, or ULPI Cloud embeddings
+
+## Quick Start
+
+```bash
+npm install -g @ulpi/codemap
+
+codemap init          # Choose provider + model
+codemap index         # Index your project
+codemap search "authentication middleware"
+```
+
+## Embedding Providers
+
+| Provider | Models | Dims | Cost | Requires |
+|----------|--------|------|------|----------|
+| **Ollama** | `nomic-embed-text` (768), `mxbai-embed-large` (1024), `all-minilm` (384) | varies | Free | Ollama running locally |
+| **OpenAI** | `text-embedding-3-small` (1536), `text-embedding-3-large` (3072) | varies | Paid | `OPENAI_API_KEY` |
+| **ULPI Cloud** | `code` (1024) | 1024 | Managed | `ULPI_API_KEY` |
+
+`codemap init` walks you through provider and model selection interactively.
+
+## Command Reference
+
+### `codemap init`
+
+Interactive first-time setup. Prompts for embedding provider, model, and API key.
+
+```bash
+codemap init
+codemap init --provider ollama    # Skip interactive prompt
+codemap init --provider openai
+codemap init --provider ulpi
+```
+
+### `codemap index`
+
+Index the current project for code search. Scans files, chunks with AST awareness, generates embeddings, and builds the dependency graph.
+
+```bash
+codemap index
+codemap index --full              # Force full re-index (ignore incremental state)
+```
+
+### `codemap search <query>`
+
+Search code using hybrid vector + BM25 scoring.
+
+```bash
+codemap search "database connection pool"
+codemap search "error handling" --limit 20
+codemap search "auth middleware" --json
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-l, --limit <n>` | Max results | `10` |
+| `--json` | Output as JSON | — |
+
+### `codemap symbols <query>`
+
+Find functions, classes, and types by name.
+
+```bash
+codemap symbols "createUser"
+codemap symbols "Router" --limit 5
+codemap symbols "Handler" --json
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-l, --limit <n>` | Max results | `20` |
+| `--json` | Output as JSON | — |
+
+### `codemap status`
+
+Show index statistics for the current project.
+
+```bash
+codemap status
+codemap status --json
+```
+
+### `codemap watch`
+
+Watch for file changes and update the index in real-time.
+
+```bash
+codemap watch
+codemap watch --debounce 500
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--debounce <ms>` | Debounce interval | `300` |
+
+### `codemap deps <file>`
+
+Show files this file depends on (outgoing imports).
+
+```bash
+codemap deps src/routes/auth.ts
+codemap deps src/index.ts --json
+```
+
+### `codemap dependents <file>`
+
+Show files that depend on this file (incoming imports).
+
+```bash
+codemap dependents src/utils/db.ts
+codemap dependents src/config.ts --json
+```
+
+### `codemap rank [file]`
+
+Show PageRank importance scores. Without a file argument, lists top-ranked files.
+
+```bash
+codemap rank                      # Top 20 files by importance
+codemap rank --limit 50
+codemap rank src/index.ts         # Single file score
+codemap rank --json
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-l, --limit <n>` | Number of top files | `20` |
+| `--json` | Output as JSON | — |
+
+### `codemap cycles`
+
+Detect circular dependencies in the codebase.
+
+```bash
+codemap cycles
+codemap cycles --json
+```
+
+### `codemap ignore`
+
+Generate or reset `.codemapignore` with default exclusion patterns.
+
+```bash
+codemap ignore
+codemap ignore --force            # Overwrite existing .codemapignore
+```
+
+### `codemap config`
+
+Get, set, or list configuration values.
+
+```bash
+codemap config list
+codemap config get embedding.provider
+codemap config set embedding.provider openai
+codemap config set embedding.apiKey sk-...
+```
+
+### `codemap serve`
+
+Start an MCP server over stdio for AI agent integration.
+
+```bash
+codemap serve
+```
+
+### Global Options
+
+All commands support:
+
+| Option | Description |
+|--------|-------------|
+| `--cwd <dir>` | Override project directory |
+| `--version` | Show version |
+| `--help` | Show help |
+
+## MCP Integration
+
+`codemap serve` starts an [MCP](https://modelcontextprotocol.io/) server over stdio, exposing 12 code intelligence tools to any compatible AI agent or editor.
+
+### Claude Code
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "codemap": {
+      "command": "codemap",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "codemap": {
+      "command": "codemap",
+      "args": ["serve"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "codemap": {
+      "command": "codemap",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Kiro
+
+Add to `.kiro/settings/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "codemap": {
+      "command": "codemap",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### VS Code (Copilot)
+
+Add to `.vscode/mcp.json` in your project root:
+
+```json
+{
+  "servers": {
+    "codemap": {
+      "command": "codemap",
+      "args": ["serve"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+### JetBrains (IntelliJ, WebStorm, etc.)
+
+Go to Settings > Tools > AI Assistant > MCP Servers, add:
+
+```json
+{
+  "mcpServers": {
+    "codemap": {
+      "command": "codemap",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "codemap": {
+      "command": "codemap",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Zed
+
+Add to `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "codemap": {
+      "command": {
+        "path": "codemap",
+        "args": ["serve"]
+      }
+    }
+  }
+}
+```
+
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `search_code` | Search code using hybrid vector + BM25 |
+| `search_symbols` | Find functions, classes, and types by name |
+| `get_file_summary` | Get file overview with symbols and size |
+| `get_index_stats` | Get code search index statistics |
+| `reindex` | Trigger a full code search re-index |
+| `get_dependencies` | Get files this file imports (outgoing edges) |
+| `get_dependents` | Get files that import this file (incoming edges) |
+| `get_file_rank` | Get PageRank importance score for files |
+| `find_cycles` | Detect circular dependencies |
+| `get_coupling_metrics` | Analyze afferent/efferent coupling and instability |
+| `get_depgraph_stats` | Get aggregate dependency graph statistics |
+| `rebuild_depgraph` | Recompute PageRank and dependency metrics |
+
+## Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `CODEMAP_DATA_DIR` | Override data directory | `~/.codemap` |
+| `OPENAI_API_KEY` | OpenAI API key | — |
+| `OLLAMA_HOST` | Ollama server URL | `http://localhost:11434` |
+| `ULPI_API_KEY` | ULPI Cloud API key | — |
+| `CODEMAP_PROJECT_DIR` | Override project directory (MCP mode) | `cwd` |
+
+## Configuration
+
+Configuration is loaded in order of precedence (highest first):
+
+1. **Project config** — `.codemap.json` in project root
+2. **Global config** — `~/.codemap/config.json`
+3. **Defaults**
+
+Manage with the `config` command:
+
+```bash
+codemap config list                          # Show all values
+codemap config get embedding.provider        # Get a value
+codemap config set embedding.model nomic-embed-text   # Set a value
+```
+
+## How It Works
+
+1. **Scan** — discovers source files respecting `.gitignore` and deny patterns
+2. **Chunk** — splits files into AST-aware chunks (functions, classes, blocks)
+3. **Embed** — generates vector embeddings via your chosen provider
+4. **Store** — writes vectors to LanceDB and builds a BM25 index
+5. **Graph** — extracts import/export edges with tree-sitter, computes PageRank
+6. **Search** — combines vector similarity, BM25 keyword scoring, symbol boosting, and graph rank
+
+Data is stored per-project and per-branch at `~/.codemap/{projectSlug}/{branchSlug}/`.
+
+## Requirements
+
+- **Node.js** 18+
+- **Ollama** provider: running Ollama instance with model pulled (`ollama pull nomic-embed-text`)
+- **OpenAI** provider: valid `OPENAI_API_KEY`
+- **ULPI Cloud** provider: valid `ULPI_API_KEY`
+
+## License
+
+See [LICENSE](./LICENSE).

package/dist/chunk-5ISZDDN7.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import {
+  resolveApiKey
+} from "./chunk-SNG7R3UC.js";
+
+// ../../packages/intelligence/embed-engine/dist/chunk-WX74CUTY.js
+var OPENAI_EMBEDDINGS_URL = "https://api.openai.com/v1/embeddings";
+var MAX_RETRIES = 3;
+var RETRY_BASE_MS = 1e3;
+var OpenAIEmbedder = class {
+  provider = "openai";
+  model;
+  dimensions;
+  apiKey;
+  constructor(model = "text-embedding-3-small", dimensions = 1536) {
+    this.model = model;
+    this.dimensions = dimensions;
+    const key = resolveApiKey("openai");
+    if (!key) {
+      throw new Error(
+        "OpenAI API key not found. Set it with:\n  ulpi config set openai-key <your-key>\nOr switch to Ollama (local, no key needed):\n  ulpi codemap config embedding.provider ollama"
+      );
+    }
+    this.apiKey = key;
+  }
+  async embed(texts) {
+    if (texts.length === 0) return [];
+    const body = {
+      input: texts,
+      model: this.model,
+      dimensions: this.dimensions
+    };
+    let lastError = null;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      try {
+        const response = await fetch(OPENAI_EMBEDDINGS_URL, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`
+          },
+          body: JSON.stringify(body)
+        });
+        if (!response.ok) {
+          const errorText = await response.text();
+          if (response.status === 401 || response.status === 403) {
+            throw new Error(`OpenAI API authentication error (${response.status}): check your OPENAI_API_KEY`);
+          }
+          if (response.status === 429 || response.status >= 500) {
+            lastError = new Error(`OpenAI API error (${response.status}): ${errorText.slice(0, 200)}`);
+            const delay = RETRY_BASE_MS * Math.pow(2, attempt);
+            await sleep(delay);
+            continue;
+          }
+          throw new Error(`OpenAI API error (${response.status}): ${errorText.slice(0, 200)}`);
+        }
+        const data = await response.json();
+        const sorted = data.data.sort((a, b) => a.index - b.index);
+        return sorted.map((item) => item.embedding);
+      } catch (err) {
+        if (err instanceof Error && (err.message.includes("authentication") || err.message.includes("Unknown"))) {
+          throw err;
+        }
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < MAX_RETRIES - 1) {
+          const delay = RETRY_BASE_MS * Math.pow(2, attempt);
+          await sleep(delay);
+        }
+      }
+    }
+    throw lastError ?? new Error("OpenAI embedding failed after retries");
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export {
+  OpenAIEmbedder
+};