@egentica/codemap 0.1.5

package/dist/core/TargetResolver.d.ts

@@ -0,0 +1,115 @@
+/**
+ * TargetResolver - Central target resolution and formatting.
+ *
+ * The single source of truth for converting between:
+ * - Absolute file paths (Windows/Unix)
+ * - Relative paths (forward-slash)
+ * - Symbol references (relativePath$symbolName)
+ *
+ * Future extensions will support non-file targets:
+ * - Database tables/records
+ * - API endpoints
+ * - Remote resources
+ *
+ * @codemap.domain.name Target Resolution
+ * @codemap.usage Change path format conversion logic between absolute/relative formats
+ * @codemap.usage Fix path resolution bugs (relative path handling, Windows path support)
+ * @codemap.usage Add support for new target types (database records, API endpoints, remote resources)
+ * @codemap.policy This is the ONLY place that handles path format conversions.
+ * @codemap.policy All output paths must go through formatTarget().
+ * @codemap.policy FileSystemIO uses this before all operations.
+ */
+/**
+ * Path format for output.
+ */
+export type PathFormat = 'logical' | 'relative' | 'absolute';
+/**
+ * Resolved target - canonical representation.
+ * Future: may include dbTable, recordId, apiEndpoint, etc.
+ */
+export interface ResolvedTarget {
+    /** Absolute path on disk */
+    filePath: string;
+    /** Project-relative path (forward slashes) - this is the canonical identifier */
+    relativePath: string;
+    /** File extension (without dot), empty for directories */
+    extension: string;
+    /** Whether this is a directory */
+    isDirectory: boolean;
+}
+/**
+ * Parsed target with optional range.
+ */
+export interface ParsedTarget {
+    /** Base target without range */
+    target: string;
+    /** Optional line range */
+    range: {
+        start: number;
+        end: number;
+    } | null;
+}
+/**
+ * Central target resolver.
+ */
+export declare class TargetResolver {
+    private rootPath;
+    constructor(rootPath: string);
+    /**
+     * Resolve a target string to its canonical forms.
+     *
+     * Accepts:
+     * - Absolute path: `P:\Workspace\project\src\main\index.ts`
+     * - Relative path: `src/main/index.ts` or `src\main\index.ts`
+     * - Symbol reference: `src/main/index.ts$main` (relativePath$symbolName)
+     *
+     * @param target - Target string in any format
+     * @returns Resolved target with all canonical forms
+     */
+    resolve(target: string): Promise<ResolvedTarget>;
+    /**
+     * Format a resolved target for output.
+     *
+     * @param resolved - Resolved target
+     * @param format - Desired output format
+     * @returns Formatted target string
+     */
+    formatTarget(resolved: ResolvedTarget, format: PathFormat): string;
+    /**
+     * Format an absolute path directly (convenience method).
+     *
+     * @param absolutePath - Absolute file path
+     * @param format - Desired output format
+     * @returns Formatted path
+     */
+    formatPath(absolutePath: string, format: PathFormat): Promise<string>;
+    /**
+     * Extract symbol content from file content.
+     *
+     * If target contains $symbolName, extracts just that symbol's content
+     * using the symbol's position information (startLine/startCol/endLine/endCol).
+     *
+     * @param target - Original target (may contain $symbolName)
+     * @param content - Full file content
+     * @param symbols - Symbol entries from the file
+     * @returns Symbol content if $ present and symbol found, otherwise full content
+     */
+    extractSymbolContent(target: string, content: string, symbols: any[]): string;
+    /**
+     * Parse target with optional range syntax.
+     * Supports: "file.ts:10-20", "src/main/index.ts:5-10"
+     *
+     * @param target - Target with optional range
+     * @returns Parsed target and range
+     */
+    parseRange(target: string): ParsedTarget;
+    /**
+     * Convert absolute path to project-relative with forward slashes.
+     */
+    private toRelativePath;
+    /**
+     * Extract file extension without dot.
+     */
+    private extractExtension;
+}
+//# sourceMappingURL=TargetResolver.d.ts.map

package/dist/core/TargetResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TargetResolver.d.ts","sourceRoot":"","sources":["../../src/core/TargetResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9C;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ;gBAAR,QAAQ,EAAE,MAAM;IAG1B;;;;;;;;;;OAUG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAkCtD;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM;IAclE;;;;;;OAMG;IACG,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAK3E;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,MAAM;IA+C7E;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY;IA4BxC;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAIzB"}

package/dist/core/TargetResolver.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * TargetResolver - Central target resolution and formatting.
+ *
+ * The single source of truth for converting between:
+ * - Absolute file paths (Windows/Unix)
+ * - Relative paths (forward-slash)
+ * - Symbol references (relativePath$symbolName)
+ *
+ * Future extensions will support non-file targets:
+ * - Database tables/records
+ * - API endpoints
+ * - Remote resources
+ *
+ * @codemap.domain.name Target Resolution
+ * @codemap.usage Change path format conversion logic between absolute/relative formats
+ * @codemap.usage Fix path resolution bugs (relative path handling, Windows path support)
+ * @codemap.usage Add support for new target types (database records, API endpoints, remote resources)
+ * @codemap.policy This is the ONLY place that handles path format conversions.
+ * @codemap.policy All output paths must go through formatTarget().
+ * @codemap.policy FileSystemIO uses this before all operations.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TargetResolver = void 0;
+const path = __importStar(require("node:path"));
+/**
+ * Central target resolver.
+ */
+class TargetResolver {
+    rootPath;
+    constructor(rootPath) {
+        this.rootPath = rootPath;
+    }
+    /**
+     * Resolve a target string to its canonical forms.
+     *
+     * Accepts:
+     * - Absolute path: `P:\Workspace\project\src\main\index.ts`
+     * - Relative path: `src/main/index.ts` or `src\main\index.ts`
+     * - Symbol reference: `src/main/index.ts$main` (relativePath$symbolName)
+     *
+     * @param target - Target string in any format
+     * @returns Resolved target with all canonical forms
+     */
+    async resolve(target) {
+        // Check for symbol reference (relativePath$symbolName)
+        // Extract just the file path part before the $
+        const dollarIndex = target.indexOf('$');
+        const fileTarget = dollarIndex !== -1 ? target.substring(0, dollarIndex) : target;
+        let absolutePath;
+        if (path.isAbsolute(fileTarget)) {
+            // Already absolute
+            absolutePath = path.normalize(fileTarget);
+        }
+        else if (fileTarget.includes('/') || fileTarget.includes('\\')) {
+            // Relative path with slashes
+            absolutePath = path.resolve(this.rootPath, fileTarget);
+        }
+        else if (fileTarget === '.' || fileTarget === '..') {
+            // Current or parent directory
+            absolutePath = path.resolve(this.rootPath, fileTarget);
+        }
+        else {
+            // Single word - treat as relative from root
+            absolutePath = path.resolve(this.rootPath, fileTarget);
+        }
+        const relativePath = this.toRelativePath(absolutePath);
+        const extension = this.extractExtension(absolutePath);
+        const isDirectory = !extension;
+        return {
+            filePath: absolutePath,
+            relativePath,
+            extension,
+            isDirectory
+        };
+    }
+    /**
+     * Format a resolved target for output.
+     *
+     * @param resolved - Resolved target
+     * @param format - Desired output format
+     * @returns Formatted target string
+     */
+    formatTarget(resolved, format) {
+        switch (format) {
+            case 'logical':
+                // Legacy support - logical format now returns relativePath
+                return resolved.relativePath;
+            case 'relative':
+                return resolved.relativePath;
+            case 'absolute':
+                return resolved.filePath;
+            default:
+                return resolved.relativePath;
+        }
+    }
+    /**
+     * Format an absolute path directly (convenience method).
+     *
+     * @param absolutePath - Absolute file path
+     * @param format - Desired output format
+     * @returns Formatted path
+     */
+    async formatPath(absolutePath, format) {
+        const resolved = await this.resolve(absolutePath);
+        return this.formatTarget(resolved, format);
+    }
+    /**
+     * Extract symbol content from file content.
+     *
+     * If target contains $symbolName, extracts just that symbol's content
+     * using the symbol's position information (startLine/startCol/endLine/endCol).
+     *
+     * @param target - Original target (may contain $symbolName)
+     * @param content - Full file content
+     * @param symbols - Symbol entries from the file
+     * @returns Symbol content if $ present and symbol found, otherwise full content
+     */
+    extractSymbolContent(target, content, symbols) {
+        const dollarIndex = target.indexOf('$');
+        if (dollarIndex === -1) {
+            // No symbol reference, return full content
+            return content;
+        }
+        const symbolName = target.substring(dollarIndex + 1);
+        const symbol = symbols?.find(s => s.name === symbolName);
+        if (!symbol) {
+            throw new Error(`Symbol '${symbolName}' not found in file`);
+        }
+        // Use new column tracking fields (with fallback to deprecated fields)
+        const startLine = (symbol.startLine ?? symbol.line ?? 1) - 1; // Convert to 0-indexed
+        const startCol = symbol.startCol ?? 0;
+        const endLine = (symbol.endLine ?? symbol.bodyEnd ?? startLine + 1) - 1; // Convert to 0-indexed
+        const endCol = symbol.endCol ?? 0;
+        const lines = content.split('\n');
+        // Extract line range
+        if (startLine === endLine) {
+            // Single line symbol
+            return lines[startLine].substring(startCol, endCol + 1);
+        }
+        // Multi-line symbol
+        const symbolLines = [];
+        // First line (from startCol to end)
+        symbolLines.push(lines[startLine].substring(startCol));
+        // Middle lines (full lines)
+        for (let i = startLine + 1; i < endLine; i++) {
+            symbolLines.push(lines[i]);
+        }
+        // Last line (from start to endCol)
+        if (endLine < lines.length) {
+            symbolLines.push(lines[endLine].substring(0, endCol + 1));
+        }
+        return symbolLines.join('\n');
+    }
+    /**
+     * Parse target with optional range syntax.
+     * Supports: "file.ts:10-20", "src/main/index.ts:5-10"
+     *
+     * @param target - Target with optional range
+     * @returns Parsed target and range
+     */
+    parseRange(target) {
+        const lastColon = target.lastIndexOf(':');
+        // No colon or colon is part of Windows path (e.g., "C:\...")
+        if (lastColon === -1 || lastColon === 1) {
+            return { target, range: null };
+        }
+        const beforeColon = target.slice(0, lastColon);
+        const afterColon = target.slice(lastColon + 1);
+        // Check if afterColon is a valid range (N-M format)
+        const rangeMatch = afterColon.match(/^(\d+)-(\d+)$/);
+        if (!rangeMatch) {
+            return { target, range: null };
+        }
+        const start = parseInt(rangeMatch[1], 10);
+        const end = parseInt(rangeMatch[2], 10);
+        return {
+            target: beforeColon,
+            range: { start, end }
+        };
+    }
+    // ── Internal Helpers ─────────────────────────────────────────────────────
+    /**
+     * Convert absolute path to project-relative with forward slashes.
+     */
+    toRelativePath(absolutePath) {
+        const normalized = path.normalize(absolutePath);
+        const normalizedRoot = path.normalize(this.rootPath);
+        if (normalized.startsWith(normalizedRoot)) {
+            const rel = normalized.slice(normalizedRoot.length);
+            return rel.replace(/^[\\\/]+/, '').replace(/\\/g, '/');
+        }
+        return normalized.replace(/\\/g, '/');
+    }
+    /**
+     * Extract file extension without dot.
+     */
+    extractExtension(filePath) {
+        const ext = path.extname(filePath);
+        return ext ? ext.slice(1) : '';
+    }
+}
+exports.TargetResolver = TargetResolver;
+//# sourceMappingURL=TargetResolver.js.map

package/dist/core/TargetResolver.js.map

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

package/dist/core/WriteSafetyGuard.d.ts

@@ -0,0 +1,101 @@
+/**
+ * WriteSafetyGuard — File Write Protection Layer
+ *
+ * Provides 5 critical safety guarantees for all write operations:
+ *
+ * 1. **Pre-Write Snapshot + Rollback**: Always recoverable from failures
+ * 2. **Fragment Detection**: No partial/corrupt code fragments
+ * 3. **Targeting Verification**: Ensure replace operations match correctly
+ * 4. **Atomic Writes**: Write succeeds completely or fails cleanly
+ * 5. **Write Locks**: No concurrent writes to same file
+ *
+ * @codemap.domain.name Write Safety
+ * @codemap.domain.relevance 1.0
+ * @codemap.domain.message File write protection with snapshot/rollback, fragment validation, atomic writes, and write locks.
+ * @codemap.tags FileSystem,Safety,WriteProtection,Atomicity,Rollback
+ * @codemap.usage ensure safe writes → use guard.safeWrite() instead of provider.write()
+ * @codemap.usage validate write target → use guard.verifyReplaceTarget() before replace operations
+ * @codemap.warning Rollback uses in-memory snapshot - large files may consume memory
+ * @codemap.note All write operations should flow through safeWrite() for protection
+ */
+import type { FileSystemProvider } from '../types/contracts/FileSystemProvider';
+/**
+ * Write operation result with safety metadata.
+ */
+export interface SafeWriteResult {
+    success: boolean;
+    path: string;
+    originalContent?: string;
+    error?: string;
+    verificationPassed: boolean;
+}
+/**
+ * Replace operation verification.
+ */
+export interface ReplaceVerification {
+    found: boolean;
+    matches: number;
+    context?: string;
+    lineNumber?: number;
+}
+/**
+ * WriteSafetyGuard implements all write safety guarantees.
+ *
+ * @codemap.usage const guard = new WriteSafetyGuard(fsProvider);
+ * @codemap.usage const result = await guard.safeWrite('file.ts', content);
+ */
+export declare class WriteSafetyGuard {
+    private provider;
+    private writeLocks;
+    constructor(provider: FileSystemProvider);
+    /**
+     * Safely write content with automatic rollback on failure.
+     *
+     * Flow:
+     * 1. Snapshot original (if file exists)
+     * 2. Attempt write
+     * 3. Verify written content matches intended
+     * 4. If verification fails → rollback to snapshot
+     *
+     * @param path - Target file path
+     * @param content - New content to write
+     * @returns Write result with verification status
+     */
+    safeWrite(path: string, content: string): Promise<SafeWriteResult>;
+    /**
+     * Verify that a replace operation will match correctly.
+     * Returns context around the match for user confirmation.
+     *
+     * @param path - File to search
+     * @param oldString - String to find
+     * @returns Verification result with context
+     */
+    verifyReplaceTarget(path: string, oldString: string): Promise<ReplaceVerification>;
+    /**
+     * Write to temp file first, then rename for atomicity.
+     * Either succeeds completely or fails cleanly.
+     *
+     * @param path - Target file path
+     * @param content - Content to write
+     */
+    private atomicWrite;
+    /**
+     * Acquire write lock for a file.
+     * Waits if file is already locked.
+     */
+    private acquireWriteLock;
+    /**
+     * Release write lock for a file.
+     */
+    private releaseWriteLock;
+    /**
+     * Replace text in file with safety guarantees.
+     *
+     * @param path - File path
+     * @param oldString - Text to find (must be unique)
+     * @param newString - Replacement text
+     * @returns Write result
+     */
+    safeReplace(path: string, oldString: string, newString: string): Promise<SafeWriteResult>;
+}
+//# sourceMappingURL=WriteSafetyGuard.d.ts.map

package/dist/core/WriteSafetyGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WriteSafetyGuard.d.ts","sourceRoot":"","sources":["../../src/core/WriteSafetyGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,UAAU,CAA6B;gBAEnC,QAAQ,EAAE,kBAAkB;IAOxC;;;;;;;;;;;;OAYG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAmGxE;;;;;;;OAOG;IACG,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA+BxF;;;;;;OAMG;YACW,WAAW;IA6BzB;;;OAGG;YACW,gBAAgB;IAiB9B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;;;;;;OAOG;IACG,WAAW,CACf,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,CAAC;CA4B5B"}