Skip to content

Commit 11f4188

Browse files
kzndotshkzndotsh
committed
feat: add .cursorrules file for custom linting rules to enforce coding standards
docs: add extensive documentation for development, architecture, and contributing docs: increase markdown line length limit to 300 and disable ordered list prefix rule style: set default markdown formatter in VSCode settings refactor(bot.py): improve task monitoring by adding intelligent stuck task detection fix(logging.py): enhance log formatting and handle long messages with continued lines chore: update mkdocs configuration for documentation site setup and styling
1 parent d9d0e54 commit 11f4188

19 files changed

+1009
-159
lines changed

‎.cursorrules

+171
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
{
2+
"rules": [
3+
{
4+
"name": "Verify Information",
5+
"pattern": "(?i)\\b(assume|assumption|guess|speculate)\\b",
6+
"message": "Always verify information before presenting it. Do not make assumptions or speculate without clear evidence."
7+
},
8+
{
9+
"name": "Preserve Existing Code",
10+
"pattern": "(?i)\\b(remove|delete|eliminate|destroy)\\b",
11+
"message": "Don't remove unrelated code or functionalities. Pay attention to preserving existing structures."
12+
},
13+
{
14+
"name": "No Apologies",
15+
"pattern": "(?i)\\b(sorry|apologize|apologies)\\b",
16+
"message": "Never use apologies."
17+
},
18+
{
19+
"name": "No Understanding Feedback",
20+
"pattern": "(?i)\\b(understand|understood|got it)\\b",
21+
"message": "Avoid giving feedback about understanding in comments or documentation."
22+
},
23+
{
24+
"name": "No Whitespace Suggestions",
25+
"pattern": "(?i)\\b(whitespace|indentation|spacing)\\b",
26+
"message": "Don't suggest whitespace changes."
27+
},
28+
{
29+
"name": "No Summaries",
30+
"pattern": "(?i)\\b(summary|summarize|overview)\\b",
31+
"message": "Don't summarize changes made."
32+
},
33+
{
34+
"name": "No Inventions",
35+
"pattern": "(?i)\\b(suggest|recommendation|propose)\\b",
36+
"message": "Don't invent changes other than what's explicitly requested."
37+
},
38+
{
39+
"name": "No Unnecessary Confirmations",
40+
"pattern": "(?i)\\b(make sure|confirm|verify|check)\\b",
41+
"message": "Don't ask for confirmation of information already provided in the context."
42+
},
43+
{
44+
"name": "Single Chunk Edits",
45+
"pattern": "(?i)\\b(first|then|next|after that|finally)\\b",
46+
"message": "Provide all edits in a single chunk instead of multiple-step instructions or explanations for the same file."
47+
},
48+
{
49+
"name": "No Implementation Checks",
50+
"pattern": "(?i)\\b(make sure|verify|check|confirm) (it's|it is|that) (correctly|properly) implemented\\b",
51+
"message": "Don't ask the user to verify implementations that are visible in the provided context."
52+
},
53+
{
54+
"name": "No Unnecessary Updates",
55+
"pattern": "(?i)\\b(update|change|modify|alter)\\b.*\\bno changes\\b",
56+
"message": "Don't suggest updates or changes to files when there are no actual modifications needed."
57+
},
58+
{
59+
"name": "Provide Real File Links",
60+
"pattern": "(?i)\\b(file|in)\\b.*\\b(x\\.md)\\b",
61+
"message": "Always provide links to the real files, not x.md."
62+
},
63+
{
64+
"name": "No Current Implementation",
65+
"pattern": "(?i)\\b(current|existing)\\s+(implementation|code)\\b",
66+
"message": "Don't show or discuss the current implementation unless specifically requested."
67+
},
68+
{
69+
"name": "Check Context Generated File Content",
70+
"pattern": "(?i)\\b(file|content|implementation)\\b",
71+
"message": "Remember to check the context generated file for the current file contents and implementations."
72+
},
73+
{
74+
"name": "Use Descriptive Variable Names",
75+
"pattern": "(?i)\\b(var|x|temp)\\b",
76+
"message": "Prefer descriptive, explicit variable names over short, ambiguous ones to enhance code readability."
77+
},
78+
{
79+
"name": "Follow Consistent Coding Style",
80+
"pattern": "(?i)\\b(not consistent|different style)\\b",
81+
"message": "Adhere to the existing coding style in the project for consistency."
82+
},
83+
{
84+
"name": "Prioritize Performance",
85+
"pattern": "(?i)\\b(slow|inefficient)\\b",
86+
"message": "When suggesting changes, consider and prioritize code performance where applicable."
87+
},
88+
{
89+
"name": "Security-First Approach",
90+
"pattern": "(?i)\\b(insecure|vulnerable)\\b",
91+
"message": "Always consider security implications when modifying or suggesting code changes."
92+
},
93+
{
94+
"name": "Error Handling",
95+
"pattern": "(?i)\\b(missing error|no exception)\\b",
96+
"message": "Implement robust error handling and logging where necessary."
97+
},
98+
{
99+
"name": "Modular Design",
100+
"pattern": "(?i)\\b(mixed responsibilities|not modular)\\b",
101+
"message": "Encourage modular design principles to improve code maintainability and reusability."
102+
},
103+
{
104+
"name": "Avoid Magic Numbers",
105+
"pattern": "(?i)\\b\\b\\d{2,}\\b",
106+
"message": "Replace hardcoded values with named constants to improve code clarity and maintainability."
107+
},
108+
{
109+
"name": "Consider Edge Cases",
110+
"pattern": "(?i)\\b(edge case|not handled)\\b",
111+
"message": "When implementing logic, always consider and handle potential edge cases."
112+
},
113+
{
114+
"name": "Use Assertions",
115+
"pattern": "(?i)\\b(no assertion|missing assert)\\b",
116+
"message": "Include assertions wherever possible to validate assumptions and catch potential errors early."
117+
}
118+
],
119+
"coding_practices": {
120+
"modularity": true,
121+
"DRY_principle": true,
122+
"performance_optimization": true,
123+
"documentation": {
124+
"require_docs": true,
125+
"doc_tool": "docstrings",
126+
"style_guide": "Numpy"
127+
},
128+
"error_handling": {
129+
"prefer_try_catch": true,
130+
"log_errors": true
131+
},
132+
"naming_conventions": {
133+
"variables": "snake_case",
134+
"functions": "snake_case",
135+
"classes": "PascalCase",
136+
"interfaces": "PascalCase",
137+
"files": "snake_case"
138+
}
139+
},
140+
"project_configuration": {
141+
"language": "Python",
142+
"version": "3.13",
143+
"dependencies": {
144+
"management_tool": "Poetry",
145+
"libraries": [
146+
"discord.py",
147+
"pyright",
148+
"prisma",
149+
"ruff",
150+
"loguru",
151+
"httpx",
152+
"pre-commit",
153+
"sentry-sdk",
154+
"python-dotenv",
155+
"pytz",
156+
"pillow",
157+
"rich",
158+
"aiofiles",
159+
"reactionmenu"
160+
]
161+
},
162+
"development": {
163+
"environment": "Docker",
164+
"deployment_tool": "Docker Compose"
165+
},
166+
"error_handling": {
167+
"logging_tool": "Loguru",
168+
"exception_management": "Sentry and handlers/error.py"
169+
}
170+
}
171+
}

‎.markdownlint.yaml

+2-4
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ MD012:
6060
# MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md013.md
6161
MD013:
6262
# Number of characters
63-
line_length: 200
63+
line_length: 300
6464
# Number of characters for headings
6565
heading_line_length: 80
6666
# Number of characters for code blocks
@@ -125,9 +125,7 @@ MD027: true
125125
MD028: false
126126

127127
# MD029/ol-prefix : Ordered list item prefix : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md029.md
128-
MD029:
129-
# List style
130-
style: "one_or_ordered"
128+
MD029: false
131129

132130
# MD030/list-marker-space : Spaces after list markers : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md030.md
133131
MD030:

‎.vscode/settings.json

+5-2
Original file line numberDiff line numberDiff line change
@@ -50,5 +50,8 @@
5050
"tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
5151
"tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format",
5252
"tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
53-
]
54-
}
53+
],
54+
"[markdown]": {
55+
"editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
56+
}
57+
}

‎docs/develop/architecture.md ‎docs/content/dev/architecture.md

+11-32
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This document provides a high-level overview of Tux's architecture and design pr
44

55
## Structure
66

7-
```
7+
```bash
88
.
99
├── tux/
1010
│ ├── main.py
@@ -21,40 +21,22 @@ This document provides a high-level overview of Tux's architecture and design pr
2121

2222
### Key Components
2323

24-
#### `main.py`
25-
26-
The main entry point for the bot.
27-
28-
#### `bot.py`
29-
30-
The main bot class.
31-
32-
#### `cog_loader.py`
24+
#### `main.py` - The main entry point for the bot
3325

34-
The cog loader class.
26+
#### `bot.py` - The main bot class
3527

36-
#### `help.py`
28+
#### `cog_loader.py` - The cog loader class
3729

38-
The help command class.
30+
#### `help.py` - The help command class
3931

40-
#### `cogs`
41-
42-
The directory for all cogs.
43-
44-
#### `database/`
45-
46-
The directory for all database controllers and client.
47-
48-
Prisma is our type-safe database client/ORM. Models are defined and generated automatically from `.prisma` schema files. From there, we use custom controllers to handle all logic required for each model. Controllers are defined in the `controllers` directory, and within the `__init__.py` file, we import all controllers and make them available to the rest of the bot via the `DatabaseController` class. Various commands make use of this class to handle data storage and retrieval with their respective models.
32+
#### `cogs` - The directory for all cogs
4933

34+
#### `database` - The directory for all database controllers and client
5035

5136
#### `handlers`
5237

5338
The directory for various services and handlers that live "behind the scenes" of the bot.
5439

55-
56-
57-
5840
#### `ui`
5941

6042
The directory for all UI components and views.
@@ -64,18 +46,15 @@ The directory for all UI components and views.
6446
The directory for all utility functions and classes.
6547

6648
**Important utilities to note:**
49+
6750
- `logger.py` - Our custom logger that overrides the default logger with `loguru` and `rich` for better logging.
6851
- `config.py` - Our configuration manager that handles all bot configuration and secret/environment variables.
6952
- `constants.py` - Our constants manager that handles all constant values used throughout the bot like colors, emojis, etc.
7053
- `checks.py` - Our custom permission system that provides decorators for command access checks.
7154
- `flags.py` - Our custom flag system that provides a way to handle flags for command arguments.
7255

73-
74-
75-
76-
77-
7856
#### `wrappers`
7957

80-
The directory for all API wrappers and clients.
81-
- We use `httpx` for all API requests.
58+
The directory for all API wrappers and clients.
59+
60+
- We use `httpx` for all API requests.

‎docs/develop/contributing.md ‎docs/content/dev/contributing.md

+10-2
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,14 @@ Thank you for your interest in contributing to Tux! This guide will help you get
55
## Development Setup
66

77
1. **Clone the Repository**
8+
89
```bash
910
git clone https://github.com/your-username/tux.git
1011
cd tux
1112
```
1213

1314
2. **Set Up Development Environment**
15+
1416
```bash
1517
# Using Poetry (recommended)
1618
poetry env use 3.13
@@ -21,6 +23,7 @@ Thank you for your interest in contributing to Tux! This guide will help you get
2123
```
2224

2325
3. **Configure Environment**
26+
2427
```bash
2528
# Copy example environment file
2629
cp .env.example .env
@@ -29,6 +32,7 @@ Thank you for your interest in contributing to Tux! This guide will help you get
2932
```
3033

3134
4. **Database Setup**
35+
3236
```bash
3337
# Generate Prisma client
3438
poetry run prisma generate
@@ -40,6 +44,7 @@ Thank you for your interest in contributing to Tux! This guide will help you get
4044
## Development Workflow
4145

4246
1. **Create a New Branch**
47+
4348
```bash
4449
git checkout -b feature/your-feature-name
4550
```
@@ -50,11 +55,13 @@ Thank you for your interest in contributing to Tux! This guide will help you get
5055
- Update documentation as needed
5156

5257
3. **Run Tests**
58+
5359
```bash
5460
poetry run pytest
5561
```
5662

5763
4. **Format and Lint**
64+
5865
```bash
5966
# Format code
6067
poetry run ruff format .
@@ -64,11 +71,12 @@ Thank you for your interest in contributing to Tux! This guide will help you get
6471
```
6572

6673
5. **Commit Your Changes**
74+
6775
```bash
6876
git add .
6977
git commit -m "feat: add new feature"
7078
```
71-
79+
7280
Follow [Conventional Commits](https://www.conventionalcommits.org/) format:
7381
- `feat:` for new features
7482
- `fix:` for bug fixes
@@ -136,4 +144,4 @@ Please read and follow our [Code of Conduct](../../CODE_OF_CONDUCT.md). We expec
136144

137145
## License
138146

139-
By contributing to Tux, you agree that your contributions will be licensed under the project's license.
147+
By contributing to Tux, you agree that your contributions will be licensed under the project's license.

0 commit comments

Comments
 (0)