Skip to content

Commit 48c9ac5

Browse files
CopilotCopilot
authored
Add GitHub Copilot instructions configuration (#87)
1 parent 22e19bf commit 48c9ac5

File tree

1 file changed

+242
-0
lines changed

1 file changed

+242
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
# Copilot Coding Agent Instructions
2+
3+
## Project Overview
4+
5+
**fast-url** is a high-performance TypeScript/JavaScript library for building URLs safely and conveniently. It's a fork of [urlcat](https://github.com/balazsbotond/urlcat) with a focus on performance and simplicity.
6+
7+
### Key Features
8+
- Lightweight with minimal dependencies (only fast-querystring)
9+
- Type-safe with full TypeScript definitions
10+
- URL-safe with automatic parameter escaping
11+
- Unicode-aware using `codePointAt` for proper Unicode handling
12+
- Multiple ways to build URLs for different use cases
13+
14+
### Tech Stack
15+
- **Language**: TypeScript
16+
- **Runtime**: Node.js (with support for Bun and Deno)
17+
- **Build Tool**: tsdown (powered by rolldown)
18+
- **Testing**: Vitest with coverage reporting
19+
- **Linting/Formatting**: Biome
20+
- **Benchmarking**: CodSpeed
21+
- **Package Manager**: Bun (but npm/pnpm also work)
22+
23+
## Building the Project
24+
25+
### Prerequisites
26+
- Node.js (reasonably recent version)
27+
- Bun installed (recommended) or npm
28+
29+
### Installation
30+
```bash
31+
# Clone the repository
32+
git clone [email protected]:hckhanh/fast-url.git
33+
cd fast-url
34+
35+
# Install dependencies
36+
bun install
37+
# OR
38+
npm install
39+
```
40+
41+
### Build Commands
42+
```bash
43+
# Build the library (outputs to dist/)
44+
bun run build
45+
# OR
46+
npm run build
47+
```
48+
49+
The build process uses tsdown to compile TypeScript and bundle the library. Output appears in the `dist/` directory.
50+
51+
## Running Tests
52+
53+
### Test Commands
54+
```bash
55+
# Run all tests
56+
bun test
57+
# OR
58+
npm test
59+
60+
# Run tests with coverage
61+
bun run test --coverage
62+
63+
# Run benchmarks
64+
bun run bench
65+
# OR
66+
npm run bench
67+
```
68+
69+
### Test Structure
70+
- Tests are located in the `test/` directory
71+
- Test files follow the pattern `*.test.ts`
72+
- Tests use Vitest as the test runner
73+
- All new features should have corresponding tests in the `test/` directory
74+
75+
### Test Coverage Requirements
76+
- The project uses Codecov for coverage reporting
77+
- Tests should maintain high coverage standards
78+
- Coverage reports are uploaded automatically in CI
79+
80+
## Code Style and Formatting
81+
82+
### Biome Configuration
83+
The project uses Biome for linting and formatting with the following standards:
84+
- **Indent**: 2 spaces
85+
- **Quotes**: Single quotes for JavaScript/TypeScript
86+
- **Semicolons**: As needed (ASNeeded style)
87+
- **Arrow Parentheses**: Always
88+
- **Import Organization**: Automatic via Biome
89+
90+
### Format and Lint Commands
91+
```bash
92+
# Check and auto-fix formatting/linting issues
93+
bun run format
94+
# OR
95+
npm run format
96+
97+
# Check without auto-fixing
98+
bun biome check
99+
# OR
100+
npx biome check
101+
```
102+
103+
### Important Rules
104+
- **No unused imports**: Warnings with safe auto-fix
105+
- **Use consistent type definitions**: Warnings with safe auto-fix
106+
- **Use Node.js import protocol**: Warnings with safe auto-fix
107+
- **Template literals**: Off (string concatenation allowed)
108+
109+
### Before Committing
110+
Always run `bun run format` or `npm run format` before committing to ensure code style compliance.
111+
112+
## Dependencies
113+
114+
### Production Dependencies
115+
- **fast-querystring**: The only production dependency, used for query string building
116+
117+
### Development Dependencies
118+
- **@biomejs/biome**: Code formatting and linting
119+
- **@changesets/cli**: Release management
120+
- **@codspeed/vitest-plugin**: Performance benchmarking
121+
- **@vitest/coverage-v8**: Test coverage reporting
122+
- **knip**: Dead code detection
123+
- **syncpack**: Keep package versions in sync
124+
- **tsdown**: Build tool
125+
- **typescript**: Type checking and compilation
126+
- **vitest**: Testing framework
127+
128+
### Adding New Dependencies
129+
- Keep the dependency footprint minimal
130+
- Prefer well-maintained, popular libraries
131+
- Ensure TypeScript type definitions are available
132+
- Run tests after adding dependencies to ensure compatibility
133+
134+
## Project Structure
135+
136+
```
137+
fast-url/
138+
├── .github/ # GitHub configuration and workflows
139+
├── benchmark/ # Performance benchmark tests
140+
├── dist/ # Build output (gitignored)
141+
├── docs/ # Documentation assets
142+
├── src/ # Source code
143+
│ ├── index.ts # Main entry point
144+
│ └── querystring/ # Query string utilities
145+
├── test/ # Test files
146+
├── tools/ # Build and development tools
147+
└── web/ # Website/demo workspace
148+
```
149+
150+
## CI/CD and Quality Gates
151+
152+
### GitHub Actions Workflows
153+
1. **Test Workflow** (`test.yml`):
154+
- Runs Knip for dead code detection
155+
- Runs Deno type checking
156+
- Runs unit tests with coverage
157+
- Runs benchmarks with CodSpeed
158+
- Uploads coverage to Codecov
159+
160+
2. **CodeQL** (`codeql.yml`):
161+
- Security analysis for JavaScript/TypeScript
162+
163+
3. **Release** (`release.yml`):
164+
- Automated releases via changesets
165+
166+
4. **Scorecards** (`scorecards.yml`):
167+
- Security best practices scoring
168+
169+
### Quality Standards
170+
- All tests must pass
171+
- Code coverage should be maintained or improved
172+
- No Biome linting errors
173+
- No unused code (verified by Knip)
174+
- Security scanning via CodeQL and Scorecards
175+
- Socket Firewall enabled for dependency security
176+
177+
### Pull Request Requirements
178+
- PRs must pass all CI checks
179+
- Tests should be added for new features
180+
- Code should be formatted with Biome
181+
- Coverage should not decrease
182+
- Security scans must pass
183+
184+
## Documentation
185+
186+
### Updating Documentation
187+
- Update `README.md` when adding new features or changing APIs
188+
- Add JSDoc comments to exported functions
189+
- Update `CHANGELOG.md` via changesets (run `changeset` command)
190+
- Keep inline code examples up to date
191+
192+
### Documentation Files
193+
- `README.md`: Main project documentation and usage examples
194+
- `CONTRIBUTING.md`: Contribution guidelines
195+
- `OPTIMIZATION_GUIDE.md`: Performance optimization notes
196+
- `QUERYSTRING_UPDATE_SUMMARY.md`: Query string implementation details
197+
- `CODE_OF_CONDUCT.md`: Code of conduct
198+
- `SECURITY.md`: Security policy
199+
200+
## Restrictions and Guidelines
201+
202+
### Do NOT
203+
- **Remove or modify tests** unless they are broken or outdated
204+
- **Add unnecessary dependencies** - keep the library lightweight
205+
- **Break backward compatibility** without major version bump
206+
- **Modify files in `dist/`** - these are build artifacts
207+
- **Commit build artifacts** - `dist/` is gitignored
208+
- **Change core algorithms** without benchmarking performance impact
209+
- **Remove security features** like parameter escaping
210+
211+
### Do
212+
- **Write minimal, focused changes**
213+
- **Add tests for new features**
214+
- **Run format and tests before committing**
215+
- **Update documentation for API changes**
216+
- **Use TypeScript for type safety**
217+
- **Maintain performance characteristics**
218+
- **Follow existing code patterns and conventions**
219+
220+
## Performance Considerations
221+
222+
This library is focused on performance. When making changes:
223+
- Run benchmarks before and after changes (`bun run bench`)
224+
- Avoid unnecessary allocations
225+
- Consider the impact on bundle size
226+
- Test with large inputs when relevant
227+
- Use efficient algorithms and data structures
228+
229+
The project uses CodSpeed for continuous performance monitoring in CI.
230+
231+
## Support and Contact
232+
233+
- **Issues**: https://github.com/hckhanh/fast-url/issues
234+
- **Email**: [email protected]
235+
- **Homepage**: https://fast-url.khanh.id
236+
237+
## Additional Resources
238+
239+
- [urlcat (original library)](https://github.com/balazsbotond/urlcat)
240+
- [Vitest Documentation](https://vitest.dev/)
241+
- [Biome Documentation](https://biomejs.dev/)
242+
- [tsdown Documentation](https://tsdown.deno.dev/)

0 commit comments

Comments
 (0)