obfuscator/PLAN-LST-FILTER.md

План: фильтрация файлов через .lst

Цель

Добавить в file picker режим manifest-фильтра:

• пользователь выбирает папку целиком;
• если в корне выбранной папки есть obscure.lst, он ограничивает набор файлов;
• если .lst нет, сохраняется текущее поведение: выбираются все поддерживаемые файлы;
• сам obscure.lst никогда не отправляется на обработку;
• другие файлы с расширением .lst не являются manifest-файлами и не загружаются.

Правила obscure.lst

Одна строка — одно правило.

• пустые строки игнорируются;
• строки, начинающиеся с #, являются комментариями;
• ! в начале строки означает отрицательное правило;
• пути относительны к выбранной папке;
• абсолютные пути и сегменты .. запрещены;
• разделители \ нормализуются в /;
• весь путь сравнивается без учёта регистра;
• несколько совпавших правил не создают дубли.

Пример:

*.pdf
reports/name*.docx
!archive/**
!**/*draft*.*

Glob-маски

Поддержать общепринятые шаблоны:

• * — любое количество символов, кроме /;
• ? — один символ, кроме /;
• ** — любое количество каталогов;
• [abc] и [a-z] — классы и диапазоны символов;
• [!a] и [^a] — отрицательные классы;
• обычный путь без glob-символов — точное совпадение.

Семантика:

• *.pdf — PDF только в корне выбранной папки;
• reports/*.pdf — PDF внутри reports;
• **/*.pdf — PDF на любой глубине;
• name*.pdf — файлы с префиксом name в корне;
• reports/name*.pdf — файлы с префиксом name непосредственно в reports;
• reports/ — то же, что reports/**;
• a**b — две звёздочки внутри сегмента работают как обычная *.

Правило без / не применяется рекурсивно. Для поиска на любой глубине нужно явно использовать **/, например **/*.pdf.

Положительные правила формируют набор кандидатов. Отрицательные правила удаляют совпавшие файлы из результата.

Алгоритм

1. Получить все файлы выбранной папки и подпапок через webkitdirectory.
2. Нормализовать webkitRelativePath, убрав имя корневой выбранной папки.
3. Найти только obscure.lst в корне выбранной папки, без учёта регистра. Остальные .lst игнорировать.
4. Если obscure.lst нет, передать в текущую логику все поддерживаемые файлы.
5. Если obscure.lst найден:
   • прочитать UTF-8 и убрать BOM;
   • разобрать строки и скомпилировать glob в RegExp;
   • отбросить некорректные правила с предупреждением и номером строки;
   • выбрать поддерживаемые файлы, совпавшие хотя бы с одним положительным правилом;
   • удалить совпадения с отрицательными правилами;
   • удалить .lst из результата;
   • сохранить исходный порядок файлов и убрать дубли по нормализованному пути.
6. Передать итоговый список в существующий цикл построения таблицы без изменений.

Если все положительные правила отсутствуют или некорректны, результат пустой. Автоматический fallback на все файлы запрещён.

Если положительное правило не совпало ни с одним файлом, показать предупреждение, но продолжить обработку остальных правил. Неподдерживаемые файлы не добавлять.

obscure.lst во вложенной папке не является manifest-фильтром и обрабатывается как обычный неподдерживаемый файл.

Содержимое ZIP отдельно не фильтровать: ZIP выбирается как один файл и далее обрабатывается существующим механизмом раскрытия архивов.

Нормализация и предупреждения

Перед сопоставлением:

• заменить \ на /;
• убрать ведущие ./;
• свернуть повторные /;
• убрать имя корневой выбранной папки из webkitRelativePath;
• отклонить абсолютные пути, сегменты .. и пустые правила;
• отклонить незакрытые классы [ с указанием номера строки.

Ошибки и предупреждения передавать через существующий cfg.onError или statusEl. Ошибка одного правила не должна останавливать остальные правила. Ошибка чтения или декодирования obscure.lst даёт предупреждение и пустой результат.

Где менять код

Алгоритм фильтра вынести в чистый модуль рядом с текущим picker, например:

upload/frontend/table/lst_filter.js

Точка подключения — on_folder_change.js, до существующего цикла построения дерева. DOM и upload-транспорт в модуль фильтра не добавлять.

Сборочные site/static/dist/*.js изменять только штатной сборкой.

Минимальные тесты

Проверить:

1. Папка без .lst сохраняет старое поведение.
2. obscure.lst не попадает в результат, другие .lst также не загружаются.
3. *.pdf, name*.pdf, ?, ** и классы символов.
4. *.pdf совпадает только с файлом в корне, а **/*.pdf — также с x.pdf в корне и файлами в подпапках.
5. docs/name*.pdf, docs/, a**b и точные пути.
6. Положительные и отрицательные правила вместе.
7. Комментарии, пустые строки, BOM, CRLF и пробелы.
8. Регистр всего пути (DOCS/A.PDF совпадает с docs/*.pdf).
9. Кириллицу, пробелы, вложенные каталоги и обратные слеши (docs\a.pdf).
10. Дубли и перекрывающиеся маски.
11. Запрет /etc/x, C:/x, ../x, a/../b.
12. Битую маску без падения всего picker.
13. Ошибка чтения .lst даёт пустой результат и предупреждение.
14. Правило без совпадений даёт предупреждение.
15. Только отрицательные или полностью битые правила дают пустой результат.
16. Другой .lst в корне не включает manifest-режим.
17. obscure.lst во вложенной папке не включает manifest-режим.
18. ZIP выбирается целиком, без фильтрации его внутреннего содержимого.

Ограничения реализации

• Не менять backend-контракт.
• Не добавлять базу данных, отдельный сервис или новый формат конфигурации.
• Не переписывать существующий picker.
• Изменить минимальное число файлов.
• Сначала реализовать алгоритм и тесты, затем обновить dist штатной сборкой.