docs: agentic rules and commands #1101
Conversation
Reviewer's GuideIntroduces a Cursor-focused rules and commands system into the Tux repo, including a Sequence diagram for rules validation via pre-commit and CLIsequenceDiagram
actor Developer
participant Git as GitPreCommit
participant PreCommit as PreCommitHook
participant Uv as UvRunner
participant RulesEntrypoint as ScriptsRulesMain
participant RulesCLI as RulesCLI
participant FS as FileSystem
Developer->>Git: git commit
Git->>PreCommit: run hooks
PreCommit->>PreCommit: validate-rules hook
PreCommit->>Uv: uv run rules validate --rules-dir .cursor/rules --commands-dir .cursor/commands
Uv->>RulesEntrypoint: scripts.rules:main()
RulesEntrypoint->>RulesCLI: RulesCLI()
RulesEntrypoint->>RulesCLI: cli.run()
RulesCLI->>FS: list .cursor/rules/*.mdc
loop For each rule file
RulesCLI->>FS: read rule file
RulesCLI->>RulesCLI: _validate_rule(file_path)
end
RulesCLI->>FS: list .cursor/commands/**/*.md
loop For each command file
RulesCLI->>FS: read command file
RulesCLI->>RulesCLI: _validate_command(file_path)
end
RulesCLI->>RulesCLI: _print_validation_summary(...)
alt validation errors
RulesCLI-->>Uv: exit code 1
Uv-->>PreCommit: non-zero exit
PreCommit-->>Git: hook failed
Git-->>Developer: commit blocked, show errors
else all valid
RulesCLI-->>Uv: exit code 0
Uv-->>PreCommit: success
PreCommit-->>Git: hook passed
Git-->>Developer: commit proceeds
end
Class diagram for the new RulesCLI validation systemclassDiagram
class BaseCLI {
+str name
+str description
+console
+app
+_command_registry
+__init__(name, description)
+add_command(func, name, help_text)
+run()
}
class Command {
+str name
+callable func
+str help_text
+__init__(name, func, help_text)
}
class RulesCLI {
+__init__()
-_setup_command_registry() void
-_setup_commands() void
-_check_rule_frontmatter(file_path, content) tuple~list~str~~, str or None~
-_check_rule_description(file_path, frontmatter, is_spec, is_reference) list~str~
-_check_rule_content(file_path, content, frontmatter_end, is_spec, is_reference, is_docs_rule) list~str~
-_validate_rule(file_path) list~str~
-_validate_command(file_path) list~str~
+validate(rules_dir, commands_dir) void
-_print_validation_summary(rule_files, cmd_files, all_errors) void
}
class TyperApp {
+callback()
+command()
+__call__()
}
BaseCLI <|-- RulesCLI
RulesCLI o--> Command : registers
RulesCLI o--> TyperApp : uses app
class RulesModule {
+app
+main() void
}
RulesModule ..> RulesCLI : instantiates
RulesModule ..> TyperApp : exposes as app
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey there - I've reviewed your changes - here's some feedback:
- In
scripts/rules.py,validate()currently exits with an error if either the rules or commands directory is missing; consider treating a missing directory as an empty set (or making each optional) so validation can still run in repos/branches that only use one of the two. - The extension checks in
_validate_ruleand_validate_commandare redundant because you already filter files withrglob('*.mdc')andrglob('*.md'); you can remove those checks to simplify the validators. - You construct
RulesCLItwice (once for the module-levelappand again inmain()); reusing a single instance or delegatingmain()to the existingappwould reduce duplicate setup logic.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In `scripts/rules.py`, `validate()` currently exits with an error if either the rules or commands directory is missing; consider treating a missing directory as an empty set (or making each optional) so validation can still run in repos/branches that only use one of the two.
- The extension checks in `_validate_rule` and `_validate_command` are redundant because you already filter files with `rglob('*.mdc')` and `rglob('*.md')`; you can remove those checks to simplify the validators.
- You construct `RulesCLI` twice (once for the module-level `app` and again in `main()`); reusing a single instance or delegating `main()` to the existing `app` would reduce duplicate setup logic.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
📚 Documentation Preview
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1101 +/- ##
=======================================
Coverage 40.24% 40.24%
=======================================
Files 204 204
Lines 14373 14373
Branches 1686 1686
=======================================
Hits 5784 5784
Misses 8589 8589 ☔ View full report in Codecov by Sentry. |
- Introduced `CursorCLI` for validating rules and commands against Tux project standards. - Added validation logic for rule frontmatter, description, content, and command structure. - Integrated a new pre-commit hook to validate cursor rules and commands during commits.
- Introduced new markdown files for linting, refactoring, reviewing diffs, and database operations. - Each file outlines steps, checklists, and error handling for maintaining code quality in the Tux project. - Enhanced documentation for Docker commands and testing procedures to streamline development processes.
- Changed the entry command for the cursor validation hook to include 'validate' for improved clarity and functionality. - Removed unnecessary arguments from the hook configuration to streamline the validation process.
- Added a new `RulesCLI` for validating rules and commands against Tux project standards. - Updated pre-commit configuration to use the new validation command. - Enhanced the `pyproject.toml` to include the rules CLI entry point. - Refactored existing code to integrate the new validation logic and ensure proper command structure.
- Added a comprehensive catalog of all Cursor rules and commands for the Tux project, enhancing clarity and accessibility. - Updated individual rule files with detailed descriptions, best practices, and anti-patterns for various components, including database, modules, and security. - Introduced new files for database migrations, queries, and service patterns, ensuring a structured approach to database operations. - Enhanced documentation for error handling, logging, and testing patterns to improve overall code quality and maintainability. - Removed outdated overview files and streamlined the organization of rules for better navigation and usability.
- Introduced new markdown templates for commands and rules to standardize documentation practices. - The command template includes sections for overview, steps, error handling, and checklists. - The rule template features patterns, best practices, anti-patterns, and examples to guide users in implementation. - These templates aim to enhance clarity and consistency in documenting commands and rules within the Tux project.
…nd rules - Introduced two new guides: "Creating Cursor Commands" and "Creating Cursor Rules" to provide step-by-step instructions for developers. - Each guide includes quick start sections, detailed steps, best practices, and templates to standardize the creation of commands and rules within the Tux project. - Updated the main developer guides index to include links to the new guides, enhancing accessibility and organization of documentation resources.
- Introduced a new README file detailing the structure and usage of Cursor's rules and commands system. - Provided an overview of rules and commands, their organization by domain and category, and instructions for usage. - Included links to comprehensive guides and resources for contributing to Cursor rules and commands, enhancing developer onboarding and documentation accessibility.
- Added a new section detailing Cursor's rules and commands system, including their organization and usage. - Included validation commands and links to comprehensive guides for creating rules and commands. - Updated development workflow to incorporate rules validation as a step before committing changes. - Improved documentation structure for better clarity and accessibility of Cursor-related resources.
- Included links to "Creating Cursor Rules" and "Creating Cursor Commands" in the developer guides index. - These additions enhance the documentation structure and provide developers with essential resources for implementing Cursor functionalities.
…dling - Added autofix and autoupdate commit message formats for pre-commit hooks. - Excluded validation rules from the pre-commit checks to streamline the process. - Updated Python version specification to 3.13 for consistency.
kzndotsh
force-pushed
the
feat/agents
branch
from
1f73363 to
94abd23
Compare
WalkthroughAdds a Cursor “rules & commands” documentation suite (many Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Developer
participant CLI as scripts.ai (Typer)
participant Validator as validate_rules
participant FS as Filesystem (.cursor/.cursor/commands)
participant Console as Console
Developer->>CLI: run `ai validate-rules`
CLI->>Validator: dispatch validate_rules command
Validator->>FS: enumerate & read rule (`*.mdc`) and command (`*.md`) files
FS-->>Validator: return file contents
Validator->>Validator: parse frontmatter & content checks
Validator->>Console: print per-file errors/warnings
Validator->>Console: print summary (counts & status)
Console-->>Developer: validation result (pass/fail)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
Comment |
![sentry[bot]](https://avatars.githubusercontent.com/u/1396951?s=60&v=4){kind=small}
scripts/rules.py
Outdated
| from scripts.base import BaseCLI | ||
| from scripts.registry import Command |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 13
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.cursor/rules/ui/cv2.mdc (1)
52-77: Duplicate "Best Practices" section creates confusion about scope and structure.The file now has two "Best Practices" sections:
- Lines 52–60: LayoutView-specific best practices (newly added)
- Lines 610–622: Broader UI pattern best practices (existing)
These serve different purposes but share the same heading, making it unclear which guidance applies and creating maintenance burden. Additionally, the placement of the new section immediately after "LayoutView Methods" (without explicit sub-heading) suggests it belongs to that section, but the content is broader guidance.
Recommendation: Either (a) rename the new section to "LayoutView Best Practices" to clarify scope, (b) move it to the end of the LayoutView section as a subsection, or (c) merge both "Best Practices" sections into a unified guide with LayoutView-specific callouts.
🧹 Nitpick comments (11)
.cursor/commands/development/docker-down.md (1)
21-25: Consider making the data loss warning more prominent.The warning about potential data loss is important but might be overlooked in a plain "Notes" section. If the documentation format supports it, consider using:
- A warning/danger admonition block
- Bold or emphasized text for the data loss line
- Moving it higher in the document (before Steps)
This is particularly important since data loss can significantly impact developers.
.cursor/rules/security/secrets.mdc (1)
1-5: Verify glob pattern scope for configuration files.The glob pattern
config/*.toml, config/*.yaml, config/*.jsononly matches files at the root level of theconfig/directory. If nested configuration files are expected (e.g.,config/db/*.toml), the pattern should useconfig/**/*.{toml,yaml,json}to capture subdirectories.Verify whether configuration files are stored in nested subdirectories under
config/and adjust the glob pattern accordingly if needed..cursor/commands/debugging/debug.md (1)
30-41: Add "See Also" section for consistency with other command guides.All other command guides (generate-docs, refactor, write-unit-tests) include a "See Also" section with cross-references. This guide should include one as well, linking to related debugging rules and other debugging-related commands.
🔎 Suggested structure
## See Also - Related rule: @error-handling/patterns.mdc - Related rule: @debugging/logging.mdc (if available) - Related command: `/logs` (if available).cursor/rules/database/services.mdc (1)
118-129: Transaction guidance could be more prominent.Transactions are covered under "Async Operations" section, but given their importance for multi-step database operations, consider elevating this pattern to a dedicated section or emphasizing it earlier in the document. Based on learnings, transactions are a critical pattern for data consistency in multi-step operations.
.cursor/rules/database/migrations.mdc (1)
39-67: Unusedsqlmodelimport in migration example.Line 45 imports
sqlmodelbut it's not used in the example migration. While this may reflect autogenerated migrations, consider removing it or adding a comment explaining when it would be used.🔎 Optional cleanup
from __future__ import annotations from typing import Sequence, Union from alembic import op import sqlalchemy as sa -import sqlmodel +# import sqlmodel # Only needed when migrating SQLModel-specific types.cursor/rules/modules/events.mdc (1)
101-108: Prefer guard clauses overassertfor type narrowing.Line 105 uses
assert member.guildfor type narrowing, but this will crash at runtime if the assertion fails. The actual codebase uses guard clauses (e.g.,if not channel.guild: returninevent.py), which is safer.🔎 Proposed fix
@commands.Cog.listener() async def on_member_join(self, member: discord.Member) -> None: """Handle member joins.""" - assert member.guild + if not member.guild: + return # Welcome member, assign roles, etc. pass.cursor/rules/database/models.mdc (1)
126-131: Clarify that this DateTime example is for custom date fields, not timestamps.This example could be confused with the earlier guidance that timestamps are automatic. Consider adding a comment clarifying this is for custom DateTime fields (e.g.,
scheduled_at,expires_at), notcreated_at/updated_at.🔎 Proposed fix
-# DateTime with timezone +# DateTime with timezone (for custom date fields, NOT timestamps) created_at: datetime | None = Field( + # Note: Use a different name like scheduled_at, expires_at, etc. + # created_at/updated_at are automatic from BaseModel sa_type=DateTime(timezone=True), - description="Creation timestamp" + description="Custom datetime field" )scripts/rules.py (3)
464-471: Double instantiation of RulesCLI.Line 465 creates a
RulesCLIinstance for the module-levelapp, andmain()creates another instance. This is inefficient and could cause issues if the CLI has stateful initialization.Consider reusing the same instance:
🔎 Proposed fix
# Create the CLI app instance -app = RulesCLI().app +_cli = RulesCLI() +app = _cli.app def main() -> None: """Entry point for the cursor CLI script.""" - cli = RulesCLI() - cli.run() + _cli.run()
85-94: Frontmatter detection could be fragile with edge cases.Line 88 checks for
"---\n"starting at position 4, which assumes the file starts with exactly---\n. This could miss edge cases like BOM characters or CRLF line endings.Consider using a more robust regex match:
🔎 Proposed fix
def _check_rule_frontmatter( self, file_path: Path, content: str, ) -> tuple[list[str], str | None]: ... errors: list[str] = [] + + # Normalize line endings for consistent parsing + content = content.replace('\r\n', '\n') if not content.startswith("---"): errors.append(f"{file_path}: Rule must start with frontmatter (---)") + return errors, None - if "---\n" not in content[4:]: + # Find closing frontmatter delimiter + second_delim = content.find("---\n", 4) + if second_delim == -1: errors.append(f"{file_path}: Rule must have closing frontmatter (---)")
231-234: Consider handling file read errors gracefully.
read_text()can raise exceptions for encoding issues or permission errors. Consider wrapping in try-except to provide a clearer error message.🔎 Proposed fix
def _validate_rule(self, file_path: Path) -> list[str]: ... errors: list[str] = [] - content = file_path.read_text(encoding="utf-8") + try: + content = file_path.read_text(encoding="utf-8") + except (OSError, UnicodeDecodeError) as e: + return [f"{file_path}: Failed to read file: {e}"].cursor/rules/testing/pytest.mdc (1)
111-132: Clarify the relationship between theasyncmarker and@pytest.mark.asynciodecorator.The markers list (line 116) defines an
asyncmarker, but the async test example (line 128) uses@pytest.mark.asynciofrom pytest-asyncio. These are different conventions. The documentation should clarify: Are both needed? Should developers use asyncio (required for pytest-asyncio to recognize async tests) or the custom async marker (for filtering)? Consider using both if they serve different purposes (asyncio for pytest-asyncio support, async for test categorization), but make this explicit.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (62)
.cursor/README.md.cursor/commands/code-quality/lint.md.cursor/commands/code-quality/refactor.md.cursor/commands/code-quality/review-existing-diffs.md.cursor/commands/database/health.md.cursor/commands/database/migration.md.cursor/commands/database/reset.md.cursor/commands/debugging/debug.md.cursor/commands/development/docker-down.md.cursor/commands/development/docker-up.md.cursor/commands/development/setup-project.md.cursor/commands/discord/create-module.md.cursor/commands/discord/test-command.md.cursor/commands/documentation/docs-serve.md.cursor/commands/documentation/generate-docs.md.cursor/commands/documentation/update-docs.md.cursor/commands/error-handling/add-error-handling.md.cursor/commands/security/security-review.md.cursor/commands/testing/integration-tests.md.cursor/commands/testing/run-all-tests-and-fix.md.cursor/commands/testing/test-coverage.md.cursor/commands/testing/write-unit-tests.md.cursor/rules/core/tech-stack.mdc.cursor/rules/database/migrations.mdc.cursor/rules/database/models.mdc.cursor/rules/database/overview.mdc.cursor/rules/database/queries.mdc.cursor/rules/database/service.mdc.cursor/rules/database/services.mdc.cursor/rules/docs/docs.mdc.cursor/rules/error-handling/logging.mdc.cursor/rules/error-handling/patterns.mdc.cursor/rules/error-handling/sentry.mdc.cursor/rules/error-handling/user-feedback.mdc.cursor/rules/meta/cursor-commands.mdc.cursor/rules/meta/cursor-rules.mdc.cursor/rules/modules/cogs.mdc.cursor/rules/modules/commands.mdc.cursor/rules/modules/events.mdc.cursor/rules/modules/interactions.mdc.cursor/rules/modules/permissions.mdc.cursor/rules/rules.mdc.cursor/rules/security/dependencies.mdc.cursor/rules/security/patterns.mdc.cursor/rules/security/secrets.mdc.cursor/rules/security/validation.mdc.cursor/rules/testing/async.mdc.cursor/rules/testing/coverage.mdc.cursor/rules/testing/fixtures.mdc.cursor/rules/testing/markers.mdc.cursor/rules/testing/pytest.mdc.cursor/rules/ui/cv2.mdc.cursor/templates/command-template.md.cursor/templates/rule-template.mdc.pre-commit-config.yamlAGENTS.mddocs/content/developer/guides/creating-cursor-commands.mddocs/content/developer/guides/creating-cursor-rules.mddocs/content/developer/guides/index.mdpyproject.tomlscripts/rules.pyzensical.toml
💤 Files with no reviewable changes (2)
- .cursor/rules/database/service.mdc
- .cursor/rules/database/overview.mdc
🧰 Additional context used
📓 Path-based instructions (1)
**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
**/*.py: Use strict type hints withType | Noneinstead ofOptional[Type]
Use NumPy docstrings for documenting functions and classes
Prefer absolute imports; relative imports allowed only within the same module
Organize imports in order: stdlib → third-party → local
Use 88 character line length
Use snake_case for functions and variables, PascalCase for classes, UPPER_CASE for constants
Always add imports to the top of the file unless absolutely necessary
Use async/await for I/O operations
Use custom exceptions for business logic with context logging and meaningful user messages
Use Pydantic for data validation
Keep files to a maximum of 1600 lines
Use one class or function per file when possible
Use descriptive filenames
Add appropriate logging to services and error handlers
Files:
scripts/rules.py
🧠 Learnings (11)
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/alembic/**/*.py : Use Alembic for database migrations
Applied to files:
.cursor/commands/database/migration.md.cursor/rules/database/migrations.mdcAGENTS.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: No secrets in code; use environment variables for configuration
Applied to files:
.cursor/rules/security/secrets.mdc
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/database/**/*.py : Use transactions for multi-step database operations
Applied to files:
.cursor/rules/database/services.mdc.cursor/rules/database/migrations.mdcAGENTS.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/database/**/*.py : Optimize database queries
Applied to files:
.cursor/rules/database/queries.mdcAGENTS.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/database/**/*.py : Use SQLModel for type-safe database operations
Applied to files:
.cursor/rules/database/queries.mdc.cursor/rules/database/migrations.mdc.cursor/rules/database/models.mdcAGENTS.md
📚 Learning: 2025-12-21T20:54:29.808Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: .cursor/rules/rules.mdc:0-0
Timestamp: 2025-12-21T20:54:29.808Z
Learning: Follow the coding agent rules defined in AGENTS.md
Applied to files:
.cursor/rules/meta/cursor-rules.mdcAGENTS.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/modules/**/*.py : Implement role-based permissions for Discord commands
Applied to files:
.cursor/commands/discord/create-module.md.cursor/rules/modules/permissions.mdc.cursor/rules/modules/commands.mdc.cursor/commands/discord/test-command.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/modules/**/*.py : Use hybrid commands (slash + traditional) for Discord commands
Applied to files:
.cursor/commands/discord/create-module.md.cursor/rules/modules/commands.mdc
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/modules/**/*.py : Use rich embeds and implement cooldowns/rate limiting for Discord interactions
Applied to files:
.cursor/rules/modules/interactions.mdc.cursor/rules/modules/commands.mdc
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/*.py : Use custom exceptions for business logic with context logging and meaningful user messages
Applied to files:
.cursor/rules/error-handling/patterns.mdc
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/database/**/*.py : Use model-level validation in SQLModel models
Applied to files:
.cursor/rules/database/models.mdc
🧬 Code graph analysis (5)
.cursor/rules/modules/interactions.mdc (7)
src/tux/core/bot.py (1)
Tux(45-403)src/tux/modules/tools/tldr.py (1)
slash_tldr(244-263)src/tux/modules/info/info.py (1)
Info(25-851)src/tux/modules/utility/wiki.py (1)
Wiki(19-180)src/tux/modules/moderation/report.py (2)
report(31-42)Report(16-42)src/tux/core/context.py (1)
_get_interaction_details(25-47)src/tux/ui/modals/report.py (1)
on_submit(65-134)
.cursor/rules/error-handling/patterns.mdc (2)
src/tux/core/app.py (1)
TuxApp(57-224)src/tux/core/bot.py (1)
Tux(45-403)
.cursor/rules/modules/events.mdc (1)
src/tux/services/handlers/event.py (1)
EventHandler(12-138)
.cursor/rules/modules/permissions.mdc (1)
src/tux/modules/moderation/purge.py (1)
Purge(20-234)
.cursor/rules/modules/commands.mdc (1)
src/tux/modules/moderation/purge.py (1)
Purge(20-234)
🪛 LanguageTool
.cursor/commands/code-quality/lint.md
[style] ~5-~5: Consider using a different verb for a more formal wording.
Context: ... (ruff, basedpyright) and automatically fix issues according to project coding stan...
(FIX_RESOLVE)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Run All Tests (3.13.8)
- GitHub Check: Sourcery review
- GitHub Check: Seer Code Review
🔇 Additional comments (75)
.cursor/rules/ui/cv2.mdc (1)
71-73: Verify cross-reference format for internal documentation links.The "See Also" section references other documentation using
@notation (e.g.,@modules/interactions.mdc,@AGENTS.md). Confirm that this reference format is:
- Properly recognized by the Cursor rules validation system
- Correctly resolving to actual files/rules in the repository
- Consistent with other cross-references in the
.cursorcatalogIf these files don't exist or the format is incorrect, the references may break during validation or become orphaned links.
docs/content/developer/guides/index.md (1)
12-18: LGTM!The "Available Guides" section provides clear navigation to the developer guides, including the new Cursor-related documentation. The structure is clean and follows standard Markdown conventions.
zensical.toml (1)
91-92: LGTM!The navigation entries for the new Cursor guides are correctly structured and follow the existing pattern in the configuration file.
.cursor/commands/testing/integration-tests.md (2)
43-48: Verify mixed reference syntax is supported.The "See Also" section uses both
@prefix (for rules) and/prefix (for commands). While this distinction makes semantic sense, ensure both syntaxes are:
- Documented in the meta specification files
- Consistently applied across all command files
- Will be correctly resolved/rendered for users
10-10: Theintegrationpytest marker is properly registered inpyproject.toml(line 433), actively used throughout the test suite (10+ occurrences intest_database_controllers.pyandtest_database_migrations.py), and documented in.cursor/rules/testing/markers.mdcat line 20. The command is correct and no action is required.Likely an incorrect or invalid review comment.
.cursor/commands/development/docker-down.md (1)
10-10: Verify theuv run docker downcommand exists.Similar to the
docker upcommand, please confirm thatuv run docker downis a valid registered command in the project's CLI configuration.Refer to the verification script in the docker-up.md review comment.
.cursor/rules/rules.mdc (2)
1-8: LGTM!The updated header and description clearly communicate the purpose of this index file. The frontmatter
alwaysApply: truesetting ensures this catalog is readily available to users.
123-128: The relative file path references in the "See Also" section are correct. All links resolve properly from the.cursor/rules/directory:
../../AGENTS.md→ repository root../README.md→.cursor/README.md- Developer guides under
../../docs/content/developer/guides/all existNo changes needed.
.cursor/commands/testing/run-all-tests-and-fix.md (2)
43-47: Reference syntax verification needed.As with other command files, verify that the
@(rules) and/(commands) reference syntax is properly documented and supported in the Cursor system.
10-10: Theuv run test allcommand is a valid, registered project script. It is defined inpyproject.tomlastest = "scripts.test:main"with the "all" subcommand implemented inscripts/test/all.py. This command is consistently documented and used throughout the project (AGENTS.md, git.md, code-review.md, ci-cd.md), confirming it is an intentional project convention. No changes needed.Likely an incorrect or invalid review comment.
.cursor/rules/docs/docs.mdc (1)
204-214: The@reference syntax is correct and properly supported.This syntax is documented in
.cursor/rules/meta/cursor-rules.mdc(lines 31 and 67) as the recommended approach for file references within Cursor rules. All referenced files exist and are accessible:
- ✓
@docs/principals.mdc- ✓
@docs/style.mdc- ✓
@docs/syntax.mdc- ✓
@docs/structure.mdc- ✓
@docs/patterns.mdc- ✓
@docs/zensical.mdc- ✓
@AGENTS.md- ✓
@rules.mdcNo changes needed.
.cursor/templates/rule-template.mdc (1)
1-64: Template structure aligns with established pattern.The rule template provides a clear, well-organized scaffold that matches the structure used in other rule files (secrets.mdc, coverage.mdc, etc.). The frontmatter, pattern sections, and See Also references are all appropriate.
.cursor/templates/command-template.md (1)
1-44: Command template provides appropriate structure for workflow documentation.The template establishes a clear, actionable format for commands with Overview, Steps, Error Handling, Checklist, and See Also sections. The structure is consistent with existing command files and provides useful scaffolding for contributors.
.cursor/commands/documentation/update-docs.md (1)
44-48: Documentation rules referenced in the See Also section exist.The referenced rules
@docs/docs.mdcand@docs/style.mdcare present in.cursor/rules/docs/..cursor/rules/security/secrets.mdc (2)
31-46: The CONFIG object API is correctly documented. BothCONFIG.BOT_TOKENandCONFIG.database_urlexist insrc/tux/shared/config/settings.pywith the correct casing and are used consistently throughout the codebase.
77-85: [rewritten comment]
[classification tag].cursor/commands/security/security-review.md (2)
51-55: All referenced security rules exist.The three security rules referenced in the See Also section are present in
.cursor/rules/security/:@security/patterns.mdc,@security/secrets.mdc, and@security/validation.mdc. Note: A fourth rule file (@security/dependencies.mdc) exists in the directory but is not currently referenced in this document.
9-13: Correct the description ofuv run dev all—it does not check for vulnerabilities or outdated packages.The command
uv run dev allexists and is properly registered, but the security review documentation mischaracterizes its purpose. This command runs code quality checks (linting, formatting, type checking, docstrings, and pre-commit hooks), not security audits. It cannot replace dedicated dependency vulnerability scanning. For actual security checks, useuv pip compile --python-version 3.13with a security audit tool, or refer touv.lockdirectly for outdated packages. Reword this step to accurately reflect that it validates code quality rather than security.Likely an incorrect or invalid review comment.
.cursor/rules/testing/async.mdc (2)
48-76: Fixtures verified and properly documented.All referenced fixtures (
pglite_engine,pglite_async_manager,db_service) are defined intests/fixtures/database_fixtures.pyand registered viapytest_pluginsinconftest.py. The async patterns, dependencies, and scopes (session for manager, function for engine and service) match the documented examples exactly.
20-26: All markers, fixtures, and dependencies are correctly configured.Verification confirms:
- The
unitmarker is defined inpyproject.tomlunder[tool.pytest.ini_options]as "Unit tests with isolated components"- The marker is consistently used across 12 test files in the project
- Fixtures
db_service,pglite_engine, andpglite_async_managerare properly defined intests/fixtures/database_fixtures.py- Both
pytest-asyncio>=1.2.0andpytest-timeout>=2.4.0are in project dependencies- AsyncIO configuration is properly set with
asyncio_mode = "auto"and appropriate fixture loop scopes.cursor/rules/testing/coverage.mdc (1)
34-45: Commandsuv run test allanduv run test htmlare correctly configured and functional.Both test subcommands are properly wired in
scripts/test/__init__.pyand implement the documented behavior:
uv run test allruns pytest with coverage enabled (configured inpyproject.tomladdopts with--cov=src/tux)uv run test htmlruns pytest with--cov-report=html, generating coverage reports inhtmlcov/index.htmlThe pytest-cov and pytest-html dependencies are already included in the project's test dependency group.
docs/content/developer/guides/creating-cursor-rules.md (1)
272-275: The template file reference at line 273 is correct and the file exists at.cursor/templates/rule-template.mdc..cursor/rules/modules/interactions.mdc (1)
169-190: All utility functions referenced in lines 171-179 and 186-189 are confirmed to exist in the codebase.validate_author(line 25),validate_interaction_data(line 53), andhandle_callback_error(line 76) are properly defined insrc/tux/ui/views/config/callbacks.py. The interactions.mdc rule accurately references these functions.Likely an incorrect or invalid review comment.
.cursor/rules/modules/cogs.mdc (1)
218-223: Cross-references look good.See Also section properly links to related module documentation and general coding standards.
.cursor/rules/security/validation.mdc (1)
1-190: Well-structured security validation guidance.Documentation comprehensively covers input validation across command, interaction, database, and string domains with practical examples and clear anti-patterns. The reference to helper functions and SQLModel's automatic safeguards is accurate.
.cursor/rules/database/services.mdc (1)
192-197: Cross-references are consistent and appropriate.See Also section properly links to controller, model, and standards documentation.
docs/content/developer/guides/creating-cursor-commands.md (2)
275-275: Verify template path reference is correct.Line 275 uses a relative path to reference the command template:
../../../../.cursor/templates/command-template.md. Please verify this path resolves correctly from the docs/content/developer/guides/ directory. If the file structure differs, the path may need adjustment.
1-277: Comprehensive and well-structured guide for creating Cursor commands.Documentation provides clear step-by-step guidance, practical examples, complete templates, and quality standards. The organization from quick start through maintenance workflow is logical and actionable. Validation integration with
uv run rules validateis properly referenced..cursor/commands/discord/test-command.md (1)
1-48: Practical Discord command testing guide.Documentation provides clear workflow for manual testing with comprehensive checklist. Steps appropriately cover startup verification, command execution with valid/invalid inputs, permission checks, logging, and response rendering. Covers the testing essentials without unnecessary verbosity.
.cursor/rules/error-handling/sentry.mdc (1)
1-132: Well-organized Sentry integration guidance.Documentation clearly explains automatic capture with context, manual capture patterns, context setting helpers, automatic sanitization, and performance monitoring. The emphasis on using
capture_exception_safewrapper rather than direct SDK calls is appropriate. Anti-patterns appropriately discourage manual capture when error handler should handle it..cursor/rules/security/patterns.mdc (1)
1-178: Comprehensive security patterns reference.Documentation appropriately covers input validation, permission checks, database security, and error handling with practical examples. The emphasis on generic user messages while logging detailed errors is a strong security practice. Parameterized query guidance via SQLModel is accurate. Cross-references to related security and error-handling documentation are appropriate.
.cursor/commands/testing/test-coverage.md (1)
1-46: Clear test coverage workflow guide.Documentation provides practical steps for generating reports, analyzing coverage, and improving test coverage. Explicit coverage goals (80%+ overall, 100% on critical paths) provide clear targets. Checklist is comprehensive and verifiable. References to related rule documentation and other test commands are appropriate.
.pre-commit-config.yaml (2)
86-94: LGTM! Local hook configuration looks correct.The
validate-ruleshook is properly configured with system language, correct file pattern matching for.cursorrules and commands, andpass_filenames: falsesince the CLI handles file discovery internally.
29-29: Verify the version downgrades are intentional.Several hook versions have been downgraded:
- yamlfix: 1.19.1 → 1.19.0
- markdownlint-cli: v0.47.0 → v0.46.0
- ruff: v0.14.10 → v0.14.7
If these are intentional (e.g., due to compatibility issues), consider adding a comment explaining the reason. Otherwise, these may have been accidentally reverted.
Also applies to: 44-44, 52-52, 57-57
.cursor/rules/security/dependencies.mdc (1)
1-101: LGTM! Well-structured dependency security documentation.The rule file follows the MDC format correctly with proper frontmatter, clear good/bad examples, and actionable guidance for
uvdependency management. The globs appropriately targetpyproject.toml,uv.lock, and requirements files..cursor/rules/meta/cursor-rules.mdc (1)
1-160: Overall specification is well-structured.The Cursor Rules Specification provides comprehensive guidance on rule types, MDC format, constraints, and validation criteria. The document follows its own standards and serves as a good reference for rule authors. Based on learnings, this aligns with AGENTS.md coding agent rules.
.cursor/rules/meta/cursor-commands.mdc (1)
1-108: Rest of the specification is well-documented.The command type classification, file format requirements, invocation syntax, content requirements, and comparison with rules are all clear and useful for contributors.
Also applies to: 120-203
.cursor/rules/database/migrations.mdc (1)
1-249: Comprehensive Alembic migration documentation.The guide covers migration creation, patterns (tables, columns, foreign keys, enums), safety practices, and anti-patterns effectively. Based on learnings, this aligns with the project's use of Alembic for database migrations.
.cursor/rules/modules/events.mdc (1)
1-100: Well-structured event handler documentation.The guide covers event listeners, common events, organization patterns, and error handling effectively. The patterns align with the actual implementation in
src/tux/services/handlers/event.py.Also applies to: 109-265
.cursor/rules/database/models.mdc (1)
1-125: Comprehensive SQLModel documentation aligned with project patterns.The guide effectively covers BaseModel inheritance, field definitions, relationships, and validation. Based on learnings, this aligns with using SQLModel for type-safe database operations and model-level validation.
Also applies to: 132-260
scripts/rules.py (2)
22-63: CLI structure and command registration look good.The
RulesCLIclass properly inherits fromBaseCLI, uses the command registry pattern, and the callback trick to force Typer into subcommand mode is a known workaround for single-command apps.
121-166: Validation logic is comprehensive and well-structured.The description and content validation methods properly handle special cases (specs, references, docs rules) and provide clear error messages. Command validation checks for required sections with appropriate regex patterns.
Also applies to: 281-329
pyproject.toml (1)
66-66: LGTM! Script entry correctly registered.The new
rulesscript entry is properly configured and follows the existing pattern for CLI tools in this project. This enables theuv run rulescommand referenced throughout the documentation..cursor/rules/error-handling/logging.mdc (3)
1-5: Frontmatter correctly configured.The rule frontmatter is properly structured with an appropriate glob pattern for Python files and correctly set to apply only when editing matching files.
149-155: All cross-referenced files in the "See Also" section exist in their expected locations.
18-18: Verify logging module references are accurate.The documentation references
logurulogger (line 18),CONFIG.LOG_LEVEL(line 93), andconfigure_testing_loggingfromtux.core.logging(line 102). Confirm these exist in the codebase.Applies to: Lines 18, 89-104
.cursor/commands/database/reset.md (3)
32-33: Appropriate data loss warning.The prominent warning about data deletion is well-placed and clearly communicates the destructive nature of the reset operation.
47-49: Verify referenced files exist.Confirm the referenced rule (@database/migrations.mdc) and command files (/database-migration, /database-health) exist in the repository structure.
15-15: All documented database subcommands are implemented and properly registered in thescripts.dbmodule:
reset()command inscripts/db/reset.pystatus()command inscripts/db/status.pyhealth()command inscripts/db/health.pyAll three are imported and added to the app via
app.add_typer()inscripts/db/__init__.py. Documentation is accurate..cursor/commands/database/migration.md (2)
45-47: Cross-references align with PR structure.The see-also references point to related database documentation files that are part of this PR, creating a cohesive documentation set.
11-11: No changes needed. The migration directory pathsrc/tux/database/migrations/versions/exists and is correctly referenced in the documentation..cursor/commands/discord/create-module.md (2)
22-24: Documentation aligns with project patterns.The guidance correctly emphasizes hybrid commands and permission checks, consistent with established project patterns. Based on learnings, this aligns with the requirement to implement role-based permissions and use hybrid commands for Discord commands.
17-17: All referenced components exist in the codebase:BaseCog(src/tux/core/base_cog.py),ModerationCogBase(src/tux/modules/moderation/init.py),@requires_command_permissiondecorator (src/tux/core/decorators.py), andtux.ui.embedsmodule. The documentation references are accurate..cursor/commands/code-quality/lint.md (3)
57-59: All referenced commands and rules exist:/refactorand/review-existing-diffscommands are present in.cursor/commands/code-quality/, and@core/tech-stack.mdcrule exists in.cursor/rules/core/.
19-19: NumPy docstring format is properly configured in the project (pydoclint and pydocstyle both set tostyle = "numpy"in pyproject.toml). The lint.md documentation correctly reflects this as a project standard.
10-13: Thedev allcommand is properly implemented inscripts/dev/all.pyand registered in the dev command group. No issues found..cursor/commands/documentation/docs-serve.md (2)
51-53: All referenced files exist:@docs/zensical.mdcis located at.cursor/rules/docs/zensical.mdc, and both/generate-docsand/update-docscommands are present at.cursor/commands/documentation/generate-docs.mdand.cursor/commands/documentation/update-docs.mdrespectively. The see-also section references are valid.
10-10: No changes needed.Both verification points in the original comment have been confirmed:
- The
scripts.docsmodule does implement aservesubcommand (defined inscripts/docs/serve.pywith@app.command(name="serve"))- Port 8000 is indeed the default (set as the default value for
dev_addrparameter:"localhost:8000")The
uv run docs servecommand documentation is accurate and complete..cursor/README.md (3)
18-42: Verify documented directory structure exists.The README documents a comprehensive directory structure for rules and commands. Confirm these directories exist as documented:
- Rules directories:
core/,database/,modules/,testing/,docs/,security/,error-handling/,ui/,meta/- Commands directories:
code-quality/,testing/,database/,discord/,security/,debugging/,error-handling/,documentation/,development/
62-62: All referenced documentation files exist at the specified paths. No action required.
rules/rules.mdc→.cursor/rules/rules.mdc✓creating-cursor-rules.md→docs/content/developer/guides/creating-cursor-rules.md✓creating-cursor-commands.md→docs/content/developer/guides/creating-cursor-commands.md✓AGENTS.md→./AGENTS.md✓
73-74: Documentation links are valid. Both Cursor documentation URLs point to the correct resources and are accessible..cursor/commands/error-handling/add-error-handling.md (1)
1-47: Well-structured command documentation with clear guidance.The error handling command provides practical step-by-step guidance and a comprehensive checklist. All referenced error-handling rules exist in this PR and cross-references are accurate.
.cursor/rules/error-handling/patterns.mdc (1)
1-163: Comprehensive error handling guidance aligned with best practices.The patterns documentation correctly emphasizes custom exceptions from
tux.shared.exceptions, proper error context preservation withfrom e, and separation of local vs. global error handlers. The examples and anti-patterns are clear and actionable..cursor/commands/development/setup-project.md (1)
1-61: Clear setup workflow with proper sequencing.The setup guide follows a logical progression and references both Docker and database commands appropriately. The cross-references use consistent notation (@ for rules, / for commands).
.cursor/rules/testing/fixtures.mdc (1)
1-206: Comprehensive fixture patterns with proper scope and organization guidance.The fixture documentation correctly describes scoping strategies (session for expensive setup, function for isolation), shows proper typing, and emphasizes cleanup patterns. The fixture dependency chain example clearly demonstrates composition.
.cursor/commands/code-quality/review-existing-diffs.md (1)
1-57: Clear code review workflow with actionable checklist.The review guidance covers Tux-specific checks (database, tests, docs, scripts) and includes a comprehensive checklist. Cross-references to related linting, refactoring, and test commands are consistent with project structure.
.cursor/commands/database/health.md (1)
1-47: Practical database health check guide with clear diagnostic steps.The health check command provides systematic troubleshooting steps from connection verification through operation testing. Cross-references to related database commands and rules are consistent.
.cursor/rules/core/tech-stack.mdc (3)
2-3: Good additions to frontmatter and workflow section.The added description field and alwaysApply flag are appropriate. The development workflow examples effectively demonstrate the correct use of
uvcommands and discourage common anti-patterns like bypassing setup or using Python directly.
62-64: Database driver documentation is accurate.The characterization of asyncpg being approximately 5x faster than psycopg aligns with documented performance benchmarks. Positioning asyncpg as primary and psycopg[binary,pool] as backup is a sensible choice for an async-first Discord bot that prioritizes concurrency and performance, particularly given the project's asyncio foundation.
122-144: Development workflow examples enforce project standards effectively.The GOOD examples correctly show the required setup sequence (
uv sync, environment configuration, quality checks, testing), and the BAD examples explicitly discourage common mistakes. This is pedagogically effective and aligns with the project's use ofuvas the single entry point for all CLI operations..cursor/rules/modules/permissions.mdc (2)
7-156: Content and examples are accurate and well-structured.The permission patterns, examples, and flow descriptions align with the Discord bot permission model used in the codebase (verified against the Purge cog context). The GOOD/BAD examples clearly demonstrate the decorator-based permission pattern, and the checking flow is logical and comprehensive.
1-156: All cross-referenced rule files are present.The permissions.mdc file references @modules/commands.mdc, @modules/cogs.mdc, @database/models.mdc, and @rules.mdc—all of which exist in the .cursor/rules/ directory.
AGENTS.md (3)
141-182: Workflow and PR requirements are well-integrated and consistent.The rules validation step is properly placed in the development workflow (step 4, between database and commit phases) and appropriately listed as a PR requirement. This aligns with the enforcement pattern described in the PR objectives (pre-commit hook + validation CLI).
60-64: Documentation updates provide valuable clarity on .cursor structure and database stack.The project structure now clearly documents the .cursor directory organization, and the database stack explicitly mentions psycopg async for PostgreSQL async support. These additions improve clarity for developers setting up the project and understanding the async database architecture.
Also applies to: 98-98
10-32: All referenced documentation files and CLI configuration are properly in place. The.cursor/rules/rules.mdcmaster catalog exists, both developer guide files (creating-cursor-rules.mdandcreating-cursor-commands.md) are present, and theuv run rules validatecommand is correctly registered inpyproject.tomlviascripts.rules:main. No changes required.
| ```toml | ||
| [tool.pytest.ini_options.markers] | ||
| unit = "Unit tests (uses py-pglite)" | ||
| integration = "Integration tests (uses py-pglite)" | ||
| slow = "Slow tests (>5 seconds)" | ||
| database = "Tests requiring database access" | ||
| async = "Async tests" | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Check the actual content of the markers.mdc file around the specified lines
cat -n .cursor/rules/testing/markers.mdc | sed -n '1,30p'Repository: allthingslinux/tux
Length of output: 949
🏁 Script executed:
# Check lines around 107-108 to see the example usage
cat -n .cursor/rules/testing/markers.mdc | sed -n '100,115p'Repository: allthingslinux/tux
Length of output: 510
🏁 Script executed:
# Check if pyproject.toml exists and what markers are defined there
if [ -f pyproject.toml ]; then
cat -n pyproject.toml | grep -A 10 "tool.pytest.ini_options.markers"
fiRepository: allthingslinux/tux
Length of output: 44
🌐 Web query:
pytest-asyncio marker naming convention what is the correct marker name
💡 Result:
The correct marker is pytest.mark.asyncio (e.g. @pytest.mark.asyncio). [1][2]
Sources:
[1] pytest-asyncio documentation — Markers.
[2] pytest-asyncio PyPI project page — Markers.
Fix async marker definition in TOML snippet.
The markers list defines async = "Async tests" (line 23), but the code example uses @pytest.mark.asyncio (line 107). The TOML snippet should be corrected to match the standard pytest-asyncio marker name:
asyncio = "Async tests"Alternatively, if a custom async marker is intended, update the code example to use @pytest.mark.async instead.
🤖 Prompt for AI Agents
In .cursor/rules/testing/markers.mdc around lines 17 to 24, the TOML markers
section defines the pytest async marker as `async = "Async tests"` which doesn't
match the code example that uses `@pytest.mark.asyncio`; update the TOML key to
`asyncio = "Async tests"` so the marker name matches pytest-asyncio, or
alternatively change the code examples to use `@pytest.mark.async` if a custom
`async` marker is intended—pick one approach and make the TOML and code
consistent.
…tation - Replaced the `uv run rules validate` command with `uv run ai validate-rules` for improved clarity and consistency in validation processes. - Updated relevant documentation across multiple files to reflect the new command structure, ensuring developers have accurate guidance on validation procedures. - Introduced a new `ai` command group to encapsulate AI-related tools and utilities, enhancing the organization of command functionalities. - Removed the deprecated `rules.py` file, streamlining the codebase and focusing on the new validation approach.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (4)
scripts/ai/__init__.py (1)
10-12: Consider explicit naming for the subcommand group.The
add_typercall omits thenameparameter. Sincevalidate_rules.appis created withcreate_app()(no name), the subcommand will inherit the command name from@app.command(name="validate-rules"). This works but could be confusing if more commands are added tovalidate_rules.applater.If this module is intended to hold only the
validate-rulescommand, the current approach is fine. If you plan to add more commands, consider either:
- Passing
name="validate-rules"explicitly here, or- Giving
validate_rules.appa name in itscreate_app()callscripts/ai/validate_rules.py (3)
188-196: Consider more robust path matching for special cases.The special case detection uses string matching on paths (e.g.,
"meta/" in str(file_path),"ui/cv2.mdc" in str(file_path)). This works but could fail on Windows or with unexpected path structures.Consider using
Path.partsorPath.match()for more robust matching:🔎 Proposed improvement
- is_spec = "meta/" in str(file_path) - is_docs_rule = "docs/" in str(file_path) - is_large_reference = "ui/cv2.mdc" in str(file_path) + is_spec = "meta" in file_path.parts + is_docs_rule = "docs" in file_path.parts + is_large_reference = file_path.match("**/ui/cv2.mdc")
41-50: Edge case in frontmatter closing check.Line 44 checks
"---\n" not in content[4:], which assumes the opening---is exactly 3 characters. If there's a BOM or extra whitespace, this could give false positives. The subsequent regex match (line 47) is more robust and will catch these cases, so this is low risk.🔎 Potential simplification
Consider relying solely on the regex match for validation:
def _check_rule_frontmatter(...) -> tuple[list[str], str | None]: ... if not content.startswith("---"): errors.append(f"{file_path}: Rule must start with frontmatter (---)") + return errors, None - if "---\n" not in content[4:]: - errors.append(f"{file_path}: Rule must have closing frontmatter (---)") - frontmatter_match = re.match(r"^---\n(.*?)\n---\n", content, re.DOTALL) if not frontmatter_match: - errors.append(f"{file_path}: Invalid frontmatter format") + errors.append(f"{file_path}: Invalid or missing closing frontmatter (---)") return errors, None
189-190: Consider error handling for file read operations.
file_path.read_text()can raiseOSErrororUnicodeDecodeError. While unlikely in normal operation, adding a try-except would make the tool more resilient:🔎 Proposed improvement
def _validate_rule(file_path: Path) -> list[str]: ... errors: list[str] = [] - content = file_path.read_text(encoding="utf-8") + try: + content = file_path.read_text(encoding="utf-8") + except OSError as e: + return [f"{file_path}: Failed to read file: {e}"] + except UnicodeDecodeError as e: + return [f"{file_path}: Invalid encoding: {e}"]Apply similar handling in
_validate_command.Also applies to: 248-249
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
.pre-commit-config.yamlAGENTS.mddocs/content/developer/guides/creating-cursor-commands.mddocs/content/developer/guides/creating-cursor-rules.mdpyproject.tomlscripts/__init__.pyscripts/ai/__init__.pyscripts/ai/validate_rules.py
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/content/developer/guides/creating-cursor-rules.md
🧰 Additional context used
📓 Path-based instructions (1)
**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
**/*.py: Use strict type hints withType | Noneinstead ofOptional[Type]
Use NumPy docstrings for documenting functions and classes
Prefer absolute imports; relative imports allowed only within the same module
Organize imports in order: stdlib → third-party → local
Use 88 character line length
Use snake_case for functions and variables, PascalCase for classes, UPPER_CASE for constants
Always add imports to the top of the file unless absolutely necessary
Use async/await for I/O operations
Use custom exceptions for business logic with context logging and meaningful user messages
Use Pydantic for data validation
Keep files to a maximum of 1600 lines
Use one class or function per file when possible
Use descriptive filenames
Add appropriate logging to services and error handlers
Files:
scripts/ai/__init__.pyscripts/ai/validate_rules.pyscripts/__init__.py
🧠 Learnings (5)
📚 Learning: 2025-12-21T20:54:29.808Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: .cursor/rules/rules.mdc:0-0
Timestamp: 2025-12-21T20:54:29.808Z
Learning: Follow the coding agent rules defined in AGENTS.md
Applied to files:
AGENTS.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/database/**/*.py : Use SQLModel for type-safe database operations
Applied to files:
AGENTS.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/alembic/**/*.py : Use Alembic for database migrations
Applied to files:
AGENTS.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/database/**/*.py : Optimize database queries
Applied to files:
AGENTS.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/database/**/*.py : Use transactions for multi-step database operations
Applied to files:
AGENTS.md
🧬 Code graph analysis (2)
scripts/ai/__init__.py (4)
scripts/ai/validate_rules.py (1)
validate_rules(329-405)scripts/core.py (1)
create_app(35-66)typings/typer/main.pyi (1)
add_typer(31-32)scripts/__init__.py (1)
main(27-29)
scripts/ai/validate_rules.py (1)
scripts/core.py (1)
create_app(35-66)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Run All Tests (3.13.8)
- GitHub Check: Sourcery review
🔇 Additional comments (9)
.pre-commit-config.yaml (2)
86-94: Well-structured pre-commit hook for Cursor validation.The hook configuration correctly:
- Uses
systemlanguage to leverage the localuvinstallation- Passes directory arguments explicitly
- Scopes file matching to
.cursor/(rules|commands)/paths- Uses
pass_filenames: falsesince the validator processes directories
29-29: Verify intentional version downgrades.Several hook versions were downgraded:
yamlfix: 1.19.1 → 1.19.0markdownlint-cli: v0.47.0 → v0.46.0ruff-pre-commit: v0.14.10 → v0.14.7If these are intentional (e.g., to avoid bugs in newer versions), consider adding a brief comment. Otherwise, these may have been accidentally reverted.
Also applies to: 44-44, 52-52, 57-57
docs/content/developer/guides/creating-cursor-commands.md (1)
1-277: Comprehensive and well-structured documentation.The guide provides clear, actionable steps for creating Cursor commands with appropriate templates, examples, and validation instructions. The cross-references to related documentation are helpful.
AGENTS.md (1)
10-33: Clear Cursor integration documentation.The new section provides a good overview of the rules/commands system with links to detailed documentation. The tip admonition directing users to domain-specific rules is helpful.
scripts/__init__.py (1)
8-8: Clean CLI group registration.The
aicommand group is properly imported and registered following the existing pattern for other command groups. Alphabetical ordering is maintained.Also applies to: 18-18
pyproject.toml (1)
66-66: Correct script entry registration.The new
aiscript entry follows the established pattern and correctly points toscripts.ai:main.scripts/ai/__init__.py (1)
1-17: Well-structured command group module.The module follows project patterns with NumPy docstrings and proper CLI wiring. The entry point is correctly defined for the pyproject.toml script.
scripts/ai/validate_rules.py (2)
328-344: Well-designed CLI command with sensible defaults.The command uses
AnnotatedwithOptionfor clear parameter documentation, and the default paths align with the project's.cursor/structure. The NumPy docstring is complete.
363-395: Good defensive handling for missing directories.The validation gracefully handles missing directories with warnings rather than errors, which is appropriate for a validation tool that might run in different contexts.
…-quality Python code - Added a new `deslop` command to guide developers in producing consistent, maintainable code while adhering to Tux project standards. - Included detailed steps for a research-first protocol, writing consistent code, and following Python standards to avoid common anti-patterns. - Established a checklist for self-audit and error handling to ensure code quality and adherence to best practices.
… rule files - Enhanced the frontmatter validation logic to provide clearer error messages for invalid or missing closing frontmatter. - Added error handling for file reading operations to catch and report issues related to file access and encoding. - Refactored checks for special cases in rule file paths to improve clarity and maintainability.
- Changed the validation command from `uv run rules validate` to `uv run ai validate-rules` in AGENTS.md to align with recent command structure updates. - Ensured that the documentation reflects the latest changes in the validation process for improved clarity and guidance.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
scripts/ai/validate_rules.py (1)
176-237: Hardcoded file exception for size limit.Line 201 hardcodes
**/ui/cv2.mdcas a large reference exception. Consider extracting this to a constant or configuration if more exceptions are needed in the future.🔎 Suggested refactor
+# Files exempt from the 500-line limit +LARGE_FILE_EXCEPTIONS: set[str] = {"**/ui/cv2.mdc"} + + def _validate_rule(file_path: Path) -> list[str]: # ... is_spec = "meta" in file_path.parts is_docs_rule = "docs" in file_path.parts - is_large_reference = file_path.match("**/ui/cv2.mdc") + is_large_reference = any(file_path.match(pattern) for pattern in LARGE_FILE_EXCEPTIONS)
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
.cursor/commands/code-quality/deslop.md.cursor/commands/deslop.mdAGENTS.mdscripts/ai/validate_rules.py
💤 Files with no reviewable changes (1)
- .cursor/commands/deslop.md
🧰 Additional context used
📓 Path-based instructions (1)
**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
**/*.py: Use strict type hints withType | Noneinstead ofOptional[Type]
Use NumPy docstrings for documenting functions and classes
Prefer absolute imports; relative imports allowed only within the same module
Organize imports in order: stdlib → third-party → local
Use 88 character line length
Use snake_case for functions and variables, PascalCase for classes, UPPER_CASE for constants
Always add imports to the top of the file unless absolutely necessary
Use async/await for I/O operations
Use custom exceptions for business logic with context logging and meaningful user messages
Use Pydantic for data validation
Keep files to a maximum of 1600 lines
Use one class or function per file when possible
Use descriptive filenames
Add appropriate logging to services and error handlers
Files:
scripts/ai/validate_rules.py
🧠 Learnings (6)
📓 Common learnings
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: .cursor/rules/rules.mdc:0-0
Timestamp: 2025-12-21T20:54:29.808Z
Learning: Follow the coding agent rules defined in AGENTS.md
📚 Learning: 2025-12-21T20:54:29.808Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: .cursor/rules/rules.mdc:0-0
Timestamp: 2025-12-21T20:54:29.808Z
Learning: Follow the coding agent rules defined in AGENTS.md
Applied to files:
AGENTS.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/database/**/*.py : Use SQLModel for type-safe database operations
Applied to files:
AGENTS.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/alembic/**/*.py : Use Alembic for database migrations
Applied to files:
AGENTS.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/database/**/*.py : Optimize database queries
Applied to files:
AGENTS.md
📚 Learning: 2025-12-28T16:20:43.646Z
Learnt from: CR
Repo: allthingslinux/tux PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T16:20:43.646Z
Learning: Applies to **/database/**/*.py : Use transactions for multi-step database operations
Applied to files:
AGENTS.md
🪛 LanguageTool
.cursor/commands/code-quality/deslop.md
[grammar] ~1-~1: Ensure spelling is correct
Context: # Deslop ## Overview Produce high-quality Python co...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Run All Tests (3.13.8)
- GitHub Check: Sourcery review
🔇 Additional comments (11)
.cursor/commands/code-quality/deslop.md (3)
1-6: LGTM! Well-structured command guide.The "Deslop" term is intentional (removing "slop" patterns from AI-generated code) and the static analysis spelling warning is a false positive. The document provides comprehensive, actionable guidance for maintaining code quality.
29-36: Python standards section aligns with project coding guidelines.The documented standards (
Type | None, NumPy docstrings, 88-char line length, naming conventions) correctly reflect the project's coding guidelines.
140-148: All cross-referenced commands and rules exist in the repository. No issues found with the references in the "See Also" section.AGENTS.md (4)
10-33: LGTM! Well-structured Cursor Rules & Commands section.This new section provides clear documentation with validation commands, links to guides, and a helpful tip about detailed rules. The command
uv run ai validate-rulesis consistently referenced throughout the document.
134-138: Past review comment addressed.The command reference is now correctly
uv run ai validate-rules, matching other references in this file.
252-255: Past review comment addressed.The troubleshooting section now correctly uses
uv run ai validate-rules.
98-98: Incorrect driver terminology in stack description.The stack should reference "psycopg" (not "psycopg async"). The codebase uses
psycopg[binary,pool]>=3.2.9as the PostgreSQL driver, which natively supports async operations via SQLAlchemy'screate_async_engine. The term "psycopg async" is imprecise;asyncpgis not used as the driver (onlyasyncpg-stubsexists for type checking). Update line 98 to:**Stack:** SQLModel (ORM) • Alembic (migrations) • PostgreSQL (psycopg)Likely an incorrect or invalid review comment.
scripts/ai/validate_rules.py (4)
1-18: LGTM! Well-organized module structure.Module docstring, imports (stdlib → third-party → local), and app initialization follow project standards.
21-75: LGTM! Robust frontmatter validation.The function correctly handles edge cases:
- Missing frontmatter start
- Invalid/missing closing frontmatter
- Array format detection for globs
- Quoted pattern detection
Good use of early returns with error context.
338-415: LGTM! Well-implemented CLI command.The
validate_rulesfunction:
- Uses
AnnotatedwithOptionfor Typer integration- Has complete NumPy-style docstring
- Handles missing directories gracefully with warnings
- Provides clear console output with rich formatting
- Correctly exits with code 1 on validation failure
190-195: Good error handling for file operations.Catching both
OSErrorandUnicodeDecodeErrorseparately provides clear, specific error messages for different failure modes.
…tation - Changed the command for creating migrations from `uv run db migrate-dev` to `uv run db dev` for consistency. - Updated Docker service startup commands from `uv run docker up` to `docker compose up -d` in both the setup-project and docker-up documentation. - Revised related command references for clarity and accuracy in the documentation.
…tion - Introduced a set of exempted files from the 500-line limit, specifically for `ui/cv2.mdc`. - Updated the validation logic to check against this set, improving handling of large reference files in the validation process.
Pull Request
Description
Provide a clear summary of your changes and reference any related issues. Include the motivation behind these changes and list any new dependencies if applicable.
If your PR is related to an issue, please include the issue number below:
Related Issue: Closes #
Type of Change:
Guidelines
My code follows the style guidelines of this project (formatted with Ruff)
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation if needed
My changes generate no new warnings
I have tested this change
Any dependent changes have been merged and published in downstream modules
I have added all appropriate labels to this PR
I have followed all of these guidelines.
How Has This Been Tested? (if applicable)
Please describe how you tested your code. e.g describe what commands you ran, what arguments, and any config stuff (if applicable)
Screenshots (if applicable)
Please add screenshots to help explain your changes.
Additional Information
Please add any other information that is important to this PR.
Summary by Sourcery
Integrate a Cursor-based rules and commands system into the project and document how to use and validate it as part of the standard development workflow.
New Features:
uv run rules …) for validating Cursor rules and commands and expose it via the project scripts entry point..cursor/commands.Enhancements:
Build:
pyproject.tomlso it can be invoked viauv run rules.CI:
uv run rules validateon.cursorrule and command changes to enforce consistency and standards.Documentation:
.cursor/README.mdexplaining the rules and commands system, directory structure, usage patterns, and contribution guidelines.