@egentica/codemap 0.1.5

package/LICENSE.md

@@ -0,0 +1,165 @@
+      GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+
+This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+0. Additional Definitions.
+
+As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+"The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+1. Exception to Section 3 of the GNU GPL.
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+2. Conveying Modified Versions.
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+a) under this License, provided that you make a good faith effort to
+ensure that, in the event an Application does not supply the
+function or data, the facility still operates, and performs
+whatever part of its purpose remains meaningful, or
+
+b) under the GNU GPL, with none of the additional permissions of
+this License applicable to that copy.
+
+3. Object Code Incorporating Material from Library Header Files.
+
+The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+a) Give prominent notice with each copy of the object code that the
+Library is used in it and that the Library and its use are
+covered by this License.
+
+b) Accompany the object code with a copy of the GNU GPL and this license
+document.
+
+4. Combined Works.
+
+You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+a) Give prominent notice with each copy of the Combined Work that
+the Library is used in it and that the Library and its use are
+covered by this License.
+
+b) Accompany the Combined Work with a copy of the GNU GPL and this license
+document.
+
+c) For a Combined Work that displays copyright notices during
+execution, include the copyright notice for the Library among
+these notices, as well as a reference directing the user to the
+copies of the GNU GPL and this license document.
+
+d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+e) Provide Installation Information, but only if you would otherwise
+be required to provide such information under section 6 of the
+GNU GPL, and only to the extent that such information is
+necessary to install and execute a modified version of the
+Combined Work produced by recombining or relinking the
+Application with a modified version of the Linked Version. (If
+you use option 4d0, the Installation Information must accompany
+the Minimal Corresponding Source and Corresponding Application
+Code. If you use option 4d1, you must provide the Installation
+Information in the manner specified by section 6 of the GNU GPL
+for conveying Corresponding Source.)
+
+5. Combined Libraries.
+
+You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+a) Accompany the combined library with a copy of the same work based
+on the Library, uncombined with any other library facilities,
+conveyed under the terms of this License.
+
+b) Give prominent notice with the combined library that part of it
+is a work based on the Library, and explaining where to find the
+accompanying uncombined form of the same work.
+
+6. Revised Versions of the GNU Lesser General Public License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/README.md

@@ -0,0 +1,479 @@
+# @egentica/codemap
+
+> Universal code knowledge graph with zero-configuration setup
+
+[![npm version](https://img.shields.io/npm/v/@egentica/codemap.svg)](https://www.npmjs.com/package/@egentica/codemap)
+[![License: LGPL-3.0](https://img.shields.io/badge/License-LGPL--3.0-blue.svg)](https://opensource.org/licenses/LGPL-3.0)
+
+CodeMap is a language-agnostic code knowledge graph that builds deep understanding of your codebase through AST-based parsing, dependency tracking, and topology-aware navigation.
+
+## Features
+
+- **🚀 Zero Configuration** - Works out of the box with Node.js, no setup required
+- **🔍 Deep Code Understanding** - AST-based parsing with symbol extraction and dependency tracking
+- **🔌 Bundled Parsers** - TypeScript/JavaScript and Vue support included
+- **📊 Knowledge Graph** - Build relationships between files, symbols, and dependencies
+- **🎯 Smart Search** - Keyword search, symbol search, and hybrid search with relevance ranking
+- **🏷️ Labels & Groups** - Organize code with labels and logical groupings
+- **📝 Session Tracking** - Automatic change tracking and history
+- **🔧 MCP Server** - Built-in Model Context Protocol server for AI integration
+
+## Installation
+
+```bash
+npm install @egentica/codemap
+```
+
+**Bundled language parsers** (no additional packages needed):
+- ✅ TypeScript/JavaScript (`.ts`, `.tsx`, `.js`, `.jsx`)
+- ✅ Vue (`.vue` single-file components)
+
+## Quick Start
+
+```typescript
+import { CodeMap } from '@egentica/codemap';
+
+// Initialize CodeMap
+const codemap = new CodeMap({
+  rootPath: '/path/to/project'
+});
+
+// Scan the project
+await codemap.scan();
+
+// Search for code
+const results = codemap.query.search({
+  query: 'authentication',
+  mode: 'hybrid'
+});
+
+// Get file dependencies
+const file = codemap.graph.getFile('src/auth/login.ts');
+console.log('Symbols:', file.symbols);
+console.log('Imports:', file.references);
+console.log('Imported by:', file.referencedBy);
+```
+
+## Core Concepts
+
+### CodeMap Instance
+
+The `CodeMap` class is your main entry point:
+
+```typescript
+const codemap = new CodeMap({
+  rootPath: '/project',
+  ignore: ['node_modules/**', 'dist/**', '.git/**']
+});
+```
+
+### Scanning
+
+Build the knowledge graph by scanning your project:
+
+```typescript
+// Full project scan
+const stats = await codemap.scan();
+console.log(`Scanned ${stats.filesScanned} files in ${stats.durationMs}ms`);
+```
+
+### Knowledge Graph
+
+Direct access to files, symbols, and dependencies:
+
+```typescript
+// Get file entry
+const file = codemap.graph.getFile('src/components/Button.tsx');
+
+// Get all files
+const allFiles = codemap.graph.getAllFiles();
+
+// Get symbols in a file
+const symbols = file.symbols;
+
+// Get dependencies
+const imports = file.references;      // Files this file imports
+const importedBy = file.referencedBy; // Files that import this file
+```
+
+### Querying
+
+Multiple search modes for finding code:
+
+```typescript
+// Keyword search (file names, paths)
+const files = codemap.query.search({
+  query: 'authentication',
+  mode: 'text'
+});
+
+// Symbol search (functions, classes, interfaces)
+const symbols = codemap.query.search({
+  query: 'getUserById',
+  mode: 'symbol'
+});
+
+// Hybrid search (best of both)
+const results = codemap.query.search({
+  query: 'auth login',
+  mode: 'hybrid'
+});
+```
+
+### File Operations
+
+All file operations go through the lifecycle-aware gateway:
+
+```typescript
+// Read file
+const content = await codemap.fs.read('src/index.ts');
+
+// Write file (emits events)
+await codemap.fs.write('src/new.ts', 'export const x = 1;');
+
+// Check existence
+const exists = await codemap.fs.exists('src/config.json');
+```
+
+## Symbols
+
+CodeMap extracts symbols from your code:
+
+```typescript
+interface SymbolEntry {
+  name: string;            // Symbol name
+  kind: SymbolKind;        // function|class|interface|const|type|enum|etc.
+  startLine: number;       // Start line number
+  startCol: number;        // Start column
+  exported?: boolean;      // Export status
+  signature?: string;      // Function signature
+}
+
+// Access symbols
+const file = codemap.graph.getFile('src/api/users.ts');
+const functions = file.symbols.filter(s => s.kind === 'function');
+const exported = file.symbols.filter(s => s.exported);
+```
+
+## Labels
+
+Organize code with labels:
+
+```typescript
+// Create a label
+await codemap.labels.create({
+  emoji: '🔒',
+  name: 'security-critical',
+  description: 'Security-sensitive code requiring review'
+});
+
+// Assign labels to files
+await codemap.labels.assign('security-critical', [
+  'src/auth/login.ts',
+  'src/auth/jwt.ts'
+]);
+
+// Search by label
+const labeled = await codemap.labels.search('security-critical');
+
+// List all labels
+const allLabels = await codemap.labels.list();
+```
+
+## Groups
+
+Organize related files and symbols:
+
+```typescript
+// Create a group
+await codemap.groups.add({
+  name: 'auth-system',
+  description: 'Authentication and authorization components',
+  members: [
+    'src/auth/login.ts',
+    'src/auth/jwt.ts',
+    'src/auth/permissions.ts$checkPermission'  // Symbol reference
+  ]
+});
+
+// Get group details
+const group = await codemap.groups.get('auth-system');
+
+// List all groups
+const allGroups = await codemap.groups.list();
+```
+
+## Sessions
+
+Track changes and history:
+
+```typescript
+// Start a session
+await codemap.sessions.start();
+
+// Operations are automatically tracked
+await codemap.fs.write('src/new.ts', 'content');
+
+// Close session with summary
+await codemap.sessions.close('Added new authentication module');
+
+// List session history
+const history = await codemap.sessions.list();
+```
+
+## Annotations
+
+Add semantic metadata to code:
+
+```typescript
+// Add annotation
+await codemap.annotations.add('src/auth/login.ts', {
+  key: 'domain.name',
+  value: 'Authentication System'
+});
+
+// Get annotations
+const file = codemap.graph.getFile('src/auth/login.ts');
+console.log(file.annotations);
+```
+
+## Plugins
+
+CodeMap is extensible through plugins:
+
+### Language Parsers
+
+Add support for additional languages:
+
+```typescript
+import { LanguageParser, ParseResult } from '@egentica/codemap';
+
+class MyParser implements LanguageParser {
+  name = 'my-language-parser';
+  extensions = ['.mylang'];
+  
+  async parse(content: string, filePath: string): Promise<ParseResult> {
+    // Parse AST and extract symbols
+    return {
+      symbols: [...],
+      references: [...]
+    };
+  }
+}
+
+// Register parser
+await codemap.registerPlugin(new MyParser());
+```
+
+### Feature Plugins
+
+Extend CodeMap with custom analysis:
+
+```typescript
+import { Plugin, CodeMapHost } from '@egentica/codemap';
+
+class MyPlugin implements Plugin {
+  name = 'my-plugin';
+  version = '1.0.0';
+  
+  async initialize(codemap: CodeMapHost): Promise<void> {
+    // Hook into events
+    codemap.on('scan:complete', async () => {
+      console.log('Scan complete!');
+    });
+  }
+}
+
+// Register plugin
+await codemap.registerPlugin(new MyPlugin());
+```
+
+## Event System
+
+Hook into lifecycle events:
+
+```typescript
+// File operations
+codemap.on('file:write:before', async (payload) => {
+  console.log('About to write:', payload.path);
+});
+
+codemap.on('file:write:after', async (payload) => {
+  console.log('Wrote:', payload.path);
+});
+
+// Scan events
+codemap.on('scan:start', async () => {
+  console.log('Scan starting...');
+});
+
+codemap.on('scan:file', async (payload) => {
+  console.log('Scanned:', payload.file.relativePath);
+});
+
+codemap.on('scan:complete', async () => {
+  console.log('Scan complete!');
+});
+```
+
+## MCP Server
+
+CodeMap includes a built-in MCP (Model Context Protocol) server for AI integration:
+
+### Installation
+
+```bash
+npm install -g @egentica/codemap
+```
+
+### Configuration
+
+Add to Claude Desktop config file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "codemap": {
+      "command": "codemap-server",
+      "args": []
+    }
+  }
+}
+```
+
+### Usage
+
+The server provides 50+ tools for AI-assisted code navigation:
+
+- **Search & Discovery** - Find files, symbols, text, annotations
+- **File Operations** - Read, write, edit files
+- **Graph & Dependencies** - Analyze relationships and impact
+- **Code Organization** - Groups, annotations, labels
+- **Session Management** - Track changes and workflows
+
+## Configuration
+
+Create `.codemap/config.json` in your project root:
+
+```json
+{
+  "version": 1,
+  "ignore": [
+    "node_modules/**",
+    "dist/**",
+    "coverage/**",
+    ".git/**"
+  ],
+  "plugins": [],
+  "parsers": [],
+  "writeAnnotationsToSource": false,
+  "backup": {
+    "enabled": true,
+    "maxDailyBackups": 7,
+    "maxTurnBackups": 20
+  }
+}
+```
+
+## API Reference
+
+### CodeMap
+
+```typescript
+class CodeMap {
+  constructor(config: CodeMapConfig);
+  
+  // Lifecycle
+  scan(options?: ScanOptions): Promise<ScanStats>;
+  
+  // Plugin management
+  registerPlugin(plugin: Plugin): Promise<void>;
+  unregisterPlugin(name: string): Promise<boolean>;
+  
+  // Event system
+  on(event: CodeMapEvent, handler: EventHandler): void;
+  off(event: CodeMapEvent, handler: EventHandler): void;
+  
+  // Public APIs
+  graph: FileSystemGraph;       // Knowledge graph
+  query: QueryEngine;           // Search & query
+  fs: FileSystemIO;             // File operations  
+  io: FileSystemIO;             // Extended I/O operations
+  resolver: TargetResolver;     // Path resolution
+  labels: LabelStore;           // Label management
+  groups: GroupStore;           // Group management  
+  sessions: SessionLog;         // Session tracking
+  annotations: AnnotationStore; // Annotation management
+}
+```
+
+### QueryEngine
+
+```typescript
+class QueryEngine {
+  search(request: SearchRequest): SearchResponse;
+  findByName(pattern: string): FileEntry[];
+  findRelevant(task: string, maxResults?: number): RelevanceMatch[];
+  findImporters(path: string): FileEntry[];
+  findImports(path: string): FileEntry[];
+  traverse(path: string, direction: 'imports'|'importers', depth?: number): FileEntry[];
+}
+
+interface SearchRequest {
+  query: string;
+  mode?: 'text' | 'symbol' | 'hybrid';
+  maxResults?: number;
+  symbolKinds?: SymbolKind[];
+  useRegex?: boolean;
+}
+```
+
+### FileSystemGraph
+
+```typescript
+class FileSystemGraph {
+  getFile(path: string): FileEntry | undefined;
+  getAllFiles(): FileEntry[];
+  getFilesByDirectory(dir: string): FileEntry[];
+  getDependencies(path: string): string[];
+  getDependents(path: string): string[];
+}
+```
+
+## Advanced Usage
+
+### Custom FileSystemProvider
+
+For non-Node.js environments or custom storage:
+
+```typescript
+import { CodeMap, FileSystemProvider } from '@egentica/codemap';
+
+class CustomProvider implements FileSystemProvider {
+  async read(path: string): Promise<string> { /* ... */ }
+  async write(path: string, content: string): Promise<void> { /* ... */ }
+  async exists(path: string): Promise<boolean> { /* ... */ }
+  async readdir(path: string): Promise<string[]> { /* ... */ }
+  // ... implement other methods
+}
+
+const codemap = new CodeMap({
+  rootPath: '/project',
+  provider: new CustomProvider()
+});
+```
+
+## TypeScript Support
+
+CodeMap is written in TypeScript and provides full type definitions. All APIs are fully typed.
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+
+## License
+
+LGPL-3.0 © Egentica