# 配置规范

配置文件默认位于 release domain 根的 `.changeset/config.json`，除非使用 `--config`。单生态时 domain 通常等于 workspace 根；混合时可包含多个 workspace。配置 schema 版本为 `1`；未知顶层字段默认报错，实验字段位于 `experimental` 对象。本地 JSON Schema 草案见 [schema/config-v1.json](schema/config-v1.json)；下方远端 `$schema` 地址仅为预留标识，尚未验证托管可用性。

## 1. 合并优先级

```text
defaults < .changeset/config.json < MOONSET_*（仅非机密运行选项） < CLI
```

环境变量只用于 CI 的运行开关和凭据引用，例如 `MOONSET_NON_INTERACTIVE=1`、`MOONSET_REGISTRY_TOKEN_ENV=NPM_TOKEN`；配置文件和日志永远不包含 token 本身。

## 2. 默认配置

```json
{
  "$schema": "https://moonset.dev/schema/config-v1.json",
  "schemaVersion": 1,
  "changelog": { "generator": "builtin", "file": "CHANGELOG.md" },
  "commit": { "mode": "never", "addMessage": "chore: add changeset", "versionMessage": "chore: release" },
  "baseBranch": "main",
  "access": "public",
  "updateInternalDependencies": "patch",
  "updateInternalDependents": "out-of-range",
  "changedFilePatterns": ["**"],
  "fixed": [],
  "linked": [],
  "ignore": [],
  "privatePackages": { "version": false, "tag": false, "publish": false },
  "pre": { "file": ".changeset/pre.json", "directory": ".changeset/pre" },
  "snapshot": { "enabled": false, "useCalculatedVersion": false, "prereleaseTemplate": "{tag}-{datetime}" },
  "tag": { "create": true, "afterPublish": true, "format": "auto", "push": false },
  "publisher": { "kind": "moon", "registry": "default", "dryRunFirst": true },
  "format": "auto",
  "github": { "links": true, "thanks": true }
}
```

## 3. 字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| `changelog` | object/false | `generator` 为 `builtin`、`git`、`github` 或自定义 API 名；`options` 传给生成器。 |
| `commit` | object/false | `mode` 为 `never`、`add`、`version`、`both`；默认不自动提交。 |
| `baseBranch` | string | `status --since` 和 Action 默认比较分支。 |
| `access` | `public/restricted` | 传给 publisher 的可见性请求；最终由 registry 权限决定。 |
| `updateInternalDependencies` | `patch/minor` | 已参与发布的单元更新依赖声明时，上游变更的最低级别；越界时始终更新。默认 patch。 |
| `updateInternalDependents` | `out-of-range/always` | 是否把尚未参与发布的依赖者带入 patch 发布；默认仅越界时带入。 |
| `fixed` | string[][] | 每组包共享同一目标版本。支持精确名称与 `*`/`?`/`[...]`/`{...}`/`(...)` glob 匹配；展开后若发生跨组重叠则报错。 |
| `linked` | string[][] | 一组包共享版本线，但没有变更时不强制发布。支持精确名称与 glob 匹配。 |
| `ignore` | string[] | 暂时跳过的包（支持精确名称与 glob 匹配）；若与非 ignore 包存在必须联动的依赖，规划失败。 |
| `privatePackages` | object | 分别控制 version、tag、publish，默认全关；不能绕过 npm `private: true` 等原生发布禁令。MoonBit 的 restricted visibility 不等于 npm private。 |
| `pre` | object | 预发布状态文件（默认 `.changeset/pre.json`）和 changeset 隔离目录（默认 `.changeset/pre`）；active 预发布期间已消费 changeset 会原子迁入隔离目录并在 `pre exit` 毕业时统一清理。 |
| `snapshot` | object | 快照版本开关（`enabled`，默认 `false`）、基准版本策略（`useCalculatedVersion`，`false` 使用 `0.0.0`，`true` 使用计算版本）与预发布模板（`prereleaseTemplate`，默认 `{tag}-{datetime}`，支持 `{tag}`、`{datetime}`、`{commit}`、`{version}`）。 |
| `tag` | object | 标签创建时机、模板策略和推送开关。 |
| `publisher` | object | `moon`、`command` 或 `api` publisher；`command` 走参数化 JSONL 协议，`api` 通过 `ApiPublisherRegistry` + `publish_release_with_api` 编程接入；`registry` 支持全局值或分目标映射（如 `npm=https://...,cargo=private`）。 |
| `changedFilePatterns` | string[] | `status --since` 认定包发生变化的 glob 列表，支持 `*`、`**`、`?`、`[...]`、`{...}`、`(...)`/extglob 与 `!` 否定过滤。 |
| `formatter` | string | 格式化工具选择：`builtin`、`prettier`、`oxfmt`、`biome`、`dprint`；默认 `builtin`。 |
| `format` | string/false | `auto`（跟随 `formatter`）、`false`（禁用自动格式化）或直接指定外部格式化工具名；可被 CLI `--no-format` 覆盖。 |
| `github` | object | changelog 链接和感谢语开关；PR Bot 行为由 Action 输入控制，见 [自动化设计](automation.md) §5。 |
| `experimental.mixedWorkspaces` | object | 混合 domain 的 workspace、UnitId 覆盖、bridge 和锁文件策略；Proposed，见下节。 |

## 4. 示例

```json
{
  "schemaVersion": 1,
  "baseBranch": "main",
  "access": "public",
  "fixed": [["unmbt/core", "unmbt/cli"]],
  "linked": [["unmbt/plugin-a", "unmbt/plugin-b"]],
  "updateInternalDependencies": "patch",
  "privatePackages": { "version": true, "tag": false, "publish": false },
  "changelog": {
    "generator": "github",
    "options": { "repo": "unmbt/moonset", "disableThanks": false }
  },
  "tag": { "create": true, "afterPublish": true, "format": "{name}@{version}", "push": false },
  "snapshot": { "enabled": true, "useCalculatedVersion": true, "prereleaseTemplate": "{tag}-{datetime}" },
  "publisher": { "kind": "moon", "registry": "default", "dryRunFirst": true }
}
```

## 5. 设计约束

- 默认值必须在 `Config::default` 中集中定义，不能散落到命令实现。
- CLI flag 覆盖配置，但不能把安全检查静默关闭；如 `--allow-uncommitted` 必须出现在 plan 和日志中。
- `fixed`、`linked`、`ignore` 与 `changedFilePatterns` 的 glob 语法在 `parse_config` 阶段完成合法性校验；`changedFilePatterns` 相对模块目录按顺序求值（支持 `!` 否定排除）。
- 外部格式化器仅对工具本身支持的文件扩展名执行（排除 `.moonset/` 内部状态文件），且通过可执行文件与参数数组直接调用（禁止 shell 插值）。
- `changelog` 和 `publisher` 的自定义名称只能引用注册的 MoonBit API 或显式允许的外部命令。
- 配置错误在任何写操作前报告；错误消息包含 JSON path，例如 `$.tag.format`。

## 6. 混合 workspace（实验草案）

Phase 1 接受 MoonBit-only 的显式 coexist 分区；同目录 JS/Cargo 文件报告 unmanaged。显式声明 npm/Cargo workspace、unified 模式或非空 bridges 会报能力错误。其他执行阶段字段只做配置验证，不执行生成器、格式化器或 publisher。缺失默认配置时采用默认值；显式指定不存在的配置时报错。

详见 [混合 workspace 设计](mixed-workspaces.md) 和 [完整配置示例](examples/mixed-workspaces.json)。该扩展已加入本地 JSON Schema，以便验证文档形状；通过 schema 不代表 CLI 已实现该能力。

| 子字段 | 契约 |
|---|---|
| `mode` | `coexist` 分区共存，或 `unified` 统一管理；不自动接管已有 Changesets 的目录。 |
| `workspaces` | 显式 `{id, ecosystem, root, manager, includeRoot}`；路径相对 domain。npm/pnpm 共用 `npm` 生态。 |
| `units` | 已发现 UnitId 的 `publish`、`publisher`、`tagFormat` 与可选 `artifacts`（`{target, package?, required?, path?}`）覆盖；不得用未知 ID 隐式创建源码单元。 |
| `bridges` | `{consumer, producer, kind: "build", bump, waitFor}`；构建依赖，默认不改原生依赖声明。 |
| `lockfiles` | `refresh`（缺省）在 staging 刷新并审阅；`verify-only` 在预期锁文件需变化时失败。 |

混合模式 `fixed`、`linked`、`ignore` 使用完整 UnitId。未覆盖的 publisher 按生态选择：MoonBit → moon，npm → npm；全局 moon publisher 不作用于 JS。全局显式指定 incompatible publisher 则报错。`tagFormat` 的生态模板用于避免同名跨生态 Git tag 冲突；不能直接使用包含冒号的 UnitId。

schema 可校验结构和 manager/生态配对；重复 workspace ID、路径越界、字段所有权、不存在的 UnitId、依赖环和 publisher 能力需要语义校验。`cargo` 在 schema 中保留，但在 Cargo adapter 发布前必须返回 unsupported capability。


### External changelog generators

External generators are registered under `plugins.generators` with an executable, argv, explicit executable allow-list, environment variable allow-list, timeout, and output limit. `changelog.generator` references the registration name. The process receives one JSONL `generate` request and must return one response whose `result.text` is the changelog; optional metadata participates in the version plan fingerprint. Plugins are trusted processes and do not receive an implicit OS sandbox.

### Cargo workspaces

An experimental mixed workspace can declare `ecosystem: "cargo"` and `manager: "cargo"`. Moonset discovers explicit Cargo workspace members, inherited `workspace.package.version`, path/workspace dependencies, target dependency sections, and `publish = false`. `pack` uses `cargo package --allow-dirty`; `publish` preflights with `cargo publish --dry-run` and targets crates.io. Other Cargo registries and Tauri remain deferred.
