@sudocode-ai/cli 0.1.16 → 0.1.18-dev.0

package/dist/git-merge.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Git Merge-File Wrapper
+ *
+ * Wrapper around `git merge-file` command for three-way merging of YAML content.
+ * Enables git's native three-way merge algorithm to work on YAML representations.
+ *
+ * Security: Uses execFile (not exec) to prevent shell injection vulnerabilities.
+ */
+/**
+ * Result of a merge operation
+ */
+export interface MergeResult {
+    /** Whether the merge completed without conflicts */
+    success: boolean;
+    /** The merged content (may include conflict markers if success=false) */
+    content: string;
+    /** Whether conflicts were detected */
+    hasConflicts: boolean;
+}
+/**
+ * Three-way merge input versions
+ */
+export interface MergeInput {
+    /** Base version (common ancestor) */
+    base: string;
+    /** Our version (current/local changes) */
+    ours: string;
+    /** Their version (incoming changes) */
+    theirs: string;
+}
+/**
+ * Perform three-way merge using git merge-file
+ *
+ * This function wraps the `git merge-file` command to provide three-way merging
+ * of YAML content. It creates temporary files for the merge operation and cleans
+ * them up afterwards.
+ *
+ * Security: Uses execFileSync with array arguments to prevent shell injection.
+ *
+ * Git merge-file exit codes:
+ * - 0: Clean merge, no conflicts
+ * - 1: Conflicts detected (most common, merge produces output with conflict markers)
+ * - 2+: Can indicate conflicts OR fatal errors
+ *
+ * Strategy: If git produced output (file exists and has content), treat as conflict
+ * scenario regardless of exit code. Only throw if no output was produced.
+ *
+ * @param input - The three versions to merge (base, ours, theirs)
+ * @returns MergeResult - The merge result with success status and content
+ * @throws Error if git command fails fatally (no output produced)
+ *
+ * @example
+ * ```typescript
+ * const result = mergeYamlContent({
+ *   base: 'title: Original\nstatus: open',
+ *   ours: 'title: Updated\nstatus: open',
+ *   theirs: 'title: Original\nstatus: closed'
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Clean merge:', result.content);
+ * } else {
+ *   console.log('Conflicts detected:', result.content);
+ * }
+ * ```
+ */
+export declare function mergeYamlContent(input: MergeInput): MergeResult;
+/**
+ * Read content from a specific git index stage
+ *
+ * During a merge conflict, git maintains three versions in the index:
+ * - Stage 1: Base version (common ancestor)
+ * - Stage 2: Ours version (current branch)
+ * - Stage 3: Theirs version (incoming branch)
+ *
+ * @param filePath - Path to the file (relative to git root or absolute)
+ * @param stage - Git stage number (1=base, 2=ours, 3=theirs)
+ * @returns File content as string, or null if stage doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const base = readGitStage('.sudocode/issues/issues.jsonl', 1);
+ * const ours = readGitStage('.sudocode/issues/issues.jsonl', 2);
+ * const theirs = readGitStage('.sudocode/issues/issues.jsonl', 3);
+ * ```
+ */
+export declare function readGitStage(filePath: string, stage: 1 | 2 | 3): string | null;
+//# sourceMappingURL=git-merge.d.ts.map

package/dist/git-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-merge.d.ts","sourceRoot":"","sources":["../src/git-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAkG/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,GAAG,IAAI,CAiE9E"}

package/dist/git-merge.js

@@ -0,0 +1,214 @@
+/**
+ * Git Merge-File Wrapper
+ *
+ * Wrapper around `git merge-file` command for three-way merging of YAML content.
+ * Enables git's native three-way merge algorithm to work on YAML representations.
+ *
+ * Security: Uses execFile (not exec) to prevent shell injection vulnerabilities.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+/**
+ * Perform three-way merge using git merge-file
+ *
+ * This function wraps the `git merge-file` command to provide three-way merging
+ * of YAML content. It creates temporary files for the merge operation and cleans
+ * them up afterwards.
+ *
+ * Security: Uses execFileSync with array arguments to prevent shell injection.
+ *
+ * Git merge-file exit codes:
+ * - 0: Clean merge, no conflicts
+ * - 1: Conflicts detected (most common, merge produces output with conflict markers)
+ * - 2+: Can indicate conflicts OR fatal errors
+ *
+ * Strategy: If git produced output (file exists and has content), treat as conflict
+ * scenario regardless of exit code. Only throw if no output was produced.
+ *
+ * @param input - The three versions to merge (base, ours, theirs)
+ * @returns MergeResult - The merge result with success status and content
+ * @throws Error if git command fails fatally (no output produced)
+ *
+ * @example
+ * ```typescript
+ * const result = mergeYamlContent({
+ *   base: 'title: Original\nstatus: open',
+ *   ours: 'title: Updated\nstatus: open',
+ *   theirs: 'title: Original\nstatus: closed'
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Clean merge:', result.content);
+ * } else {
+ *   console.log('Conflicts detected:', result.content);
+ * }
+ * ```
+ */
+export function mergeYamlContent(input) {
+    // Create temporary directory for merge files
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'git-merge-'));
+    // Temp file paths
+    const basePath = path.join(tmpDir, 'base.yaml');
+    const oursPath = path.join(tmpDir, 'ours.yaml');
+    const theirsPath = path.join(tmpDir, 'theirs.yaml');
+    // Track whether base is empty (simulated 3-way merge)
+    const baseIsEmpty = input.base.length === 0;
+    try {
+        // Write content to temp files
+        fs.writeFileSync(basePath, input.base, 'utf8');
+        fs.writeFileSync(oursPath, input.ours, 'utf8');
+        fs.writeFileSync(theirsPath, input.theirs, 'utf8');
+        // Execute git merge-file using execFileSync (safe from shell injection)
+        try {
+            execFileSync('git', ['merge-file', oursPath, basePath, theirsPath], {
+                encoding: 'utf8',
+            });
+            // Exit code 0 means clean merge
+            const mergedContent = fs.readFileSync(oursPath, 'utf8');
+            return {
+                success: true,
+                content: mergedContent,
+                hasConflicts: false,
+            };
+        }
+        catch (error) {
+            // Git merge-file exit codes:
+            // - 0: Clean merge (handled above, no error thrown)
+            // - 1: Conflicts detected (most common)
+            // - 2+: Can indicate conflicts OR fatal errors
+            //
+            // Strategy: If git produced output (file exists and has content),
+            // treat as conflict scenario regardless of exit code.
+            // Only throw if no output was produced (indicates real error).
+            const exitCode = error.status || error.code || 'unknown';
+            // Debug: log what we got
+            if (process.env.DEBUG_GIT_MERGE) {
+                console.log('Git merge-file error:', {
+                    status: error.status,
+                    code: error.code,
+                    baseIsEmpty,
+                    stderr: error.stderr?.toString(),
+                    stdout: error.stdout?.toString(),
+                });
+            }
+            // Try to read the output file - if it has content, this is a conflict scenario
+            if (error.status > 0) {
+                try {
+                    const mergedContent = fs.readFileSync(oursPath, 'utf8');
+                    // Validate that git produced output (not a real error)
+                    if (mergedContent.length > 0) {
+                        return {
+                            success: false,
+                            content: mergedContent,
+                            hasConflicts: true,
+                        };
+                    }
+                    // If no output, this is likely a real error - fall through to throw
+                }
+                catch (readError) {
+                    // File read failed - fall through to throw with details
+                    const stderr = error.stderr?.toString().trim();
+                    const stdout = error.stdout?.toString().trim();
+                    const errorDetails = stderr || stdout || error.message || 'Unknown error';
+                    throw new Error(`Git merge-file command failed (exit code ${exitCode}, baseIsEmpty=${baseIsEmpty}, fileExists=${fs.existsSync(oursPath)}, readError=${readError}): ${errorDetails}`);
+                }
+            }
+            // No exit code or negative exit code means a fatal error occurred
+            // Include stderr output which contains the actual git error message
+            const stderr = error.stderr?.toString().trim();
+            const stdout = error.stdout?.toString().trim();
+            const errorDetails = stderr || stdout || error.message || 'Unknown error';
+            throw new Error(`Git merge-file command failed (status=${error.status}, code=${error.code}, exitCode=${exitCode}, baseIsEmpty=${baseIsEmpty}, baseLength=${input.base.length}, oursLength=${input.ours.length}, theirsLength=${input.theirs.length}): ${errorDetails}`);
+        }
+    }
+    finally {
+        // Clean up temp files and directory
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch (cleanupError) {
+            // Log cleanup errors but don't throw
+            console.error('Warning: Failed to clean up temp files:', cleanupError);
+        }
+    }
+}
+/**
+ * Read content from a specific git index stage
+ *
+ * During a merge conflict, git maintains three versions in the index:
+ * - Stage 1: Base version (common ancestor)
+ * - Stage 2: Ours version (current branch)
+ * - Stage 3: Theirs version (incoming branch)
+ *
+ * @param filePath - Path to the file (relative to git root or absolute)
+ * @param stage - Git stage number (1=base, 2=ours, 3=theirs)
+ * @returns File content as string, or null if stage doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const base = readGitStage('.sudocode/issues/issues.jsonl', 1);
+ * const ours = readGitStage('.sudocode/issues/issues.jsonl', 2);
+ * const theirs = readGitStage('.sudocode/issues/issues.jsonl', 3);
+ * ```
+ */
+export function readGitStage(filePath, stage) {
+    try {
+        // Convert absolute path to relative path from repo root
+        let relativePath = filePath;
+        if (path.isAbsolute(filePath)) {
+            const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            relativePath = path.relative(repoRoot, filePath);
+        }
+        // Use git checkout-index to extract stage to temp file
+        // This avoids buffer size limits by having git write directly to disk
+        // Format: "tempfile\tpath" (tempfile is relative to repo root)
+        const output = execFileSync('git', ['checkout-index', `--stage=${stage}`, '--temp', relativePath], {
+            encoding: 'utf8',
+            cwd: path.isAbsolute(filePath)
+                ? execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim()
+                : undefined,
+        }).trim();
+        // Parse output: "tempfile\toriginalpath"
+        const [tempFile] = output.split('\t');
+        if (!tempFile) {
+            return null;
+        }
+        // Get repo root to resolve temp file path (git outputs relative to repo root)
+        const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            encoding: 'utf8',
+        }).trim();
+        const tempFilePath = path.join(repoRoot, tempFile);
+        try {
+            // Read content from git's temp file
+            const content = fs.readFileSync(tempFilePath, 'utf8');
+            return content;
+        }
+        finally {
+            // Always clean up the temp file git created
+            try {
+                fs.unlinkSync(tempFilePath);
+            }
+            catch (unlinkError) {
+                // Best effort cleanup - don't fail if file already gone
+                if (process.env.DEBUG_GIT_MERGE) {
+                    console.warn('Warning: Failed to clean up temp file:', unlinkError);
+                }
+            }
+        }
+    }
+    catch (error) {
+        // Stage doesn't exist (e.g., file added in one branch, deleted in another)
+        // This is expected and not an error
+        if (error.status === 128 || error.status === 1) {
+            return null;
+        }
+        // Re-throw unexpected errors
+        throw new Error(`Failed to read git stage ${stage} for ${filePath}: ${error.message}`);
+    }
+}
+//# sourceMappingURL=git-merge.js.map

package/dist/git-merge.js.map

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

package/dist/index.d.ts

@@ -12,4 +12,6 @@ export * from "./markdown.js";
 export * from "./sync.js";
 export * from "./id-generator.js";
 export * from "./config.js";
+export * from "./yaml-converter.js";
+export * from "./yaml-conflict-resolver.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC"}

package/dist/index.js

@@ -12,4 +12,6 @@ export * from "./markdown.js";
 export * from "./sync.js";
 export * from "./id-generator.js";
 export * from "./config.js";
+export * from "./yaml-converter.js";
+export * from "./yaml-conflict-resolver.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC"}

package/dist/merge-resolver.d.ts

@@ -70,16 +70,88 @@ export declare function hasGitConflictMarkers(filePath: string): boolean;
 export declare function parseMergeConflictFile(content: string): ConflictSection[];
 /**
  * Merge metadata from multiple versions of same entity
+ *
+ * USE FOR: Two-way merge scenarios (manual conflict resolution)
+ * Merges both array fields (union) and scalar fields (latest-wins)
  */
 export declare function mergeMetadata<T extends JSONLEntity>(entities: T[]): T;
+/**
+ * Merge ONLY array fields from multiple versions (union semantics)
+ *
+ * USE FOR: Three-way merge scenarios (git merge driver)
+ * Only merges array fields (relationships, tags, feedback)
+ * Scalar fields (status, priority, title, etc.) are NOT merged
+ *
+ * This allows git merge-file to see actual differences in scalar fields
+ * for proper three-way merge semantics.
+ */
+export declare function mergeArrayFields<T extends JSONLEntity>(entities: T[]): Partial<T>;
+/**
+ * Resolve git conflict markers in YAML content using latest-wins per block
+ *
+ * When git merge-file produces conflicts in YAML, this function resolves
+ * each conflict block individually while preserving cleanly merged sections.
+ *
+ * @param yamlWithConflicts - YAML content containing git conflict markers
+ * @param useOurs - If true, use "ours" side for conflicts; if false, use "theirs"
+ * @returns Resolved YAML content without conflict markers
+ *
+ * @example
+ * ```typescript
+ * const yaml = `title: test
+ * <<<<<<< ours
+ * content: ours text
+ * =======
+ * content: theirs text
+ * >>>>>>> theirs
+ * priority: 3`;
+ *
+ * const resolved = resolveYamlConflicts(yaml, true);
+ * // Returns: "title: test\ncontent: ours text\npriority: 3"
+ * ```
+ */
+export declare function resolveYamlConflicts(yamlWithConflicts: string, useOurs: boolean): string;
 /**
  * Resolve all entities using UUID-based deduplication
  * Handles different UUIDs, same UUID conflicts, and metadata merging
+ *
+ * USE CASE: TWO-WAY MERGE
+ * - Manual conflict resolution (sudocode resolve-conflicts)
+ * - Conflicts already isolated by git conflict markers
+ * - No base version available (git index cleared after conflict)
+ * - Simple UUID deduplication is sufficient and faster
+ * - No benefit from YAML expansion overhead
+ *
+ * DO NOT USE FOR: Three-way merge with base/ours/theirs
+ * For that case, use mergeThreeWay() instead.
  */
 export declare function resolveEntities<T extends JSONLEntity>(entities: T[], options?: ResolveOptions): ResolvedResult<T>;
 /**
  * Three-way merge for git merge driver
- * Merges base, ours, and theirs versions
+ * Uses hybrid approach: field-level merge for scalars + line-level merge for multi-line text
+ *
+ * USE CASE: THREE-WAY MERGE
+ * - Git merge driver operations (automatic merge)
+ * - Worktree sync with true base/ours/theirs versions
+ * - Field-level merging preserves changes from either branch
+ *
+ * DO NOT USE FOR: Manual conflict resolution (use resolveEntities)
+ *
+ * This function implements true three-way merge semantics:
+ * 1. Group entities by UUID across base/ours/theirs
+ * 2. Handle deletion cases (modification wins over deletion)
+ * 3. Merge array fields FIRST (tags, relationships, feedback) with union semantics
+ * 4. Field-level three-way merge for SCALAR fields only (status, priority, etc.)
+ * 5. YAML + git merge-file for multi-line text fields (content, description)
+ * 6. Handle ID collisions (hash conflicts with .1, .2 suffixes)
+ * 7. Sort by created_at (git-friendly)
+ *
+ * Field-level three-way merge logic:
+ * - If base == ours == theirs: use any value (no changes)
+ * - If base == ours && base != theirs: use theirs (only theirs changed)
+ * - If base == theirs && base != ours: use ours (only ours changed)
+ * - If base != ours && base != theirs && ours == theirs: use either (both made same change)
+ * - If base != ours && base != theirs && ours != theirs: conflict -> latest wins
  */
 export declare function mergeThreeWay<T extends JSONLEntity>(base: T[], ours: T[], theirs: T[]): ResolvedResult<T>;
 //# sourceMappingURL=merge-resolver.d.ts.map

package/dist/merge-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merge-resolver.d.ts","sourceRoot":"","sources":["../src/merge-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,QAAQ,EAAE,CAAC,EAAE,CAAC;IACd,KAAK,EAAE,eAAe,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,GAAG,mBAAmB,CAAC;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAW/D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE,CA0FzE;AAmCD;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,CAsDrE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,WAAW,EACnD,QAAQ,EAAE,CAAC,EAAE,EACb,OAAO,GAAE,cAAmB,GAC3B,cAAc,CAAC,CAAC,CAAC,CAuHnB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,EACjD,IAAI,EAAE,CAAC,EAAE,EACT,IAAI,EAAE,CAAC,EAAE,EACT,MAAM,EAAE,CAAC,EAAE,GACV,cAAc,CAAC,CAAC,CAAC,CAMnB"}
+{"version":3,"file":"merge-resolver.d.ts","sourceRoot":"","sources":["../src/merge-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIxD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,QAAQ,EAAE,CAAC,EAAE,CAAC;IACd,KAAK,EAAE,eAAe,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,GAAG,mBAAmB,CAAC;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAW/D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE,CA0FzE;AAmCD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,CAsDrE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAkDjF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAAC,iBAAiB,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAgBxF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,WAAW,EACnD,QAAQ,EAAE,CAAC,EAAE,EACb,OAAO,GAAE,cAAmB,GAC3B,cAAc,CAAC,CAAC,CAAC,CAuHnB;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,EACjD,IAAI,EAAE,CAAC,EAAE,EACT,IAAI,EAAE,CAAC,EAAE,EACT,MAAM,EAAE,CAAC,EAAE,GACV,cAAc,CAAC,CAAC,CAAC,CAmSnB"}