opencode-skills-collection 3.0.49 → 3.0.51

package/bundled-skills/super-code/php/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: php
+description: "Language-specific super-code guidelines for php."
+risk: safe
+source: community
+date_added: "2026-06-16"
+---
+# PHP: Idiomatic Efficiency Reference
+
+## Table of Contents
+1. [Arrays & Collections](#arrays)
+2. [Type Safety](#types)
+3. [Error Handling](#errors)
+4. [String Handling](#strings)
+5. [OOP & Modern PHP](#oop)
+6. [Functions & Closures](#functions)
+7. [Anti-patterns specific to PHP](#antipatterns)
+
+---
+
+## 1. Arrays & Collections {#arrays}
+
+```php
+// ❌ Manual accumulation
+$result = [];
+foreach ($items as $item) {
+    if ($item->isActive()) {
+        $result[] = strtoupper($item->getName());
+    }
+}
+
+// ✅
+$result = array_map(
+    fn($i) => strtoupper($i->getName()),
+    array_filter($items, fn($i) => $i->isActive())
+);
+```
+
+```php
+// ❌ Manual key-value grouping
+$grouped = [];
+foreach ($items as $item) {
+    $grouped[$item->getCategory()][] = $item;
+}
+
+// ✅ (PHP 8.1+) — or use the loop above; PHP lacks a built-in groupBy
+// The foreach is actually idiomatic PHP for grouping. No need to force array_* here.
+```
+
+```php
+// ❌ Checking isset then accessing
+if (isset($data['key'])) {
+    $value = $data['key'];
+} else {
+    $value = 'default';
+}
+
+// ✅
+$value = $data['key'] ?? 'default';
+```
+
+```php
+// ❌ array_push for single element
+array_push($items, $newItem);
+
+// ✅
+$items[] = $newItem;
+```
+
+**Use `array_map`/`array_filter` for transforms. The `foreach` loop is fine when array functions would be less readable.**
+
+---
+
+## 2. Type Safety {#types}
+
+```php
+// ❌ No type declarations
+function process($items) {
+    return $items;
+}
+
+// ✅ (PHP 8.0+)
+function process(array $items): array {
+    return $items;
+}
+```
+
+```php
+// ❌ Union type for nullable
+function find(string $key): string|null { ... }
+
+// ✅
+function find(string $key): ?string { ... }
+```
+
+```php
+// ❌ Loose comparison
+if ($value == '0') { ... } // true for 0, '', false, null
+
+// ✅
+if ($value === '0') { ... }
+```
+
+```php
+// ❌ Type checking with gettype()
+if (gettype($x) === 'integer') { ... }
+
+// ✅
+if (is_int($x)) { ... }
+// or with union types, avoid checks entirely
+```
+
+**Enable `declare(strict_types=1)` at the top of every file.**
+
+---
+
+## 3. Error Handling {#errors}
+
+```php
+// ❌ Suppressing errors with @
+$data = @file_get_contents($path);
+
+// ✅
+$data = file_get_contents($path);
+if ($data === false) {
+    throw new RuntimeException("Failed to read: $path");
+}
+```
+
+```php
+// ❌ Catching \Exception and swallowing
+try { process(); }
+catch (\Exception $e) { /* silence */ }
+
+// ✅
+try {
+    process();
+} catch (SpecificException $e) {
+    $this->logger->error($e->getMessage(), ['exception' => $e]);
+    throw new AppException('Processing failed', previous: $e);
+}
+```
+
+```php
+// ❌ Returning mixed types for error indication
+function divide(int $a, int $b): int|false {
+    if ($b === 0) return false;
+    return intdiv($a, $b);
+}
+
+// ✅ — throw exception for exceptional cases
+function divide(int $a, int $b): int {
+    if ($b === 0) throw new \DivisionByZeroError();
+    return intdiv($a, $b);
+}
+```
+
+---
+
+## 4. String Handling {#strings}
+
+```php
+// ❌ Concatenation for variable interpolation
+$msg = 'Hello, ' . $name . '! You have ' . $count . ' messages.';
+
+// ✅
+$msg = "Hello, {$name}! You have {$count} messages.";
+```
+
+```php
+// ❌ Manual string contains check
+if (strpos($haystack, $needle) !== false) { ... }
+
+// ✅ (PHP 8.0+)
+if (str_contains($haystack, $needle)) { ... }
+```
+
+```php
+// ❌ substr for prefix/suffix check
+if (substr($str, 0, 4) === 'http') { ... }
+if (substr($str, -4) === '.php') { ... }
+
+// ✅ (PHP 8.0+)
+if (str_starts_with($str, 'http')) { ... }
+if (str_ends_with($str, '.php')) { ... }
+```
+
+---
+
+## 5. OOP & Modern PHP {#oop}
+
+```php
+// ❌ Manual constructor property assignment
+class User {
+    private string $name;
+    private int $age;
+    public function __construct(string $name, int $age) {
+        $this->name = $name;
+        $this->age = $age;
+    }
+}
+
+// ✅ (PHP 8.0+)
+class User {
+    public function __construct(
+        private readonly string $name,
+        private readonly int $age,
+    ) {}
+}
+```
+
+```php
+// ❌ Constants as class properties
+class Status {
+    const ACTIVE = 'active';
+    const INACTIVE = 'inactive';
+}
+
+// ✅ (PHP 8.1+)
+enum Status: string {
+    case Active = 'active';
+    case Inactive = 'inactive';
+}
+```
+
+```php
+// ❌ instanceof chains
+if ($shape instanceof Circle) { ... }
+elseif ($shape instanceof Rectangle) { ... }
+
+// ✅ (PHP 8.0+)
+$area = match(true) {
+    $shape instanceof Circle => $shape->radius ** 2 * M_PI,
+    $shape instanceof Rectangle => $shape->width * $shape->height,
+    default => throw new \InvalidArgumentException("Unknown shape"),
+};
+```
+
+```php
+// ❌ Named constructor via static method returning new self()
+class Money {
+    public static function fromCents(int $cents): self {
+        $m = new self();
+        $m->cents = $cents;
+        return $m;
+    }
+}
+
+// ✅ (PHP 8.0+) — constructor promotion + named arguments
+class Money {
+    public function __construct(
+        public readonly int $cents,
+    ) {}
+}
+$m = new Money(cents: 500);
+```
+
+---
+
+## 6. Functions & Closures {#functions}
+
+```php
+// ❌ Verbose closure for simple operation
+$doubled = array_map(function ($x) { return $x * 2; }, $numbers);
+
+// ✅ (PHP 7.4+)
+$doubled = array_map(fn($x) => $x * 2, $numbers);
+```
+
+```php
+// ❌ Passing globals or using `global` keyword
+global $db;
+function getUser(int $id) {
+    global $db;
+    return $db->find($id);
+}
+
+// ✅ — dependency injection
+function getUser(int $id, PDO $db): ?User {
+    return $db->find($id);
+}
+```
+
+```php
+// ❌ Named arguments abused for every call
+str_pad(string: $s, length: 10, pad_string: ' ', pad_type: STR_PAD_LEFT);
+
+// ✅ — named args are useful for readability on ambiguous params; don't force
+str_pad($s, 10, ' ', STR_PAD_LEFT);
+// but named args shine for: new User(name: 'Alice', age: 30)
+```
+
+---
+
+## 7. Anti-patterns specific to PHP {#antipatterns}
+
+| Anti-pattern | Preferred |
+|---|---|
+| `==` for comparison | `===` (strict equality) |
+| `@` error suppression | explicit error handling |
+| `global` keyword | dependency injection |
+| `extract()` on user input | access keys explicitly |
+| `die()` / `exit()` in library code | throw exception |
+| `strpos !== false` for contains | `str_contains()` (PHP 8.0) |
+| Manual constructor assignment | constructor promotion (PHP 8.0) |
+| Class constants for enums | `enum` (PHP 8.1) |
+| `mixed` return types | specific typed returns |
+| `array` for everything | typed classes / DTOs |
+| `var_dump` / `print_r` debugging | proper logging (PSR-3) |
+| Not using `declare(strict_types=1)` | always enable |
+
+
+
+## Limitations
+- These are language-specific guidelines and do not cover overall architectural decisions.
+- Over-compression might reduce readability; apply judgement.

package/bundled-skills/super-code/python/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: python
+description: "Language-specific super-code guidelines for python."
+risk: safe
+source: community
+date_added: "2026-06-16"
+---
+# Python: Idiomatic Efficiency Reference
+
+## Table of Contents
+1. [Comprehensions & Generators](#comprehensions)
+2. [Unpacking & Destructuring](#unpacking)
+3. [Built-ins & stdlib](#builtins)
+4. [Functions & Defaults](#functions)
+5. [Classes & Dataclasses](#classes)
+6. [Error Handling](#errors)
+7. [Type Hints](#types)
+8. [Anti-patterns specific to Python](#antipatterns)
+
+---
+
+## 1. Comprehensions & Generators {#comprehensions}
+
+```python
+# ❌ Imperative accumulation
+result = []
+for item in items:
+    if item.active:
+        result.append(item.name.upper())
+
+# ✅
+result = [item.name.upper() for item in items if item.active]
+```
+
+```python
+# ❌ Dict built in a loop
+d = {}
+for k, v in pairs:
+    d[k] = v
+
+# ✅
+d = dict(pairs)
+# or
+d = {k: v for k, v in pairs}
+```
+
+```python
+# ❌ Generator converted to list unnecessarily
+total = sum(list(x * 2 for x in nums))
+
+# ✅ — generator expression works directly in sum()
+total = sum(x * 2 for x in nums)
+```
+
+**Use generator expressions (not list comprehensions) when the result is consumed once and not stored.**
+
+---
+
+## 2. Unpacking & Destructuring {#unpacking}
+
+```python
+# ❌ Index access
+first = items[0]
+rest = items[1:]
+
+# ✅
+first, *rest = items
+```
+
+```python
+# ❌ Temporary variable for swap
+tmp = a
+a = b
+b = tmp
+
+# ✅
+a, b = b, a
+```
+
+```python
+# ❌ items() with separate indexing
+for i in range(len(items)):
+    print(i, items[i])
+
+# ✅
+for i, item in enumerate(items):
+    print(i, item)
+```
+
+```python
+# ❌ zip with separate index
+for i in range(len(a)):
+    process(a[i], b[i])
+
+# ✅
+for x, y in zip(a, b):
+    process(x, y)
+```
+
+---
+
+## 3. Built-ins & stdlib {#builtins}
+
+```python
+# ❌ Manual max search
+max_val = items[0]
+for item in items[1:]:
+    if item > max_val:
+        max_val = item
+
+# ✅
+max_val = max(items)
+```
+
+```python
+# ❌ Manual grouping
+from collections import defaultdict
+groups = defaultdict(list)
+for item in items:
+    groups[item.category].append(item)
+
+# ✅ — same thing, just be explicit about defaultdict; it IS the right tool
+# (this example is already correct — don't replace defaultdict with a loop)
+```
+
+```python
+# ❌ Manual sentinel for dict default
+if key in d:
+    val = d[key]
+else:
+    val = default
+
+# ✅
+val = d.get(key, default)
+```
+
+```python
+# ❌ Rolling your own counter
+counts = {}
+for item in items:
+    counts[item] = counts.get(item, 0) + 1
+
+# ✅
+from collections import Counter
+counts = Counter(items)
+```
+
+**Use `itertools` (chain, islice, groupby, product) before writing nested loops for combinatorial or streaming logic.**
+
+---
+
+## 4. Functions & Defaults {#functions}
+
+```python
+# ❌ Mutable default argument (bug, not just style)
+def append_to(item, lst=[]):
+    lst.append(item)
+    return lst
+
+# ✅
+def append_to(item, lst=None):
+    if lst is None:
+        lst = []
+    lst.append(item)
+    return lst
+```
+
+```python
+# ❌ Positional args for everything when keyword clarity helps
+create_user("Alice", True, False, 30)
+
+# ✅ — use keyword args at call site for boolean/ambiguous params
+create_user("Alice", is_admin=True, is_active=False, age=30)
+```
+
+```python
+# ❌ Long function doing multiple things
+def process_and_save(data):
+    # 40 lines of transform
+    # 20 lines of DB write
+    ...
+
+# ✅ — split only if each part is reused OR independently testable
+def _transform(data): ...
+def _save(record): ...
+def process_and_save(data): _save(_transform(data))
+```
+
+---
+
+## 5. Classes & Dataclasses {#classes}
+
+```python
+# ❌ Manual __init__ for data holders
+class Point:
+    def __init__(self, x, y):
+        self.x = x
+        self.y = y
+
+# ✅
+from dataclasses import dataclass
+
+@dataclass
+class Point:
+    x: float
+    y: float
+```
+
+```python
+# ❌ Class just to hold a namespace of functions
+class MathUtils:
+    @staticmethod
+    def add(a, b): return a + b
+
+# ✅ — module-level functions; classes for state + behavior
+def add(a, b): return a + b
+```
+
+```python
+# ❌ __repr__ written manually when dataclass gives it free
+# (see above — use @dataclass)
+```
+
+**Use `@dataclass(frozen=True)` for immutable value objects. Use `NamedTuple` when you need tuple unpacking.**
+
+---
+
+## 6. Error Handling {#errors}
+
+```python
+# ❌ Bare except
+try:
+    risky()
+except:
+    pass
+
+# ✅ — catch the specific exception; don't swallow silently
+try:
+    risky()
+except ValueError as e:
+    logger.warning("Invalid value: %s", e)
+```
+
+```python
+# ❌ LBYL (look before you leap) when EAFP is cleaner
+if os.path.exists(path):
+    with open(path) as f:
+        data = f.read()
+
+# ✅ (EAFP)
+try:
+    with open(path) as f:
+        data = f.read()
+except FileNotFoundError:
+    data = None
+```
+
+```python
+# ❌ Re-raising with raise e (loses traceback)
+except Exception as e:
+    raise e
+
+# ✅
+except Exception:
+    raise  # bare raise preserves original traceback
+```
+
+---
+
+## 7. Type Hints {#types}
+
+```python
+# ❌ Overly verbose Union syntax (Python <3.10 style in new code)
+from typing import Optional, Union
+def f(x: Optional[int]) -> Union[str, None]: ...
+
+# ✅ (Python 3.10+)
+def f(x: int | None) -> str | None: ...
+```
+
+```python
+# ❌ Any where a TypeVar or Protocol would be informative
+from typing import Any
+def first(lst: list[Any]) -> Any: ...
+
+# ✅
+from typing import TypeVar
+T = TypeVar("T")
+def first(lst: list[T]) -> T: ...
+```
+
+**Don't add type hints to every local variable — annotate function signatures and class fields; leave obvious locals inferred.**
+
+---
+
+## 8. Anti-patterns specific to Python {#antipatterns}
+
+| Anti-pattern | Preferred |
+|---|---|
+| `len(lst) == 0` | `not lst` |
+| `if x == True:` | `if x:` |
+| `if x == None:` | `if x is None:` |
+| `range(len(lst))` for iteration | `enumerate(lst)` |
+| String concatenation in a loop | `"".join(parts)` |
+| `import *` | explicit imports |
+| Catching `Exception` to log and re-raise | bare `raise` or let it propagate |
+| `print()` for debug output | `logging.debug()` |
+| `os.path.join` (Python 3.4+) | `pathlib.Path / "subpath"` |
+| Manual `__eq__` + `__hash__` on value objects | `@dataclass(eq=True, frozen=True)` |
+
+
+
+## Limitations
+- These are language-specific guidelines and do not cover overall architectural decisions.
+- Over-compression might reduce readability; apply judgement.