globs.ts

/**
 * @fileoverview Glob pattern matching utilities with default ignore patterns.
 * Provides file filtering and glob matcher functions for npm-like behavior.
 */

import type * as fastGlobType from './external/fast-glob.js'
import type picomatchType from './external/picomatch.js'

let _fastGlob: typeof fastGlobType | undefined
/*@__NO_SIDE_EFFECTS__*/
function getFastGlob() {
  if (_fastGlob === undefined) {
    _fastGlob = /*@__PURE__*/ require('./external/fast-glob.js')
  }
  return _fastGlob!
}

let _picomatch: typeof picomatchType | undefined
/*@__NO_SIDE_EFFECTS__*/
function getPicomatch() {
  if (_picomatch === undefined) {
    _picomatch = /*@__PURE__*/ require('./external/picomatch.js')
  }
  return _picomatch!
}

import { objectFreeze as ObjectFreeze } from './objects'
import {
  LICENSE_GLOB,
  LICENSE_GLOB_RECURSIVE,
  LICENSE_ORIGINAL_GLOB_RECURSIVE,
} from './paths/globs'

// Type definitions
type Pattern = string

interface FastGlobOptions {
  absolute?: boolean
  baseNameMatch?: boolean
  braceExpansion?: boolean
  caseSensitiveMatch?: boolean
  concurrency?: number
  cwd?: string
  deep?: number
  dot?: boolean
  extglob?: boolean
  followSymbolicLinks?: boolean
  fs?: unknown
  globstar?: boolean
  ignore?: string[]
  ignoreFiles?: string[]
  markDirectories?: boolean
  objectMode?: boolean
  onlyDirectories?: boolean
  onlyFiles?: boolean
  stats?: boolean
  suppressErrors?: boolean
  throwErrorOnBrokenSymbolicLink?: boolean
  unique?: boolean
}

export interface GlobOptions extends FastGlobOptions {
  ignoreOriginals?: boolean
  recursive?: boolean
}

export type { Pattern, FastGlobOptions }

export const defaultIgnore = ObjectFreeze([
  // Most of these ignored files can be included specifically if included in the
  // files globs. Exceptions to this are:
  // https://docs.npmjs.com/cli/v10/configuring-npm/package-json#files
  // These can NOT be included.
  // https://github.com/npm/npm-packlist/blob/v10.0.0/lib/index.js#L280
  '**/.git',
  '**/.npmrc',
  // '**/bun.lockb?',
  '**/node_modules',
  // '**/package-lock.json',
  // '**/pnpm-lock.ya?ml',
  // '**/yarn.lock',
  // Include npm-packlist defaults:
  // https://github.com/npm/npm-packlist/blob/v10.0.0/lib/index.js#L15-L38
  '**/.DS_Store',
  '**/.gitignore',
  '**/.hg',
  '**/.lock-wscript',
  '**/.npmignore',
  '**/.svn',
  '**/.wafpickle-*',
  '**/.*.swp',
  '**/._*/**',
  '**/archived-packages/**',
  '**/build/config.gypi',
  '**/CVS',
  '**/npm-debug.log',
  '**/*.orig',
  // Inline generic socket-registry .gitignore entries.
  '**/.env',
  '**/.eslintcache',
  '**/.nvm',
  '**/.tap',
  '**/.vscode',
  '**/*.tsbuildinfo',
  '**/Thumbs.db',
  // Inline additional ignores.
  '**/bower_components',
])

/**
 * Create a stream of license file paths matching glob patterns.
 */
/*@__NO_SIDE_EFFECTS__*/
export function globStreamLicenses(
  dirname: string,
  options?: GlobOptions,
): NodeJS.ReadableStream {
  const {
    ignore: ignoreOpt,
    ignoreOriginals,
    recursive,
    ...globOptions
  } = { __proto__: null, ...options } as GlobOptions
  const ignore = [
    ...(Array.isArray(ignoreOpt) ? ignoreOpt : defaultIgnore),
    '**/*.{cjs,cts,js,json,mjs,mts,ts}',
  ]
  if (ignoreOriginals) {
    ignore.push(LICENSE_ORIGINAL_GLOB_RECURSIVE)
  }
  /* c8 ignore start - External fast-glob call */
  const fastGlob = getFastGlob()
  return fastGlob.globStream(
    [recursive ? LICENSE_GLOB_RECURSIVE : LICENSE_GLOB],
    {
      __proto__: null,
      absolute: true,
      caseSensitiveMatch: false,
      cwd: dirname,
      ...globOptions,
      ...(ignore ? { ignore } : {}),
    } as import('fast-glob').Options,
  )
  /* c8 ignore stop */
}

const MATCHER_CACHE_MAX_SIZE = 100
const matcherCache = new Map<string, (path: string) => boolean>()
const matcherAccessOrder: string[] = []

function evictLRUMatcher() {
  if (
    matcherCache.size >= MATCHER_CACHE_MAX_SIZE &&
    matcherAccessOrder.length > 0
  ) {
    const oldest = matcherAccessOrder.shift()
    if (oldest) {
      matcherCache.delete(oldest)
    }
  }
}

/**
 * Get a cached glob matcher function.
 */
/*@__NO_SIDE_EFFECTS__*/
export function getGlobMatcher(
  glob: Pattern | Pattern[],
  options?: { dot?: boolean; nocase?: boolean; ignore?: string[] },
): (path: string) => boolean {
  const patterns = Array.isArray(glob) ? glob : [glob]
  // Create stable cache key by sorting patterns and option keys
  const sortedPatterns = [...patterns].sort()
  const sortedOptions = options
    ? Object.keys(options)
        .sort()
        .map(k => `${k}:${JSON.stringify(options[k as keyof typeof options])}`)
        .join(',')
    : ''
  const key = `${sortedPatterns.join('|')}:${sortedOptions}`
  let matcher: ((path: string) => boolean) | undefined = matcherCache.get(key)
  if (matcher) {
    // Move to end of access order (LRU)
    const index = matcherAccessOrder.indexOf(key)
    if (index !== -1) {
      matcherAccessOrder.splice(index, 1)
      matcherAccessOrder.push(key)
    }
    return matcher
  }

  // Evict oldest entry if cache is full
  evictLRUMatcher()

  // Separate positive and negative patterns.
  const positivePatterns = patterns.filter(p => !p.startsWith('!'))
  const negativePatterns = patterns
    .filter(p => p.startsWith('!'))
    .map(p => p.slice(1))

  // Use ignore option for negation patterns.
  const matchOptions = {
    dot: true,
    nocase: true,
    ...options,
    ...(negativePatterns.length > 0 ? { ignore: negativePatterns } : {}),
  }

  /* c8 ignore next 5 - External picomatch call */
  const picomatch = getPicomatch()
  matcher = picomatch(
    positivePatterns.length > 0 ? positivePatterns : patterns,
    matchOptions,
  ) as (path: string) => boolean

  matcherCache.set(key, matcher)
  matcherAccessOrder.push(key)
  return matcher
}

/**
 * Asynchronously find files matching glob patterns.
 * Wrapper around fast-glob.
 */
/*@__NO_SIDE_EFFECTS__*/
export function glob(
  patterns: Pattern | Pattern[],
  options?: FastGlobOptions,
): Promise<string[]> {
  /* c8 ignore next - External fast-glob call */
  const fastGlob = getFastGlob()
  return fastGlob.glob(patterns, options as import('fast-glob').Options)
}

/**
 * Synchronously find files matching glob patterns.
 * Wrapper around fast-glob.sync.
 */
/*@__NO_SIDE_EFFECTS__*/
export function globSync(
  patterns: Pattern | Pattern[],
  options?: FastGlobOptions,
): string[] {
  /* c8 ignore next - External fast-glob call */
  const fastGlob = getFastGlob()
  return fastGlob.globSync(patterns, options as import('fast-glob').Options)
}