# Architecture

MoonContract 把 OpenAPI 文档编译成只读的运行时契约。各层之间只传递结构化数据，
网络和文件系统被限制在最外层适配器中。

```text
JSON / YAML
    |
    v
OpenAPI parser -----> structured diagnostics
    |
    v
reference resolver + route compiler
    |
    v
Contract
    |-------------------|
    v                   v
request/response     deterministic
validator            mock generator
    |                   |
    |----------|--------|
               v
       case replay / native server / CLI
```

## Packages

- `src/diagnostic`：稳定错误码、位置、文本和 JSON 输出。
- `src/openapi`：OpenAPI AST、JSON/YAML 输入和语义解析。
- `src/contract`：引用解析、路由编译、HTTP 模型和校验器。
- `src/mock`：Schema 值生成、响应选择和生成结果自校验。
- `src/cases`：用例格式、正负用例回放和汇总结果。
- `src/cli`：可测试的纯命令调度，不直接退出进程。
- `src/server`：跨后端请求目标解析与 native HTTP 适配器。
- `cmd/mooncontract`：文件系统、进程退出和服务启动入口。

## Invariants

- 规范包含错误时不会产生 `Contract`。
- 编译后的 Schema 不保留未解析本地引用。
- 同一个 HTTP 方法不能存在两个相同路由形状。
- Mock 响应发送前必须再次通过响应契约校验。
- 相同规范、请求、状态码和 seed 产生相同 JSON 响应。
- 核心包不执行网络请求，外部 `$ref` 永远不会被自动加载。