open-agent-library/rule/code-styling-guidelines.md

description

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.