Документация 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)

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

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

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

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

Тема	Файл	Назначение
Дополнительные функции	`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`	Необязательное управление зависимостями

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

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

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

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

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

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

npq v3.24.0

Категории