create-merlin-brain 3.8.2 → 3.10.0

package/rules/python.md

@@ -0,0 +1,38 @@
+# Python Coding Rules
+
+## Type Hints
+- Type hints on all function signatures — parameters and return types
+- Use `from __future__ import annotations` for forward references
+- Prefer concrete types (`list[str]`) over generic aliases (`List[str]`) for Python 3.9+
+- `Optional[X]` → `X | None` (Python 3.10+ union syntax preferred)
+
+## Data Structures
+- Dataclasses (`@dataclass`) for plain data containers — avoid raw dicts for structured data
+- Pydantic for validated data (API payloads, configs) — use `model_validator` not `__init__`
+- No mutable default arguments: `def foo(items=None): items = items or []` pattern
+- Prefer `TypedDict` over plain `dict` when shape is known and Pydantic is overkill
+
+## Strings & Output
+- f-strings for all string interpolation — never `%` formatting or `.format()` for new code
+- Multi-line strings: use triple-quoted f-strings, not concatenation
+- `str.join()` for building strings from lists — avoid `+=` in loops
+
+## File & Resource Handling
+- `pathlib.Path` for all filesystem paths — never `os.path.join` in new code
+- Context managers (`with`) for files, network connections, locks — never manual `.close()`
+- `tempfile` module for temporary files — never hardcode `/tmp/`
+
+## Functions & Classes
+- Single responsibility per function; >20 lines is a signal to refactor
+- Class methods that don't use `self` should be `@staticmethod` or module-level functions
+- `__slots__` on data classes where performance matters
+- Abstract base classes (`ABC`) to define interfaces; avoid duck-typing where contracts matter
+
+## Error Handling
+- Specific exceptions over `except Exception` — catch the narrowest type possible
+- Custom exception classes for domain errors (inherit from `Exception` with a clear name)
+- `logging` module, not `print()` — use structured log fields
+
+## Async
+- `asyncio.gather()` for concurrent coroutines — avoid sequential `await` in a loop
+- Mark I/O-bound functions `async def`; CPU-bound code stays sync (use `ProcessPoolExecutor`)

package/rules/rust.md

@@ -0,0 +1,34 @@
+# Rust Coding Rules
+
+## Ownership & Borrowing
+- Ownership over reference counting — prefer passing values or borrows over `Rc`/`Arc`
+- `Arc<Mutex<T>>` for shared mutable state across threads; document why sharing is needed
+- Avoid cloning in hot paths — profile before adding `.clone()` calls
+- Return owned values from functions that create data; accept borrows in functions that read
+
+## Error Handling
+- `Result<T, E>` for all fallible operations — never panic in library code
+- Custom error types with `thiserror` for libraries; `anyhow` for application binaries
+- `?` operator for propagation — avoid `unwrap()` in production code; prefer `expect("reason")`
+- Map errors at boundaries: `map_err(|e| MyError::Database(e))`
+
+## Types & Traits
+- Derive traits liberally: `#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]`
+- `impl` blocks immediately after their `struct`/`enum` definition in the same file
+- Prefer `&str` over `String` in function parameters (accepts both literals and owned strings)
+- `Into<T>` / `From<T>` for ergonomic conversions; implement `Display` for user-facing types
+
+## Structs & Enums
+- Exhaustive `match` on enums — no `_ =>` catch-all unless truly irrelevant variants exist
+- Newtype pattern (`struct UserId(u64)`) to prevent mixing domain IDs
+- Builder pattern for structs with many optional fields (derive with `typed-builder`)
+
+## Async
+- `tokio` for async runtime; `async-trait` for async in trait methods
+- `tokio::join!` / `tokio::try_join!` for concurrent futures
+- Avoid blocking calls inside async context — use `tokio::task::spawn_blocking`
+
+## Safety
+- No `unsafe` without a `// SAFETY:` comment explaining the invariant
+- Keep `unsafe` blocks as small as possible; encapsulate behind a safe API
+- Prefer `Vec` and slices over raw pointer arithmetic

package/rules/swift.md

@@ -0,0 +1,35 @@
+# Swift Coding Rules
+
+## Concurrency (Swift 6)
+- `async`/`await` for all asynchronous operations — no completion handler callbacks in new code
+- Actors for shared mutable state: `actor MyService { ... }`
+- `@MainActor` on UI-bound types and functions
+- `Sendable` conformance required for types crossing actor boundaries — use `@unchecked Sendable` sparingly with a justification comment
+- `async let` for independent concurrent work; `withTaskGroup` for dynamic concurrency
+
+## Types & Values
+- Value types (`struct`, `enum`) by default — use `class` only when reference semantics are required (identity, inheritance, Obj-C interop)
+- Protocol-oriented design: define capabilities as protocols, extend with default implementations
+- `enum` with associated values for discriminated unions instead of subclassing
+- Avoid `@objc` and `NSObject` subclasses unless required for interoperability
+
+## Optionals & Safety
+- `guard` for early returns when preconditions fail — keeps happy path unindented
+- Never force-unwrap (`!`) except in tests or `@IBOutlet` — use `guard let` or `if let`
+- `??` for default values on optionals; avoid chained optionals deeper than 2 levels
+- Mark parameters optional (`T?`) only when absence carries meaning; prefer overloads otherwise
+
+## Memory Management
+- `weak` references to break retain cycles (delegates, closures capturing self)
+- `unowned` only when the object is guaranteed to outlive the reference — prefer `weak` when uncertain
+- Use `[weak self]` captures in closures stored beyond the current scope
+
+## Protocols & Extensions
+- Small, focused protocols (Interface Segregation) — prefer many narrow protocols over one wide one
+- Extensions to add protocol conformances, keeping the type definition clean
+- `Codable` for serialisable types; `CodingKeys` enum to map non-Swift naming
+
+## Style
+- `let` by default; `var` only when mutation is needed
+- 4-space indentation, Allman-style braces
+- Prefer named parameters at call sites for clarity

package/rules/typescript.md

@@ -0,0 +1,38 @@
+# TypeScript Coding Rules
+
+## Type Safety
+- Enable strict mode — no `any` without an explicit justification comment
+- Prefer `unknown` over `any` for values of uncertain type; narrow with type guards
+- Use `satisfies` operator for type-safe literal assignments
+- Avoid type assertions (`as Foo`) unless interfacing with untyped third-party code
+
+## Variables & Functions
+- `const` by default, `let` only when reassignment is necessary — never `var`
+- `async`/`await` over raw Promise chains; avoid `.then()` chains longer than 2 steps
+- Explicit return types on exported functions; internal functions may infer
+- Exhaustive switch/case: add a `default` that asserts `never` to catch future enum additions
+
+## Interfaces & Types
+- `interface` for object shapes (extendable, declaration-merged)
+- `type` for unions, intersections, primitives, and mapped types
+- No empty interfaces (`interface Foo {}`); use `Record<never, never>` or a comment
+
+## Error Handling
+- Typed errors: extend `Error` with named subclasses for domain errors
+- No bare `catch (e) {}` — always log or rethrow with context
+- Use `Result<T, E>` patterns for expected failure paths (avoid throw-for-control-flow)
+- Wrap third-party calls in try/catch at the boundary, not deep in business logic
+
+## Imports & Modules
+- Use named exports; avoid default exports (harder to rename/trace)
+- Group imports: external packages → internal modules → relative paths (blank line between)
+- Barrel files (`index.ts`) only at module boundaries, not within a feature folder
+
+## Async & Concurrency
+- `Promise.all` for independent async operations (don't serialize what can parallelize)
+- Avoid `async` functions that never `await` anything
+- Always handle rejected promises — no floating promise anti-pattern
+
+## Null Safety
+- Prefer optional chaining (`?.`) and nullish coalescing (`??`) over manual null checks
+- Avoid optional properties (`foo?: string`) on data types; use `| null` for explicitness