feat: add 'some-with-excludes' predicate quantifier (#322)

src/filter.ts

@@ -21,6 +21,12 @@ const MatchOptions = {
 interface FilterRuleItem {
   status?: ChangeStatus[] // Required change status of the matched files
   isMatch: (str: string) => boolean // Matches the filename
+  // Matchers for the individual polarities of the patterns this item was created from.
+  // They are used only by the PredicateQuantifier.SOME_WITH_EXCLUDES quantifier,
+  // which has to tell inclusions and exclusions apart. The other quantifiers keep
+  // evaluating the item as a whole via 'isMatch'.
+  isInclude?: (str: string) => boolean // Matches any of the patterns which are not negated
+  isExclude?: (str: string) => boolean // Matches any of the patterns which are negated (e.g. '!**/*.md')
 }
 
 /**
@@ -47,7 +53,17 @@ export enum PredicateQuantifier {
    * at least one pattern that matches them. This is the default behavior if you don't
    * specify anything as a predicate quantifier.
    */
-  SOME = 'some'
+  SOME = 'some',
+  /**
+   * When choosing 'some-with-excludes' in the config it means that files will get matched if
+   * at least one of the patterns matches them and none of the negated patterns (the ones
+   * prefixed with '!') matches them. An exclusion is final - a file excluded by one pattern
+   * can't be included back by another one.
+   *
+   * A filter which consists of negated patterns only never matches anything,
+   * because there is no pattern which could include a file in the first place.
+   */
+  SOME_WITH_EXCLUDES = 'some-with-excludes'
 }
 
 /**
@@ -104,13 +120,35 @@ export class Filter {
   }
 
   private isMatch(file: File, patterns: FilterRuleItem[]): boolean {
-    const aPredicate = (rule: Readonly<FilterRuleItem>): boolean => {
-      return (rule.status === undefined || rule.status.includes(file.status)) && rule.isMatch(file.filename)
+    const isStatusMatch = (rule: Readonly<FilterRuleItem>): boolean => {
+      return rule.status === undefined || rule.status.includes(file.status)
     }
-    if (this.filterConfig?.predicateQuantifier === 'every') {
-      return patterns.every(aPredicate)
-    } else {
-      return patterns.some(aPredicate)
+    const aPredicate = (rule: Readonly<FilterRuleItem>): boolean => {
+      return isStatusMatch(rule) && rule.isMatch(file.filename)
+    }
+
+    switch (this.filterConfig?.predicateQuantifier) {
+      case PredicateQuantifier.EVERY:
+        return patterns.every(aPredicate)
+      case PredicateQuantifier.SOME_WITH_EXCLUDES: {
+        let isIncluded = false
+        for (const rule of patterns) {
+          if (!isStatusMatch(rule)) {
+            continue
+          }
+          // Once a file is excluded it stays excluded - no other pattern can include it back.
+          // Therefore all the patterns have to be evaluated even if the file is already included.
+          if (rule.isExclude?.(file.filename)) {
+            return false
+          }
+          if (!isIncluded && rule.isInclude?.(file.filename)) {
+            isIncluded = true
+          }
+        }
+        return isIncluded
+      }
+      default:
+        return patterns.some(aPredicate)
     }
   }
 
@@ -120,7 +158,7 @@ export class Filter {
     }
 
     if (typeof item === 'string') {
-      return [{status: undefined, isMatch: picomatch(item, MatchOptions)}]
+      return [createRuleItem(item)]
     }
 
     if (typeof item === 'object') {
@@ -130,14 +168,12 @@ export class Filter {
             `Expected [key:string]= pattern:string | string[], but [${key}:${typeof key}]= ${pattern}:${typeof pattern} found`
           )
         }
-        return {
-          status: key
-            .split('|')
-            .map(x => x.trim())
-            .filter(x => x.length > 0)
-            .map(x => x.toLowerCase()) as ChangeStatus[],
-          isMatch: picomatch(pattern, MatchOptions)
-        }
+        const status = key
+          .split('|')
+          .map(x => x.trim())
+          .filter(x => x.length > 0)
+          .map(x => x.toLowerCase()) as ChangeStatus[]
+        return createRuleItem(pattern, status)
       })
     }
 
@@ -154,3 +190,25 @@ export class Filter {
 function flat<T>(arr: T[][]): T[] {
   return arr.reduce((acc, val) => acc.concat(val), [])
 }
+
+// Compiles filename pattern(s) of a single filter rule item into matchers.
+// Multiple patterns are OR-ed together, which is how picomatch treats an array of globs.
+// Patterns are also split by their polarity, so PredicateQuantifier.SOME_WITH_EXCLUDES
+// can tell inclusions from exclusions. Note that only a leading '!' negates the whole
+// pattern - the '!(...)' extglob is a regular pattern matching everything it doesn't enumerate.
+function createRuleItem(patterns: string | string[], status?: ChangeStatus[]): FilterRuleItem {
+  const matchers = (Array.isArray(patterns) ? patterns : [patterns]).map(pattern =>
+    picomatch(pattern, MatchOptions, true)
+  )
+  // picomatch inverts the result of a matcher created from a negated pattern.
+  // Inverting it back gives a matcher of the filenames such pattern excludes.
+  const includes = matchers.filter(matcher => !matcher.state.negated)
+  const excludes = matchers.filter(matcher => matcher.state.negated)
+
+  return {
+    status,
+    isMatch: str => matchers.some(matcher => matcher(str)),
+    isInclude: includes.length > 0 ? str => includes.some(matcher => matcher(str)) : undefined,
+    isExclude: excludes.length > 0 ? str => excludes.some(matcher => !matcher(str)) : undefined
+  }
+}