Документация 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 - Обнаружение похожих имён пакетов (typosquatting)

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

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

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

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

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

• Разработка - локальная настройка, рабочие процессы и полезные команды.
• Тестирование - команды тестирования, организация тестов и ожидания по проверке.
• Архитектура - структура репозитория, границы пакетов и важные потоки.
• Соглашения - соглашения по коду, документации и сопровождению.

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

• Поддержка пользовательского реестра - утверждённый дизайн поддержки npm-совместимого Artifactory и частных реестров.
• Детектирование coding-агентов для JSON-режима - утверждённый дизайн автоматического выбора режима JSON-аудита в средах coding-агентов.
• JSON-вывод аудита - утверждённый дизайн версионированных, неинтерактивных машиночитаемых результатов аудита.
• Предупреждения об истёкших доменах мейнтейнеров - утверждённый дизайн атрибутируемых предупреждений об истёкших доменах.
• Разрешённая версия для истёкших доменов - дизайн разрешения точной версии зависимости для проверок истёкших доменов.

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

• Поддержка пользовательского реестра - пошаговый план реализации для задачи #429.
• Детектирование coding-агентов для JSON-режима - план реализации по принципу test-first для задачи #426 в npq и npq-hero.
• JSON-вывод аудита - пошаговый план версионированного JSON-вывода CLI только для аудита.
• Разрешённая версия для истёкших доменов - план реализации точного разрешения версии зависимости в проверках истёкших доменов.
• Предупреждения об истёкших доменах мейнтейнеров - план реализации по принципу test-first для атрибутируемых предупреждений об истёкших доменах.