---
docgen:
  source: npm/scripts/lib/resolve-target-files.mjs
  crc: a3b361d9
---

# resolve-target-files.mjs

## Огляд

Цей файл відповідає за перевірку наявності файлів, що відповідають певним правилам, вказаним у файлах `policy/<name>/target.json`. Він створює список файлів для подальшого використання, використовуючи або конкретні відносні шляхи, або обхід каталогу з використанням шаблонів та ігнорування файлів. Це забезпечує узгодженість та контроль над файлами, які потрібно обробити, відповідно до заданих політик.

## Поведінка

1.  **Ініціалізація:** Отримує специфікацію файлів з `target.json`, включаючи `single` або `walkGlob`.
2.  **Обробка `single`:** Якщо `files.single` є рядком, перевіряє, чи шлях є відносним та не містить сегменту `..`. Якщо шлях безпечний, перевіряє наявності файлу за шляхом та повертає масив з абсолютним шляхом, якщо файл існує, або порожній масив, якщо ні.
3.  **Обробка `walkGlob`:** Якщо `files.walkGlob` є не визначеним, або є масивом рядків, виконує обхід дерева файлів від заданого кореня.
4.  **Завантаження ігнорування:** Завантажує список абсолютних шляхів, які слід ігнорувати, з конфігурації `.n-cursor.json:ignore`.
5.  **Кешування обходу:** Використовує кеш обходу дерева (Map) для запобігання повторному обходу одного й того ж набору ігнорування. Якщо обхід вже виконано для заданого набору ігнорування, повертає результат з кешу.
6.  **Обхід дерева:** Якщо обхід не кешований або кеш порожній, виконує обхід дерева файлів від заданого кореня, використовуючи `walkDir`. Під час обходу генерує відносні шляхи файлів від кореня.
7.  **Фільтрація за масками:** Для кожного відносного шляху файлу застосовує маски `walkGlob` за допомогою `picomatch`. Фільтрує файли, які відповідають маскам, та виключає ті, що відповідають негативним маскам.
8.  **Збіг з ігноруванням:** Перевіряє, чи файл не входить до списку ігнорування.
9.  **Збіг шляху:** Перетворює відносні шляхи файлів у абсолютні шляхи, додавши корень.
10. **Повернення результатів:** Повертає масив абсолют

## Публічний API

resolveTargetFiles — Знаходить файли, що вказані в `target.json:files`.

## Гарантії поведінки

- **Контракт на поліси:** Зчитуються лише файли з репозиторію.
- **`single`:** Якщо `existsSync`, повертається список файлів, що відповідають `single`. Інакше, повертається порожній список.
- **`walkGlob`:** Використовується picomatch для обробки glob-шаблонів відносно шляхів, отриманих з обходу `walkDir` від `root`.
- **Ігнорування:** Підтримується ігнорування файлів за допомогою `.n-cursor.json:ignore` та кешування шляхів ігнорування у `walkCache`.
- **Кешування:** Результати обходу кешуються для повторного використання при однаковому наборі ігнорувань.
- **Path-traversal:** При розв'язанні шляхів у формі `single` виникає помилка.
- **Відсутність результатів:** Якщо не знайдено жодного файлу, що відповідає критеріям, повертається порожній список.
- **Fail-safe:** Якщо `required` встановлено на `true`, і не знайдено жодного файлу, що відповідає критеріям, виникає помилка.
-
