@egentica/codemap 0.1.5

package/dist/query/TextSearch.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * TextSearch - Keyword-based text search in paths and symbols.
+ *
+ * Provides:
+ * - Keyword extraction from queries
+ * - Path matching (keyword overlap)
+ * - Symbol name matching
+ * - Relevance scoring
+ *
+ * @example
+ * ```typescript
+ * const search = new TextSearch();
+ * const results = search.searchFiles(query, files);
+ * // → Ranked files with relevance scores
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TextSearch = void 0;
+class TextSearch {
+    /**
+     * Search files by text/keyword matching.
+     *
+     * @param query - Search query
+     * @param files - Files to search
+     * @returns Ranked results with scores
+     */
+    searchFiles(query, files) {
+        const queryKeywords = this.extractKeywords(query);
+        const results = [];
+        for (const file of files) {
+            const matches = [];
+            let score = 0;
+            // 1. Path matching
+            const pathKeywords = this.extractKeywords(file.relativePath);
+            for (const keyword of queryKeywords) {
+                if (pathKeywords.includes(keyword)) {
+                    score += 5;
+                    matches.push({
+                        keyword,
+                        location: 'path',
+                        score: 1.0
+                    });
+                }
+            }
+            // 2. Symbol matching
+            if (file.symbols && file.symbols.length > 0) {
+                for (const symbol of file.symbols) {
+                    const symbolKeywords = this.extractKeywords(symbol.name);
+                    for (const keyword of queryKeywords) {
+                        if (symbolKeywords.includes(keyword)) {
+                            score += 3;
+                            matches.push({
+                                keyword,
+                                location: 'symbol',
+                                score: 1.0
+                            });
+                        }
+                    }
+                }
+            }
+            if (score > 0) {
+                results.push({ file, score, matches });
+            }
+        }
+        // Sort by score descending
+        return results.sort((a, b) => b.score - a.score);
+    }
+    /**
+     * Extract keywords from text.
+     *
+     * @param text - Text to extract from
+     * @returns Array of keywords
+     */
+    extractKeywords(text) {
+        // Convert to lowercase, split on non-alphanumeric
+        const words = text.toLowerCase().split(/[^a-z0-9]+/);
+        // Filter out stop words and short words
+        const stopWords = new Set([
+            'a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'to', 'of',
+            'in', 'on', 'at', 'by', 'for', 'with', 'from', 'as', 'this', 'that'
+        ]);
+        return words
+            .filter(w => w.length > 2 && !stopWords.has(w))
+            .filter((w, i, arr) => arr.indexOf(w) === i); // Deduplicate
+    }
+    /**
+     * Calculate keyword overlap between two sets.
+     *
+     * @param keywords1 - First set
+     * @param keywords2 - Second set
+     * @returns Overlap ratio (0-1)
+     */
+    calculateOverlap(keywords1, keywords2) {
+        if (keywords1.length === 0 || keywords2.length === 0) {
+            return 0;
+        }
+        const set1 = new Set(keywords1);
+        const set2 = new Set(keywords2);
+        let overlap = 0;
+        for (const keyword of set1) {
+            if (set2.has(keyword)) {
+                overlap++;
+            }
+        }
+        return overlap / Math.max(keywords1.length, keywords2.length);
+    }
+}
+exports.TextSearch = TextSearch;
+//# sourceMappingURL=TextSearch.js.map

package/dist/query/TextSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextSearch.js","sourceRoot":"","sources":["../../src/query/TextSearch.ts"],"names":[],"mappings":"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"}

package/dist/storage/NodeFsProvider.d.ts

@@ -0,0 +1,148 @@
+/**
+ * NodeFsProvider - Node.js filesystem storage adapter
+ *
+ * File-based storage adapter for Node.js/Electron environments.
+ * Implements FileSystemProvider using node:fs/promises.
+ *
+ * Zero dependencies — pure Node.js.
+ */
+import type { FileSystemProvider } from '../types/contracts/FileSystemProvider';
+/**
+ * Node.js filesystem storage adapter.
+ *
+ * Implements FileSystemProvider contract using node:fs/promises.
+ * This is the default storage backend for Node.js and Electron environments.
+ *
+ * @example
+ * ```typescript
+ * import { CodeMap, NodeFsProvider } from '@egentica/codemap';
+ *
+ * const codemap = new CodeMap({
+ *   rootPath: '/project',
+ *   provider: new NodeFsProvider()
+ * });
+ * ```
+ */
+export declare class NodeFsProvider implements FileSystemProvider {
+    /**
+     * Read file contents as UTF-8 string.
+     *
+     * @param filePath - Absolute path to file
+     * @returns File content as string
+     * @throws Error if file doesn't exist or cannot be read
+     */
+    read(filePath: string): Promise<string>;
+    /**
+     * Write content to file.
+     * Creates parent directories if they don't exist.
+     *
+     * @param filePath - Absolute path to file
+     * @param content - Content to write
+     * @throws Error if write fails
+     */
+    write(filePath: string, content: string): Promise<void>;
+    /**
+     * Check if file or directory exists.
+     *
+     * @param filePath - Absolute path to check
+     * @returns True if exists
+     */
+    exists(filePath: string): Promise<boolean>;
+    /**
+     * Read directory contents.
+     *
+     * @param dirPath - Absolute path to directory
+     * @returns Array of entry names (not full paths)
+     * @throws Error if directory doesn't exist or cannot be read
+     */
+    readdir(dirPath: string): Promise<string[]>;
+    /**
+     * Get file/directory stats.
+     *
+     * @param filePath - Absolute path to file or directory
+     * @returns Stats object with isDirectory, size, mtime
+     * @throws Error if path doesn't exist or cannot be accessed
+     */
+    stat(filePath: string): Promise<{
+        isDirectory: boolean;
+        size: number;
+        mtime: number;
+    }>;
+    /**
+     * Remove file.
+     *
+     * @param filePath - Absolute path to file
+     * @throws Error if file doesn't exist or cannot be deleted
+     */
+    remove(filePath: string): Promise<void>;
+    /**
+     * Rename or move file.
+     *
+     * @param oldPath - Current absolute path
+     * @param newPath - New absolute path
+     * @throws Error if operation fails
+     */
+    rename(oldPath: string, newPath: string): Promise<void>;
+    /**
+     * Create directory.
+     * Creates parent directories if they don't exist.
+     *
+     * @param dirPath - Absolute path to directory
+     * @throws Error if creation fails
+     */
+    mkdir(dirPath: string): Promise<void>;
+    /**
+     * Remove directory.
+     *
+     * @param dirPath - Absolute path to directory
+     * @param options - Options (recursive: delete directory and contents)
+     * @throws Error if deletion fails
+     */
+    rmdir(dirPath: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+}
+/**
+ * Synchronous filesystem operations.
+ *
+ * Use sparingly — async operations are preferred.
+ * Useful for initialization code that must be synchronous.
+ */
+export declare class NodeFsProviderSync {
+    /**
+     * Check if file or directory exists (synchronous).
+     *
+     * @param filePath - Absolute path to check
+     * @returns True if exists
+     */
+    existsSync(filePath: string): boolean;
+    /**
+     * Read file contents (synchronous).
+     *
+     * @param filePath - Absolute path to file
+     * @returns File content as string
+     * @throws Error if file doesn't exist or cannot be read
+     */
+    readSync(filePath: string): string;
+    /**
+     * Write file contents (synchronous).
+     *
+     * @param filePath - Absolute path to file
+     * @param content - Content to write
+     * @throws Error if write fails
+     */
+    writeSync(filePath: string, content: string): void;
+    /**
+     * Create directory (synchronous).
+     *
+     * @param dirPath - Absolute path to directory
+     * @throws Error if creation fails
+     */
+    mkdirSync(dirPath: string): void;
+}
+/**
+ * Default export: async provider instance.
+ */
+declare const _default: NodeFsProvider;
+export default _default;
+//# sourceMappingURL=NodeFsProvider.d.ts.map

package/dist/storage/NodeFsProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeFsProvider.d.ts","sourceRoot":"","sources":["../../src/storage/NodeFsProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAEhF;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAe,YAAW,kBAAkB;IACvD;;;;;;OAMG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAU7C;;;;;;;OAOG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7D;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAShD;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAUjD;;;;;;OAMG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QACpC,WAAW,EAAE,OAAO,CAAC;QACrB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IAeF;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7C;;;;;;OAMG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7D;;;;;;OAMG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU3C;;;;;;OAMG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAa/E;AAED;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IASrC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAUlC;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAclD;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CASjC;AAED;;GAEG;;AACH,wBAAoC"}

package/dist/storage/NodeFsProvider.js

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * NodeFsProvider - Node.js filesystem storage adapter
+ *
+ * File-based storage adapter for Node.js/Electron environments.
+ * Implements FileSystemProvider using node:fs/promises.
+ *
+ * Zero dependencies — pure Node.js.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeFsProviderSync = exports.NodeFsProvider = void 0;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Node.js filesystem storage adapter.
+ *
+ * Implements FileSystemProvider contract using node:fs/promises.
+ * This is the default storage backend for Node.js and Electron environments.
+ *
+ * @example
+ * ```typescript
+ * import { CodeMap, NodeFsProvider } from '@egentica/codemap';
+ *
+ * const codemap = new CodeMap({
+ *   rootPath: '/project',
+ *   provider: new NodeFsProvider()
+ * });
+ * ```
+ */
+class NodeFsProvider {
+    /**
+     * Read file contents as UTF-8 string.
+     *
+     * @param filePath - Absolute path to file
+     * @returns File content as string
+     * @throws Error if file doesn't exist or cannot be read
+     */
+    async read(filePath) {
+        try {
+            return await promises_1.default.readFile(filePath, 'utf-8');
+        }
+        catch (error) {
+            throw new Error(`Failed to read file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Write content to file.
+     * Creates parent directories if they don't exist.
+     *
+     * @param filePath - Absolute path to file
+     * @param content - Content to write
+     * @throws Error if write fails
+     */
+    async write(filePath, content) {
+        try {
+            // Ensure parent directory exists
+            const dir = node_path_1.default.dirname(filePath);
+            await this.mkdir(dir);
+            // Write file
+            await promises_1.default.writeFile(filePath, content, 'utf-8');
+        }
+        catch (error) {
+            throw new Error(`Failed to write file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Check if file or directory exists.
+     *
+     * @param filePath - Absolute path to check
+     * @returns True if exists
+     */
+    async exists(filePath) {
+        try {
+            await promises_1.default.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Read directory contents.
+     *
+     * @param dirPath - Absolute path to directory
+     * @returns Array of entry names (not full paths)
+     * @throws Error if directory doesn't exist or cannot be read
+     */
+    async readdir(dirPath) {
+        try {
+            return await promises_1.default.readdir(dirPath);
+        }
+        catch (error) {
+            throw new Error(`Failed to read directory ${dirPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Get file/directory stats.
+     *
+     * @param filePath - Absolute path to file or directory
+     * @returns Stats object with isDirectory, size, mtime
+     * @throws Error if path doesn't exist or cannot be accessed
+     */
+    async stat(filePath) {
+        try {
+            const stats = await promises_1.default.stat(filePath);
+            return {
+                isDirectory: stats.isDirectory(),
+                size: stats.size,
+                mtime: stats.mtimeMs
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to stat ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Remove file.
+     *
+     * @param filePath - Absolute path to file
+     * @throws Error if file doesn't exist or cannot be deleted
+     */
+    async remove(filePath) {
+        try {
+            await promises_1.default.unlink(filePath);
+        }
+        catch (error) {
+            throw new Error(`Failed to remove file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Rename or move file.
+     *
+     * @param oldPath - Current absolute path
+     * @param newPath - New absolute path
+     * @throws Error if operation fails
+     */
+    async rename(oldPath, newPath) {
+        try {
+            // Ensure destination directory exists
+            const dir = node_path_1.default.dirname(newPath);
+            await this.mkdir(dir);
+            await promises_1.default.rename(oldPath, newPath);
+        }
+        catch (error) {
+            throw new Error(`Failed to rename ${oldPath} to ${newPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Create directory.
+     * Creates parent directories if they don't exist.
+     *
+     * @param dirPath - Absolute path to directory
+     * @throws Error if creation fails
+     */
+    async mkdir(dirPath) {
+        try {
+            await promises_1.default.mkdir(dirPath, { recursive: true });
+        }
+        catch (error) {
+            throw new Error(`Failed to create directory ${dirPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Remove directory.
+     *
+     * @param dirPath - Absolute path to directory
+     * @param options - Options (recursive: delete directory and contents)
+     * @throws Error if deletion fails
+     */
+    async rmdir(dirPath, options) {
+        try {
+            if (options?.recursive) {
+                await promises_1.default.rm(dirPath, { recursive: true, force: true });
+            }
+            else {
+                await promises_1.default.rmdir(dirPath);
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to remove directory ${dirPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+exports.NodeFsProvider = NodeFsProvider;
+/**
+ * Synchronous filesystem operations.
+ *
+ * Use sparingly — async operations are preferred.
+ * Useful for initialization code that must be synchronous.
+ */
+class NodeFsProviderSync {
+    /**
+     * Check if file or directory exists (synchronous).
+     *
+     * @param filePath - Absolute path to check
+     * @returns True if exists
+     */
+    existsSync(filePath) {
+        try {
+            node_fs_1.default.accessSync(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Read file contents (synchronous).
+     *
+     * @param filePath - Absolute path to file
+     * @returns File content as string
+     * @throws Error if file doesn't exist or cannot be read
+     */
+    readSync(filePath) {
+        try {
+            return node_fs_1.default.readFileSync(filePath, 'utf-8');
+        }
+        catch (error) {
+            throw new Error(`Failed to read file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Write file contents (synchronous).
+     *
+     * @param filePath - Absolute path to file
+     * @param content - Content to write
+     * @throws Error if write fails
+     */
+    writeSync(filePath, content) {
+        try {
+            // Ensure parent directory exists
+            const dir = node_path_1.default.dirname(filePath);
+            this.mkdirSync(dir);
+            node_fs_1.default.writeFileSync(filePath, content, 'utf-8');
+        }
+        catch (error) {
+            throw new Error(`Failed to write file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Create directory (synchronous).
+     *
+     * @param dirPath - Absolute path to directory
+     * @throws Error if creation fails
+     */
+    mkdirSync(dirPath) {
+        try {
+            node_fs_1.default.mkdirSync(dirPath, { recursive: true });
+        }
+        catch (error) {
+            throw new Error(`Failed to create directory ${dirPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+exports.NodeFsProviderSync = NodeFsProviderSync;
+/**
+ * Default export: async provider instance.
+ */
+exports.default = new NodeFsProvider();
+//# sourceMappingURL=NodeFsProvider.js.map

package/dist/storage/NodeFsProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeFsProvider.js","sourceRoot":"","sources":["../../src/storage/NodeFsProvider.ts"],"names":[],"mappings":"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"}

package/dist/types/annotation.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Annotation metadata storage types.
+ *
+ * Supports two types of annotations:
+ * 1. Inline - found in file content by parser
+ * 2. Meta - attached externally via annotate operation
+ */
+/**
+ * Annotation type categories.
+ */
+export type AnnotationType = 'policy' | 'warning' | 'note' | 'gate' | 'contract' | 'systempolicy';
+/**
+ * Annotation severity levels.
+ */
+export type AnnotationSeverity = 'info' | 'warning' | 'error' | 'critical';
+/**
+ * Source of an annotation.
+ */
+export type AnnotationSource = 'inline' | 'meta';
+/**
+ * Single annotation entry.
+ */
+export interface Annotation {
+    /** Annotation type */
+    type: AnnotationType;
+    /** Annotation text content */
+    text: string;
+    /** Optional severity level */
+    severity?: AnnotationSeverity;
+    /** Line number in file (only for inline annotations) */
+    line?: number;
+    /** Column number in file (only for inline annotations) */
+    column?: number;
+    /** Timestamp when attached (only for meta annotations) */
+    attachedAt?: string;
+    /** Source of this annotation */
+    source: AnnotationSource;
+}
+/**
+ * Annotation set for a file (both inline and meta).
+ */
+export interface AnnotationSet {
+    /** Annotations found in file content by parser */
+    inline: Annotation[];
+    /** Annotations attached externally as metadata */
+    meta: Annotation[];
+}
+/**
+ * Annotation database structure.
+ *
+ * Maps file paths to their annotation sets.
+ */
+export interface AnnotationDatabase {
+    [filePath: string]: AnnotationSet;
+}
+/**
+ * Parameters for attaching annotations to a file.
+ */
+export interface AttachAnnotationsParams {
+    /** Target file path */
+    target: string;
+    /** Annotation strings to attach (e.g., "@codemap.policy This is a rule") */
+    annotations: string[];
+}
+/**
+ * Result of attaching annotations.
+ */
+export interface AttachAnnotationsResult {
+    ok: boolean;
+    /** Target file path */
+    target: string;
+    /** Number of annotations successfully attached */
+    attached: number;
+    /** Total annotations now on this file (inline + meta) */
+    totalAnnotations: number;
+    /** Error message if operation failed */
+    error?: string;
+}
+//# sourceMappingURL=annotation.d.ts.map

package/dist/types/annotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation.d.ts","sourceRoot":"","sources":["../../src/types/annotation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,SAAS,GACT,MAAM,GACN,MAAM,GACN,UAAU,GACV,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAE3E;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,QAAQ,GACR,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,sBAAsB;IACtB,IAAI,EAAE,cAAc,CAAC;IAErB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IAEb,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAE9B,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,gCAAgC;IAChC,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,MAAM,EAAE,UAAU,EAAE,CAAC;IAErB,kDAAkD;IAClD,IAAI,EAAE,UAAU,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IAEf,4EAA4E;IAC5E,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IAEZ,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IAEf,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IAEjB,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;IAEzB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/types/annotation.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Annotation metadata storage types.
+ *
+ * Supports two types of annotations:
+ * 1. Inline - found in file content by parser
+ * 2. Meta - attached externally via annotate operation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=annotation.js.map

package/dist/types/annotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation.js","sourceRoot":"","sources":["../../src/types/annotation.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}