npq

# Документация NPQ

Этот каталог содержит исчерпывающую документацию для инструмента аудита безопасности NPQ (Node Package Quality).

## Основная документация

### `optional-features.md`
Конфигурация и использование дополнительных функций безопасности, включая недавние улучшения и исправления ошибок.

### `age.marshall.md`  
Подробная документация компонента безопасности Age Marshall, который проверяет возраст и зрелость пакета.

## Документация функций

Каталог `feature/` содержит подробную документацию для конкретных функций и реализаций:

### Последние разработки

- **`test-coverage-improvements.md`** — Комплексные улучшения тестового покрытия, которые повысили общее покрытие с 84,4% до 93,39%
- **`signature-verification-fix.md`** — Критическое исправление ошибки проверки подписи с диапазонами версий (например, `@angular/common@^20.2.4`)

### Существующие функции  

- **`auto-continue.md`** — Документация функции автоматического продолжения, которая оптимизирует рабочие процессы установки пакетов
- **`exit-codes.md`** — Справочник по поведению кодов выхода процессов `npq` и `npq-hero`
- **`json-output.md`** — Версионированный, машиночитаемый вывод только для аудита для CI и автоматизации
- **`malicious-package.md`** — Документация по обнаружению известных вредоносных пакетов через данные Snyk/OSV
- **`pacote-dependency-reduction.md`** — Сводка реализации необязательного сокращения зависимостей pacote

## Стандарты документации

### Структура
- Каждая функция получает собственный файл Markdown в `feature/`
- Основная функциональность документируется на корневом уровне документации  
- Технические детали реализации включаются с примерами кода
- Конфигурация для пользователей документируется с примерами использования

### Рекомендации по содержимому
- **Обзор**: Краткое описание функции/компонента
- **Технический дизайн**: Детали архитектуры и реализации
- **Примеры использования**: Практические примеры с фрагментами кода
- **Тестирование**: Информация о покрытии и валидации
- **Будущие соображения**: Заметки по сопровождению и развитию

## Документация Marshall

Компоненты Marshall — это основные модули проверки безопасности в NPQ. Каждый Marshall фокусируется на конкретном аспекте безопасности:

- **Age Marshall** (`age.marshall.md`) — Проверка возраста и зрелости пакета
- **Signature Marshall** — Проверка подписи реестра NPM (см. `signature-verification-fix.md`)
- **Provenance Marshall** — Проверка подтверждения сборки пакета
- **Snyk Marshall** — Интеграция с базой данных уязвимостей
- **Typosquatting Marshall** — Обнаружение схожести имён пакетов

## Вклад в документацию

При добавлении новых функций или внесении значительных изменений:

1. **Документация функции**: Создайте новый файл в каталоге `feature/`
2. **Обновление индекса**: Добавьте запись в этот README
3. **Перекрёстные ссылки**: Обновите связанные файлы документации
4. **Примеры**: Включите практические примеры использования
5. **Тестирование**: Документируйте тестовое покрытие и валидацию

## Краткий справочник

| Тема | Файл | Назначение |
|-------|------|---------|
| Дополнительные функции | `optional-features.md` | Конфигурация функций и недавние улучшения |
| Проверка возраста | `age.marshall.md` | Проверки безопасности возраста и зрелости пакета |
| Тестовое покрытие | `feature/test-coverage-improvements.md` | Недавние улучшения тестового набора |
| Проверка подписи | `feature/signature-verification-fix.md` | Исправление ошибки диапазона версий и валидация |
| Автопродолжение | `feature/auto-continue.md` | Автоматизированный рабочий процесс установки |
| JSON-вывод аудита | `feature/json-output.md` | Версионированные машиночитаемые результаты аудита для CI |
| Коды выхода | `feature/exit-codes.md` | Поведение кодов выхода CLI и менеджера пакетов |
| Вредоносные пакеты | `feature/malicious-package.md` | Обнаружение и отчётность по известным вредоносным пакетам |
| Сокращение зависимостей | `feature/pacote-dependency-reduction.md` | Необязательное управление зависимостями |

## Контекст проекта

- [Разработка](https://github.com/lirantal/npq/blob/main/development.md) — локальная настройка, рабочие процессы и полезные команды.
- [Тестирование](https://github.com/lirantal/npq/blob/main/testing.md) — команды тестирования, организация тестов и ожидания по проверке.
- [Архитектура](https://github.com/lirantal/npq/blob/main/architecture.md) — структура репозитория, границы пакетов и важные потоки.
- [Соглашения](https://github.com/lirantal/npq/blob/main/conventions.md) — соглашения по кодированию, документации и сопровождению.

## Спецификации дизайна

- [Безопасность неинтерактивной установки](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-24-non-interactive-install-safety-design.md) — утверждённый дизайн для безопасных при сбое не-TTY установок с явным согласием для автоматизации и кодинг-агентов.

- [Безопасность неинтерактивной установки](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-24-non-interactive-install-safety.md) — план, ориентированный на тестирование, для маршрутизации не-TTY установок с безопасным сбоем и передачи кодинг-агентам.
- [Запуск менеджера пакетов без оболочки](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-15-package-manager-shell-free-launching-design.md) — утверждённый дизайн для передачи аргументов менеджера пакетов без реконструкции команд оболочки.
- [Поддержка пользовательских реестров](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-11-custom-registry-support-design.md) — утверждённый дизайн для поддержки совместимых с npm Artifactory и частных реестров.
- [Обнаружение JSON кодинг-агентами](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-09-coding-agent-json-detection-design.md) — утверждённый дизайн для автоматического выбора режима JSON-аудита в средах кодинг-агентов.
- [JSON-вывод аудита](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-09-json-output-design.md) — утверждённый дизайн для версионированных, неинтерактивных машиночитаемых результатов аудита.
- [Предупреждения об истёкших доменах для сопровождающих](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-17-expired-domain-maintainer-identities-design.md) — утверждённый дизайн для атрибутируемых предупреждений об истёкших доменах.
- [Разрешённая версия для истёкших доменов](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-17-expired-domain-resolved-version-design.md) — дизайн для разрешения точной версии зависимости для проверок истёкших доменов.

## Планы реализации

- [Безопасность неинтерактивной установки](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-24-non-interactive-install-safety.md) — план, ориентированный на тестирование, для маршрутизации не-TTY установок с безопасным сбоем и передачи кодинг-агентам.
- [Запуск менеджера пакетов без оболочки](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-15-package-manager-shell-free-launching.md) — план, ориентированный на тестирование, для запуска менеджеров пакетов без реконструкции команд оболочки.
- [Поддержка пользовательских реестров](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-11-custom-registry-support.md) — пошаговый план реализации для задачи #429.
- [Обнаружение JSON кодинг-агентами](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-09-coding-agent-json-detection.md) — план реализации, ориентированный на тестирование, для задачи #426 в `npq` и `npq-hero`.
- [JSON-вывод аудита](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-09-json-audit-output.md) — пошаговый план для версионированного, только аудиторского JSON-вывода CLI.
- [Разрешённая версия для истёкших доменов](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-17-expired-domain-resolved-version.md) — план реализации для точного разрешения версии зависимости в проверках истёкших доменов.
- [Предупреждения об истёкших доменах для сопровождающих](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-17-expired-domain-maintainer-identities.md) — план реализации, ориентированный на тестирование, для атрибутируемых предупреждений об истёкших доменах.