style

rule/code-styling-guidelines.md

@@ -0,0 +1,97 @@
+---
+description: Comprehensive style and quality guidelines for writing python, typescript, and rust in compliance with code governance.
+---
+
+# Code Styling Guidelines
+
+This document outlines the coding standards, patterns, and architectural decisions for the NoteFlow project. Adherence to these guidelines ensures consistency, maintainability, and quality across the codebase.
+
+## Guidelines
+
+- **General Principles**
+    - **Strict Typing:** Python, TypeScript, and Rust codebases enforce strict typing.
+        - **No Type Suppression:** Bypassing the type system is strictly forbidden (no `# type: ignore`, `@ts-ignore`, or `#[allow(...)]` for type errors).
+        - **No Generic Types:** Use specific types; `Any` or `any` is forbidden unless absolutely no other option exists.
+    - **Async First:** The system is designed with asynchrony at its core.
+    - **Domain-Driven Design (DDD):** The backend follows DDD principles with clear separation of Domain, Application, and Infrastructure.
+    - **Local-First:** The architecture supports local-first operations.
+    - **Zero Tolerance:**
+        - **No TODOs/FIXMEs:** Do not commit technical debt markers. Fix it or track it externally.
+        - **No Commented Code:** Remove dead code entirely.
+        - **No Linter Warnings:** CI fails on any warning.
+    - **Centralization:** Helpers (formatting, conversion, storage wrappers) must be centralized, not scattered.
+- **Python Backend (`src/noteflow`)**
+    - **Tooling & Environment**
+        - **Manager:** `uv`.
+        - **Lint/Format:** `ruff` (line length **100**).
+        - **Type Check:** `mypy` & `basedpyright` (`strict = true`). No `type: ignore`.
+        - **Test:** `pytest` + `pytest-asyncio`.
+    - **Quality Gates (Enforced by `tests/quality`)**
+        - **Module Size:** Hard limit **600 lines** (Soft 350). *Action: Split into package.*
+        - **Complexity:**
+            - No "God Classes" (too many methods/responsibilities).
+            - No deep nesting (extract methods).
+            - Parameters < 5 (use Dataclasses for complex args).
+        - **Testing Standards:**
+            - **No Logic:** No `if`, `for`, `while` in tests (except stress tests).
+            - **No Sleep:** Never use `time.sleep` (flaky). Use async synchronization.
+            - **No `unittest`:** Use plain `assert`, never `self.assertEqual`.
+            - **Exceptions:** Use `pytest.raises(Exc, match="...")`. Never `try/except`.
+            - **Fixtures:** Must have type hints. No session-scoped mutation.
+        - **Smells:**
+            - **No Magic Numbers:** Use named constants.
+            - **No Sensitive Equality:** Avoid `assert str(obj) == "..."`.
+            - **No Eager Tests:** Test one behavior per method.
+    - **Architectural Patterns**
+        - **Layered:** `domain` (pure) -> `application` (services) -> `infrastructure` (adapters).
+        - **Entities:** `@dataclass(frozen=True)` or standard classes.
+        - **Ports:** `typing.Protocol` in `domain/ports`.
+        - **Services:** composed of Mixins (e.g., `MeetingServiceCrudMixin`) to keep files small.
+        - **Typing:** `str | None` (not `Optional`), `list[T]` (built-in generics).
+- **TypeScript Frontend (`client/src`)**
+    - **Tooling**
+        - **Build:** `vite`.
+        - **Lint/Format:** `biome` (primary), `eslint` (type-safety).
+        - **Test:** `vitest`.
+    - **Quality Gates (Enforced by `code-quality.test.ts`)**
+        - **File Size:** Limit **500 lines**.
+        - **Duplication:**
+            - **Strings:** No repeated literals (>3x). Extract to constants.
+            - **JSX:** No repeated complex patterns. Extract components.
+            - **Logic:** Centralize `format`/`parse` utils. No duplicate implementations of `cn`, `formatDate`.
+        - **React Patterns:**
+            - **Naming:** Components must be `PascalCase`.
+            - **No Prop Drilling:** Use Composition or Context.
+            - **No Nested Ternaries:** Use `if/return` or `switch`.
+            - **No Inline Styles:** Use Tailwind (`cn(...)`).
+            - **No Trivial Wrappers:** Don't wrap components just to rename props.
+        - **Async Safety:**
+            - **No Naked Catch:** `promise.catch(() => {})` is banned.
+            - **Fire-and-Forget:** Use `fireAndForget(promise)` wrapper for detached ops.
+    - **Type Safety**
+        - **No Suppressions:** `@ts-ignore`, `@ts-nocheck`, and `@ts-expect-error` are strictly forbidden.
+        - **No Unsafe Types:** Using `any` or `unknown` as a shortcut is banned. Use specific interfaces or Generics.
+        - **No Type Assertions:** Avoid `as any` or `as specificType` unless dealing with external JSON boundary.
+- **Rust Backend (`client/src-tauri`)**
+    - **Tooling**
+        - **Lint:** `cargo clippy -- -D warnings`.
+        - **Format:** `rustfmt`.
+        - **Check:** `./scripts/code_quality.sh`.
+    - **Quality Gates**
+        - **Safety:**
+            - **No `unwrap()`:** Strictly forbidden. Use `?`, `expect("context")`, or `unwrap_or`.
+            - **Clone Limit:** < 10 "suspicious" clones per file. Use `Arc` or references.
+        - **Complexity:**
+            - **Function Length:** < **90 lines**.
+            - **Nesting:** < **7 levels** (indentation).
+            - **Parameters:** Limit **5**. Use Structs.
+            - **File Size:** Limit **500 lines**.
+        - **Maintainability:**
+            - **No Magic Numbers:** Use `const`.
+            - **No Repeated Strings:** Extract `const`.
+            - **No Duplicated Errors:** Use specialized Error enums (e.g., `thiserror`).
+            - **Centralized Helpers:** `format_`, `convert_` fns must be in shared modules.
+- **Git & Workflow**
+    - **Commits:** Clear, imperative messages (e.g., "Add meeting service").
+    - **Pre-commit:** All quality checks (Python, TS, Rust) must pass locally.
+    - **Modularity:** Break down large files immediately upon hitting limits.