# nark-corpus
**nark 的契约库 —— 包含 169+ 个 npm 包错误处理要求的 YAML 定义。**
这是 [nark](https://github.com/nark-sh/nark)（契约覆盖率扫描器）使用的契约库。它包含了 169+ 个契约，用于描述 npm 包在运行时如何失败，以及调用者必须提供怎样的错误处理。
## 什么是 Contract？
Contract 是一个 YAML 文件，用于描述：
- 包中的哪些函数/方法可能会失败
- 它们是如何失败的（抛出错误、reject 的 promise、错误事件）
- 调用者必须做什么来处理这些失败
`axios` 的 Contract 示例：
```
package: axios
version: ">=0.21.0"
status: stable
imports:
- module: axios
default: axios
named: [isAxiosError, AxiosError]
postconditions:
- id: network-error-handling
description: "HTTP requests must be wrapped in try-catch"
severity: error
trigger:
function_call:
object: axios
methods: [get, post, put, patch, delete, request, head, options]
requires:
error_handling:
type: try-catch
```
## 结构
```
nark-corpus/
├── packages/
│ ├── axios/
│ │ ├── contract.yaml # Contract definition
│ │ ├── SOURCES.md # Research sources
│ │ └── fixtures/ # Test fixtures
│ ├── @prisma/client/
│ │ ├── contract.yaml
│ │ ├── SOURCES.md
│ │ └── fixtures/
│ └── ...149 more packages
├── schema/
│ └── contract.schema.json # JSON Schema for contracts
├── scripts/
│ └── validate-contracts.js # Validation script
└── package.json
```
## 涵盖的包 (169+)
| 类别 | 包 |
|----------|----------|
| HTTP 客户端 | axios, got, node-fetch, undici, superagent, ky |
| 数据库 | prisma, knex, sequelize, typeorm, drizzle-orm, pg, mysql2, better-sqlite3, mongoose |
| Redis | ioredis, redis |
| 云服务 - AWS | @aws-sdk/client-s3, client-dynamodb, client-ses, client-sqs, 以及更多 |
| 云服务 - GCP | @google-cloud/storage, bigquery, pubsub, firestore |
| 云服务 - Azure | @azure/storage-blob, cosmos, identity |
| 认证 | jsonwebtoken, bcrypt, passport, @clerk/*, @auth0/* |
| 队列 | bullmq, amqplib, kafkajs, bee-queue |
| AI/ML | openai, @anthropic-ai/sdk, @langchain/*, @mistralai/* |
| 邮件 | nodemailer, @sendgrid/mail, resend, postmark |
| 支付 | stripe, @paypal/checkout-server-sdk |
| 框架 | express, fastify, @nestjs/*, @hapi/* |
| 文件/存储 | sharp, multer, fs-extra, archiver |
| 监控 | @sentry/node, winston, pino, @datadog/* |
| 以及更多... | 额外 50+ 个包 |
## 使用该语料库
### 配合 nark 使用（推荐）
```
npm install nark nark-corpus
npx nark --tsconfig ./tsconfig.json
```
### 编程式访问
```
import { getCorpusPath, getSchemaPath, getCorpusInfo } from 'nark-corpus';
// Get the path to the packages directory
const corpusPath = getCorpusPath();
// Get version and path info
const info = getCorpusInfo();
```
### 验证 contract
```
npm run validate
```
## 贡献 Contract
1. 按照 schema 创建 `packages/
/contract.yaml`
2. 添加 `SOURCES.md`，链接到官方文档、错误参考、changelogs
3. 在 `packages//fixtures/` 中添加测试 fixtures
4. 运行 `npm run validate` 检查你的 contract
5. 提交一个 PR
完整 contract schema 请参见 `schema/contract.schema.json`。
## License
CC-BY-4.0 —— 这些契约可免费使用，但需注明出处。