Skip to content

Commit c3c65a5

Browse files
cab-mikeecab-mikee
committed
chore: add clarity and docs
1 parent d7f4d37 commit c3c65a5

File tree

12 files changed

+452
-36
lines changed

12 files changed

+452
-36
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: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
description: General information based on the latest ./README.md content
3+
globs:
4+
---
5+
Update it if APIs change:
6+
7+
# GitLint
8+
9+
> Efficient Git Commit Message Linting and Formatting
10+
11+
GitLint is a tool for enforcing consistent Git commit message conventions. It analyzes commit messages to ensure they follow the [Conventional Commits](https://www.conventionalcommits.org/) specification and other configurable rules.
12+
13+
## Installation
14+
15+
```bash
16+
# Install globally
17+
npm install -g @stacksjs/gitlint
18+
19+
# Or using bun
20+
bun install -g @stacksjs/gitlint
21+
```
22+
23+
_We are looking to get it published as `gitlint` on npm, but it's not allowing us to do so due to `git-lint`. Please npm 🙏🏽_
24+
25+
## Usage
26+
27+
### CLI
28+
29+
```bash
30+
# Check a commit message from a file
31+
gitlint path/to/commit-message.txt
32+
33+
# Use with git commit message hook (common use case)
34+
gitlint --edit $1
35+
36+
# Show help
37+
gitlint --help
38+
```
39+
40+
### Git Hooks Integration
41+
42+
GitLint can automatically install Git hooks for your repository:
43+
44+
```bash
45+
# Install the commit-msg hook
46+
gitlint hooks --install
47+
48+
# Force overwrite if a hook already exists
49+
gitlint hooks --install --force
50+
51+
# Uninstall the hooks
52+
gitlint hooks --uninstall
53+
```
54+
55+
Or manually add to your `.git/hooks/commit-msg` file:
56+
57+
```bash
58+
#!/bin/sh
59+
gitlint --edit "$1"
60+
```
61+
62+
Or use with [husky](https://github.com/typicode/husky):
63+
64+
```jsonc
65+
// package.json
66+
{
67+
"husky": {
68+
"hooks": {
69+
"commit-msg": "gitlint --edit $HUSKY_GIT_PARAMS"
70+
}
71+
}
72+
}
73+
```
74+
75+
## Configuration
76+
77+
Create a `gitlint.config.js` file in your project root:
78+
79+
```js
80+
// gitlint.config.js
81+
module.exports = {
82+
verbose: true,
83+
rules: {
84+
'conventional-commits': 2,
85+
'header-max-length': [2, { maxLength: 72 }],
86+
'body-max-line-length': [2, { maxLength: 100 }],
87+
'body-leading-blank': 2,
88+
'no-trailing-whitespace': 1
89+
},
90+
ignores: [
91+
'^Merge branch',
92+
'^Merge pull request'
93+
]
94+
}
95+
```
96+
97+
### Rule Levels
98+
99+
- `0` or `off`: Disable the rule
100+
- `1` or `warning`: Warning (doesn't cause exit code to be non-zero)
101+
- `2` or `error`: Error (causes exit code to be non-zero)
102+
103+
## Built-in Rules
104+
105+
- `conventional-commits`: Enforces conventional commit format (`<type>(scope): description`)
106+
- `header-max-length`: Enforces a maximum header length
107+
- `body-max-line-length`: Enforces a maximum body line length
108+
- `body-leading-blank`: Enforces a blank line between header and body
109+
- `no-trailing-whitespace`: Checks for trailing whitespace
110+
111+
## Programmatic Usage
112+
113+
```js
114+
import { lintCommitMessage, parseCommitMessage } from '@stacksjs/gitlint'
115+
116+
// Lint a commit message
117+
const result = lintCommitMessage('feat: add new feature')
118+
console.log(result.valid) // true or false
119+
console.log(result.errors) // array of error messages
120+
console.log(result.warnings) // array of warning messages
121+
122+
// Parse a commit message
123+
const parsed = parseCommitMessage('feat(scope): description\n\nBody text\n\nCloses #123')
124+
console.log(parsed.type) // 'feat'
125+
console.log(parsed.scope) // 'scope'
126+
console.log(parsed.references) // [{issue: '123', ...}]
127+
```
128+
129+
## Testing
130+
131+
```bash
132+
bun test
133+
```

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

0 commit comments

Comments
 (0)