matcher.ts

/**
 * @file `getGlobMatcher` — picomatch-backed sync predicate with an LRU-memoized
 *   matcher cache. `getMatchesGlob` exposes Node 22+'s native
 *   `path.matchesGlob` for the rare case where the caller wants strict
 *   (`nocase: false`, `dot: false`) matching.
 */

import { ArrayIsArray } from '../primordials/array'
import { JSONStringify } from '../primordials/json'
import { ObjectKeys } from '../primordials/object'
import { StringPrototypeStartsWith } from '../primordials/string'

import { getPicomatch, MATCHER_CACHE_MAX_SIZE, matcherCache } from './_internal'

import type { PicomatchOptions } from '../external/picomatch'
import type NodePath from 'node:path'
import type { Pattern } from './types'

// `path.matchesGlob` was added in Node v22.5.0 / v20.17.0 (Stable).
// Engines is >=22, so it's missing only on 22.0.x – 22.4.x.
// `matchesGlobCache` caches the resolved native function; `matchesGlobProbed`
// distinguishes "not yet probed" from "probed but absent".
let matchesGlobCache: ((p: string, pattern: string) => boolean) | undefined
let matchesGlobProbed = false

/**
 * Return a glob-matcher function, memoized by pattern + options.
 *
 * The returned function is a fast synchronous predicate built on picomatch.
 * Results are memoized — calling `getGlobMatcher(['*.ts'])` a thousand times in
 * a loop returns the same compiled matcher each time, so callers do not need to
 * hoist it themselves.
 *
 * The cache is LRU with a cap of 100 entries. Cache keys fold together the
 * (sorted) pattern list and (sorted) option set, so arguments that differ only
 * in ordering share a matcher.
 *
 * Default options: `dot: true`, `nocase: true`. Patterns starting with `!`
 * become ignore patterns.
 *
 * @example
 *   ;```typescript
 *   const isMatch = getGlobMatcher('*.ts')
 *   isMatch('index.ts') // true
 *   isMatch('index.js') // false
 *
 *   const isSource = getGlobMatcher(['src/**', '!**\/*.test.ts'])
 *   ```
 */
export function getGlobMatcher(
  glob: Pattern | Pattern[],
  options?: {
    dot?: boolean | undefined
    nocase?: boolean | undefined
    ignore?: string[] | undefined
  },
): (path: string) => boolean {
  options = { __proto__: null, ...options } as typeof options
  const patterns = ArrayIsArray(glob) ? glob : [glob]
  // Create stable cache key by sorting patterns and option keys.
  // Option values that are arrays (e.g. `ignore: ['a', 'b']`) get sorted
  // element-wise so `['a', 'b']` and `['b', 'a']` hit the same entry —
  // otherwise equivalent matchers re-compile and evict each other under
  // the 100-entry cap.
  const sortedPatterns = [...patterns].toSorted()
  const sortedOptions = options
    ? ObjectKeys(options)
        .toSorted()
        .map(k => {
          const value = options[k as keyof typeof options]
          const normalized = ArrayIsArray(value) ? [...value].toSorted() : value
          return `${k}:${JSONStringify(normalized)}`
        })
        .join(',')
    : ''
  const key = `${sortedPatterns.join('|')}:${sortedOptions}`
  const existing = matcherCache.get(key)
  if (existing) {
    // Re-insert to mark as most-recently-used.
    matcherCache.delete(key)
    matcherCache.set(key, existing)
    return existing
  }

  // LRU eviction triggers at 100 entries; not reachable from typical
  // test runs.
  /* c8 ignore start */
  if (matcherCache.size >= MATCHER_CACHE_MAX_SIZE) {
    const oldest = matcherCache.keys().next().value
    if (oldest !== undefined) {
      matcherCache.delete(oldest)
    }
  }
  /* c8 ignore stop */

  // Narrow `path.matchesGlob` fast-path. picomatch's defaults
  // (`dot: true`, `nocase: true`) silently differ from
  // `path.matchesGlob`'s behavior (case-sensitive, no dot match), so
  // taking the fast-path under those defaults silently changes
  // observable behavior — that's how the previous draft of this
  // file regressed the case-insensitive default and the dot-match
  // contract. Activate ONLY when the caller has explicitly opted
  // out of both defaults (`nocase: false` AND `dot: false`),
  // signaling "I want strict, case-sensitive, no-dotfile-match" —
  // which is exactly what `path.matchesGlob` provides. No caller in
  // the fleet does this today, but the path is correct + auditable.
  let matcher: ((path: string) => boolean) | undefined
  /* c8 ignore start */
  if (
    patterns.length === 1 &&
    !StringPrototypeStartsWith(patterns[0]!, '!') &&
    options !== undefined &&
    options.nocase === false &&
    options.dot === false &&
    (options.ignore === undefined || options.ignore.length === 0)
  ) {
    const matchesGlob = getMatchesGlob()
    if (matchesGlob !== undefined) {
      const pattern = patterns[0]!
      matcher = (p: string) => matchesGlob(p, pattern)
    }
  }
  /* c8 ignore stop */
  if (matcher === undefined) {
    // Separate positive and negative patterns.
    const positivePatterns = patterns.filter(
      p => !StringPrototypeStartsWith(p, '!'),
    )
    const negativePatterns = patterns
      .filter(p => StringPrototypeStartsWith(p, '!'))
      .map(p => p.slice(1))

    // Use ignore option for negation patterns. Cast at the picomatch
    // boundary: the caller's option props carry `| undefined`, which
    // PicomatchOptions rejects under exactOptionalPropertyTypes even
    // though the runtime values are valid.
    const matchOptions = {
      dot: true,
      nocase: true,
      ...options,
      ...(negativePatterns.length > 0 ? { ignore: negativePatterns } : {}),
    }

    // External picomatch call
    /* c8 ignore start - external picomatch lib, exercised via integration */
    const picomatch = getPicomatch()
    matcher = picomatch(
      positivePatterns.length > 0 ? positivePatterns : patterns,
      matchOptions as PicomatchOptions,
    ) as (path: string) => boolean
    /* c8 ignore stop */
  }

  matcherCache.set(key, matcher)
  return matcher
}

/**
 * Resolve `path.matchesGlob` (or `undefined` if the runtime predates it).
 * Probes once and caches the result for every subsequent call.
 *
 * Used by `getGlobMatcher`'s narrow fast-path — see the conditions spelled out
 * at the call site. Exported for unit tests.
 *
 * @internal
 */
export function getMatchesGlob():
  | ((p: string, pattern: string) => boolean)
  | undefined {
  if (!matchesGlobProbed) {
    // The /*@__PURE__*/ stays adjacent to the require() call — oxfmt
    // reformats `(/*@__PURE__*/ require(…) as T).x` back into the
    // outside-paren form that rolldown doesn't honor; using an
    // intermediate const sidesteps the reformat. See task #23.
    const pathMod =
      /*@__PURE__*/ require('node:path') as typeof NodePath & {
        matchesGlob?: unknown | undefined
      }
    const fn = pathMod.matchesGlob
    // path.matchesGlob is present on Node 22+; missing-fn arm fires
    // only on older runtimes.
    /* c8 ignore start */
    if (typeof fn === 'function') {
      matchesGlobCache = fn as (p: string, pattern: string) => boolean
    }
    /* c8 ignore stop */
    matchesGlobProbed = true
  }
  return matchesGlobCache
}