Skip to content

Commit 2708a23

Browse files
cab-mikeecab-mikee
committed
chore: add clarity and cursor rules
1 parent bc2fedb commit 2708a23

File tree

13 files changed

+197
-1
lines changed

13 files changed

+197
-1
lines changed

‎.cursor/rules/code-style.mdc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
description: Code Style & Structure specifics
3+
globs:
4+
---
5+
## Code Style & Structure
6+
7+
- Write concise, technical TypeScript code with accurate examples in the docblock
8+
- If Bun native modules are available, use them
9+
- Use functional and declarative programming patterns; avoid classes unless needed
10+
- Prefer iteration and modularization over code duplication
11+
- Use descriptive variable names with auxiliary verbs (e.g., `isLoading`, `hasError`)
12+
- Use proper jsdoc comments for functions, types, interfaces, and ensure examples are accurate

‎.cursor/rules/documentation.mdc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
description: Documentation specific rules
3+
globs: docs/**/*.md
4+
---
5+
## Documentation
6+
7+
- Write documentation for all functions, types, interfaces, and ensure examples are accurate
8+
- The `./docs` directory is where the vitepress markdown documentation is stored
9+
- Make sure to update the docs markdown files

‎.cursor/rules/error-handling.mdc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Error Handling and Validation specifics
3+
globs:
4+
---
5+
## Error Handling and Validation
6+
7+
- Prioritize error handling: handle errors and edge cases early
8+
- Use early returns and guard clauses
9+
- Implement proper error logging and user-friendly messages
10+
- Use error boundaries for unexpected errors
11+
- when `neverthrow` is available, ensure errors are typed

‎.cursor/rules/key-conventions.mdc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Key code conventions
3+
globs:
4+
---
5+
## Key Conventions
6+
7+
- If there are two equally valid implementations, the browser version should be preferred
8+
- Aim for 100% test coverage
9+
- Avoid usage of `any`
10+
- Reuse eslint-ignore comments where present, unless not needed
11+
- ensure we log everything properly, including for debug reasons

‎.cursor/rules/project-structure.mdc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Project structure information
3+
globs:
4+
---
5+
## Project Structure
6+
7+
- the `./src` directory is the source code
8+
- the `./test` directory is the test code
9+
- the `./bin` directory is the command-line code
10+
- you can also call the CLI via `./clarity ...`
11+
- the `./docs` directory is the documentation

‎.cursor/rules/readme.mdc‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
description: General information based on the latest ./README.md content
3+
globs:
4+
---
5+
Update it if APIs change:
6+
7+
# ts-punycode
8+
9+
A modern TypeScript implementation of Punycode (RFC 3492) with full RFC 5891 support. This library helps you convert Unicode domain names to ASCII (Punycode) and back.
10+
11+
## Features
12+
13+
- 🔄 **Bidirectional Conversion** - Convert between Unicode and Punycode seamlessly
14+
- 📧 **Email Support** - Handles email addresses with Unicode domains
15+
- 💪 **Type-Safe** - Full TypeScript support with comprehensive type definitions
16+
- 🌐 **RFC Compliant** - Implements RFC 3492 and RFC 5891 specifications
17+
- 🧪 **Well-Tested** - Comprehensive test suite ensuring reliability
18+
- 📦 **Zero Dependencies** - Lightweight and self-contained
19+
- 🔍 **Unicode 15.1** - Support for the latest Unicode standard
20+
21+
## Installation
22+
23+
```bash
24+
# Using npm
25+
npm install ts-punycode
26+
27+
# Using yarn
28+
yarn add ts-punycode
29+
30+
# Using pnpm
31+
pnpm add ts-punycode
32+
33+
# Using bun
34+
bun add ts-punycode
35+
```
36+
37+
## Usage
38+
39+
### Basic Usage
40+
41+
```typescript
42+
import punycode from 'ts-punycode'
43+
44+
// Convert Unicode to Punycode
45+
punycode.encode('münchen') // Returns 'mnchen-3ya'
46+
47+
// Convert Punycode to Unicode
48+
punycode.decode('mnchen-3ya') // Returns 'münchen'
49+
50+
// Convert Domain Names
51+
punycode.toASCII('münchen.de') // Returns 'xn--mnchen-3ya.de'
52+
punycode.toUnicode('xn--mnchen-3ya.de') // Returns 'münchen.de'
53+
54+
// Handle Email Addresses
55+
punycode.toASCII('user@münchen.de') // Returns '[email protected]'
56+
punycode.toUnicode('[email protected]') // Returns 'user@münchen.de'
57+
```
58+
59+
### Advanced Usage
60+
61+
```typescript
62+
import punycode from 'ts-punycode'
63+
// import { punycode } from 'ts-punycode'
64+
65+
// Working with Unicode Code Points
66+
const codePoints = punycode.ucs2.decode('☃') // Returns [9731]
67+
const string = punycode.ucs2.encode([9731]) // Returns '☃'
68+
69+
// Version Information
70+
console.log(punycode.version) // Returns current version
71+
```
72+
73+
## API Reference
74+
75+
### Main Methods
76+
77+
- **`encode(input: string): string`**
78+
Converts a string of Unicode symbols to a Punycode string of ASCII-only symbols.
79+
80+
- **`decode(input: string): string`**
81+
Converts a Punycode string of ASCII-only symbols to a string of Unicode symbols.
82+
83+
- **`toASCII(input: string): string`**
84+
Converts a Unicode string representing a domain name or email address to Punycode.
85+
86+
- **`toUnicode(input: string): string`**
87+
Converts a Punycode string representing a domain name or email address to Unicode.
88+
89+
### UCS-2 Utilities
90+
91+
- **`ucs2.decode(string: string): number[]`**
92+
Creates an array containing the numeric code points of each Unicode character.
93+
94+
- **`ucs2.encode(codePoints: number[]): string`**
95+
Creates a string based on an array of numeric code points.
96+
97+
## Error Handling
98+
99+
The library throws `RangeError` with descriptive messages for various error conditions:
100+
101+
- **Overflow**: When input needs wider integers to process
102+
- **Not Basic**: When encountering illegal input >= 0x80 (not a basic code point)
103+
- **Invalid Input**: For general invalid input conditions

‎.cursor/rules/syntax-formatting.mdc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
description: Syntax and Formatting specifics
3+
globs:
4+
---
5+
## Syntax and Formatting
6+
7+
- Use the "function" keyword for pure functions
8+
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements
9+
- Make sure everything is properly commented

‎.cursor/rules/testing.mdc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
description: Testing specifics
3+
globs:
4+
---
5+
## Testing
6+
7+
- Write tests for all functions, types, interfaces, and ensure examples are accurate
8+
- The `./test` directory is where the tests are stored
9+
- Use `bun test` to run the tests
10+
- Use bun native modules for testing from `import { x, y, z } from 'bun:test'`

‎.cursor/rules/typescript.mdc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
description: TypeScript Usage specifics
3+
globs: docs/**/*.md
4+
---
5+
## TypeScript Usage
6+
7+
- Use TypeScript for all code; prefer interfaces over types
8+
- Avoid enums; use `maps` instead, or `as const`
9+
- Use functional components with TypeScript interfaces

‎bun.lock‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"name": "bun-ts-starter",
66
"devDependencies": {
77
"@stacksjs/bumpx": "^0.1.17",
8+
"@stacksjs/clarity": "^0.3.23",
89
"@stacksjs/docs": "^0.70.23",
910
"@stacksjs/eslint-config": "^4.2.1-beta.1",
1011
"@stacksjs/gitlint": "^0.1.5",
@@ -481,6 +482,8 @@
481482

482483
"@stacksjs/clapp": ["@stacksjs/[email protected]", "", { "bin": { "clapp": "dist/bin/cli.js", "@stacksjs/clapp": "dist/bin/cli.js" } }, "sha512-BDmYu9Rk/HHIVc4vQjgQO6MzXNMJvPG6ZGiiEAPQT8EAidx3/6S6O7kyY2UdfJSksiCd5SKFK+WYd1uAs88BrQ=="],
483484

485+
"@stacksjs/clarity": ["@stacksjs/[email protected]", "", { "bin": { "clarity": "dist/bin/cli.js" } }, "sha512-qrQjjcXWueBSM1vr1i0OmEMGYtCICVBtNvpVtoMLXIqR+jKAGRUqvguEOwg9vKth6VKMBqJ0FDpukJVJZhKGcg=="],
486+
484487
"@stacksjs/docs": ["@stacksjs/[email protected]", "", { "dependencies": { "@iconify-json/carbon": "^1.2.8", "@shikijs/vitepress-twoslash": "^3.2.1", "@vite-pwa/assets-generator": "^1.0.0", "@vite-pwa/vitepress": "^1.0.0", "unocss": "^66.0.0", "unplugin-icons": "^22.1.0", "unplugin-vue-components": "^28.4.1", "vite-plugin-pwa": "^1.0.0", "vitepress": "1.6.3" } }, "sha512-kRk/aza/wQAAgF0fhUhG8bUHhqk3RnjBkZyoRW0fvYs3dLaAArJYX/uVquZixlQnqgizGeGZT986tEFjs5Ly+A=="],
485488

486489
"@stacksjs/dtsx": ["@stacksjs/[email protected]", "", { "bin": { "dtsx": "dist/cli.js" } }, "sha512-+u/PEp478qHM8s7xT0AOZowd93mZ/5ptHFyiz0B/gcxmdrdNdM6bLIK5si5Uzy1cR5TOVN4oAB3+WMKDnJ3n1w=="],

0 commit comments

Comments
 (0)