Skip to content

Add GitHub Copilot instructions configuration #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 12, 2025
Merged

Add GitHub Copilot instructions configuration #87

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b7c8cf0
Initial plan
Copilot Nov 12, 2025
d4bc7d2
Add GitHub Copilot instructions configuration
Copilot Nov 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
242 changes: 242 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,242 @@
# Copilot Coding Agent Instructions

## Project Overview

**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.

### Key Features
- Lightweight with minimal dependencies (only fast-querystring)
Copy link

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The claim that fast-querystring is a dependency is incorrect. The package.json file shows no 'dependencies' section at all, meaning there are zero production dependencies. The query string functionality is implemented in the local src/querystring/ directory, not via an external package.

Suggested change
- Lightweight with minimal dependencies (only fast-querystring)
- Lightweight with zero production dependencies (query string functionality is implemented locally)

Copilot uses AI. Check for mistakes.
- Type-safe with full TypeScript definitions
- URL-safe with automatic parameter escaping
- Unicode-aware using `codePointAt` for proper Unicode handling
- Multiple ways to build URLs for different use cases

### Tech Stack
- **Language**: TypeScript
- **Runtime**: Node.js (with support for Bun and Deno)
- **Build Tool**: tsdown (powered by rolldown)
- **Testing**: Vitest with coverage reporting
- **Linting/Formatting**: Biome
- **Benchmarking**: CodSpeed
- **Package Manager**: Bun (but npm/pnpm also work)

## Building the Project

### Prerequisites
- Node.js (reasonably recent version)
- Bun installed (recommended) or npm

### Installation
```bash
# Clone the repository
git clone [email protected]:hckhanh/fast-url.git
cd fast-url

# Install dependencies
bun install
# OR
npm install
```

### Build Commands
```bash
# Build the library (outputs to dist/)
bun run build
# OR
npm run build
```

The build process uses tsdown to compile TypeScript and bundle the library. Output appears in the `dist/` directory.

## Running Tests

### Test Commands
```bash
# Run all tests
bun test
# OR
npm test

# Run tests with coverage
bun run test --coverage
Copy link

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] The command should be bun test --coverage (without run), as shown in the actual test.yml workflow which uses bun run test --coverage but the package.json script is just test: vitest. Using bun run test --coverage would work, but the simpler bun test --coverage is more consistent with line 56.

Suggested change
bun run test --coverage
bun test --coverage

Copilot uses AI. Check for mistakes.

# Run benchmarks
bun run bench
# OR
npm run bench
```

### Test Structure
- Tests are located in the `test/` directory
- Test files follow the pattern `*.test.ts`
- Tests use Vitest as the test runner
- All new features should have corresponding tests in the `test/` directory

### Test Coverage Requirements
- The project uses Codecov for coverage reporting
- Tests should maintain high coverage standards
- Coverage reports are uploaded automatically in CI

## Code Style and Formatting

### Biome Configuration
The project uses Biome for linting and formatting with the following standards:
- **Indent**: 2 spaces
- **Quotes**: Single quotes for JavaScript/TypeScript
- **Semicolons**: As needed (ASNeeded style)
- **Arrow Parentheses**: Always
- **Import Organization**: Automatic via Biome

### Format and Lint Commands
```bash
# Check and auto-fix formatting/linting issues
bun run format
# OR
npm run format

# Check without auto-fixing
bun biome check
# OR
npx biome check
```

### Important Rules
- **No unused imports**: Warnings with safe auto-fix
- **Use consistent type definitions**: Warnings with safe auto-fix
- **Use Node.js import protocol**: Warnings with safe auto-fix
- **Template literals**: Off (string concatenation allowed)

### Before Committing
Always run `bun run format` or `npm run format` before committing to ensure code style compliance.

## Dependencies

### Production Dependencies
- **fast-querystring**: The only production dependency, used for query string building
Copy link

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is incorrect. The package.json file has no production dependencies. The query string functionality is implemented locally in src/querystring/stringify.ts and src/querystring/node.ts, not imported from fast-querystring. This section should either be removed or corrected to state 'No production dependencies'.

Suggested change
- **fast-querystring**: The only production dependency, used for query string building
- None (all query string functionality is implemented locally)

Copilot uses AI. Check for mistakes.

### Development Dependencies
- **@biomejs/biome**: Code formatting and linting
- **@changesets/cli**: Release management
- **@codspeed/vitest-plugin**: Performance benchmarking
- **@vitest/coverage-v8**: Test coverage reporting
- **knip**: Dead code detection
- **syncpack**: Keep package versions in sync
- **tsdown**: Build tool
- **typescript**: Type checking and compilation
- **vitest**: Testing framework

### Adding New Dependencies
- Keep the dependency footprint minimal
- Prefer well-maintained, popular libraries
- Ensure TypeScript type definitions are available
- Run tests after adding dependencies to ensure compatibility

## Project Structure

```
fast-url/
├── .github/ # GitHub configuration and workflows
├── benchmark/ # Performance benchmark tests
├── dist/ # Build output (gitignored)
├── docs/ # Documentation assets
├── src/ # Source code
│ ├── index.ts # Main entry point
│ └── querystring/ # Query string utilities
├── test/ # Test files
├── tools/ # Build and development tools
└── web/ # Website/demo workspace
```

## CI/CD and Quality Gates

### GitHub Actions Workflows
1. **Test Workflow** (`test.yml`):
- Runs Knip for dead code detection
- Runs Deno type checking
- Runs unit tests with coverage
- Runs benchmarks with CodSpeed
- Uploads coverage to Codecov

2. **CodeQL** (`codeql.yml`):
- Security analysis for JavaScript/TypeScript

3. **Release** (`release.yml`):
- Automated releases via changesets

4. **Scorecards** (`scorecards.yml`):
- Security best practices scoring

### Quality Standards
- All tests must pass
- Code coverage should be maintained or improved
- No Biome linting errors
- No unused code (verified by Knip)
- Security scanning via CodeQL and Scorecards
- Socket Firewall enabled for dependency security

### Pull Request Requirements
- PRs must pass all CI checks
- Tests should be added for new features
- Code should be formatted with Biome
- Coverage should not decrease
- Security scans must pass

## Documentation

### Updating Documentation
- Update `README.md` when adding new features or changing APIs
- Add JSDoc comments to exported functions
- Update `CHANGELOG.md` via changesets (run `changeset` command)
- Keep inline code examples up to date

### Documentation Files
- `README.md`: Main project documentation and usage examples
- `CONTRIBUTING.md`: Contribution guidelines
- `OPTIMIZATION_GUIDE.md`: Performance optimization notes
- `QUERYSTRING_UPDATE_SUMMARY.md`: Query string implementation details
- `CODE_OF_CONDUCT.md`: Code of conduct
- `SECURITY.md`: Security policy

## Restrictions and Guidelines

### Do NOT
- **Remove or modify tests** unless they are broken or outdated
- **Add unnecessary dependencies** - keep the library lightweight
- **Break backward compatibility** without major version bump
- **Modify files in `dist/`** - these are build artifacts
- **Commit build artifacts** - `dist/` is gitignored
- **Change core algorithms** without benchmarking performance impact
- **Remove security features** like parameter escaping

### Do
- **Write minimal, focused changes**
- **Add tests for new features**
- **Run format and tests before committing**
- **Update documentation for API changes**
- **Use TypeScript for type safety**
- **Maintain performance characteristics**
- **Follow existing code patterns and conventions**

## Performance Considerations

This library is focused on performance. When making changes:
- Run benchmarks before and after changes (`bun run bench`)
- Avoid unnecessary allocations
- Consider the impact on bundle size
- Test with large inputs when relevant
- Use efficient algorithms and data structures

The project uses CodSpeed for continuous performance monitoring in CI.

## Support and Contact

- **Issues**: https://github.com/hckhanh/fast-url/issues
- **Email**: [email protected]
- **Homepage**: https://fast-url.khanh.id

## Additional Resources

- [urlcat (original library)](https://github.com/balazsbotond/urlcat)
- [Vitest Documentation](https://vitest.dev/)
- [Biome Documentation](https://biomejs.dev/)
- [tsdown Documentation](https://tsdown.deno.dev/)