Thank you for your interest in contributing to xterm-mouse! This document provides guidelines and instructions for contributing to the project.
- Bun: This project uses Bun as its runtime and package manager. Install it from bun.sh.
- Git: For version control.
git clone https://github.com/neiromaster/xterm-mouse.git
cd xterm-mousebun installbun run buildThis compiles the TypeScript code into the dist/ directory and generates type declaration files.
xterm-mouse/
├── src/
│ ├── core/
│ │ ├── Mouse.ts # Main Mouse class implementation
│ │ └── Mouse.test.ts # Tests for Mouse class
│ ├── parser/
│ │ ├── ansiParser.ts # ANSI escape sequence parser
│ │ ├── ansiParser.test.ts
│ │ └── constants.ts # Parser constants
│ ├── types/
│ │ └── index.ts # TypeScript type definitions
│ └── index.ts # Main entry point
├── examples/
│ ├── basic.ts # Basic usage example
│ └── streaming.ts # Streaming API example
├── package.json
├── tsup.config.ts # Build configuration
└── tsconfig.json # TypeScript configuration
The project includes examples that demonstrate the library's usage:
# Run the basic example with hot-reloading
bun run dev:basic
# Run the streaming example with hot-reloading
bun run dev:streamingNote
The examples use --watch mode, so any changes you make will automatically restart the example.
# Run all tests
bun test
# Run tests with coverage
bun run coveragebun run typecheckThis runs TypeScript compiler to check for type errors without emitting files.
This project uses:
- Biome: For fast linting and formatting.
- dprint: For additional code formatting.
bun run lintbun run formatThis automatically formats your code according to the project's style guide.
The project uses lefthook to run pre-commit checks. These are automatically installed when you run bun install. The hooks ensure that:
- Code is properly formatted
- Linting passes
- Tests pass
Caution
If you need to bypass pre-commit hooks (not recommended), use git commit --no-verify.
Use descriptive branch names:
feature/for new features (e.g.,feature/add-wheel-support)fix/for bug fixes (e.g.,fix/coordinate-parsing)docs/for documentation updates (e.g.,docs/update-readme)refactor/for code refactoring (e.g.,refactor/parser-architecture)
Write clear, descriptive commit messages:
feat: add support for horizontal wheel scrolling
fix: correct coordinate calculation in SGR mode
docs: update API documentation for stream() method
refactor: simplify event queue management
Follow the Conventional Commits specification:
feat:for new featuresfix:for bug fixesdocs:for documentation changesrefactor:for code refactoringtest:for adding or updating testschore:for maintenance tasks
-
Fork the repository and create your branch from
main. -
Make your changes following the code style guidelines.
-
Test your changes:
bun test bun run typecheck bun run lint -
Update documentation if your changes affect the API or usage.
-
Commit your changes with a clear commit message.
-
Push to your fork and create a pull request.
- Provide a clear description of the changes and why they're necessary.
- Link related issues using
#issue-number. - Ensure all CI checks pass.
- Keep changes focused and minimal.
- Update tests to cover new functionality.
Tests should be placed alongside the source files they test with a .test.ts suffix:
src/core/Mouse.ts → src/core/Mouse.test.ts
src/parser/ansiParser.ts → src/parser/ansiParser.test.ts
import { test, expect } from "bun:test";
test("descriptive test name", () => {
// Arrange
const input = /* test input */;
// Act
const result = /* function call */;
// Assert
expect(result).toBe(/* expected value */);
});- Keep documentation in sync with code changes.
- Use clear examples in code comments.
- Update README.md if you add new features or change the API.
- Follow the existing documentation style in README.md.
- GitHub Issues: Use GitHub Issues for bug reports and feature requests.
- Discussions: Use GitHub Discussions for questions and general topics.
Be respectful, inclusive, and constructive. We aim to maintain a welcoming community for all contributors.
By contributing to xterm-mouse, you agree that your contributions will be licensed under the same license as the project.