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 - 自动继续（auto-continue）功能的文档，可简化软件包安装工作流
• exit-codes.md - npq 和 npq-hero 进程退出行为参考
• json-output.md - 面向 CI 和自动化场景的带版本号、机器可读的仅审计输出
• malicious-package.md - 通过 Snyk/OSV 数据检测已知恶意软件包的文档
• pacote-dependency-reduction.md - 可选 pacote 依赖缩减的实现摘要

文档规范

结构

• 每个功能在 feature/ 目录中拥有独立的 markdown 文件
• 核心功能在文档根目录层级记录
• 技术实现细节附带代码示例
• 面向用户的配置配有使用示例

内容准则

• 概述：功能/组件的简要描述
• 技术设计：架构与实现细节
• 使用示例：带代码片段的实用示例
• 测试：覆盖率与验证信息
• 未来考量：维护与演进说明

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. 测试：记录测试覆盖率与验证

快速参考

项目背景

• 开发 - 本地环境搭建、工作流程和实用命令。
• 测试 - 测试命令、测试组织结构和验证预期。
• 架构 - 仓库结构、包边界和重要流程。
• 约定 - 编码、文档和维护约定。

设计规范

• 自定义注册表支持 - 针对兼容 npm 的 Artifactory 和私有注册表支持的已批准设计。
• 编码代理 JSON 检测 - 针对在编码代理环境中自动选择 JSON 审计模式的已批准设计。
• JSON 审计输出 - 针对带版本号、非交互式机器可读审计结果的已批准设计。
• 过期域名维护者身份警告 - 针对可归因的过期域名警告的已批准设计。
• 过期域名解析版本 - 针对在过期域名检查中解析精确依赖版本的设计。

实施计划

• 自定义注册表支持 - 针对 issue #429 的逐任务实施计划。
• 编码代理 JSON 检测 - 针对 issue #426、跨越 npq 和 npq-hero 的测试先行实施计划。
• JSON 审计输出 - 针对带版本号、仅审计的 JSON CLI 输出的逐任务计划。
• 过期域名解析版本 - 针对在过期域名检查中实现精确依赖版本解析的实施计划。
• 过期域名维护者身份警告 - 针对可归因的过期域名警告的测试先行实施计划。