# Papa Parse: мастерская CSV

Авторская учебная мастерская ae-nekrasov.ru. Papa Parse 5.7.1, Bootstrap5.3.9,
Node24 LTS (>=24.15). Девять задач, восемнадцать вариантов. Все данные вымышлены.

## Что работает

Настоящая библиотека разбирает редактируемый CSV в отдельном браузерном Worker.
Результаты не берутся из записанного JSON. Файлы читаются локально; содержимое
не отправляется на сервер. Учебный контракт проверяет id/name/quantity; запись
в базу отсутствует. JSON-отчёт сохраняет все результаты в пределах лимитов.

Рабочие сценарии: кавычки и переносы, разделитель, заголовки, типы значений,
контракт, ошибки, прогресс и отмена, CSV-экспорт, кодировки. Source viewer
показывает реальные файлы проекта. При изменении входа старый результат очищается.

## Windows / PowerShell

```powershell
node --version
npm ci --ignore-scripts --no-audit --no-fund
npm run build
npm test
npm run capture
npm run serve
# Откройте http://127.0.0.1:8553/
# При занятом порте:
$env:PORT = '8653'
npm run serve
```

Для просмотра уже собранного public можно сразу выполнить npm run serve:
сервер использует только стандартные модули Node. Ctrl+C останавливает сервер.
Он слушает 127.0.0.1. Не открывайте index.html как file://: Worker и source viewer
должны загружаться по HTTP. Альтернатива при установленном PHP:

```powershell
php -S 127.0.0.1:8553 -t public
```

## Linux / Bash

```bash
npm ci --ignore-scripts --no-audit --no-fund
npm run build
npm test
npm run capture
PORT=8653 npm run serve
```

Не переносите node_modules с Windows. npm ci использует закреплённый lock-файл.
В готовом public нет платформенных исполняемых файлов. Для независимого Linux-
повтора в Docker скрипт копирует только исходники и пишет доказательства в /out:

```bash
mkdir -p linux-qa
docker run --rm --name aen-papa-linux-check \
  --mount type=bind,src="$PWD",dst=/src,readonly \
  --mount type=bind,src="$PWD/linux-qa",dst=/out \
  node:24.22.2-bookworm-slim sh /src/tools/run-linux-check.sh
```

PowerShell для того же контейнера:

```powershell
New-Item -ItemType Directory -Force linux-qa
$labDir = (Get-Location).Path
docker run --rm --name aen-papa-linux-check `
  --mount "type=bind,src=$labDir,dst=/src,readonly" `
  --mount "type=bind,src=$labDir/linux-qa,dst=/out" `
  node:24.22.2-bookworm-slim sh /src/tools/run-linux-check.sh
```

Контейнеру нужен доступ к npm при установке. Имя и каталог выберите свои, если
они уже заняты. Скрипт не очищает глобальные Docker-ресурсы.

## CLI: проверка перед импортом

```bash
node tools/cli.mjs fixtures/catalog.csv report.json
node tools/cli.mjs fixtures/windows-1251.csv report-1251.json windows-1251
node tools/cli.mjs fixtures/invalid.csv report-invalid.json
```

Exit0: контракт пройден. Exit2: отчёт записан, но есть ошибки данных/CSV.
Exit1: чтение, декодирование, лимит или запись отчёта не удались. CLI не
перезаписывает существующий отчёт и не позволяет выбрать исходный CSV как
выходной путь. Никаких изменений БД он не выполняет.

```bash
docker build -t aen-papa-cli:1 .
mkdir -p out
# UID1000 должен иметь право писать в out; при другом UID используйте --user.
docker run --rm --network none \
  --mount type=bind,src="$PWD/out",dst=/out \
  aen-papa-cli:1 fixtures/catalog.csv /out/report.json
```

## Ограничения и безопасное применение

- До1MiB исходного текста/файла; до10000 записей; до100 в таблице.
- Браузерный бюджет15секунд, включая учебную задержку.
- Потоковые step-вызовы идут внутри собственного Worker. Это не worker:true
  Papa; пауза parser.pause()/resume() работает в его локальном контексте.
- Worker обеспечивает отзывчивость, но проект сохраняет ограниченный набор
  принятых/отклонённых строк в памяти. Это не конвейер неограниченных файлов.
- Прогресс — доля UTF-16 cursor в длине строки, а не загрузка по сети.
- Отмена завершает Worker и не публикует частичный результат.
- CSV-экспорт применяет escapeFormulae:true. Апостроф меняет исходное значение;
  у получателя всё равно должна быть согласованная политика импорта таблиц.
- Кодировка применяется к байтам файла. UTF-8 BOM не означает Windows-1251.
- Ошибки row относятся к индексу записи, а не физической строке текста.
- Browser validation не заменяет повторную проверку на сервере, права доступа,
  транзакцию и ограничение количества/частоты импортов.

## Проверки и публикация

npm test выполняет настоящие Papa Parse вызовы, Worker Thread, отмену/прогресс,
CLI и защиту исходника. npm run capture сохраняет18 реальных результатов Node
и SHA256 исходников в qa/actual-node-results.json. Браузерный и мобильный QA
выполняются отдельно; JSDOM и unit tests не выдаются за физический телефон.

Для VPS см. VPS.md. Авторские исходники MIT; сторонние лицензии public/LICENSES.txt.
Документация: https://www.papaparse.com/docs

