diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..3d4a83de2 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,52 @@ +# AI Coding Agent Guidelines for MoonBit Core + +Welcome to the MoonBit Core repository! This document provides essential guidelines for AI coding agents to be productive and effective contributors to this codebase. + +## Project Overview +MoonBit Core is the standard library for the MoonBit language. It is organized into modular packages, each with its own directory. Key files include: +- `moon.pkg.json`: Defines package dependencies. +- `.mbti` files: Generated interfaces for packages, providing a formal description of their public API. +- `.mbt` files: Core implementation files, organized in block style with `///|` separators. +- `_test.mbt` and `_wbtest.mbt`: Blackbox and whitebox test files, respectively. + +The top-level `moon.mod.json` file contains metadata about the entire module. + +## Key Workflows +1. **Code Formatting and Interface Updates**: + - Use `moon fmt` to format code. + - Run `moon info` to update `.mbti` files. If no changes occur, your modifications are safe for external users. + +2. **Testing**: + - Run `moon test` to execute tests. + - Use `moon test --update` to update snapshots when behavior changes. + - Analyze test coverage with `moon coverage analyze > uncovered.log`. + +3. **Linting**: + - Use `moon check` to ensure code adheres to linting rules. + +## Project-Specific Conventions +- **Block Style Organization**: Code blocks are separated by `///|`. The order of blocks is irrelevant, allowing independent processing. +- **Deprecated Code**: Place deprecated blocks in `deprecated.mbt` files within the respective directory. +- **Testing Practices**: Prefer `inspect` for snapshot testing. Use `assert_eq` sparingly, such as in loops with variable snapshots. + +## Integration Points +- **External Dependencies**: Defined per package in `moon.pkg.json`. +- **Cross-Component Communication**: Interfaces are formalized in `.mbti` files, ensuring clear boundaries between packages. + +## Examples +- **Adding a New Function**: + 1. Implement the function in a `.mbt` file, using `///|` to separate blocks. + 2. Update the corresponding `.mbti` file with `moon info`. + 3. Write tests in `_test.mbt` or `_wbtest.mbt`. + 4. Format and lint the code with `moon fmt` and `moon check`. + +- **Refactoring**: + 1. Modify code block by block. + 2. Ensure no unexpected changes in `.mbti` files after running `moon info`. + 3. Verify tests pass and update snapshots if needed. + +## Additional Notes +- Refer to `AGENTS.md` for more detailed refactoring tips. +- Use `agent-todo.md` for small, AI-friendly tasks. + +By following these guidelines, AI agents can contribute effectively to the MoonBit Core project. If any section is unclear or incomplete, please provide feedback for improvement! diff --git a/.github/instructions/interface.instructions.md b/.github/instructions/interface.instructions.md new file mode 100644 index 000000000..3c8b54de1 --- /dev/null +++ b/.github/instructions/interface.instructions.md @@ -0,0 +1,10 @@ +--- +applyTo: **/pkg.generated.mbti +--- + +# MoonBit Interface File + +`pkg.generated.mbti` contains the public API surface for the current package. + +- Execute `moon info` to sync all the interface files with the actual code in the project. +- Any change of the interface files, which reflects the change of the API, should be reviewed carefully. diff --git a/.github/instructions/package.instructions.md b/.github/instructions/package.instructions.md new file mode 100644 index 000000000..8b29e48b7 --- /dev/null +++ b/.github/instructions/package.instructions.md @@ -0,0 +1,9 @@ +--- +applyTo: **/moon.pkg.json +--- + +# MoonBit Package File + +`moon.pkg.json` is the package manifest file for the MoonBit project. It contains metadata about the package, including dependencies, and other configuration options. + +[Reference]: https://docs.moonbitlang.com/en/latest/toolchain/moon/package.html diff --git a/.github/instructions/readme.instructions.md b/.github/instructions/readme.instructions.md new file mode 100644 index 000000000..61d54a7a5 --- /dev/null +++ b/.github/instructions/readme.instructions.md @@ -0,0 +1,10 @@ +--- +applyTo: "**/README.mbt.md" +--- + +# Documentation writing guidlines + +`README.mbt.md` is the documentation whose MoonBit code snippets will be checked and tested. + +- It should be written from the aspect of the user of the API. +- Write actual code. Do not write pseudocode in MoonBit code blocks. diff --git a/.github/prompts/consistency-review.prompt.md b/.github/prompts/consistency-review.prompt.md new file mode 100644 index 000000000..76d88f258 --- /dev/null +++ b/.github/prompts/consistency-review.prompt.md @@ -0,0 +1,26 @@ +--- +mode: agent +model: GPT-4o +description: Review the consistency between APIs +--- + +Your goal is to review the consistency between similar APIs. Ask for the type +names (at least 2) if not provided. + +Find the definition of the type, figure out the directory it locates, and review the `pkg.generated.mbti` file. + +**Criteria** + +1. Clarity and readability of the interface definitions. +2. Consistency in naming conventions and structure. +3. Usability and functionality. + +**Guidelines** + +1. Only keep necessary APIs, such as those can only be defined internally to + achieve the best performance. +2. Follow the existing naming convention of other programming language standard + libraries for familiarity, but prioritize the consistency. + +Be specific on the review. Point out the API that is problematic, together with +arguments, and suggested improvements.