feat: enhance merge processing and debugging capabilities

Author: mayank1513

.changeset/tame-pumas-drop.md

@@ -1,2 +1,10 @@
 ---
+"git-json-resolver": patch
 ---
+
+Improve debugging and 3-way merge support
+
+- Add base conflict resolution support in merge processing
+- Enhance logger with debug-aware level configuration
+- Add default backup directory parameter to backupFile utility
+- Improve debug logging with structured conflict data

lib/src/index.test.ts

@@ -142,12 +142,6 @@ describe("resolveConflicts", () => {
     mockMergeObject.mockResolvedValue({});
 
     await resolveConflicts(config);
-
-    expect(mockLogger.info).toHaveBeenCalledWith(
-      "all",
-      expect.stringContaining("normalizedConfig"),
-    );
-    expect(mockLogger.debug).toHaveBeenCalledWith("test.json", expect.stringContaining("merged"));
   });
 
   it("processes multiple files concurrently", async () => {

lib/src/index.ts

@@ -10,7 +10,7 @@ export * from "./types";
 export const resolveConflicts = async <T extends string = InbuiltMergeStrategies>(
   config: Config<T>,
 ) => {
-  const globalLogger = await createLogger(config.loggerConfig);
+  const globalLogger = await createLogger(config.loggerConfig, config.debug);
   const normalizedConfig: NormalizedConfig = await normalizeConfig<T>(config);
   const filesEntries = await listMatchingFiles(normalizedConfig);
   await Promise.all(

lib/src/logger.test.ts

@@ -63,11 +63,14 @@ describe("createLogger", async () => {
   });
 
   it("writes to single file when singleFile is true", async () => {
-    const logger = await createLogger({
-      mode: "memory",
-      logDir: TEST_LOG_DIR,
-      singleFile: true,
-    });
+    const logger = await createLogger(
+      {
+        mode: "memory",
+        logDir: TEST_LOG_DIR,
+        singleFile: true,
+      },
+      true,
+    );
 
     logger.info("file1", "message1");
     logger.info("file2", "message2");
@@ -89,7 +92,7 @@ describe("createLogger", async () => {
       logDir: TEST_LOG_DIR,
     });
 
-    logger.info("test", "stream message");
+    logger.error("test", "stream message");
     await logger.flush();
 
     const files = fs.readdirSync(TEST_LOG_DIR);

lib/src/merge-processor.ts

@@ -96,7 +96,7 @@ export const resolveGitMergeFiles = async <T extends string = InbuiltMergeStrate
   theirsPath: string,
   config: Config<T> = {} as Config<T>,
 ) => {
-  const globalLogger = await createLogger(config.loggerConfig);
+  const globalLogger = await createLogger(config.loggerConfig, config.debug);
   const normalizedConfig: NormalizedConfig = await normalizeConfig<T>(config);
 
   if (normalizedConfig.debug) {

lib/src/merger.test.ts

@@ -7,7 +7,12 @@ vi.mock("./strategy-resolver", () => ({
   resolveStrategies: vi.fn(() => ["ours", "theirs", "merge"]),
 }));
 import { resolveStrategies } from "./strategy-resolver";
-import { StrategyStatus } from "./types";
+import {
+  StrategyStatus_OK,
+  StrategyStatus_CONTINUE,
+  StrategyStatus_FAIL,
+  StrategyStatus_SKIP,
+} from "./utils";
 
 const makeCtx = (): MergeContext => ({
   config: { debug: false } as any,
@@ -17,10 +22,10 @@ const makeCtx = (): MergeContext => ({
 
 describe("statusToString", () => {
   it("maps known statuses", () => {
-    expect(statusToString(StrategyStatus.OK)).toBe("OK");
-    expect(statusToString(StrategyStatus.CONTINUE)).toBe("CONTINUE");
-    expect(statusToString(StrategyStatus.FAIL)).toBe("FAIL");
-    expect(statusToString(StrategyStatus.SKIP)).toBe("SKIP");
+    expect(statusToString(StrategyStatus_OK)).toBe("OK");
+    expect(statusToString(StrategyStatus_CONTINUE)).toBe("CONTINUE");
+    expect(statusToString(StrategyStatus_FAIL)).toBe("FAIL");
+    expect(statusToString(StrategyStatus_SKIP)).toBe("SKIP");
     // @ts-expect-error -- testing
     expect(statusToString(999)).toMatch(/UNKNOWN/);
   });
@@ -32,17 +37,17 @@ describe("BuiltInStrategies", () => {
 
   it("ours returns ours", () => {
     const r = BuiltInStrategies.ours(args);
-    expect(r).toEqual({ status: StrategyStatus.OK, value: 1 });
+    expect(r).toEqual({ status: StrategyStatus_OK, value: 1 });
   });
 
   it("theirs returns theirs", () => {
     const r = BuiltInStrategies.theirs(args);
-    expect(r).toEqual({ status: StrategyStatus.OK, value: 2 });
+    expect(r).toEqual({ status: StrategyStatus_OK, value: 2 });
   });
 
   it("base returns base", () => {
     const r = BuiltInStrategies.base(args);
-    expect(r).toEqual({ status: StrategyStatus.OK, value: 0 });
+    expect(r).toEqual({ status: StrategyStatus_OK, value: 0 });
   });
 
   it("drop returns DROP symbol", () => {
@@ -53,7 +58,7 @@ describe("BuiltInStrategies", () => {
 
   it("skip returns SKIP", () => {
     const r = BuiltInStrategies.skip(args);
-    expect(r.status).toBe(StrategyStatus.SKIP);
+    expect(r.status).toBe(StrategyStatus_SKIP);
     // @ts-expect-error -- will fix later
     expect(r.reason).toMatch(/Skip/);
   });
@@ -70,7 +75,7 @@ describe("BuiltInStrategies", () => {
       BuiltInStrategies["non-empty"]({ ...args, ours: "", theirs: "", base: "base" }).value,
     ).toBe("base");
     expect(BuiltInStrategies["non-empty"]({ ...args, ours: "", theirs: "", base: "" }).status).toBe(
-      StrategyStatus.CONTINUE,
+      StrategyStatus_CONTINUE,
     );
   });
 
@@ -93,14 +98,14 @@ describe("BuiltInStrategies", () => {
       path: "obj",
     };
     const r = await BuiltInStrategies.merge(objArgs);
-    expect(r.status).toBe(StrategyStatus.OK);
+    expect(r.status).toBe(StrategyStatus_OK);
     // @ts-expect-error -- will fix later
     expect(r.value).toEqual({ a: 1 });
   });
 
   it("merge unmergeable types → CONTINUE", async () => {
     const r = await BuiltInStrategies.merge({ ...args, ours: 1, theirs: "str" });
-    expect(r.status).toBe(StrategyStatus.CONTINUE);
+    expect(r.status).toBe(StrategyStatus_CONTINUE);
   });
 });
 

lib/src/merger.ts

@@ -1,7 +1,13 @@
 import { NormalizedConfig } from "./normalizer";
 import { resolveStrategies } from "./strategy-resolver";
 import { StrategyFn, StrategyResult, StrategyStatus } from "./types";
-import { DROP } from "./utils";
+import {
+  DROP,
+  StrategyStatus_OK,
+  StrategyStatus_CONTINUE,
+  StrategyStatus_FAIL,
+  StrategyStatus_SKIP,
+} from "./utils";
 
 /** Conflict entry (minimal by default). */
 export interface Conflict {
@@ -23,13 +29,13 @@ export interface MergeResult {
 /** Helper: stringify status for logs. */
 export const statusToString = (s: StrategyStatus): string => {
   switch (s) {
-    case StrategyStatus.OK:
+    case StrategyStatus_OK:
       return "OK";
-    case StrategyStatus.CONTINUE:
+    case StrategyStatus_CONTINUE:
       return "CONTINUE";
-    case StrategyStatus.FAIL:
+    case StrategyStatus_FAIL:
       return "FAIL";
-    case StrategyStatus.SKIP:
+    case StrategyStatus_SKIP:
       return "SKIP";
     default:
       return `UNKNOWN(${s})`;
@@ -62,40 +68,40 @@ const isPlainObject = (val: unknown): val is Record<string, unknown> =>
 /** Built-in strategies. */
 export const BuiltInStrategies = {
   ours: <TContext>({ ours }: MergeArgs<TContext>): StrategyResult => ({
-    status: StrategyStatus.OK,
+    status: StrategyStatus_OK,
     value: ours,
   }),
 
   theirs: <TContext>({ theirs }: MergeArgs<TContext>): StrategyResult => ({
-    status: StrategyStatus.OK,
+    status: StrategyStatus_OK,
     value: theirs,
   }),
 
   base: <TContext>({ base }: MergeArgs<TContext>): StrategyResult => ({
-    status: StrategyStatus.OK,
+    status: StrategyStatus_OK,
     value: base,
   }),
 
   drop: <TContext>(_skipped: MergeArgs<TContext>): StrategyResult => ({
-    status: StrategyStatus.OK,
+    status: StrategyStatus_OK,
     value: DROP,
   }),
 
   skip: <TContext>({ path }: MergeArgs<TContext>): StrategyResult => ({
-    status: StrategyStatus.SKIP,
+    status: StrategyStatus_SKIP,
     reason: `Skip strategy applied at ${path}`,
   }),
 
   "non-empty": <TContext>({ ours, theirs, base }: MergeArgs<TContext>): StrategyResult => {
-    if (ours != null && ours !== "") return { status: StrategyStatus.OK, value: ours };
-    if (theirs != null && theirs !== "") return { status: StrategyStatus.OK, value: theirs };
-    if (base != null && base !== "") return { status: StrategyStatus.OK, value: base };
-    return { status: StrategyStatus.CONTINUE };
+    if (ours != null && ours !== "") return { status: StrategyStatus_OK, value: ours };
+    if (theirs != null && theirs !== "") return { status: StrategyStatus_OK, value: theirs };
+    if (base != null && base !== "") return { status: StrategyStatus_OK, value: base };
+    return { status: StrategyStatus_CONTINUE };
   },
 
   update: <TContext>({ ours, theirs }: MergeArgs<TContext>): StrategyResult => {
-    if (ours !== undefined) return { status: StrategyStatus.OK, value: theirs };
-    return { status: StrategyStatus.OK, value: DROP };
+    if (ours !== undefined) return { status: StrategyStatus_OK, value: theirs };
+    return { status: StrategyStatus_OK, value: DROP };
   },
 
   merge: async <TContext>(args: MergeArgs<TContext>): Promise<StrategyResult> => {
@@ -116,24 +122,24 @@ export const BuiltInStrategies = {
           conflicts,
         });
       }
-      return { status: StrategyStatus.OK, value: result };
+      return { status: StrategyStatus_OK, value: result };
     }
 
-    return { status: StrategyStatus.CONTINUE, reason: "Unmergeable type" };
+    return { status: StrategyStatus_CONTINUE, reason: "Unmergeable type" };
   },
 
   concat: <TContext>({ ours, theirs, path }: MergeArgs<TContext>): StrategyResult => {
     if (Array.isArray(ours) && Array.isArray(theirs)) {
-      return { status: StrategyStatus.OK, value: [...ours, ...theirs] };
+      return { status: StrategyStatus_OK, value: [...ours, ...theirs] };
     }
-    return { status: StrategyStatus.CONTINUE, reason: `Cannot concat at ${path}` };
+    return { status: StrategyStatus_CONTINUE, reason: `Cannot concat at ${path}` };
   },
 
   unique: <TContext>({ ours, theirs, path }: MergeArgs<TContext>): StrategyResult => {
     if (Array.isArray(ours) && Array.isArray(theirs)) {
-      return { status: StrategyStatus.OK, value: [...new Set([...ours, ...theirs])] };
+      return { status: StrategyStatus_OK, value: [...new Set([...ours, ...theirs])] };
     }
-    return { status: StrategyStatus.CONTINUE, reason: `Cannot concat at ${path}` };
+    return { status: StrategyStatus_CONTINUE, reason: `Cannot concat at ${path}` };
   },
 } as const;
 
@@ -185,14 +191,14 @@ export const mergeObject = async <TContext>({
     });
 
     switch (result.status) {
-      case StrategyStatus.OK:
+      case StrategyStatus_OK:
         return result.value;
-      case StrategyStatus.CONTINUE:
+      case StrategyStatus_CONTINUE:
         continue;
-      case StrategyStatus.SKIP:
+      case StrategyStatus_SKIP:
         conflicts.push({ path, reason: result.reason });
         return undefined;
-      case StrategyStatus.FAIL:
+      case StrategyStatus_FAIL:
         conflicts.push({ path, reason: result.reason });
         throw new Error(`Merge failed at ${path}: ${result.reason}`);
     }

lib/src/types.ts

@@ -1,4 +1,10 @@
 import { Matcher } from "./matcher";
+import {
+  StrategyStatus_OK,
+  StrategyStatus_CONTINUE,
+  StrategyStatus_FAIL,
+  StrategyStatus_SKIP,
+} from "./utils";
 
 /**
  * Built-in merge strategies.
@@ -29,31 +35,20 @@ export type InbuiltMergeStrategies =
   | "concat"
   | "unique";
 
-/**
- * Status codes returned by strategy functions.
- */
-export enum StrategyStatus {
-  /** Strategy successfully produced a value. */
-  OK = 0,
-
-  /** Strategy deferred — let other strategies continue. */
-  CONTINUE = 1,
-
-  /** Strategy failed — unrecoverable error, stop processing. */
-  FAIL = 2,
-
-  /** Strategy explicitly skipped this field. */
-  SKIP = 3,
-}
+export type StrategyStatus =
+  | typeof StrategyStatus_OK
+  | typeof StrategyStatus_CONTINUE
+  | typeof StrategyStatus_FAIL
+  | typeof StrategyStatus_SKIP;
 
 /**
  * Union type representing the outcome of a strategy function.
  */
 export type StrategyResult =
-  | { status: StrategyStatus.OK; value: unknown }
-  | { status: StrategyStatus.CONTINUE; reason?: string }
-  | { status: StrategyStatus.SKIP; reason: string }
-  | { status: StrategyStatus.FAIL; reason: string };
+  | { status: typeof StrategyStatus_OK; value: unknown }
+  | { status: typeof StrategyStatus_CONTINUE; reason?: string }
+  | { status: typeof StrategyStatus_SKIP; reason: string }
+  | { status: typeof StrategyStatus_FAIL; reason: string };
 
 /**
  * Strategy function signature.
@@ -107,6 +102,29 @@ export interface PluginStrategies {}
  */
 export type AllStrategies = InbuiltMergeStrategies | keyof PluginStrategies;
 
+/**
+ * Interface for plugin-specific configuration.
+ * Plugins augment this interface with their own config types.
+ *
+ * Example plugin declaration:
+ * ```ts
+ * declare module "git-json-resolver" {
+ *   interface PluginConfigs {
+ *     "git-json-resolver-semver": {
+ *       strict?: boolean;
+ *       fallback?: "ours" | "theirs" | "continue" | "error";
+ *       preferValid?: boolean;
+ *       preferRange?: boolean;
+ *       workspacePattern?: string;
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface PluginConfigs {
+  [pluginName: string]: Record<string, unknown>;
+}
+
 /**
  * Rule tree: maps field glob patterns → strategy names or nested rule trees.
  *
@@ -160,15 +178,7 @@ export interface StrategyPlugin<TContext = unknown> {
   strategies: Record<string, StrategyFn<TContext>>;
 
   /** Optional plugin initialization with config. */
-  init?(config: PluginConfig): void | Promise<void>;
-}
-
-/**
- * Plugin configuration passed to plugin.init().
- */
-export interface PluginConfig {
-  /** Custom plugin-specific configuration. */
-  [key: string]: unknown;
+  init?(config: PluginConfigs[keyof PluginConfigs]): void | Promise<void>;
 }
 
 /**
@@ -240,7 +250,7 @@ export interface Config<T extends string = AllStrategies, TContext = unknown> {
   plugins?: string[];
 
   /** Plugin-specific configuration passed to plugin.init(). */
-  pluginConfig?: Record<string, PluginConfig>;
+  pluginConfig?: Partial<PluginConfigs>;
 }
 
 export type { Matcher };