@diottodev/runic 1.0.0 → 1.1.0

package/engineering-team/skills/code-reviewer/languages/kotlin.md

@@ -0,0 +1,88 @@
+---
+language: kotlin
+extensions: [".kt", ".kts"]
+---
+
+# Kotlin — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Kotlin-specific rules and idioms.
+
+---
+
+## PR Analyzer — Kotlin Risk Signals
+
+- `println()` statements left in production code
+- `@Suppress` annotations — verify they are justified
+- `!!` (not-null assertion) used broadly without justification
+- Hardcoded credentials or API keys in source
+
+---
+
+## Code Quality — Kotlin Checks
+
+- `!!` used broadly — prefer `?.let`, `?:`, or `requireNotNull()`
+- `lateinit var` accessed before initialization
+- Coroutines launched with `GlobalScope` — prefer scoped coroutines
+- `runBlocking` used outside of tests or top-level entry points
+
+---
+
+## Security
+
+- Flag Room / SQLite queries built with string concatenation — require parameterized queries
+- Flag `WebView.loadUrl()` with user-controlled input without validation
+- Flag credentials stored in `SharedPreferences` — require `EncryptedSharedPreferences` or Keychain
+
+---
+
+## Async / Coroutines
+
+- Flag `GlobalScope.launch` / `GlobalScope.async` in production code — use a structured scope
+- Flag `runBlocking` outside of tests or top-level main functions
+- Flag `launch` / `async` without a `CoroutineExceptionHandler` or `supervisorScope` where individual failures should not cancel siblings
+- Flag `Dispatchers.Main` used for CPU-bound work — use `Dispatchers.Default`
+- Flag coroutine cancellation not respected — long loops should check `isActive` or call `yield()`
+
+---
+
+## Resource Management
+
+- Flag `Closeable` / `AutoCloseable` not wrapped in `.use { }` (Kotlin's try-with-resources equivalent)
+- Flag `OkHttpClient` / `Retrofit` instantiated per-request — share a singleton
+- Flag `BroadcastReceiver` registered without a corresponding `unregisterReceiver` — memory / battery leak
+- Flag coroutines that hold a resource across a `suspend` point without structured cleanup in `finally`
+
+---
+
+## Exception Handling
+
+- Flag `runCatching { }.getOrNull()` used broadly — silently swallows all exceptions
+- Flag `catch (e: Exception)` in coroutines without re-throwing `CancellationException` — breaks structured concurrency
+- Flag empty `catch` blocks
+- Flag `throw RuntimeException(e)` without a descriptive message
+- Prefer typed `sealed class` error hierarchies over raw exceptions for domain errors in coroutine flows
+
+---
+
+## Performance
+
+- Flag `buildString` / `StringBuilder` not used for multi-step string construction in loops
+- Flag `List` used for frequent `contains` checks — prefer `Set`
+- Flag `flow.collect {}` re-subscribing on every recomposition in Jetpack Compose — use `collectAsStateWithLifecycle`
+- Flag `Dispatchers.IO` used for CPU-bound work — use `Dispatchers.Default`
+- Flag `suspend` functions calling non-suspend blocking APIs directly — wrap with `withContext(Dispatchers.IO)`
+
+---
+
+## Idioms and Best Practices
+
+### Null Safety
+- Prefer safe call (`?.`) and Elvis operator (`?:`) over `!!`
+- Use `requireNotNull()` / `checkNotNull()` with a descriptive message when null means a programming error
+- Prefer `val` over `var` — immutability by default
+
+### Modern Kotlin
+- Prefer `data class` for value carriers
+- Prefer `sealed class` / `sealed interface` for exhaustive `when` expressions
+- Prefer extension functions over utility classes
+- Prefer `object` declarations for singletons

package/engineering-team/skills/code-reviewer/languages/php.md

@@ -0,0 +1,109 @@
+---
+language: php
+extensions: [".php", ".phtml", ".php3", ".php4", ".php5", ".phps"]
+---
+
+# PHP — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only PHP-specific rules and idioms.
+
+---
+
+## PR Analyzer — PHP Risk Signals
+
+- `var_dump` / `print_r` / `echo` debug statements left in production code
+- `@` error suppression operator — masks real errors; verify it is justified
+- `// phpcs:ignore` / `// phpstan-ignore` comments — verify they are justified
+- Hardcoded credentials, database passwords, or API keys in source
+- `eval()` anywhere — almost always a security issue
+- `$_GET` / `$_POST` / `$_REQUEST` / `$_COOKIE` used without sanitization
+
+---
+
+## Code Quality — PHP Checks
+
+- Missing type declarations on function parameters and return types
+- `mixed` return type used broadly — tighten to specific types
+- Global variables (`global $var`) — pass dependencies explicitly
+- Long functions (>50 lines) — PHP functions tend to accumulate logic
+- `isset()` / `empty()` used to mask type errors instead of fixing the root cause
+- Missing `strict_types=1` declaration at the top of the file
+
+---
+
+## Security
+
+- Flag `$_GET` / `$_POST` / `$_REQUEST` used directly in SQL queries — require PDO prepared statements
+- Flag `mysqli_query($conn, "SELECT ... WHERE id = " . $_GET['id'])` — SQL injection
+- Flag `echo $_GET['name']` or any unescaped output — XSS; use `htmlspecialchars()` with `ENT_QUOTES`
+- Flag `include` / `require` with user-controlled paths — local/remote file inclusion
+- Flag `eval()` — remote code execution risk; no legitimate use in application code
+- Flag `shell_exec` / `exec` / `system` / `passthru` with user-controlled input — command injection
+- Flag `unserialize()` on untrusted data — arbitrary object instantiation and code execution
+- Flag `move_uploaded_file` without MIME type validation and extension whitelist — file upload attack
+- Flag `header("Location: " . $_GET['url'])` without validation — open redirect
+- Flag missing CSRF token validation on state-changing form endpoints
+
+---
+
+## Async / Concurrency
+
+- Flag long-running synchronous operations in a request cycle — offload to a queue (Laravel Queue, RabbitMQ)
+- Flag `sleep()` used inside a request handler — blocks the PHP-FPM worker
+- Flag shared mutable state in `static` properties accessed across requests in long-running processes (Swoole, RoadRunner)
+- Flag missing idempotency in queued jobs — jobs can be retried on failure
+
+---
+
+## Resource Management
+
+- Flag database connections not closed or returned to the pool (`$pdo = null` or `$conn->close()`)
+- Flag `fopen` / `fwrite` without a matching `fclose` on all paths
+- Flag `curl_init` without `curl_close` — leaks the curl handle
+- Flag unbounded file uploads with no size or type restriction
+- Flag sessions not explicitly closed (`session_write_close()`) before long operations — session locking blocks other requests
+
+---
+
+## Exception Handling
+
+- Flag empty `catch` blocks — swallowed exceptions
+- Flag `catch (Exception $e) {}` without logging — silent failure
+- Flag `die()` / `exit()` used for error handling in library code — use exceptions
+- Flag `@` operator used to suppress errors from functions that can fail — check return values instead
+- Flag `trigger_error` used in new code — prefer exceptions
+
+---
+
+## Performance
+
+- Flag N+1 Eloquent / Doctrine queries — use eager loading (`with()`, `load()`, `join`)
+- Flag `count($array)` called repeatedly in a loop condition — cache the result
+- Flag `array_push($arr, $val)` — use `$arr[] = $val` which is faster
+- Flag `in_array` on large arrays without the strict third argument — use `isset` on a flipped array for O(1) lookup
+- Flag `file_get_contents` on remote URLs in a request cycle — use an HTTP client with timeout and async where possible
+- Flag Eloquent `all()` without pagination — loads entire table into memory
+
+---
+
+## Idioms and Best Practices
+
+### Type Safety
+- Always declare `declare(strict_types=1)` at the top of every file
+- Use union types (`int|string`) and nullable types (`?string`) rather than `mixed`
+- Use typed properties on classes — avoid untyped `public $foo`
+- Use constructor promotion for simple value objects
+
+### Modern PHP (8.x)
+- Prefer `match` expressions over `switch` — strict comparison, no fall-through
+- Use named arguments for functions with many optional parameters
+- Use `enum` for fixed sets of values instead of class constants
+- Use `readonly` properties for immutable data
+- Use nullsafe operator (`?->`) instead of nested `isset` checks
+- Use `first-class callable syntax` (`strlen(...)`) instead of string references
+
+### Laravel / Symfony Specific
+- Keep controllers thin — logic belongs in service classes or action classes
+- Use form requests for validation — never validate in the controller directly
+- Prefer Eloquent relationships over manual joins for readability
+- Flag raw queries where the ORM can express the same intent safely

package/engineering-team/skills/code-reviewer/languages/python.md

@@ -0,0 +1,94 @@
+---
+language: python
+extensions: [".py"]
+---
+
+# Python — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Python-specific rules and idioms.
+
+---
+
+## PR Analyzer — Python Risk Signals
+
+- `print()` statements left in production code
+- `# noqa` and `# type: ignore` comments — verify they are justified
+- `eval()` / `exec()` with any user-controlled input
+- `pickle` used to deserialize untrusted data
+- Hardcoded credentials or tokens in source
+
+---
+
+## Code Quality — Python Checks
+
+- Bare `except:` or `except Exception:` swallowing silently
+- Mutable default arguments (`def foo(items=[])`) — shared across calls
+- `import *` — pollutes namespace and hides dependencies
+- Missing type hints on public functions and methods
+- `assert` used for runtime validation — stripped by `-O` flag
+
+---
+
+## Security
+
+- Flag `eval()` / `exec()` with any user-controlled input
+- Flag `pickle.loads()` on untrusted data — use `json` or `msgpack`
+- Flag `subprocess` calls with `shell=True` and user input
+- Flag `flask.render_template_string()` with user data (SSTI)
+- Flag `SECRET_KEY` / `DEBUG = True` committed to source
+
+---
+
+## Async
+
+- Flag `asyncio.get_event_loop().run_until_complete()` inside an already-running loop
+- Flag mixing `threading` and `asyncio` without a clear bridge (`run_in_executor`)
+- Flag CPU-bound work inside an `async def` without offloading to `ProcessPoolExecutor`
+- Flag `time.sleep()` inside async functions — use `await asyncio.sleep()`
+
+---
+
+## Resource Management
+
+- Flag `open()` not used as a context manager (`with open(...) as f`)
+- Flag `requests.Session` created per-request instead of shared/reused
+- Flag database connections not closed or returned to a pool on all paths
+- Flag large files read entirely into memory with `.read()` — prefer streaming / chunked reads
+
+---
+
+## Exception Handling
+
+- Flag bare `except:` — catches `BaseException` including `KeyboardInterrupt` and `SystemExit`
+- Flag `except Exception: pass` — silently swallows errors
+- Flag re-raising with `raise e` instead of `raise` — loses the original traceback
+- Flag `except` clause too broad when the `try` block covers multiple operations with different failure modes — split them
+
+---
+
+## Performance
+
+- Flag `+` string concatenation in loops — use `"".join()`
+- Flag repeated `re.compile()` inside a loop — compile once at module level
+- Flag `list.append()` in a loop where a list comprehension would be more efficient
+- Flag `in` membership tests on `list` where the collection is large — use `set`
+- Flag loading entire large files into memory — prefer streaming or chunked reads
+
+---
+
+## Idioms and Best Practices
+
+### Type Safety
+- All public functions and methods should have type annotations
+- Prefer `X | None` (Python 3.10+) over `Optional[X]`
+- Use `TypedDict` or `dataclass` over plain `dict` for structured data
+
+### Modern Python (3.10+)
+- Prefer `match` statements over long `if/elif` chains
+- Prefer `dataclass` or `NamedTuple` over plain classes for data carriers
+- Prefer `pathlib.Path` over `os.path` for file operations
+- Prefer f-strings over `.format()` or `%` formatting
+
+### None Safety
+- Prefer explicit `if x is None` over falsy checks when `0` or `""` are valid values
+- Flag functions returning `None` implicitly — make it explicit or raise

package/engineering-team/skills/code-reviewer/languages/ruby.md

@@ -0,0 +1,105 @@
+---
+language: ruby
+extensions: [".rb", ".rake", ".gemspec", ".ru"]
+---
+
+# Ruby — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Ruby-specific rules and idioms.
+
+---
+
+## PR Analyzer — Ruby Risk Signals
+
+- `puts` / `p` / `pp` debug statements left in production code
+- `# rubocop:disable` comments — verify they are justified
+- `eval` / `instance_eval` / `class_eval` with user-controlled input
+- Hardcoded credentials, tokens, or `SECRET_KEY_BASE` in source
+- `binding.pry` / `byebug` / `debugger` left in code
+
+---
+
+## Code Quality — Ruby Checks
+
+- Methods longer than 15 lines — Ruby idioms favor very small methods
+- Classes with more than 10 public methods — possible god object
+- `rescue Exception` — catches `SignalException` and `SystemExit`; use `rescue StandardError` or more specific types
+- `method_missing` implemented without `respond_to_missing?`
+- Deeply nested blocks (>3 levels) — extract to methods
+- String interpolation used where a symbol would suffice (hash keys, etc.)
+
+---
+
+## Security
+
+- Flag `eval` / `instance_eval` with user-controlled strings — remote code execution
+- Flag `system()` / `exec()` / backtick calls with user-controlled input — shell injection
+- Flag `YAML.load` on untrusted data — use `YAML.safe_load`
+- Flag `Marshal.load` on untrusted data — arbitrary code execution
+- Flag raw SQL string interpolation in ActiveRecord — use parameterized queries (`where("name = ?", name)`)
+- Flag `params` passed directly to `redirect_to` without validation — open redirect
+- Flag `render inline:` with user data — XSS via ERB
+- Flag missing `strong_parameters` in Rails controllers — mass assignment vulnerability
+
+---
+
+## Async / Concurrency
+
+- Flag shared mutable state accessed from multiple threads without a `Mutex`
+- Flag `Thread.new` without storing the thread reference — exceptions are silently swallowed
+- Flag `sleep` used as a synchronization mechanism in threaded code
+- Flag `@@class_variables` mutated in multi-threaded contexts — not thread-safe
+- Flag Sidekiq / ActiveJob workers that are not idempotent — jobs can be retried
+
+---
+
+## Resource Management
+
+- Flag `File.open` without a block form — the block form guarantees `close`
+- Flag database connections or HTTP clients not released in `ensure` blocks
+- Flag `ActiveRecord` queries inside loops — N+1 pattern; use `includes` / `preload` / `eager_load`
+- Flag `ObjectSpace` usage in production — memory and performance impact
+
+---
+
+## Exception Handling
+
+- Flag `rescue Exception` — use `rescue StandardError` or a specific exception class
+- Flag empty `rescue` blocks — swallowed errors
+- Flag `rescue` used for control flow (e.g. rescuing `ActiveRecord::RecordNotFound` instead of using `find_by`)
+- Flag re-raising with `raise e` instead of bare `raise` — loses the original backtrace
+- Flag `ensure` blocks that can raise — masks the original exception
+
+---
+
+## Performance
+
+- Flag N+1 ActiveRecord queries — use `includes`, `preload`, or `eager_load`
+- Flag `Array#each` with string concatenation — use `map` + `join`
+- Flag `select` + `map` that could be a single `filter_map`
+- Flag `.count` on an ActiveRecord relation inside a view or loop — triggers a query each time
+- Flag `require` inside a method body — constant overhead on every call
+- Flag `Hash#merge` in a loop — use `merge!` or `each_with_object`
+
+---
+
+## Idioms and Best Practices
+
+### Ruby Style
+- Prefer `map` / `select` / `reject` / `reduce` over manual `each` + accumulator
+- Prefer `&method(:name)` over `{ |x| some_method(x) }` for method reference blocks
+- Prefer `freeze` on string constants to avoid repeated object allocation
+- Use `attr_reader` / `attr_writer` / `attr_accessor` instead of manual getter/setter methods
+- Prefer `Symbol#to_proc` (`&:method_name`) for simple single-method blocks
+
+### Rails-Specific
+- Keep controllers thin — logic belongs in service objects, models, or concerns
+- Use `before_action` for authentication/authorization checks — never inline
+- Prefer `find_by` over `where(...).first` — more intent-revealing
+- Flag `after_commit` callbacks with side effects that should be in a service object
+- Prefer `respond_to` blocks over separate controller actions for format variants
+
+### Modern Ruby (3.x)
+- Prefer pattern matching (`case/in`) for complex data destructuring
+- Use numbered block parameters (`_1`, `_2`) only for very short, obvious blocks
+- Prefer `Data.define` for simple immutable value objects (Ruby 3.2+)

package/engineering-team/skills/code-reviewer/languages/rust.md

@@ -0,0 +1,99 @@
+---
+language: rust
+extensions: [".rs"]
+---
+
+# Rust — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Rust-specific rules and idioms.
+
+---
+
+## PR Analyzer — Rust Risk Signals
+
+- `unsafe { }` blocks — require explicit justification and sign-off
+- `#[allow(...)]` attributes suppressing lints — verify they are justified
+- `.unwrap()` / `.expect("")` on `Option` or `Result` outside of tests or prototypes
+- Hardcoded credentials or tokens in source
+- `TODO` / `FIXME` comments near `unsafe` or ownership code
+
+---
+
+## Code Quality — Rust Checks
+
+- `.unwrap()` used broadly in production code — prefer `?`, `if let`, or `match`
+- `clone()` called excessively — may indicate ownership design issues
+- `Arc<Mutex<T>>` used where a simpler ownership model would work
+- `Box<dyn Trait>` used where generics (`impl Trait`) would avoid heap allocation
+- `pub` fields on structs that should enforce invariants — use accessor methods
+
+---
+
+## Security
+
+- Flag `unsafe` blocks accessing raw pointers without clear safety invariant documented in a comment
+- Flag `std::mem::transmute` — almost always a logic error or undefined behavior; require strong justification
+- Flag `from_utf8_unchecked` on user-controlled data — use `from_utf8` with error handling
+- Flag `unwrap()` on user-supplied input parsing — panics are a denial-of-service vector in server code
+- Flag hardcoded secrets — use environment variables or a secrets crate
+
+---
+
+## Async / Concurrency
+
+- Flag `std::sync::Mutex` used in async code — use `tokio::sync::Mutex` to avoid blocking the async runtime
+- Flag `.await` inside a `std::sync::MutexGuard` scope — holds the lock across an await point, blocking other tasks
+- Flag `spawn` without storing the `JoinHandle` — panics in the spawned task are silently ignored
+- Flag `Arc<Mutex<T>>` cloned excessively — consider message passing via channels instead
+- Flag blocking I/O calls (`std::fs`, `std::net`) inside async functions — use async equivalents
+
+---
+
+## Resource Management
+
+- Flag manual `drop` called explicitly where the natural scope boundary suffices
+- Flag `Rc<T>` used in multi-threaded code — use `Arc<T>`; the compiler catches this but flag in review for architecture discussion
+- Flag `Vec` or `String` with large pre-allocated capacity never trimmed — call `.shrink_to_fit()` if long-lived
+- Flag `impl Drop` that can panic — causes `abort` during stack unwinding
+
+---
+
+## Exception Handling
+
+- Flag `.unwrap()` in production code outside of tests — use `?` to propagate or handle explicitly
+- Flag `.expect("todo")` or `.expect("")` — messages must explain the invariant that guarantees safety
+- Flag `panic!` used for recoverable errors — use `Result<T, E>`
+- Flag `unwrap_or_default()` where the default silently masks a real error
+- Prefer typed error enums (`thiserror`) over `Box<dyn Error>` for library crates
+- Prefer `anyhow` for application-level error context; `thiserror` for library error types
+
+---
+
+## Performance
+
+- Flag `.clone()` on large types in hot paths — review whether a reference or `Cow<T>` would work
+- Flag `format!` used only to create a `String` from a literal — use `.to_string()` or `String::from`
+- Flag `collect::<Vec<_>>()` followed immediately by `.iter()` — chain iterators instead
+- Flag `Box<T>` for small types where stack allocation is fine
+- Flag `Mutex` contention on a hot path — consider `RwLock` for read-heavy workloads or sharding
+
+---
+
+## Idioms and Best Practices
+
+### Ownership
+- Prefer borrowing (`&T`, `&mut T`) over cloning wherever the lifetime allows
+- Use `Cow<'_, str>` for functions that sometimes need to own and sometimes borrow
+- Prefer `impl Trait` in function signatures over `Box<dyn Trait>` for static dispatch
+
+### Error Handling
+- Use `?` operator to propagate errors — avoid manual `match Err(e) => return Err(e)`
+- Define domain error types with `thiserror` in libraries; use `anyhow` in binaries
+- Never use `.unwrap()` in library code — it panics the caller's thread
+
+### Modern Rust
+- Prefer `if let` / `while let` for single-variant matches over full `match`
+- Prefer `?` over `unwrap` everywhere errors are recoverable
+- Use `#[derive(Debug, Clone, PartialEq)]` consistently on data types
+- Prefer `iter()` chains over manual loops — they compose and optimize well
+- Use `clippy` and treat its lints as required — flag any `#[allow(clippy::...)]` in review

package/engineering-team/skills/code-reviewer/languages/swift.md

@@ -0,0 +1,88 @@
+---
+language: swift
+extensions: [".swift"]
+---
+
+# Swift — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Swift-specific rules and idioms.
+
+---
+
+## PR Analyzer — Swift Risk Signals
+
+- `print()` statements left in production code
+- Force unwrap (`!`) on optionals outside of tests or justified init
+- Force cast (`as!`) without a safe fallback
+- Hardcoded credentials or API keys in source
+
+---
+
+## Code Quality — Swift Checks
+
+- Force unwrap (`!`) used broadly — prefer `guard let` or `if let`
+- `try!` used outside of guaranteed-safe contexts
+- Retain cycles in closures — missing `[weak self]` or `[unowned self]`
+- `@objc` / `dynamic` used without an Objective-C interop reason
+
+---
+
+## Security
+
+- Flag credentials stored in `UserDefaults` — require Keychain
+- Flag `URLSession` requests over plain HTTP in production
+- Flag `WKWebView` loading arbitrary user-supplied URLs without validation
+
+---
+
+## Async / Concurrency
+
+- Flag `DispatchQueue.main.sync` called from the main thread — deadlock
+- Flag `@escaping` closures capturing `self` strongly in reference cycles — use `[weak self]`
+- Flag mixing `async/await` and `DispatchQueue` for the same operation without clear reasoning
+- Flag `Task { }` (unstructured) where a structured `async let` or `TaskGroup` would maintain structure
+- Flag data races — shared mutable state accessed from multiple tasks without an actor
+
+---
+
+## Resource Management
+
+- Flag `URLSessionDataTask` started with no cancellation handle stored — cannot be cancelled if the view disappears
+- Flag `NotificationCenter` observers added without a corresponding `removeObserver` — memory leak
+- Flag `CLLocationManager` / `AVCaptureSession` not stopped when the owning view controller is dismissed
+
+---
+
+## Exception Handling
+
+- Flag `try!` outside of guaranteed-safe contexts (test fixtures, constants) — crashes on failure
+- Flag `try?` discarding errors where the failure mode matters to the caller
+- Flag error types conforming to `Error` with no associated values or message — makes debugging hard
+- Flag throwing functions calling `fatalError()` as a fallback — choose one error strategy
+
+---
+
+## Performance
+
+- Flag `UIImage(named:)` called repeatedly for the same asset without caching
+- Flag synchronous network calls on the main thread
+- Flag `Array` used for frequent membership tests — prefer `Set`
+- Flag `String` interpolation inside tight loops where a pre-built string would avoid allocations
+
+---
+
+## Idioms and Best Practices
+
+### Optionals
+- Prefer `guard let` for early exit; `if let` for local scope
+- Prefer optional chaining (`?.`) over force unwrap
+- Flag implicitly unwrapped optionals (`var x: String!`) outside of `@IBOutlet`
+
+### Memory Management
+- Flag closures capturing `self` strongly in reference cycles — use `[weak self]`
+- Prefer `struct` over `class` for value semantics unless identity or inheritance is needed
+- Use `unowned` only when the lifetime is guaranteed — otherwise `weak`
+
+### Concurrency (Swift 5.5+)
+- Prefer `async/await` over completion handlers in new code
+- Flag `DispatchQueue.main.async` where `@MainActor` or `await MainActor.run` is more appropriate

package/engineering-team/skills/code-reviewer/languages/typescript.md

@@ -0,0 +1,97 @@
+---
+language: typescript
+extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs"]
+---
+
+# TypeScript / JavaScript — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only TypeScript/JavaScript-specific rules and idioms.
+
+---
+
+## PR Analyzer — TypeScript / JavaScript Risk Signals
+
+- `console.log` / `debugger` statements left in production code
+- `// eslint-disable` comments — verify they are justified
+- `any` type annotations — require explicit justification
+- `@ts-ignore` / `@ts-expect-error` — verify they are justified
+- `eval()` with any dynamic or user-controlled input
+- Hardcoded API keys or tokens in source
+
+---
+
+## Code Quality — TypeScript / JavaScript Checks
+
+- `any` used broadly instead of proper typing
+- Non-null assertion (`!`) used without justification
+- `var` declarations — prefer `const` / `let`
+- Missing `await` on async function calls
+- Floating promises (no `.catch()` and no `await`)
+- `==` used instead of `===`
+
+---
+
+## Security
+
+- Flag `innerHTML`, `outerHTML`, `document.write()` with user-controlled data — use `textContent` or a sanitizer
+- Flag `dangerouslySetInnerHTML` in React without a sanitizer
+- Flag `eval()` / `new Function()` with dynamic input
+- Flag JWT decoded without signature verification
+- Flag missing `httpOnly` / `secure` flags on cookies
+
+---
+
+## Async / Promises
+
+- Flag floating promises — async calls not `await`-ed and without `.catch()`
+- Flag `Promise.all()` where `Promise.allSettled()` is safer (one failure should not cancel siblings)
+- Flag `async` functions inside `forEach` — `forEach` does not await; use `for...of` or `Promise.all()`
+- Flag unhandled promise rejection (no global `unhandledRejection` handler in Node.js services)
+
+---
+
+## Resource Management
+
+- Flag `fs.createReadStream` / `fs.createWriteStream` with no `close` or `destroy` on error
+- Flag `EventEmitter` listeners added in a loop without removal — memory leak
+- Flag `setInterval` / `setTimeout` handles not cleared when the owning component unmounts or exits
+- Flag database clients / pools not released after use in Node.js
+
+---
+
+## Exception Handling
+
+- Flag `catch (e) {}` (empty catch) — swallowed error
+- Flag `catch (e)` where `e` is used as `any` without narrowing — type the error properly
+- Flag `Promise` rejection not handled — `.catch()` or `try/await/catch` required
+- Flag re-throwing a new `Error` without wrapping the original — loses stack context
+- Use `Error` subclasses for domain errors rather than plain strings or object literals
+
+---
+
+## Performance
+
+- Flag `Array.prototype.find` / `filter` / `map` chained multiple times over the same array — combine into one pass
+- Flag DOM queries (`document.querySelector`) inside loops — cache the result
+- Flag `JSON.parse` / `JSON.stringify` in a hot path on large objects — consider streaming or partial parsing
+- Flag `async` functions called sequentially in a loop where `Promise.all()` would parallelize them
+
+---
+
+## Idioms and Best Practices
+
+### Type Safety (TypeScript)
+- Prefer `unknown` over `any` for truly unknown values — forces a type guard before use
+- Prefer type narrowing (`typeof`, `instanceof`, discriminated unions) over casting
+- Enable `strict` mode in `tsconfig.json`
+- Prefer `interface` for object shapes that may be extended; `type` for unions and aliases
+
+### Modern JavaScript / TypeScript
+- Prefer `const` by default; `let` only when reassignment is needed
+- Prefer optional chaining (`?.`) and nullish coalescing (`??`) over manual null guards
+- Prefer `structuredClone()` over manual deep-copy patterns
+- Prefer named exports over default exports for better refactoring support
+
+### Null / Undefined Safety
+- Distinguish between `null` (intentional absence) and `undefined` (not set) — be consistent
+- Flag `== null` checks that accidentally include `undefined` when only one is intended