@dv.nghiem/flowdeck 0.1.0

package/src/rules/java/patterns.md

@@ -0,0 +1,204 @@
+# Java Patterns
+
+Java conventions for FlowDeck projects. Targets Java 17+.
+
+## Constructor Injection Only
+
+Use constructor injection for all Spring-managed beans. Never use field injection.
+
+```java
+// ❌ Field injection — hides dependencies, cannot be tested without Spring
+@Service
+public class ReportService {
+    @Autowired private UserRepository users;
+    @Autowired private EmailService email;
+}
+
+// ✅ Constructor injection — explicit, testable, fields can be final
+@Service
+public class ReportService {
+    private final UserRepository users;
+    private final EmailService email;
+
+    public ReportService(UserRepository users, EmailService email) {
+        this.users = users;
+        this.email = email;
+    }
+}
+```
+
+## Never Return null from Public Methods
+
+Public methods must not return `null`. Use `Optional<T>` for absence, throw for impossible states.
+
+```java
+// ❌ null return — callers can't tell if null is expected or a bug
+public User findUser(long id) {
+    return repository.findById(id);  // returns null when not found
+}
+
+// ✅ Optional signals intentional absence
+public Optional<User> findUser(long id) {
+    return repository.findById(id);
+}
+
+// ✅ Throw when absence is a contract violation
+public User getUser(long id) {
+    return repository.findById(id)
+        .orElseThrow(() -> new UserNotFoundException(id));
+}
+```
+
+## All DTOs Should Be Records
+
+Use Java records (Java 16+) for data transfer objects, API request/response bodies, and value objects.
+
+```java
+// ❌ Mutable class with boilerplate
+public class CreateUserRequest {
+    private String email;
+    private String name;
+    // getters, setters, equals, hashCode, toString...
+}
+
+// ✅ Record — immutable, compact, compiler-generated methods
+public record CreateUserRequest(String email, String name) {}
+
+// Records can include validation
+public record PageRequest(int page, int size) {
+    public PageRequest {
+        if (page < 0) throw new IllegalArgumentException("page must be >= 0");
+        if (size < 1 || size > 100) throw new IllegalArgumentException("size must be 1–100");
+    }
+}
+```
+
+## Use var for Obvious Local Variable Types
+
+Use `var` when the right-hand side makes the type immediately apparent. Do not use `var` when it obscures the type.
+
+```java
+// ✅ Type is obvious from the right-hand side
+var users = new ArrayList<User>();
+var config = PaymentConfig.load();
+var client = new HttpClient();
+
+// ❌ Type is not obvious — write it out
+var result = process(data);   // what type is result?
+var x = getValue();           // unclear
+```
+
+## Avoid Checked Exceptions in New Code
+
+New code must not declare checked exceptions. Wrap checked exceptions from third-party libraries in unchecked exceptions and preserve the cause.
+
+```java
+// ❌ Checked exception propagates through every caller
+public List<User> loadUsers() throws IOException { ... }
+
+// ✅ Unchecked exception at the boundary
+public List<User> loadUsers() {
+    try {
+        return parser.parse(Files.readString(configPath));
+    } catch (IOException e) {
+        throw new UserLoadException("failed to read users from " + configPath, e);
+    }
+}
+```
+
+## All Database Queries Must Have Explicit Transaction Boundaries
+
+Annotate the service method with `@Transactional`, not the repository method. The service defines the unit of work.
+
+```java
+// ❌ Transaction on repository — too granular, two separate transactions
+public void transfer(long fromId, long toId, BigDecimal amount) {
+    accountRepo.debit(fromId, amount);   // tx 1
+    accountRepo.credit(toId, amount);    // tx 2 — debit committed even if credit fails
+}
+
+// ✅ Transaction on service method — single atomic unit
+@Transactional
+public void transfer(long fromId, long toId, BigDecimal amount) {
+    accountRepo.debit(fromId, amount);
+    accountRepo.credit(toId, amount);    // rolls back both on failure
+}
+```
+
+## Never Use String.format() in Hot Paths
+
+Avoid `String.format()` in loops or frequently-called methods. Use `StringBuilder` or text blocks.
+
+```java
+// ❌ String.format in a loop — allocates a new formatter each iteration
+for (var item : items) {
+    log.debug(String.format("Processing item id=%d name=%s", item.id(), item.name()));
+}
+
+// ✅ SLF4J lazy substitution — string only built if DEBUG is enabled
+for (var item : items) {
+    log.debug("Processing item id={} name={}", item.id(), item.name());
+}
+
+// ✅ StringBuilder for building large strings
+var sb = new StringBuilder();
+for (var item : items) {
+    sb.append(item.name()).append(", ");
+}
+```
+
+## Testing Strategy
+
+- **Unit tests**: pure JUnit 5 + Mockito, annotated with `@ExtendWith(MockitoExtension.class)`. No Spring context.
+- **Web slice tests**: `@WebMvcTest` for controller layer only.
+- **Integration tests**: `@SpringBootTest` for end-to-end paths. Use `@Transactional` to roll back data after each test.
+- Do not use `@SpringBootTest` for pure service or repository unit tests — it loads the full context unnecessarily.
+
+```java
+// Unit test — no Spring
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+    @Mock OrderRepository orders;
+    @InjectMocks OrderService service;
+    ...
+}
+
+// Integration test
+@SpringBootTest
+@Transactional
+class OrderFlowIntegrationTest { ... }
+```
+
+## Lombok Usage
+
+Lombok is permitted only for the following annotations:
+
+- `@Builder` — for complex object construction
+- `@Value` — for immutable classes (prefer records for new code)
+- `@Slf4j` — for logger injection
+
+Do **not** use `@Data` on JPA entities. It generates `equals`/`hashCode` based on all fields, which causes problems with proxies and lazy loading. Implement them manually using only the primary key.
+
+```java
+// ❌ @Data on entity
+@Data
+@Entity
+public class Order { ... }
+
+// ✅ @Slf4j and manual equals/hashCode on entity
+@Slf4j
+@Entity
+public class Order {
+    @Id private Long id;
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof Order other)) return false;
+        return id != null && id.equals(other.id);
+    }
+
+    @Override
+    public int hashCode() { return getClass().hashCode(); }
+}
+```

package/src/rules/python/patterns.md

@@ -0,0 +1,141 @@
+# Python Patterns
+
+Python conventions for FlowDeck projects.
+
+## Module Organization
+
+- Single `.py` file for small, cohesive utilities.
+- Convert to a package (`dir/__init__.py`) when the file grows past ~300 lines or needs sub-modules.
+- Keep `__init__.py` thin — expose only the public API; don't execute side effects.
+- Declare `__all__` in every module that has a meaningful public surface.
+
+```python
+# mypackage/__init__.py
+from .core import Engine
+from .config import Config
+
+__all__ = ["Engine", "Config"]
+```
+
+## Naming Conventions
+
+| Construct | Style | Example |
+|---|---|---|
+| Variable / function / method | `snake_case` | `get_user`, `is_active` |
+| Class | `PascalCase` | `UserService`, `HttpClient` |
+| Module / package | `snake_case` | `user_service.py` |
+| Constant (module-level) | `SCREAMING_SNAKE_CASE` | `MAX_RETRIES = 3` |
+| "Private" member | `_leading_underscore` | `_internal_cache` |
+| Name-mangled member | `__double_leading` | `__secret` (avoid in most cases) |
+
+## Never Use Mutable Default Arguments
+
+```python
+# ❌ The list is shared across all calls
+def add_item(item, lst=[]):
+    lst.append(item)
+    return lst
+
+# ✅ Use None and guard inside the function
+def add_item(item, lst=None):
+    if lst is None:
+        lst = []
+    lst.append(item)
+    return lst
+```
+
+## Always Use f-strings
+
+```python
+# ❌ %-formatting — old, hard to read
+msg = "Hello, %s! You have %d messages." % (name, count)
+
+# ❌ .format() — verbose
+msg = "Hello, {}! You have {} messages.".format(name, count)
+
+# ✅ f-string — concise, readable, evaluated at runtime
+msg = f"Hello, {name}! You have {count} messages."
+
+# f-strings support expressions and format specs
+price = f"${amount:.2f}"
+debug = f"{obj!r}"
+```
+
+## Use pathlib.Path, Not os.path
+
+```python
+# ❌ os.path — verbose and easy to misuse
+import os
+full_path = os.path.join(base_dir, "data", "users.csv")
+if os.path.exists(full_path):
+    with open(full_path) as f: ...
+
+# ✅ pathlib.Path — object-oriented, composable
+from pathlib import Path
+full_path = Path(base_dir) / "data" / "users.csv"
+if full_path.exists():
+    content = full_path.read_text()
+```
+
+## Prefer Explicit Over Implicit
+
+```python
+# ❌ Wildcard import — pollutes namespace, hides dependencies
+from mymodule import *
+
+# ✅ Explicit import — clear origin of each name
+from mymodule import SpecificClass, helper_function
+```
+
+## Type Annotations on All Public Functions
+
+Every public function and method must have type annotations on all parameters and the return type.
+
+```python
+# ❌ No annotations
+def find_users(active, limit):
+    ...
+
+# ✅ Fully annotated
+def find_users(active: bool, limit: int = 100) -> list[User]:
+    ...
+```
+
+Private/internal functions (prefixed with `_`) should be annotated where the types are non-obvious.
+
+## Testing with pytest
+
+- All tests use `pytest`. Do not use `unittest` for new code (legacy code may remain).
+- Test files: `tests/test_<module>.py` or co-located `<module>_test.py`.
+- Use fixtures for setup/teardown — not `setUp`/`tearDown` class methods.
+- Use `@pytest.mark.parametrize` for functions that need more than two input cases.
+- Tests must be deterministic — no time-dependent, order-dependent, or network-dependent tests without explicit mocking.
+
+```python
+# ✅ parametrize instead of copy-pasted test functions
+@pytest.mark.parametrize("value,expected", [
+    (0, False),
+    (1, True),
+    (-1, False),
+])
+def test_is_positive(value: int, expected: bool) -> None:
+    assert is_positive(value) == expected
+```
+
+## Virtual Environments — Never Global pip Install
+
+```bash
+# ✅ Create a venv and install there
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# ✅ uv (preferred — much faster)
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# ❌ Never install packages globally for a project
+pip install requests   # installs into system Python
+```
+
+All project dependencies must live in `pyproject.toml`. Development tools (pytest, mypy, ruff) go in `[project.optional-dependencies]` under `dev`.

package/src/rules/rust/patterns.md

@@ -0,0 +1,210 @@
+# Rust Patterns
+
+Rust conventions for FlowDeck projects.
+
+## Prefer Result<T, E> Over Panicking in Library Code
+
+Library code must not panic on expected failure conditions. Return `Result` and let the caller decide how to handle the error.
+
+```rust
+// ❌ Panics on invalid input — caller has no recovery path
+pub fn parse_port(s: &str) -> u16 {
+    s.parse().unwrap()
+}
+
+// ✅ Return Result — caller decides what to do
+pub fn parse_port(s: &str) -> Result<u16, std::num::ParseIntError> {
+    s.parse()
+}
+```
+
+Application code (binaries, CLI entrypoints) may use `?` propagation up to `main`, which prints the error and exits.
+
+## Use thiserror for Library Errors, anyhow for Application Errors
+
+```rust
+// Library crate: thiserror — structured, matchable error variants
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum CacheError {
+    #[error("key {0:?} not found")]
+    NotFound(String),
+    #[error("serialization failed: {0}")]
+    Serialize(#[from] serde_json::Error),
+}
+
+// Application binary: anyhow — ergonomic propagation with context
+use anyhow::{Context, Result};
+
+fn run() -> Result<()> {
+    let config = load_config("app.toml")
+        .context("loading application config")?;
+    serve(config).await
+}
+```
+
+## Never Use unwrap() in Production Code
+
+`unwrap()` panics on `None` or `Err`. Use `expect()` with a message that explains the invariant being asserted, or propagate with `?`.
+
+```rust
+// ❌ Panics with an unhelpful message
+let port: u16 = env::var("PORT").unwrap().parse().unwrap();
+
+// ✅ expect() with a reason
+let port_str = env::var("PORT")
+    .expect("PORT environment variable must be set");
+let port: u16 = port_str
+    .parse()
+    .expect("PORT must be a valid u16");
+
+// ✅ Propagate with ? when inside a Result-returning function
+let port: u16 = env::var("PORT")?.parse()?;
+```
+
+## All Public Items Must Have rustdoc Comments
+
+Every public function, struct, enum, trait, and module requires a doc comment (`///`).
+
+```rust
+// ❌ No documentation
+pub fn compress(data: &[u8]) -> Vec<u8> { ... }
+
+// ✅ Describe what it does, mention important contracts
+/// Compresses `data` using LZ4 and returns the compressed bytes.
+///
+/// Returns an empty `Vec` if `data` is empty.
+/// Panics if the internal compressor is exhausted (should never happen in practice).
+pub fn compress(data: &[u8]) -> Vec<u8> { ... }
+```
+
+## Use the Newtype Pattern for Semantically Distinct Primitives
+
+Wrapping primitives prevents accidentally mixing values of different meaning.
+
+```rust
+// ❌ Easy to confuse which u64 is which
+fn transfer(from: u64, to: u64, amount: u64) { ... }
+
+// ✅ Distinct types — compiler catches transpositions
+pub struct AccountId(u64);
+pub struct CentAmount(u64);
+
+fn transfer(from: AccountId, to: AccountId, amount: CentAmount) { ... }
+```
+
+Newtype wrappers have zero runtime overhead.
+
+## Prefer iter() Chains Over Explicit Loops When Semantics Are Clear
+
+```rust
+// ❌ Explicit loop for a pure transformation
+let mut result = Vec::new();
+for item in &items {
+    if item.is_active() {
+        result.push(item.name.clone());
+    }
+}
+
+// ✅ Iterator chain — intent is immediately clear
+let result: Vec<String> = items.iter()
+    .filter(|item| item.is_active())
+    .map(|item| item.name.clone())
+    .collect();
+
+// Use explicit loops when there are side effects or early returns that
+// would obscure the logic if written as a chain
+```
+
+## Derive Debug, Clone, PartialEq by Default on Data Structs
+
+```rust
+// ✅ Standard derives on data-holding structs
+#[derive(Debug, Clone, PartialEq)]
+pub struct Config {
+    pub host: String,
+    pub port: u16,
+    pub max_connections: usize,
+}
+
+// Add Eq when PartialEq implies total equality (no floats)
+// Add Hash when the type will be used as a map key
+// Add Serialize/Deserialize when crossing I/O boundaries
+#[derive(Debug, Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub struct UserId(u64);
+```
+
+## Test Organization
+
+- **Unit tests**: inside the module in a `#[cfg(test)]` block, next to the code they test.
+- **Integration tests**: in a top-level `tests/` directory. These test the public API of the crate.
+- **Doctests**: write examples in doc comments — they are compiled and run by `cargo test`.
+
+```rust
+// src/parser.rs
+pub fn parse(input: &str) -> Result<Ast, ParseError> { ... }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn empty_input_returns_error() {
+        assert!(parse("").is_err());
+    }
+
+    #[test]
+    fn valid_expression_parses_correctly() {
+        let ast = parse("1 + 2").unwrap();
+        assert_eq!(ast.eval(), 3);
+    }
+}
+```
+
+```rust
+// tests/integration_test.rs  — tests/ is a separate crate
+use mylib::parse;
+
+#[test]
+fn parses_complex_expression() {
+    let result = parse("(a + b) * c");
+    assert!(result.is_ok());
+}
+```
+
+## clippy Must Pass with No Warnings
+
+All code must pass `cargo clippy -- -D warnings` with no warnings. Enforce this in CI.
+
+If a lint must be suppressed, add `#[allow(...)]` on the smallest scope possible with a comment explaining why.
+
+```rust
+// ❌ Global allow — hides all issues of that category
+#![allow(clippy::unwrap_used)]
+
+// ✅ Local suppression with explanation
+#[allow(clippy::unwrap_used)]
+// Safety: regex pattern is a compile-time constant and always valid
+let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
+```
+
+## Never Use unsafe Without a Safety Comment
+
+Every `unsafe` block must have a comment that documents the invariants being upheld and why the operation is sound.
+
+```rust
+// ❌ unsafe with no explanation
+unsafe {
+    std::ptr::write(ptr, value);
+}
+
+// ✅ Safety comment explains the contract
+// SAFETY: `ptr` is non-null, properly aligned, and uniquely owned here.
+// The caller guaranteed these conditions in the function contract.
+unsafe {
+    std::ptr::write(ptr, value);
+}
+```
+
+If you cannot write a clear safety comment, reconsider whether `unsafe` is necessary.