@rmrdeveloper/sideroom-pi 7.1.0 → 8.0.1

package/skills/sideroom-guidelines/references/languages/php-laravel.md

@@ -1,26 +1,248 @@
-# PHP / Laravel
+# PHP / Laravel Coding Guidelines
 
-Delta only. Keep the shared table.
+Rules every PHP or Laravel change must follow.
 
-- Braces on every `if` / `else`.
-- `FormRequest` (or one equivalent boundary) is the single validator. Services trust that contract and do not re-check the same rules.
-- Keep Eloquent/HTTP types out of domain logic.
+## Index
+
+| # | Rule | Tier |
+| --- | ------ | ------ |
+| 1 | [Braced conditionals](#1-braced-conditionals) | mechanical |
+| 2 | [No magic strings](#2-no-magic-strings) | mechanical |
+| 3 | [Guard clauses](#3-guard-clauses) | structural |
+| 4 | [Fail fast](#4-fail-fast) | structural |
+| 5 | [Explicit error handling](#5-explicit-error-handling) | structural |
+| 6 | [Clear names](#6-clear-names) | structural |
+| 7 | [Command Query Separation](#7-command-query-separation-cqs) | structural |
+| 8 | [Null/undefined handling](#8-nullundefined-handling) | structural |
+| 9 | [Immutability by default](#9-immutability-by-default) | structural |
+| 10 | [Validate once](#10-validate-once) | structural |
+| 11 | [Single Responsibility](#11-single-responsibility-srp) | architectural |
+| 12 | [DRY (real duplication only)](#12-dry-real-duplication-only) | architectural |
+| 13 | [KISS](#13-kiss) | architectural |
+| 14 | [YAGNI](#14-yagni) | architectural |
+| 15 | [Law of Demeter](#15-law-of-demeter) | architectural |
+| 16 | [Composition over inheritance](#16-composition-over-inheritance) | architectural |
+| 17 | [Dependency direction](#17-dependency-direction) | architectural |
+| 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
+| 19 | [Comments](#19-comments) | architectural |
+
+---
+
+### 1. Braced conditionals
+
+RULE: Every `if`/`else` body uses braces, even a one-line guard. Never bind a statement to a conditional by indentation alone.
+
+```php
+// bad
+if ($user === null) return 0;
+// good
+if ($user === null) { return 0; }
+```
+
+### 2. No magic strings
+
+RULE: Name domain/protocol literals once (const, enum, shared contract) and reuse the name. One-off strings with no reuse and no domain meaning may stay inline.
+
+```php
+// bad
+if ($order->status === 'pending_payment') { $this->charge($order); }
+// good
+if ($order->status === OrderStatus::PendingPayment) { $this->charge($order); }
+```
+
+### 3. Guard clauses
+
+RULE: Validate and exit early. Keep the happy path last, at the shallowest indent. No pyramid nesting.
+
+```php
+// bad
+if ($user !== null) { if ($user->isActive()) { return $user->hasSubscription() ? .2 : 0; } } return 0;
+// good
+if ($user === null || !$user->isActive() || !$user->hasSubscription()) { return 0; } return .2;
+```
+
+### 4. Fail fast
+
+RULE: Invalid input, impossible state, or a broken dependency throws immediately with a clear message. No fallback chains or silent defaults.
+WHY: This is for invariants that should never happen if upstream contracts hold — not license to re-check business rules a boundary already validated (see rule 10).
+
+```php
+// bad
+$zone = $zones[$order->zoneId] ?? $zones['default'];
+// good
+$zone = $zones[$order->zoneId] ?? throw new DomainException("Unknown zoneId: {$order->zoneId}");
+```
+
+### 5. Explicit error handling
+
+RULE: Never swallow an error in an empty or generic `catch`. Re-throw with context, or let it propagate.
+
+```php
+// bad
+try { return $api->getUser($id); } catch (Throwable $error) { return null; }
+// good
+try { return $api->getUser($id); } catch (ApiException $error) { throw new UserLoadException("Failed to load user {$id}", previous: $error); }
+```
+
+### 6. Clear names
+
+RULE: Names reveal role or domain meaning. No `data`, `info`, `temp`, `result`, `obj`, `val`, `x`. A long honest name beats a short vague one.
+
+```php
+// bad
+function process(array $data): array { return array_filter($data, fn ($x) => $x->val > 0); }
+// good
+function activeSubscriptions(array $subscriptions): array { return array_filter($subscriptions, fn ($subscription) => $subscription->remainingDays > 0); }
+```
+
+### 7. Command Query Separation (CQS)
+
+RULE: A function either does something (side effect) or returns something (query) — never both. A "getter" must never mutate.
+
+```php
+// bad
+function getNextId(Counter $counter): int { return ++$counter->value; }
+// good
+function peekNextId(Counter $counter): int { return $counter->value + 1; }
+function incrementCounter(Counter $counter): void { ++$counter->value; }
+```
+
+### 8. Null/undefined handling
+
+RULE: Pick one convention for `null` and never mix meanings. Never overload null to mean several business states — give each state its own explicit value.
+
+```php
+// bad
+function discount(?User $user): ?int { return (!$user?->plan || $user->plan->discount === 0) ? null : $user->plan->discount; }
+// good
+function discount(?User $user): int { return $user?->plan?->discount ?? 0; }
+```
+
+### 9. Immutability by default
+
+RULE: Return new values instead of mutating parameters. Never hide a side effect inside what looks like a pure transform.
+
+```php
+// bad
+function addItem(Cart $cart, Item $item): Cart { $cart->items[] = $item; return $cart; }
+// good
+function addItem(Cart $cart, Item $item): Cart { return $cart->withItems([...$cart->items, $item]); }
+```
+
+### 10. Validate once
+
+RULE: Validate at the boundary that owns the input (`FormRequest`, schema, DTO). Downstream code trusts that contract — no re-checking the same required/type/range rule further in.
+
+```php
+// bad
+function update(array $validated): void { if (empty($validated['email'])) { throw new InvalidArgumentException(); } $this->user->update($validated); }
+// good
+function update(array $validated): void { $this->user->update($validated); }
+```
+
+### 11. Single Responsibility (SRP)
+
+RULE: A function, class, or module has one reason to change. If it validates AND transforms AND persists AND notifies, split it.
+
+```php
+// bad
+function save(array $input): void { $this->validate($input); $user = $this->normalize($input); $this->repo->save($user); $this->mailer->welcome($user); }
+// good
+function create(ValidatedUser $input): User { $user = $this->normalizer->normalize($input); $this->repo->save($user); return $user; }
+```
+
+### 12. DRY (real duplication only)
+
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, or extract look-alike code from different concepts.
+
+```php
+// bad — extracted after one use
+function formatName(string $value): string { return strtoupper(trim($value)); }
+// good — third occurrence confirms one domain concept
+function normalizeTicketStatus(string $status): TicketStatus { return TicketStatus::from(trim($status)); }
+```
+
+### 13. KISS
+
+RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+
+```php
+// bad
+function formatPrice(float $value, array $options = []): string { return $this->formatter->format($value, $options); }
+// good
+function formatPrice(float $value): string { return '$'.number_format($value, 2); }
+```
+
+### 14. YAGNI
+
+RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+
+```php
+// bad
+function createInvoice(Order $order, bool $recurring = false, bool $multiCurrency = false): Invoice { return $this->build($order, $recurring, $multiCurrency); }
+// good
+function createInvoice(Order $order): Invoice { return new Invoice($order->total, $order->items); }
+```
+
+### 15. Law of Demeter
+
+RULE: Talk only to immediate collaborators. Never reach through an object to grab something several levels deep inside its internal structure.
+
+```php
+// bad
+function cityName(User $user): string { return $user->address->city->name; }
+// good
+function cityName(User $user): string { return $user->cityName(); }
+```
+
+### 16. Composition over inheritance
+
+RULE: Compose small, focused behaviors instead of building inheritance chains that force unrelated methods onto every subclass.
+
+```php
+// bad
+abstract class Animal { abstract public function sound(): string; abstract public function fly(): void; }
+// good
+final class Dog { public function __construct(private SoundBehavior $sound) {} }
+```
+
+### 17. Dependency direction
+
+RULE: Inner layers (domain/business logic) never import outer layers (framework, DB, HTTP). Outer layers depend inward, never the reverse.
 
 ```php
-// Bad — Service repeats the FormRequest rule
-class ProfileService {
-    public function update(array $data) {
-        if (empty($data['email'])) {
-            throw new \InvalidArgumentException('email required');
-        }
-        $this->user->update($data);
-    }
-}
+// bad
+function total(string $id): Money { return (new EloquentInvoiceRepository())->find($id)->total(); }
+// good
+function total(Invoice $invoice): Money { return $invoice->total(); }
+```
+
+### 18. Testability as a design constraint
+
+RULE: Inject dependencies (clock, network, random) instead of hardcoding them. If a function is hard to test, redesign it — don't skip the test.
+
+```php
+// bad
+function expired(Subscription $subscription): bool { return $subscription->expiresAt < new DateTimeImmutable(); }
+// good
+function expired(Subscription $subscription, Clock $clock): bool { return $subscription->expiresAt < $clock->now(); }
+```
 
-// Good — Service trusts validated input
-class ProfileService {
-    public function update(array $validated) {
-        $this->user->update($validated);
-    }
-}
+### 19. Comments
+
+RULE: Comment only non-obvious intent — a trade-off, a constraint, a hazard names can't carry. Delete narration, restated logic, and stale TODOs. Test: if deleting the comment leaves the code equally clear, delete it.
+
+```php
+// bad
+// Increment the counter.
+++$counter;
+// good
+// Poll because the provider cannot guarantee single webhook delivery.
+Schedule::call($checkPaymentStatus)->everyFiveSeconds();
 ```
+
+---
+
+**When in doubt:** fail fast, keep it flat, keep it small.
+
+**Enforcement note:** rules 1–2 are mechanical and should be backed by PHP/Laravel formatting or linting. Rules 3–10 are structural checks. Rules 11–19 require review judgment.

package/skills/sideroom-guidelines/references/languages/python.md

@@ -1,21 +1,321 @@
-# Python
+# Python Coding Guidelines
 
-Delta only. Keep the shared table.
+Rules every Python change must follow.
 
-- Use a complete indented suite for every `if` / `else`. Never a one-line conditional body.
-- Treat `None` as "not set" or "explicitly empty" — pick one meaning and keep it. Do not use `None` for a real business state that deserves its own value.
-- Prefer returning new collections over mutating a caller's list or dict.
+## Index
+
+| # | Rule | Tier |
+| --- | ------ | ------ |
+| 1 | [Braced conditionals](#1-braced-conditionals) | mechanical |
+| 2 | [No magic strings](#2-no-magic-strings) | mechanical |
+| 3 | [Guard clauses](#3-guard-clauses) | structural |
+| 4 | [Fail fast](#4-fail-fast) | structural |
+| 5 | [Explicit error handling](#5-explicit-error-handling) | structural |
+| 6 | [Clear names](#6-clear-names) | structural |
+| 7 | [Command Query Separation](#7-command-query-separation-cqs) | structural |
+| 8 | [Null/undefined handling](#8-nullundefined-handling) | structural |
+| 9 | [Immutability by default](#9-immutability-by-default) | structural |
+| 10 | [Validate once](#10-validate-once) | structural |
+| 11 | [Single Responsibility](#11-single-responsibility-srp) | architectural |
+| 12 | [DRY (real duplication only)](#12-dry-real-duplication-only) | architectural |
+| 13 | [KISS](#13-kiss) | architectural |
+| 14 | [YAGNI](#14-yagni) | architectural |
+| 15 | [Law of Demeter](#15-law-of-demeter) | architectural |
+| 16 | [Composition over inheritance](#16-composition-over-inheritance) | architectural |
+| 17 | [Dependency direction](#17-dependency-direction) | architectural |
+| 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
+| 19 | [Comments](#19-comments) | architectural |
+
+---
+
+### 1. Braced conditionals
+
+RULE: Python has no braces: every `if`/`else` body uses a full indented suite, never a one-line body.
 
 ```python
-# Bad
-def get_discount(user):
-    if user: return 0.2 if user.is_active else 0
+# bad
+if user is None: return 0
+# good
+if user is None:
+    return 0
+```
+
+### 2. No magic strings
+
+RULE: Name domain/protocol literals once (constant, enum, shared contract) and reuse the name. One-off strings with no reuse and no domain meaning (a single log label) may stay inline.
+
+```python
+# bad
+if order.status == "pending_payment":
+    charge(order)
+# good
+PENDING_PAYMENT = "pending_payment"
+if order.status == PENDING_PAYMENT:
+    charge(order)
+```
+
+### 3. Guard clauses
+
+RULE: Validate and exit early. Keep the happy path last, at the shallowest indent. No pyramid nesting.
 
-# Good
+```python
+# bad
 def get_discount(user):
-    if user is None:
-        return 0
-    if not user.is_active:
+    if user is not None:
+        if user.is_active:
+            return 0.2 if user.has_subscription else 0
+    return 0
+# good
+def get_discount(user):
+    if user is None or not user.is_active or not user.has_subscription:
         return 0
     return 0.2
 ```
+
+### 4. Fail fast
+
+RULE: Invalid input, impossible state, or a broken dependency raises immediately with a clear message. No fallback chains or silent defaults.
+WHY: This is for invariants that should never happen if upstream contracts hold — not license to re-check business rules a boundary already validated (see rule 10).
+
+```python
+# bad
+zone = zones.get(order.zone_id, zones["default"])
+# good
+try:
+    zone = zones[order.zone_id]
+except KeyError as error:
+    raise ValueError(f"Unknown zone_id: {order.zone_id}") from error
+```
+
+### 5. Explicit error handling
+
+RULE: Never swallow an error in an empty or generic `except`. Re-raise with context, or let it propagate.
+
+```python
+# bad
+def load_user(user_id):
+    try:
+        return api.get_user(user_id)
+    except Exception:
+        return None
+# good
+def load_user(user_id):
+    try:
+        return api.get_user(user_id)
+    except ApiError as error:
+        raise UserLoadError(f"Failed to load user {user_id}") from error
+```
+
+### 6. Clear names
+
+RULE: Names reveal role or domain meaning. No `data`, `info`, `temp`, `result`, `obj`, `val`, `x`. A long honest name beats a short vague one.
+
+```python
+# bad
+def process(data):
+    return [x for x in data if x.val > 0]
+# good
+def get_active_subscriptions(subscriptions):
+    return [subscription for subscription in subscriptions if subscription.remaining_days > 0]
+```
+
+### 7. Command Query Separation (CQS)
+
+RULE: A function either does something (side effect) or returns something (query) — never both. A "getter" must never mutate.
+
+```python
+# bad
+def get_next_id(counter):
+    counter.value += 1
+    return counter.value
+# good
+def peek_next_id(counter):
+    return counter.value + 1
+
+def increment_counter(counter):
+    counter.value += 1
+```
+
+### 8. Null/undefined handling
+
+RULE: Give `None` one convention (for example, not set or explicitly empty) and never use it for several meanings. Give each business state its own explicit value.
+
+```python
+# bad
+def get_discount(user):
+    if user is None or user.plan is None or user.plan.discount == 0:
+        return None
+# good
+def get_discount(user):
+    if user is None or user.plan is None:
+        return 0
+    return user.plan.discount
+```
+
+### 9. Immutability by default
+
+RULE: Return new values instead of mutating parameters. Never hide a side effect inside what looks like a pure transform.
+
+```python
+# bad
+def add_item(cart, item):
+    cart["items"].append(item)
+    return cart
+# good
+def add_item(cart, item):
+    return {**cart, "items": [*cart["items"], item]}
+```
+
+### 10. Validate once
+
+RULE: Validate at the boundary that owns the input (schema, request model, DTO). Downstream code trusts that contract — no re-checking the same required/type/range rule in a helper, use case, or adapter further in.
+
+```python
+# bad
+def update_profile(validated_profile, repository):
+    if not validated_profile.email:
+        raise ValueError("email required")
+    repository.update(validated_profile)
+# good
+def update_profile(validated_profile, repository):
+    repository.update(validated_profile)
+```
+
+### 11. Single Responsibility (SRP)
+
+RULE: A function, class, or module has one reason to change. If it validates AND transforms AND persists AND notifies, split it.
+
+```python
+# bad
+def save_user(payload, repository, mailer):
+    if not payload["email"]:
+        raise ValueError("email required")
+    user = {**payload, "email": payload["email"].strip().lower()}
+    repository.insert(user)
+    mailer.send(user["email"], "welcome")
+# good
+def normalize_user(payload):
+    return {**payload, "email": payload["email"].strip().lower()}
+
+def create_user(validated_payload, repository):
+    user = normalize_user(validated_payload)
+    repository.insert(user)
+    return user
+```
+
+### 12. DRY (real duplication only)
+
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, and do not extract look-alike code that belongs to different concepts (a user's email validation vs a vendor's) — they will diverge.
+
+```python
+# bad — extracted after one real use
+def format_name(value):
+    return value.strip().upper()
+# good — same domain concept, third occurrence confirms the pattern
+def normalize_ticket_status(status):
+    return TicketStatus(status.strip().lower())
+```
+
+### 13. KISS
+
+RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+
+```python
+# bad
+def format_price(value, currency="USD", locale="en-US", show_symbol=True):
+    return price_formatter(value, currency, locale, show_symbol)
+# good
+def format_price(value):
+    return f"${value:.2f}"
+```
+
+### 14. YAGNI
+
+RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (Differs from KISS: KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+
+```python
+# bad
+def create_invoice(order, supports_recurring=False, supports_multi_currency=False):
+    return build_invoice(order, supports_recurring, supports_multi_currency)
+# good
+def create_invoice(order):
+    return {"total": order.total, "items": order.items}
+```
+
+### 15. Law of Demeter
+
+RULE: Talk only to immediate collaborators. Never reach through an object to grab something several levels deep inside its internal structure.
+
+```python
+# bad
+def get_city_name(user):
+    return user.address.city.name
+# good
+def get_city_name(user):
+    return user.get_city_name()
+```
+
+### 16. Composition over inheritance
+
+RULE: Compose small, focused behaviors instead of building inheritance chains that force unrelated methods onto every subclass.
+
+```python
+# bad
+class Animal:
+    def fly(self): ...
+class Dog(Animal):
+    pass
+# good
+class Bark:
+    def make_sound(self):
+        return "Woof"
+class Dog:
+    def __init__(self, sound=Bark()):
+        self.sound = sound
+```
+
+### 17. Dependency direction
+
+RULE: Inner layers (domain/business logic) never import outer layers (framework, DB, HTTP). Outer layers depend inward, never the reverse.
+
+```python
+# bad
+def calculate_invoice_total(invoice_id):
+    invoice = MysqlInvoiceRepository().get(invoice_id)
+    return sum(item.price for item in invoice.items)
+# good
+def calculate_invoice_total(invoice):
+    return sum(item.price for item in invoice.items)
+```
+
+### 18. Testability as a design constraint
+
+RULE: Inject dependencies (clock, network, random) instead of hardcoding them. If a function is hard to test, redesign it — don't skip the test.
+
+```python
+# bad
+def is_subscription_expired(subscription):
+    return subscription.expires_at < datetime.now(timezone.utc)
+# good
+def is_subscription_expired(subscription, now):
+    return subscription.expires_at < now
+```
+
+### 19. Comments
+
+RULE: Comment only non-obvious intent — a trade-off, a constraint, a hazard names can't carry. Delete narration, restated logic, and stale TODOs. Test: if deleting the comment leaves the code equally clear, delete it.
+
+```python
+# bad
+# Increment the counter by one.
+counter += 1
+# good
+# Polling avoids duplicate webhook delivery that the provider cannot prevent.
+scheduler.every(5).seconds.do(check_payment_status)
+```
+
+---
+
+**When in doubt:** fail fast, keep it flat, keep it small.
+
+**Enforcement note:** rules 1–2 are mechanical and should be backed by Python formatting or linting. Rules 3–10 are structural checks. Rules 11–19 require review judgment.