Update matcher to support escape

Author: mayank1513

lib/src/matcher.test.ts

@@ -17,6 +17,7 @@ describe("basicMatcher", () => {
     expect(basicMatcher.isMatch("a.b.c", ["a.**"])).toBe(true);
     expect(basicMatcher.isMatch("a.b.c.d", ["a.**.d"])).toBe(true);
     expect(basicMatcher.isMatch("a.b.c.d", ["**.d"])).toBe(true);
+    expect(basicMatcher.isMatch("a.b.c.d", ["*.d"])).toBe(false);
     expect(basicMatcher.isMatch("a.b.c", ["**"])).toBe(true);
   });
 
@@ -34,6 +35,16 @@ describe("basicMatcher", () => {
   it("handles empty patterns", () => {
     expect(basicMatcher.isMatch("foo.bar", [])).toBe(false);
   });
+
+  it("respects escapes", () => {
+    expect(basicMatcher.isMatch("foo.helloWorld", ["foo.hello*"])).toBe(true);
+    expect(basicMatcher.isMatch("foo.helloWorld", ["foo.hello\\*"])).toBe(false);
+    expect(basicMatcher.isMatch("foo.hello*", ["foo.hello\\*"])).toBe(true);
+
+    expect(basicMatcher.isMatch("a.b.c", ["a.**"])).toBe(true);
+    expect(basicMatcher.isMatch("a.b.c", ["a.\\*\\*"])).toBe(false);
+    expect(basicMatcher.isMatch("a.**", ["a.\\*\\*"])).toBe(true);
+  });
 });
 
 describe("loadMatcher", () => {
@@ -56,7 +67,7 @@ describe("loadMatcher", () => {
 
   it("loads picomatch when available", () => {
     const pm = loadMatcher("picomatch");
-    expect(pm.isMatch("ok", ["ok*"])).toBe(true);
+    expect(pm.isMatch("okmyfield", ["ok*"])).toBe(true);
     expect(pm.isMatch("fail", ["pattern"])).toBe(false);
   });
 

lib/src/matcher.ts

@@ -1,13 +1,13 @@
 /**
  * Matcher abstraction + adapters for micromatch/picomatch (optional).
  *
- * By default, a minimal matcher is used that understands:
+ * Default matcher understands:
  * - `*`   → matches any single field segment
  * - `**`  → matches any number of nested field segments
- * - Literal prefix/suffix globs like `prefix-*` or `*-suffix`
+ * - Prefix/suffix like `prefix-*`, `*-suffix`
+ * - Backslash escaping (micromatch-style): `a\.b` → literal dot, `\*` → literal asterisk
  *
- * Micromatch or Picomatch can be loaded at runtime if available,
- * but they are treated as optional peer dependencies.
+ * Micromatch/Picomatch can be loaded at runtime as optional peers.
  */
 
 export interface Matcher {
@@ -19,45 +19,64 @@ export interface Matcher {
 
 /**
  * Minimal homegrown matcher (default).
- * Only supports `*` and `**` operators on dot-paths.
+ * Supports:
+ * - `*`   → matches any single field segment
+ * - `**`  → matches any number of nested field segments
+ * - Literal prefix/suffix like `prefix-*`, `*-suffix`
+ * - Backslash escaping for `*` and `.`
  */
 export const basicMatcher: Matcher = {
-  isMatch: (str, patterns) => {
-    return patterns.some(pattern => matchOne(str, pattern));
-  },
+  isMatch: (str, patterns) => patterns.some(p => matchOne(str, p)),
 };
 
 /**
  * Attempts to load a named matcher adapter.
  * @param name `"micromatch" | "picomatch"`
  * @returns A Matcher implementation.
  */
+
 export const loadMatcher = (name: "micromatch" | "picomatch"): Matcher => {
   if (name === "micromatch") {
+    let micromatch: any;
     try {
-      const micromatch = require("micromatch");
-      return { isMatch: (str, pats) => micromatch.isMatch(str, pats) };
+      micromatch = require("micromatch");
     } catch {
       throw new Error(
         `micromatch is not installed. Please add it as a dependency if you want to use it.`,
       );
     }
+
+    return {
+      isMatch: (str, pats) => {
+        try {
+          return micromatch.isMatch(str, pats);
+        } catch (err) {
+          throw new Error(`micromatch failed to run isMatch: ${(err as Error).message}`);
+        }
+      },
+    };
   }
 
   if (name === "picomatch") {
+    let picomatch: any;
     try {
-      const picomatch = require("picomatch");
-      return {
-        isMatch: (str, pats) => {
-          const fn = picomatch(pats);
-          return fn(str);
-        },
-      };
+      picomatch = require("picomatch");
     } catch {
       throw new Error(
         `picomatch is not installed. Please add it as a dependency if you want to use it.`,
       );
     }
+
+    return {
+      isMatch: (str, pats) => {
+        try {
+          const fn = picomatch(pats);
+          return fn(str);
+        } catch (err) {
+          throw new Error(`picomatch failed to run isMatch: ${(err as Error).message}`);
+        }
+      },
+    };
   }
 
   throw new Error(`Unknown matcher name: ${name}`);
@@ -66,29 +85,55 @@ export const loadMatcher = (name: "micromatch" | "picomatch"): Matcher => {
 /* ---------------- Internal helpers ---------------- */
 
 /**
- * Matches a single string against a glob pattern using only * and ** semantics.
+ * Splits a glob pattern into dot-separated segments, honoring backslash escaping.
+ * - Do not split on `\.` (literal dot remains within the same segment)
+ * - Preserve backslashes so segment-level matching can distinguish escaped `*`
+ *   Examples:
+ *     "a\.b.c"   → ["a\.b", "c"]
+ *     "foo\*bar" → ["foo\*bar"]
  */
+const splitPattern = (pattern: string): string[] => {
+  const segments: string[] = [];
+  let buf = "";
+  let escaped = false;
+
+  for (const ch of pattern) {
+    if (escaped) {
+      // keep the backslash for segment matching stage
+      buf += "\\" + ch;
+      escaped = false;
+    } else if (ch === "\\") {
+      escaped = true;
+    } else if (ch === ".") {
+      segments.push(buf);
+      buf = "";
+    } else {
+      buf += ch;
+    }
+  }
+  if (escaped) buf += "\\"; // trailing backslash is literal
+  segments.push(buf);
+  return segments;
+};
+
 const matchOne = (str: string, pattern: string): boolean => {
   const strSegments = str.split(".");
-  const patSegments = pattern.split(".");
-
+  const patSegments = splitPattern(pattern);
   return matchSegments(strSegments, patSegments);
 };
 
 /**
- * Matches field segments against pattern segments.
- * - `*`  = any single segment
- * - `**` = zero or more segments
+ * `**` matches zero or more segments (only when unescaped as a whole segment).
  */
 const matchSegments = (strSegments: string[], patternSegments: string[]): boolean => {
   let si = 0;
   let pi = 0;
 
   while (si < strSegments.length && pi < patternSegments.length) {
     const pat = patternSegments[pi];
+
     if (pat === "**") {
-      // match remainder greedily
-      if (pi === patternSegments.length - 1) return true;
+      if (pi === patternSegments.length - 1) return true; // consume rest
       for (let skip = 0; si + skip <= strSegments.length; skip++) {
         if (matchSegments(strSegments.slice(si + skip), patternSegments.slice(pi + 1))) {
           return true;
@@ -110,17 +155,54 @@ const matchSegments = (strSegments: string[], patternSegments: string[]): boolea
 };
 
 /**
- * Matches a single field segment against a pattern segment.
- * - `*` = any
- * - `prefix-*` / `*-suffix` = prefix/suffix match
+ * Segment-level match with micromatch-like escapes:
+ * - Unescaped `*` → wildcard (prefix/suffix; exactly one wildcard supported)
+ * - `\*` → literal `*`
+ * - `\.` → literal `.`
+ * - Backslash escapes any next char (becomes literal)
  */
 const segmentMatches = (seg: string, pat: string): boolean => {
-  if (pat === "*") return true;
+  // Parse `pat`, tracking a single UNESCAPED `*` position
+  let escaped = false;
+  let sawUnescapedStar = false;
+  let pre = "";
+  let buf = "";
+
+  for (let i = 0; i < pat.length; i++) {
+    const ch = pat[i];
+
+    if (escaped) {
+      buf += ch; // take literally
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      escaped = true; // next char is literal
+      continue;
+    }
+    if (ch === "*") {
+      if (!sawUnescapedStar) {
+        sawUnescapedStar = true;
+        pre = buf; // capture prefix; start collecting suffix into `buf` anew
+        buf = "";
+        continue;
+      }
+      // Additional unescaped '*' are treated as literal in suffix per our minimal semantics
+      buf += "*";
+      continue;
+    }
+    buf += ch;
+  }
+  if (escaped) buf += "\\"; // trailing backslash literal
 
-  if (pat.includes("*")) {
-    const [pre, suf] = pat.split("*");
-    return seg.startsWith(pre) && seg.endsWith(suf);
+  if (!sawUnescapedStar) {
+    // No wildcard: exact match after unescaping (remove backslashes)
+    const literal = buf.replace(/\\(.)/g, "$1");
+    return seg === literal;
   }
 
-  return seg === pat;
+  // Wildcard with single unescaped `*`: prefix/suffix
+  const suf = buf.replace(/\\(.)/g, "$1");
+  const prefix = pre.replace(/\\(.)/g, "$1");
+  return seg.startsWith(prefix) && seg.endsWith(suf);
 };

lib/src/types.ts

@@ -38,15 +38,15 @@ type ForbidBangEnd<T extends string> = T extends `${string}!` ? never : T;
  * - Values: one or more strategies, or nested RuleTree
  */
 export type RuleTree<T extends string = BasicMergeStrategies> = {
-  [fieldGlob: string]: ForbidBangEnd<T>[] | RuleTree<ForbidBangEnd<T>>;
+  [fieldGlob: string]: T[] | RuleTree<T>;
 };
 
 /**
  * High-level config object for conflict resolution.
  */
 export interface Config<T extends string = BasicMergeStrategies, TContext = unknown> {
   /** Fallback strategy when no rule matches */
-  defaultStrategy?: ForbidBangEnd<T> | ForbidBangEnd<T>[];
+  defaultStrategy?: T | T[];
 
   /** Rule tree mapping globs → strategies */
   rules?: RuleTree<T>;