贡献指南

感谢你对 Nudo 的贡献兴趣。本文档涵盖环境准备、项目结构、开发流程以及如何扩展系统。

环境要求

npm install -g pnpm

git clone https://github.com/nudojs/nudo.git
cd nudo
pnpm install
pnpm run build

本 monorepo 使用 pnpm workspaces。主要包如下：

包	描述
`@nudojs/core`	类型系统（Abs 代数）、外延渲染（format）、Environment
`@nudojs/parser`	Babel 解析、指令提取、`parseCaseArgExpr`
`@nudojs/cli`	仅 CLI 命令（`infer`、`check`、`types`、`watch`、`generate`、`harvest`、`test`、`interface`）
`@nudojs/service`	高层 API：`analyzeFile`、`getTypeAtPosition`、`getCompletionsAtPosition`
`@nudojs/lsp`	Language Server Protocol 实现，含面向 AI agent 的 executeCommand/自定义请求（见 Agent 集成指南）
`@nudojs/harvester`	把 `@types/*.d.ts` 声明转换为 Nudo env 文件（`nudo harvest` 的底层引擎）
`@nudojs/env`	内置环境类型定义（`/// @nudo:env es\|web\|node`，子路径导出 `/es` `/web` `/node`）
`vite-plugin-nudo`	开发阶段的类型推断 Vite 插件
`nudo-vscode`	VS Code / Cursor 扩展
`website`	Docusaurus 文档站点

pnpm run test
pnpm run test:watch   # 监视模式

pnpm run build

pnpm exec tsx packages/cli/src/index.ts infer path/to/file.js
# 或
pnpm exec nudo infer path/to/file.js

运算符语义在代数中实现，不存在独立的 Ops 层：

二元算术 / 比较 — packages/core/src/algebra/arithmetic.ts（Abs → Abs）。一元运算与严格相等在 packages/core/src/algebra/surface.ts（typeofAbs、negAbs、notAbs、strictEqAbs）。
分支合并辅助 — packages/service/src/evaluator/abs-route.ts（tryAbsJoinObjects、φ 约束辅助）在分支合并时 join 对象形状。
添加测试，位于 packages/core/src/algebra/__tests__/（如 surface.test.ts、arithmetic.test.ts）或 packages/service/src/__tests__/。

在 packages/parser/src/directives.ts 中定义指令类型：

export type MyDirective = { kind: "my"; param: string };
export type Directive = CaseDirective | ... | MyDirective;

在 parseDirectivesFromComments 中添加正则与解析逻辑：

const MY_REGEX = /@nudo:my\s+(\w+)/g;
// 在循环中：match、extract、push { kind: "my", param: ... }

在求值器或 service 中使用指令：
- packages/cli/src/index.ts 或 packages/service/src/analyzer.ts 中实现分析行为。
- 用 d.kind === "my" 过滤 fn.directives 并应用你的逻辑。
若指令接收类型表达式参数，需更新 parseCaseArgExpr。
添加测试，位于 packages/parser/src/__tests__/directives*.test.ts。

保持 PR 聚焦；宁可多个小 PR，也不要一个大 PR。
为新行为添加或更新测试。
提交前运行 pnpm run build 和 pnpm run test。
添加指令或公开 API 时更新文档（如 docs/concepts/directives.md、API 参考）。
文档防漂移规则：修改 CLI 命令/选项、导出 API 或指令语法时，必须在同一个 PR 中同步更新 packages/website 下的文档 —— 英文源（docs/）与中文镜像（i18n/zh-Hans/docusaurus-plugin-content-docs/current/）都要改。